SOP · 前缀重建防护（判据 X）+ 默认档改 high + 口径修正¶

主题：prefix-guard-20261011 日期：2026-10-11 类型：C 类变更（改 hook 脚本 + 改规则 + 改 config.yaml 并重启代理）

1. 背景¶

本轮实测把两件事钉死了：

「增 / 删 skill、改 description、改 prompt_hint」会改 system prompt → 下一轮首请求整段前缀重建（实测增 backup-hygiene 得 176,394/189,706=93% ≈¥0.18；同轮开 prompt_hint 得 282,917 ≈¥0.28）。而改规则文本 / skill 正文只有 2%。此类改动明知要花钱，本应改到「新会话」里做（上下文小、便宜一个量级），此前却直接在当前大上下文里做了。
用户三点纠正：① 重启代理不是红线（规则与 BASELINE 早已写明「可直接重启、不打断输出流」），是我措辞把它塞进了红线；② 明知会失效的改动要先提醒开新会话；③ 默认档要一直 high，且质疑「为什么会重建」。

2. 目标¶

加 merge-guard 判据 X：写 / 删 ~/.trae-cn/skills/**/SKILL.md、或写 config.yaml 含 prompt_hint → 提醒「下一轮整段前缀重建，建议先开新会话再改」。
规则：「重启共享服务」行明确标注"不是红线"；新增一行「会进 system prompt 的改动先提示用户开新会话」。
config.yaml 默认档 default_effort: low → high。
修正两处被实测打脸的旧结论（BASELINE.md 前缀缓存边界、commands/cost.md）。

3. 前置条件¶

python3；改后重启代理用 venv 解释器：PYTHON_BIN="$PWD/venv/bin/python" ./run.sh restart。

4. 影响范围¶

单机、无需停服；重启中断约 1 秒，不打断在途输出流。
触及：merge-guard/merge-guard.py（+判据 X）、~/.trae-cn/user_rules/rule-agent-efficiency.md、config.yaml、docs/BASELINE.md、~/.trae-cn/commands/cost.md。
merge-guard 是 PreToolUse matcher:*，改动即时生效（hooks.json 未动，无需重启 Trae）。

5. 分步操作¶

步骤 1：加判据 X（`merge-guard.py`）¶

注意事项与坑：X 必须排在 M/P/Q/W 之前，并把 hit 清空——否则会被它们抢占（M=盲改、P=会话规模，二者都先于 X 触发；首版实测因此 X 从不出现）。实现见 _prefix_invalidating()。

cd ~/Documents/services/token_proxy
python3 -m py_compile merge-guard/merge-guard.py            # 预期 rc=0
python3 prefix-guard-20261011/verify_judge_x.py             # 预期 7/7

步骤 2：规则两行（`rule-agent-efficiency.md` 执行方式表）¶

「重启共享服务」行标注不是红线；新增「会进 system prompt 的改动 → 先提示用户开新会话」行。

grep -n '不是红线\|先提示用户' ~/.trae-cn/user_rules/rule-agent-efficiency.md   # 预期各 1 行

步骤 3：默认档改 high 并重启¶

注意事项与坑：改档位只改请求体的 reasoning_effort 字段，不改 prompt → 不会重建（与 prompt_hint 完全不同），重启代理即可。

grep -n 'default_effort' config.yaml                        # 预期 high
PYTHON_BIN="$PWD/venv/bin/python" ./run.sh restart           # 旧进程若非 run.sh 启动，先按 PID kill

步骤 4：口径修正（`BASELINE.md` / `commands/cost.md`）¶

把「user_rules 改动会使前缀失效」「与改 skill / 规则无关」等旧说法改为「看 system prompt 是否变」的分档口径。

6. 验证¶

python3 -m py_compile merge-guard/merge-guard.py        # rc=0
python3 prefix-guard-20261011/verify_judge_x.py         # 7/7 PASS
./run.sh status                                         # [运行中]
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8788/healthz   # 200

实测（2026-10-11）： - 判据 X 7/7：写/删 SKILL.md、改 config.yaml+prompt_hint → 提醒；改 skill 正文、改 config 其它字段、普通文件 → 静默；每会话只一次。 - 代理重启后 healthz 200、default_effort=high 生效；重启后 miss 仍 300~800（正常） → 证明「改档位参数不重建」。

7. 回滚¶

备份位置：prefix-guard-20261011/backup/，登记见 backup/README.md。

cd ~/Documents/services/token_proxy
cp -p prefix-guard-20261011/backup/merge-guard/merge-guard.py.bak.<TS> merge-guard/merge-guard.py
cp -p prefix-guard-20261011/backup/config.yaml.bak.<TS> config.yaml
cp -p prefix-guard-20261011/backup/docs/BASELINE.md.bak.<TS> docs/BASELINE.md
cp -p prefix-guard-20261011/backup/trae-cn/user_rules/rule-agent-efficiency.md.bak.<TS> ~/.trae-cn/user_rules/rule-agent-efficiency.md
cp -p prefix-guard-20261011/backup/trae-cn/commands/cost.md.bak.<TS> ~/.trae-cn/commands/cost.md
PYTHON_BIN="$PWD/venv/bin/python" ./run.sh restart

回滚后验证：verify_judge_x.py 应不再出现 【前缀重建提醒】；grep default_effort config.yaml 应回 low。

8. 风险说明¶

风险	缓解
X 误报（如新建一个不含 description 的 SKILL.md）	只提醒不阻断；「宁多勿漏」是本判据的取向（改 skill 索引必然花钱）
默认档 high 抬高输出与输入成本	用户裁定接受（low 与 high 思考量实测几乎相同，省不下）；随时可改回
重启起不来	用 venv 解释器；旧进程非 run.sh 启动时先按 PID `kill`

附录 · 交付物与回滚点¶

交付物	路径	说明
判据 X	`merge-guard/merge-guard.py`（`_prefix_invalidating` + `PROMPTS["X"]` + 主流程块）	提醒「整段重建、建议开新会话」
验证脚本	`prefix-guard-20261011/verify_judge_x.py`	正例 / 反例 / 每会话一次，7 项
规则	`rule-agent-efficiency.md`（重启行 + 新增行）	重启非红线；system prompt 改动先提示
默认档	`config.yaml` → `default_effort: high`	一律 high
口径修正	`docs/BASELINE.md` §2、`~/.trae-cn/commands/cost.md`	按「system prompt 是否变」分档
回滚点	`prefix-guard-20261011/backup/`	台账 `backup/README.md`

来源：/home/rain/Documents/services/token_proxy/prefix-guard-20261011/SOP.md ｜最后更新：2026-10-11 17:14（由 build/sync.py 同步，请勿在站点侧修改）