SOP：优化点总账挂账项落地 + 残留 backup 清理（2026-10-02）

本主题为 token_proxy 侧变更；跨工程的 #1/#8 见 ~/Documents/k8s_ins/optimization-backlog-20261002/SOP.md。 交付物目录：backlog-20261002/（本文件、backup/）。

1. 背景

上一轮建立了「优化点总账」~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md （挂账 20 / 已做 8 / 已证伪 6），但总账自身记录的教训是「写下压缩点 ≠ 执行压缩点」。 本轮按用户选定，落地其中 4 项并清理 docs/HANDOFF.md §3.1 的待决策残留 backup。

触发条件：用户在新会话下达「继续上轮未完成的」，并选定「落地总账挂账项 + 清理残留 backup」。

2. 目标（可验证）

1. md-inventory-20260923/backup/、handoff-bootstrap-20260923/backup/、mi-model-20260924/backup/ 三个目录删除，相关 SOP 的回滚引用同步修订。

2. 9：session_deep_dive.py 支持一次进程深挖多个会话（--top N / --conv a,b）。

3. 19：新增 glob-grep-guard/glob-grep-guard.py，并在 ~/.trae-cn/hooks.json 注册

   PreToolUse 的 Glob / Grep 两条 matcher；重启 Trae 后对"无目录限定的 ** 通配"必然注入提醒。
4. 总账中这 4 项由「挂账」移入「已做」。

3. 前置条件

• 权限：本机 rain；可写 ~/.trae-cn/、工程根与 .trae/skills/。
• 工具：python3、工程 ./venv/bin/python。
• 执行前检查：~/.trae-cn/hooks.json 可被 json.load 解析；logs/*.jsonl 全程只读。

4. 影响范围

项	内容
主机	192.168.31.250（本机）
组件	Hook 链路（新增 PreToolUse Glob/Grep）、cost-deep-review 脚本
是否停服	不需停服；未触碰 proxy.py / config.yaml，在途流式回答不受影响
窗口	无限制；但 hooks.json 改动须重启 Trae 才生效，重启会中断当前会话
不可逆点	三个 backup 目录的删除（放弃对应回滚副本）

5. 分步操作

步骤 1：删除三个残留 backup 目录【高危·不可逆】

做什么/为什么：三个目录的台账判据均已满足（md-inventory = 「新 HANDOFF 确认无误后」； handoff-bootstrap = 「验证通过后」；mi-model = 「验证通过并稳定运行后」）。本轮核对： HANDOFF 已迭代至 10-02；小米链路 logs/usage.jsonl 中 mi 记账 1219 条、最近一条 2026-09-30 15:30:00 status=200，/healthz 三条路由在线。

坑：handoff-bootstrap/backup/ 内含隐藏目录 .trae-cn/（ls -lR 不显示，须 ls -lRa）， 漏删会留下 rule-skill-index.md.bak；mi-model/backup/config.yaml.bak 是"回到仅 ds/glm 两路由" 的唯一回滚副本。

cd /home/rain/Documents/services/token_proxy
# 删前校验：三个目录都必须存在，避免误判路径
for d in md-inventory-20260923/backup handoff-bootstrap-20260923/backup mi-model-20260924/backup; do
  [ -d "$d" ] || { echo "缺失，终止: $d" >&2; exit 1; }
done
rm -rf -- md-inventory-20260923/backup handoff-bootstrap-20260923/backup mi-model-20260924/backup
for d in md-inventory-20260923/backup handoff-bootstrap-20260923/backup mi-model-20260924/backup; do
  [ -e "$d" ] && echo "仍存在(异常): $d" || echo "已删除: $d"
done

预期：三行「已删除」。失败判断：出现「仍存在(异常)」→ 检查权限后重跑（幂等，已删的目录会被 [ -d ] 判为缺失而终止，故重跑前须确认剩下的才是待删项）。

步骤 2：session_deep_dive.py 批量化（#9）

做什么/为什么：原脚本 --conv 只接受单个前缀，深挖 9 个会话要起 9 次进程（agent 侧 9 步）。 改为一次进程处理多个：--conv a,b,c（逗号分隔）或 --top N（按当日成本降序取前 N）； 深挖逻辑抽为 deep_dive(rs)，会话聚合 stat 提前到归因表分支之外与深挖共用。

坑：--top 与 --conv 语义重叠，必须互斥（同给时报错退出，避免歧义）； 原输出用 args.conv 打印会话名，抽函数后改用 rs[0]['conv_key']，否则多会话输出会互相串名。

cd /home/rain/Documents/services/token_proxy
cp -p .trae/skills/cost-deep-review/scripts/session_deep_dive.py \
      backlog-20261002/backup/session_deep_dive.py.bak.<YYYYmmdd-HHMMSS>   # 变更前留档
python3 -m py_compile .trae/skills/cost-deep-review/scripts/session_deep_dive.py   # 语法门禁

预期：py_compile 无输出（rc=0）。脚本文本替换以实现体为准，此处不复制正文。

步骤 3：新增 glob-grep-guard.py 并注册 Hook（#19）

做什么/为什么：2026-10-02 的 A/B 复测已证伪「规则条款足以挡住全仓库通配」——改后仍 2 次 复现 **/* 被 .venv 污染。根因是缺必然触发点。本步新增 PreToolUse 脚本，在出现 "无目录限定的 ** 通配"时必然注入提醒。

