RUNBOOK：sessionstart-hook（含过账提醒）

面向接手本机 Trae 环境运维、或需要排查"会话启动没有注入 / 过账提醒不出现"的值班人。 每条命令可直接粘贴，输出不符时见第 8 章。

1. 服务概览

项	内容
是什么	Trae 的 SessionStart Hook：每次开新会话时同步执行，向模型注入「中文指令 + 项目 docs/HANDOFF.md 交接快照 + HANDOFF 读取守卫提示 + 到点时的过账提醒」
由谁调用	~/.trae-cn/hooks.json 的 SessionStart 条目，命令为 python3 <脚本>，超时 10s
组成	单脚本 ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py（无守护进程）
依赖	python3；被读文件：工作区逐级向上的 docs/HANDOFF.md、全局优化总账 optimization-backlog.md；写自己的运行日志 state/session-start.log
异常影响	注入静默失效——不报错、不阻断会话，但模型丢失交接上下文 / 过账提醒。属"静默故障"，须靠日志发现
重要性	中（影响每个新会话的起点，但非业务链路）

2. 接入与凭据

不涉及。脚本全程只读本地文件、无网络、无凭据。

3. 日常速查表

# 看最近 5 次运行留痕（命中哪个 HANDOFF、注入字节、是否截断）
tail -n 5 ~/Documents/services/token_proxy/sessionstart-hook/state/session-start.log

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

# 演练一次（在 /tmp 下跑，避免注入 HANDOFF，只看中文指令与过账提醒）
cd /tmp && echo '{}' | python3 ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py

# 跑离线用例（8 项，只读、无副作用）
python3 ~/Documents/services/token_proxy/backlog-review-20261002/verify_backlog_review.py

# 确认 Hook 配置指向本脚本
grep -n "sessionstart-hook" ~/.trae-cn/hooks.json

4. 日常操作

本脚本无启动/停止/重启概念——它由 Trae 在会话启动时同步调用，改完脚本下一次开新会话即生效， 无需重启 Trae、无需重启任何服务。

• 看它有没有跑：看 state/session-start.log 末尾时间戳是否为最近开会话时刻；
• 看它注入了什么：日志行的 handoff=（命中的文件）、bytes=（注入字节）、truncated=（是否截断）；
• 临时停用过账提醒：把 optimization-backlog.md 的过账记录末行日期改成当天，或把挂账数降到 20 以下 （均不需改脚本）；彻底停用见第 5 章。

5. 配置管理

配置	位置	默认	修改后生效
注入上限	脚本常量 MAX_INJECT_BYTES	12288	下次开新会话
向上查找层数	MAX_UP_LEVELS	4	同上
过账提醒：天数阈值	REVIEW_MAX_DAYS	7	同上
过账提醒：挂账阈值	REVIEW_MAX_BACKLOG	20	同上
总账路径	REVIEW_LEDGER	~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md	同上

彻底停用过账提醒：把 REVIEW_MAX_DAYS 与 REVIEW_MAX_BACKLOG 调到极大值（如 10**9）即可， 无需删除代码。改任何常量后必须重跑第 3 章离线用例（用例 3/4 会随阈值变化）。

易错点：过账判据依赖总账固定章节标题（## 一、挂账 / ## 二、 / ## 四、过账记录） 与表格首列为编号/日期的格式。若总账改版，须同步脚本，否则解析失败、静默失效。

6. 备份与恢复

• 备份位置：~/Documents/services/token_proxy/backlog-review-20261002/backup/…（脚本）； ~/.trae-cn/user_rules/backup/（规则）。台账见各自 README.md；
• 恢复：用对应 .bak.<时间戳> 覆盖回原路径即可（详见 backlog-review-20261002/SOP.md 第 7 章）。

7. 监控与告警

无主动告警。唯一的观测点是 state/session-start.log。建议异常判据：

# 超过 7 天没有新日志 = 长期没开会话，或 Hook 已静默失效
ls -l --time-style=+%F ~/Documents/services/token_proxy/sessionstart-hook/state/session-start.log

8. 故障处置

场景 A：新会话没有注入中文指令 / HANDOFF

症状：开新会话后模型未收到交接快照；state/session-start.log 无新行。

诊断

