SOP — 挂账 #22 与 #28 落地（WebFetch 守卫 + 读取范围判据）

工程：token_proxy（Hook 守卫）｜实施日期：2026-10-02 交付目录：~/Documents/services/token_proxy/webfetch-guard/ 对应挂账：skills/ops-execution-efficiency/references/optimization-backlog.md #22、#28

1. 背景

两条优化点在「日志解析增强 #3/#4」那一轮的收尾自评里被确认尚未落地：

• #22（先 WebSearch 摘要，再定向 WebFetch 单页）：该条此前已挂账，但本轮仍整页 WebFetch 一次（filestream 页 ≈5145 tok），且抓回的前半页不含目标 parsers 章节——第二次踩到。 根因与 glob-grep-guard 同款：条款没有必然触发点，写进挂账不等于会被执行。
• #28（改动某文件前，只读该文件与其直接依赖）：本轮主上下文直读 3 个实现体 ≈33 KB， 其中 deployer.py / k8s_efk.py 大半内容本次未用上，上下文冲到 ~17 万 token， 其后每一步都按该规模重放。

2. 目标

1. 22 的提醒投递必然化：只要调用 WebFetch，约束提示必定进入模型上下文（每会话一次）。

2. 28 成为可判定判据：写入全局规则表与 skill 正文，跨会话复用。

3. 两者均不得阻断工具调用（PreToolUse 只提醒，不改 permissionDecision）。

3. 前置条件

• ~/.trae-cn/hooks.json 可写；python3 可用（Hook 以 python3 <script> 方式调用）。
• 改动 hooks.json 需重启 Trae 生效；改动 user_rules/ 需开新会话生效。
• 备份已就位：webfetch-guard/backup/（见 backup/README.md）。

4. 影响范围

项	内容
生效范围	全局（所有工作区、所有会话）
生效时点	Hook：重启 Trae 后；规则与 skill 判据：新会话后
每轮成本	规则表新增 2 行 → 每轮前缀 +约 120 字；Hook 提示每会话一次（≈100 字，随后每轮重放）
阻断风险	无——脚本任何异常路径均静默 exit 0，permissionDecision=allow
脚本缺失时	hooks.json 命令行内的 [ -f "$s" ] 守卫兜底，不影响任何工具调用

5. 分步操作

步骤 1：新增守卫脚本

新建 webfetch-guard/webfetch-guard.py，骨架照 glob-grep-guard.py（同一套设计约束：不阻断、 文本极短、按 (session_id, agent_id) 去重、缺 session_id 时不去重、state/ 过期标记回收并留痕）。

cd ~/Documents/services/token_proxy/webfetch-guard
chmod +x webfetch-guard.py
# 手工触发一次（应输出含 additionalContext 的 JSON）
echo '{"tool_name":"WebFetch","session_id":"manual-1","tool_input":{"url":"https://x"}}' \
  | python3 webfetch-guard.py

预期：输出 hookSpecificOutput，含 "permissionDecision": "allow" 与提示文本。 失败判断：进程非 0 退出 → 检查 main() 是否被 try/except 包裹、json.loads 是否在 try 外。

步骤 2：注册到 hooks.json

在 PreToolUse 数组内、Grep 条目之后追加 WebFetch 条目。

# 仅查看注册结果（不修改）
python3 -c "import json;d=json.load(open('$HOME/.trae-cn/hooks.json'));\
print([h.get('matcher') for h in d['hooks']['PreToolUse']])"

预期：['Read', 'Glob', 'Grep', 'WebFetch']。 失败判断：JSON 解析异常 → 本次改动使文件语法错误，立即用第 7 章回滚。

⚠ 高危提示：hooks.json 是全局 Hook 配置，写坏会让所有 Hook 失效；必须先备份（本目录 backup/），改完立即用上条命令验证 JSON 合法性。

步骤 3：规则表加两条判据

在 ~/.trae-cn/user_rules/rule-agent-efficiency.md 的「执行方式（必须）」表内， 需多步取数 / 统计 行之后插入「改动某文件前」「需外部文档」两行。