关键决策：只提醒、不拦截。PreToolUse 退出码 2 等价 permissionDecision=deny， 一次误判就废掉本轮工具调用（同 docs-read-guard.py「设计约束 1」）；且 LR §三 的原文口径 也是"即提醒"。故本处的"强制"指投递的必然性，不是阻断。

坑：① 误报会让提示每轮重放，故只对 ** 出现在 pattern/glob 开头且未给 path 的调用报； docs/**/*.md 不报。② 缺 session_id 时不去重（漏注入 > 重复注入）。③ 任何异常静默 exit 0。

cd /home/rain/Documents/services/token_proxy
chmod +x glob-grep-guard/glob-grep-guard.py
python3 -m py_compile glob-grep-guard/glob-grep-guard.py
# 离线用例（假 JSON 喂 stdin）：
printf '%s' '{"tool_name":"Glob","tool_input":{"pattern":"**/*"},"session_id":"x1"}' \
  | python3 glob-grep-guard/glob-grep-guard.py; echo
cp -p "$HOME/.trae-cn/hooks.json" backlog-20261002/backup/hooks.json.bak.<YYYYmmdd-HHMMSS>

hooks.json 的 PreToolUse 由 1 条（Read）扩为 3 条，新增两条 matcher 为 Glob / Grep， 命令均为 s="$HOME/Documents/services/token_proxy/glob-grep-guard/glob-grep-guard.py"; [ -f "$s" ] && python3 "$s" || true; exit 0。 预期：json.load 通过，三条 matcher 依次为 Read / Glob / Grep。

6. 验证

项	命令	预期
backup 已删	ls -d *_2026092*/backup mi-model-20260924/backup 2>&1	三者均 No such file or directory
#9 多会话	./venv/bin/python .trae/skills/cost-deep-review/scripts/session_deep_dive.py --top 2 \| grep -c '^====='	2
#9 互斥	... --conv x --top 1	输出「--conv 与 --top 二选一」
#19 用例	8 项离线用例（正/负/去重/畸形输入）	全部符合预期，畸形输入 exit=0
#19 注册	python3 -c "import json;print([h['matcher'] for h in json.load(open('$HOME/.trae-cn/hooks.json'))['hooks']['PreToolUse']])"	['Read', 'Glob', 'Grep']

真机验收（2026-10-02 通过）：重启 Trae 后以裸 **/* 触发 Glob，PreToolUse 注入【检索约束】提醒成功， 确认提醒落进模型上下文；同次结果按预期扫入 venv/、__pycache__ 并被 200 条上限截断，印证文案针对性。 （变更当轮只做了离线用例 + JSON 校验。）

7. 回滚

对象	备份位置	回滚命令
~/.trae-cn/hooks.json	backup/hooks.json.bak.20261002-151719	cp -p backlog-20261002/backup/hooks.json.bak.20261002-151719 ~/.trae-cn/hooks.json（改后须重启 Trae）
session_deep_dive.py	backup/session_deep_dive.py.bak.20261002-151513	cp -p backlog-20261002/backup/session_deep_dive.py.bak.20261002-151513 .trae/skills/cost-deep-review/scripts/session_deep_dive.py
glob-grep-guard.py	新增文件，无备份	删除该目录 + 从 hooks.json 撤掉两条 matcher，或直接回滚 hooks.json

备份台账见 backlog-20261002/backup/README.md。

三个残留 backup 目录无回滚副本（本轮删除的对象本身即历史备份）；受影响的回滚点见 md-inventory-20260923/SOP.md、handoff-bootstrap-20260923/SOP.md、mi-model-20260924/SOP.md 的修订说明（标注「备份已于 2026-10-02 删除」）。

8. 风险说明

风险	缓解
删除 backup 不可逆，放弃 mi 链路的 config.yaml 回滚点	判据已实测满足（链路稳定运行 8 天）；如需重建回滚点，重跑一次变更前的 config.yaml 快照
hooks.json 改动误写坏 → Hook 全体静默失效	改前 cp 备份 + json.load 校验；命令行自带 [ -f "$s" ] 守卫
新增 Hook 提醒误报 → 每轮重放占上下文	判定收窄到"** 开头且无 path"；同会话同 agent 只注入一次
Trae 不支持 Glob/Grep matcher → 提醒静默失效	失败模式为静默；重启后按第 6 章真机验收确认

附录：交付物清单

• backlog-20261002/SOP.md（本文件）
• backlog-20261002/backup/README.md（备份台账）
• glob-grep-guard/glob-grep-guard.py（新增 Hook 脚本，常驻工程目录）
• 修订：.trae/skills/cost-deep-review/scripts/session_deep_dive.py、~/.trae-cn/hooks.json
• 跨工程部分见 ~/Documents/k8s_ins/optimization-backlog-20261002/

---

来源：/home/rain/Documents/services/token_proxy/backlog-20261002/SOP.md ｜ 最后更新：2026-10-02 15:34（由 build/sync.py 同步，请勿在站点侧修改）