跳转至

SOP：把优化总账的过账变成有触发点的动作（backlog-review-20261002）

  • 变更日期：2026-10-02
  • 交付物目录：backlog-review-20261002/
  • 实施者：Trae Agent（用户确认后执行）
  • 关联：~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md、 ~/.trae-cn/user_rules/rule-agent-efficiency.md、sessionstart-hook/session-start-inject.py

1. 背景

优化总账（optimization-backlog.md）是效率体系"跟踪执行"的载体：挂账 → 已做 → 已证伪/不做。 但过账（推进挂账项）只有总账正文末尾一句人工约定——「每积累约 5 个新样本或每周过一遍」， 既无触发点、也无验收方。结果：挂账项写下即沉底，无人被提醒去推进。

这一毛病与 2026-10-01 收尾清单"两次漏执行"同源；当时的解法（结论必须出现在最终答复里） 正是本变更要复用的模式——给它一个必跑的触发点，再给它一个可见的验收方。

触发条件：用户确认「按方案 A 执行」（SessionStart 注入过账提醒 + 规则硬门禁）。

2. 目标

变更完成后应达到的可验证状态：

  1. 会话启动时，若总账「距上次过账 ≥7 天」或「挂账 ≥20 项」，注入一行 [过账提醒]；
  2. 未达任一阈值时完全静默（不留空行）；
  3. 总账缺失 / 表格结构变化 / 日期畸形时静默不注入，脚本退出码恒为 0；
  4. 全局规则新增「过账响应」：注入提醒后，最终答复必须给过账结论或不做理由；
  5. 不改 hooks.json（复用现有 SessionStart 条目），故无需重启 Trae。

3. 前置条件

  • python3 可用（Hook 以 python3 <脚本> 调用）；
  • 对 ~/.trae-cn/user_rules/ 与 ~/Documents/services/token_proxy/sessionstart-hook/ 有写权限；
  • hooks.json 的 SessionStart 条目已存在且指向 session-start-inject.py（本变更不改它）；
  • 执行前检查：git status / 备份目录可用（见第 7 章）。

4. 影响范围

项 内容
主机 本机（单机，非集群）
组件 SessionStart Hook（sessionstart-hook/session-start-inject.py）+ 全局规则 rule-agent-efficiency.md
需停服 否。Hook 为会话启动时同步执行，改脚本不影响正在运行的会话
在跑作业 不涉及。重启代理 / Trae 均非必需
生效方式 脚本：下一次开新会话即生效；规则：进每轮前缀，需开新会话（旧会话续跑会触发一次前缀重建）

5. 分步操作

步骤 1：备份

先留退路。脚本备份进本次交付物目录的 backup/（按原路径层次）；全局规则备份沿用 ~/.trae-cn/user_rules/backup/ 既有全局台账惯例，权限 600。

TS=$(date +%Y%m%d-%H%M%S)
DST="$HOME/Documents/services/token_proxy/backlog-review-20261002/backup/home/rain/Documents/services/token_proxy/sessionstart-hook"
mkdir -p "$DST"
cp -p "$HOME/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py" \
      "$DST/session-start-inject.py.bak.$TS"
cp -p "$HOME/.trae-cn/user_rules/rule-agent-efficiency.md" \
      "$HOME/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.$TS"
chmod 600 "$HOME/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.$TS"

预期：两处 .bak 生成，规则备份权限 -rw-------。 失败判断：任一 cp 报错 → 检查路径与权限，不继续。 实现体：本次无独立实现体，改动直接落在脚本源码。

步骤 2：扩展 session-start-inject.py 新增「过账提醒」段

做了什么：在既有"中文指令 + HANDOFF"注入之后，追加一个可选的过账提醒段。 要点与坑：

  • 判据无状态：只读总账文件的表格——第一节「挂账」行数、第四节「过账记录」末行日期。 不引入状态文件，故天然幂等、无过期清理（与会话规模提醒需维护 state/ 不同）；
  • 只数第一节：总账第二、三节表格首列也是数字，必须用章节标记（## 一、挂账 → ## 二、） 限定区间，否则挂账数翻倍；
  • 失败一律静默：文件缺失、结构变化、日期畸形 → 返回 None；异常不得外泄（红线： 非 0 退出码会把 stderr 塞进模型上下文）；
  • 增量编辑：本步只做局部插入（常量 + 函数 + main() 一处 append），不整篇重写。
# 核对改动已落盘（应见 _review_notice / REVIEW_LEDGER / REVIEW_MAX_DAYS）
grep -n "_review_notice\|REVIEW_LEDGER\|REVIEW_MAX_DAYS\|REVIEW_MAX_BACKLOG" \
  ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py