grep -n "改动某文件前\|需外部文档" ~/.trae-cn/user_rules/rule-agent-efficiency.md

预期：命中 2 行。 失败判断：未命中 → 表格被写坏（对齐/竖线），重新定点编辑。

步骤 4：skill 正文加同款判据

在 skills/ops-execution-efficiency/SKILL.md 第 6.2 节（agent 轮次与上下文）的 bullet 列表里， 于「同一文件要读多段时」之后追加两条含【实测】标注的 bullet。

grep -n "只读该文件与其直接依赖\|webfetch-guard" ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md

预期：命中 2 行。

6. 验证

#	用例	命令要点	预期（2026-10-02 实测）
A	WebFetch 首次注入	喂 tool_name=WebFetch	✅ 输出含提示
B	同会话第二次不注入	同 session_id 再喂	✅ 无输出
C	缺 session_id 仍注入	去掉 session_id	✅ 输出含提示
D	非目标工具静默	tool_name=Read	✅ 无输出
E	缺 tool_name 静默	只给 session_id	✅ 无输出
F	非法输入不阻断	喂 {not-json	✅ 退出码 0、无输出
G	判定为 allow	解析输出 JSON	✅ permissionDecision=allow

python3 webfetch-guard/tests_guard_cases.py    # 实测 7/7 通过
python3 -c "import json;json.load(open('$HOME/.trae-cn/hooks.json'));print('JSON 合法')"

真机验收（待做）：重启 Trae 后，在新会话里调用一次 WebFetch，确认提示出现在上下文； 再调用 Read 确认不受影响。

7. 回滚

备份位于 webfetch-guard/backup/，台账见 backup/README.md。

cd ~/Documents/services/token_proxy/webfetch-guard/backup
# 1) 还原 hooks.json（高危：覆盖全局 Hook 配置）
cp -p hooks.json.bak.20261002-211617 ~/.trae-cn/hooks.json
# 2) 还原规则文件（高危：覆盖全局规则）
cp -p rule-agent-efficiency.md.bak.20261002-211617 ~/.trae-cn/user_rules/rule-agent-efficiency.md
# 3) 撤销 skill 正文的两条 bullet（定点删除即可，无需整体还原）
# 4) 移除守卫脚本目录（确认 hooks.json 已不再引用后再删）

回滚触发条件（任一达标即回滚）：① hooks.json JSON 解析失败；② 重启 Trae 后任何工具调用被阻断 （应绝不发生——本 Hook 只 allow）；③ 提示文本被高频重复注入（去重失效）。

回滚后验证：python3 -c "import json;json.load(open('$HOME/.trae-cn/hooks.json'))" 通过； 新会话中 WebFetch 不再注入提示。

8. 风险说明

风险	缓解
脚本异常导致工具调用被拒	全路径 try/except + exit 0；只输出 allow，从不输出 deny
提示文本每轮重放抬高成本	文本压到 ~100 字；每会话只注入一次
hooks.json 写坏使全局 Hook 失效	先备份、改完立即验证 JSON；[ -f ] 守卫兜底
规则表变长抬高每轮前缀	只加 2 行（约 120 字）；属"一次投资、跨会话复用"
去重键退化为固定值导致永久静默	缺 session_id 时不写标记、直接注入（漏注入 > 重复注入）
生效时点被误解为"改完即生效"	本 SOP 与 Hook 提醒均写明：Hook 需重启 Trae、规则需开新会话

附录：交付物清单

文件	说明
webfetch-guard.py	PreToolUse 守卫（WebFetch 前注入检索成本约束）
tests_guard_cases.py	离线用例（7 项，含自清理测试标记）
backup/	hooks.json 与 rule-agent-efficiency.md 的备份与台账
SOP.md	本文件

被改文件：~/.trae-cn/hooks.json、~/.trae-cn/user_rules/rule-agent-efficiency.md、 ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md（正文，不影响前缀）。

---

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