# 1) 配置是否指向本脚本
grep -n "sessionstart-hook" ~/.trae-cn/hooks.json
# 2) 脚本是否还在（删目录会导致静默失效：脚本缺失不报错）
ls -l ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py
# 3) 手工跑一次看有无异常
cd /tmp && echo '{}' | python3 ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py

处置：脚本缺失 → 从备份恢复；路径不符 → 修正 hooks.json 后重启 Trae；手工跑报 SyntaxError → 用 .bak 回滚。 验证：手工跑有输出、state/session-start.log 新增一行。

场景 B：过账提醒不出现（但应到点）

症状：总账已多日未过账，新会话却没有 [过账提醒]。

诊断

# 1) 是否真到阈值（天数≥7 或挂账≥20）
tail -n 3 ~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md
# 2) 判据能否算出（跑演练直接看）
cd /tmp && echo '{}' | python3 ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py
# 3) 离线用例是否仍全过（结构变化会用例 5/6 失败）
python3 ~/Documents/services/token_proxy/backlog-review-20261002/verify_backlog_review.py

处置：未到阈值 → 属正常，非故障；用例 5/6 FAIL → 总账章节标题或表格格式已变，同步脚本； 路径变动 → 修正 REVIEW_LEDGER。 验证：演练输出出现 [过账提醒] … 当前挂账 N 项，N 与总账一致。

场景 C：过账提醒每轮新会话都出现，无法消除

症状：完成过账后，新会话仍重复提醒。

诊断：提醒取「或」逻辑，二者只要还有一个越阈值就会继续触发。

# 看总账：过账当天是否已补记「过账记录」末行？挂账是否仍 ≥20？
tail -n 3 ~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md

处置：过账后须在总账第四节追加当天日期行；若挂账数确实 ≥20，则阈值本身偏松， 调 REVIEW_MAX_BACKLOG。注意：提醒本身不是故障，它正是在提醒你总账还有欠账。 验证：补记后演练不再输出 [过账提醒]（或仅因挂账数触发，需继续推进）。

场景 D：注入内容过长 / HANDOFF 被截断

症状：日志 truncated=yes，模型侧交接快照不完整。

处置：HANDOFF 按 writing-handoff 技能控制在 10 KB 硬上限内；必要时把稳定内容拆到 docs/BASELINE.md。 验证：日志 truncated=no。

场景 E：模型仍把已注入的 HANDOFF 又整篇读一遍

症状：会话里出现对 docs/HANDOFF.md 的 Read，而它已由本 Hook 全文注入（MB §二十七 / §二十九 的 22:20、22:29 两次即此）。 诊断：演练一次，看输出末段是否带 [HANDOFF 读取守卫] 行——

cd /tmp && echo '{}' | python3 ~/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py | tail -3

无该行 → 脚本是旧版或被回滚（grep -n HANDOFF_READ_GUARD <脚本路径> 确认）。 处置：恢复脚本即可（守卫是纯提示、不阻断）；若提示已在而模型仍重读，属行为层问题，由 writing-handoff 与 reading-docs-for-context 两个技能的禁令兜底。 验证：演练输出末段出现 [HANDOFF 读取守卫] 以上即 docs/HANDOFF.md 的完整内容…。

9. 安全与权限

• 脚本只读本地文件、只写自己的 state/ 日志，无网络、无凭据、无提权；
• state/ 日志含工作区路径，不含敏感信息；备份文件权限 600；
• 不使用 sudo。

10. 容量与性能

• 每次会话启动执行一次，毫秒级；读文件上限由 MAX_INJECT_BYTES 约束；
• 无累积状态（过账判据不写状态文件），state/ 只增日志，可定期清理旧行。

11. 附录

文档	位置
本次变更实施与回滚	backlog-review-20261002/SOP.md
离线用例	backlog-review-20261002/verify_backlog_review.py
备份台账	backlog-review-20261002/backup/README.md、~/.trae-cn/user_rules/backup/README.md
Hook 机制与陷阱	docs/BASELINE.md
优化总账	~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md

修订记录：2026-10-02 首版（随「过账提醒」变更产出）；2026-10-02 补「HANDOFF 读取守卫」——命中注入时多输出一行「已注入、勿再 Read」，新增故障场景 E。

---

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