# 语法自检
python3 -m py_compile ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py

预期：grep 命中常量与函数定义；py_compile 无输出、退出码 0。 失败判断：SyntaxError → 按第 7 章回滚后修正重跑。

步骤 3：离线用例（8 项）

用例表见本目录 verify_backlog_review.py，以 importlib 原地加载目标脚本， 把 REVIEW_LEDGER / STATE_LOG 指向临时路径，不碰真实总账、不写真实 state。

python3 ~/Documents/services/token_proxy/backlog-review-20261002/verify_backlog_review.py

预期：8/8 通过（文件缺失静默、未达阈值静默、天数越阈值提醒、挂账越阈值提醒、 空表不崩且计数只认第一节、日期畸形静默、stdin 畸形退出码 0、与 HANDOFF 共存顺序稳定）。 失败判断：任一 FAIL → 不进入步骤 4，先修正。

步骤 4：全局规则新增「过账响应」硬门禁

做了什么：在 rule-agent-efficiency.md 的收尾自查（硬门禁）之后新增一节， 规定「注入了 [过账提醒] 即须在答复中回应」，并补一条「五修」修订记录。

grep -n "过账响应\|过账提醒" ~/.trae-cn/user_rules/rule-agent-efficiency.md

预期：命中「过账响应（2026-10-02 新增，硬门禁）」与五修记录。 失败判断：未命中 → 编辑未落盘，重做。

步骤 5：生效与验证

# 用真实总账做一次只读演练（在 /tmp 下执行以避免注入 HANDOFF，只看过账提醒）
cd /tmp && echo '{}' | python3 ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py

预期：输出含 [过账提醒] optimization-backlog 距上次过账 N 天（上次 YYYY-MM-DD），当前挂账 M 项…。 失败判断：无该行 → 按第 6 章排查。 注意：脚本改动在下一次开新会话生效；规则改动需开新会话（旧会话续跑会触发一次前缀重建，≈0.35 元）。

6. 验证

  1. 步骤 3 的 8 项离线用例全过；
  2. 步骤 5 的真实总账演练输出含 [过账提醒]，且天数 / 挂账数与总账实际一致 （2026-10-02 实测：挂账 20 项 → 触发，属挂账阈值命中）；
  3. python3 -m py_compile 退出码 0；
  4. 未达阈值场景（用例 2）确实不注入，避免每轮新会话噪音。

7. 回滚

备份位置与台账：见 backlog-review-20261002/backup/README.md； 全局规则备份台账见 ~/.trae-cn/user_rules/backup/README.md。

# 回滚脚本（用本次备份覆盖）
cp -p "$HOME/Documents/services/token_proxy/backlog-review-20261002/backup/home/rain/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py.bak.<TS>" \
      "$HOME/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py"

# 回滚规则：删除「过账响应」一节及五修记录，或整体用 .bak 覆盖
cp -p "$HOME/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.<TS>" \
      "$HOME/.trae-cn/user_rules/rule-agent-efficiency.md"

回滚后验证：重跑步骤 3 的用例应回到"无过账提醒"预期（用例 3/4 变为 FAIL 属正常，因功能已撤）； 确认脚本仍能正常注入中文指令与 HANDOFF。回滚触发条件：脚本 py_compile 失败、 新会话未注入中文指令、或过账提醒每轮新会话重复出现且无法停止。

8. 风险说明

风险 缓解
阈值过频（一个周期内多个新会话反复注入） 提醒文本极短（<100 字）；仅在越阈值时注入；阈值为两个常量，随时可调
阈值过疏（长期不提醒） 判据取或（天数 / 挂账数），任一到即触发
依赖总账表格结构 用固定章节标记 + 容错正则；结构变化则静默失效。改总账章节标题或首列格式须同步脚本（脚本 docstring 已注明）
提醒后仍不过账 规则「注入必回应」兜住可见性；但无法强制执行——本变更上限即"到点必提醒 + 必回应"
改规则使前缀重建 收尾即提醒开新会话，避免在失效前缀上反复累积

附录 A：交付物清单

文件 说明
backlog-review-20261002/SOP.md 本文件
backlog-review-20261002/RUNBOOK.md sessionstart-hook（含过账提醒）运行手册
backlog-review-20261002/verify_backlog_review.py 8 项离线用例
backlog-review-20261002/backup/README.md + backup/… 备份台账与脚本备份

附录 B：与既有机制的关系

  • 复用 2026-10-01 收尾清单的加固模式：Hook 提供触发点，规则提供验收方；
  • 与「会话规模提醒」（PostToolUse）无耦合：本变更在 SessionStart，只读总账、不写状态文件。

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