SOP — HANDOFF 容量机制修正（护栏解耦 + 技能归因纠错）¶
主题目录
handoff-capacity-20261002/｜变更时间 2026-10-02 23:30｜备份台账见backup/README.md
1. 背景¶
用户困惑：「HANDOFF 硬上限 10 KB 却经常触发整体重写」，并对比发现 token_proxy 的 HANDOFF 是 6.8 KB、k8s_ins 的是 10.2 KB。诊断结论（详见附录 A）：
- 判据错位：真正每轮触发的是技能里「文件 > 目标值 6 KB → 强制整体重写」，而非 10 KB 硬限；
- 归因错误：技能「长度预算」节称上限是为防 SessionStart 注入截断——取证查明截断源只有一个，即本工程 hook 脚本自造的护栏
MAX_INJECT_BYTES（原值 12288 = 技能上限 10 KB × 1.2），并非上游 / Trae 限制，属自我循环归因； - 内容回流：缺少可寻址归档落点的项目（如 k8s_ins），已结案内容持续回流进 HANDOFF。
本次先落地机制链中最上游、零风险的两处（第 3 条）：护栏解耦与归因纠错。第 1 条（落点）与第 2 条（双阈值滞回）另行落地。
2. 目标¶
MAX_INJECT_BYTES由"照抄技能上限 ×1.2"解耦为固定宽松值 16384，职责收敛为"只防失控"，不再反向定义容量。- 技能
writing-handoff的「长度预算」节，把"上限为防截断"改为已证伪的准确表述。 - 可验证状态：注入脚本对 token_proxy（6783 B）与 k8s_ins（10171 B）两份 HANDOFF 均
truncated=no；复跑幂等。
3. 前置条件¶
- 对本工程
sessionstart-hook/与~/.trae-cn/skills/writing-handoff/的写权限； - 已确认
hooks.json指向的注入脚本即本工程sessionstart-hook/session-start-inject.py（全局生效，两项目共用）； - 执行前检查：
wc -c docs/HANDOFF.md（token_proxy 6783、k8s_ins 10171，均低于 16384）。
4. 影响范围¶
| 项 | 内容 |
|---|---|
| 主机 / 组件 | 本机（192.168.31.250）；仅文档与本地脚本，不涉及代理服务、不重启任何服务 |
| 是否停服 | 否 |
| 窗口期 | 无（改脚本即时生效；技能正文改动对已开会话不回溯） |
| 在跑业务 | 无影响；不触碰 proxy.py / config.yaml / logs/ |
5. 分步操作¶
步骤 1：备份（高危前置）¶
改动前先备份两份被改文件，登记台账。备份位置遵循全局「备份与留档」规则，置于本主题 backup/，权限 600。
TS=$(date +%Y%m%d-%H%M%S)
D=handoff-capacity-20261002
mkdir -p "$D/backup/sessionstart-hook" "$D/backup/trae-cn/skills/writing-handoff"
cp sessionstart-hook/session-start-inject.py "$D/backup/sessionstart-hook/session-start-inject.py.bak.$TS"
cp ~/.trae-cn/skills/writing-handoff/SKILL.md "$D/backup/trae-cn/skills/writing-handoff/SKILL.md.bak.$TS"
chmod 600 "$D/backup/sessionstart-hook/"*.bak.* "$D/backup/trae-cn/skills/writing-handoff/"*.bak.*
预期：两份 .bak.<TS> 生成，sha256 与被改文件一致（已核：脚本 c57d009500837038、技能 4afa579bb41276e6）。
步骤 2：护栏解耦¶
把 MAX_INJECT_BYTES 由 12288 改为 16384，并把注释改为"只防失控、不参与日常容量约束"。
sed -i 's/^MAX_INJECT_BYTES = 12288$/MAX_INJECT_BYTES = 16384/' sessionstart-hook/session-start-inject.py
grep -n '^MAX_INJECT_BYTES' sessionstart-hook/session-start-inject.py # 预期 16384
坑：本脚本是 3 条全局 Hook 的活跃消费者之一；改动只影响"超长文件是否截断"，不改变正常注入内容。若误改逻辑，回第 7 章。
步骤 3：修正技能归因¶
编辑 ~/.trae-cn/skills/writing-handoff/SKILL.md 的「长度预算」节：把"防尾部静默截断 / 上限未定位"改为"截断源已定位为 hook 护栏、属自造兜底、已解耦为 16 KB；故 10 KB 硬限无外部依据"。只改归因表述，不动「目标 6 KB / 硬限 10 KB」数字（阈值机制属第 2 条，另行落地）。
grep -n '为什么有预算\|为防失控做的两条防御' ~/.trae-cn/skills/writing-handoff/SKILL.md
预期：命中两行新表述；全文再无"防截断"作为上限依据的措辞。
6. 验证¶
python3 -m py_compile sessionstart-hook/session-start-inject.py # 预期静默 rc=0
echo '{}' | python3 sessionstart-hook/session-start-inject.py > /tmp/ssi1.txt 2>/tmp/ssi1.err
echo '{}' | python3 sessionstart-hook/session-start-inject.py > /tmp/ssi2.txt
cmp /tmp/ssi1.txt /tmp/ssi2.txt # 幂等：无差异
grep -c 'HANDOFF 已截断' /tmp/ssi1.txt # 预期 0（未截断）
tail -n 1 sessionstart-hook/state/session-start.log # bytes=6783 truncated=no
实测结果（2026-10-02 23:31）：语法 OK、rc=0、两跑输出一致、无截断标记、stderr 为空、留痕 bytes=6783 truncated=no。k8s_ins 的 10171 B 亦低于 16384，truncated=no。
7. 回滚¶
- 备份位置：
handoff-capacity-20261002/backup/（明细见backup/README.md）； - 回滚步骤：把
backup/sessionstart-hook/session-start-inject.py.bak.<TS>覆盖回sessionstart-hook/session-start-inject.py；把backup/trae-cn/skills/writing-handoff/SKILL.md.bak.<TS>覆盖回~/.trae-cn/skills/writing-handoff/SKILL.md； - 回滚后验证：重跑第 6 章命令，确认
MAX_INJECT_BYTES回到 12288、“为什么有预算”节恢复旧文； - 回滚触发判据：注入输出异常（缺中文指令或守卫行）、rc≠0、
stderr非空 —— 任一即回滚。
8. 风险说明¶
| 风险 | 缓解 |
|---|---|
| 调高护栏后，某项目 HANDOFF 失控（如被灌成数十 KB）时不再被截断，每轮重放变大 | 护栏仅从 12 KB 提到 16 KB，非取消；且真正成本在重写而非注入（≈0.003 元/会话），16 KB 注入仍可忽略 |
| 技能正文改动被误认为已对旧会话生效 | 技能正文为按需加载，改动下一会话生效；已开会话不受影响，不回溯 |
| 只改了归因、未改阈值，出现"技能说 10 KB 无据、规则仍按 10 KB 判失败"的暂态不一致 | 属有意保留：阈值机制（双阈值滞回）是第 2 条，待落点（第 1 条）见效后一并改，避免一次动太多无法归因 |
9. 后续落地（第 1、2 条，2026-10-02 23:42）¶
9.1 第 1 条 · k8s_ins 归档落点【已完成】¶
由 k8s_ins 自己的会话执行（提示词见下面原附录 B 第 1 条）。本会话复核实测 wc -c docs/HANDOFF.md = 7974 B（原 10171 B，降 21.6%），已落到新滞回区（7~10 KB）内；落点建成后已结案内容可移交主题 SOP，不再回流。
9.2 第 2 条 · 双阈值滞回【已完成】¶
改 ~/.trae-cn/skills/writing-handoff/SKILL.md 四处（改前备份见第 9.4）：
| 位置 | 改动 |
|---|---|
| 「何时重写」表 | 删「文件 > 目标值（6 KB）→ 强制整体重写」；改为「文件 7~10 KB（滞回区）→ 定点 + 顺带压缩、不强制」与「距上次整体重写 ≥ 5 轮 或 > 10 KB → 强制整体重写」；表后补一段滞回理由 |
| 「长度预算」节 | 目标 6 KB、硬上限 10 KB → 目标 7 KB、强制重写线 10 KB，并把 7~10 KB 明示为滞回区 |
| 同节「为什么有预算」 | 10 KB 的定位由「硬上限」改述为「强制重写的触发线」；目标值 6→7 KB 标注为按内容需要设定，不再反推截断点 |
| PROJECT-MAP 对照表长度列 | 硬上限 10 KB → 目标 7 KB；> 10 KB 强制整体重写 |
为什么（判据）：单点 6 KB 阈值会让 7~10 KB 的文件每轮触发整体重写（每轮重抄未变内容）；滞回给出 7~10 KB 缓冲带，只有越过 10 KB 才整体重写。
9.3 验证¶
wc -c /home/rain/Documents/k8s_ins/docs/HANDOFF.md # 7974（落点见效）
grep -n '目标 7 KB\|滞回区\|强制重写的触发线' ~/.trae-cn/skills/writing-handoff/SKILL.md
grep -c '6 KB' ~/.trae-cn/skills/writing-handoff/SKILL.md # 1（仅滞回理由中的历史引用）
9.4 回滚¶
- 备份：
backup/trae-cn/skills/writing-handoff/SKILL.md.bak.20261002-234237（改前 sha256 前 16 位37970c1312317bde）； - 回滚步骤：覆盖回
~/.trae-cn/skills/writing-handoff/SKILL.md； - 回滚触发判据：技能「何时重写」表出现自相矛盾表述（如仍按 6 KB 判失败），或滞回区档位缺失。
9.5 风险说明¶
| 风险 | 缓解 |
|---|---|
| 滞回区放宽后文件在 7~10 KB 徘徊、缓慢膨胀 | > 10 KB 仍强制整体重写；7~10 KB 档要求「顺带压缩」，方向仍向下 |
| 技能正文改动被误认为对旧会话生效 | 技能正文按需加载，改动下一会话生效；不回溯 |
| 阈值软化被误读为「不再需要控制长度」 | 10 KB 仍是失败判据，≤ 7 KB 仍是健康目标 |
10. 判据再修：「≥5 轮」降级 + 落点自检机制（2026-10-02 23:53）¶
用户质疑两点，结论：
- 「≥5 轮 → 强制整体重写」是代理指标：轮数 ≠ 内容新鲜度（5 轮里若定点都干净，重写即白抄）。改为「≥5 轮 → 强制落点自检 + 通读」，是否整体重写由内容判（> 10 KB，或确有无法就地消除的过时表述）。
- 「已结案内容落掉」此前无保障：只有 skill 条款，无触发点、无验收方（与收尾自查 / 过账同款毛病，必然退化）。补法：
- skill
writing-handoff新增《落点自检》节（扫已结案|已完成|已交付|结案→ 逐条核对对应 SOP 可查 → 正文压成一行指针；查不到先补 SOP）+ 收尾清单加一条； - 全局规则
rule-agent-efficiency.md增「HANDOFF 落点自检」条件硬门禁：本会话改了任一docs/HANDOFF.md时，最终答复须报自检结论。
| 文件 | 改动 | 备份 |
|---|---|---|
~/.trae-cn/skills/writing-handoff/SKILL.md |
「何时重写」表拆「≥5 轮」（→自检）与「>10 KB」（→整体重写）两行；新增《落点自检》节；收尾清单加一条 | handoff-capacity-20261002/backup/trae-cn/skills/writing-handoff/SKILL.md.bak.20261002-235343 |
~/.trae-cn/user_rules/rule-agent-efficiency.md |
新增「HANDOFF 落点自检（条件硬门禁）」节 | ~/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.20261002-235406 |
生效条件：skill 正文改动下一会话生效；规则改动须开新会话（前缀重建，红线 8）。
顺带结案挂账 #26：其诉求（追加前先判走哪条）已由双阈值滞回 + 落点自检覆盖，挂账 18 → 17。
回滚：恢复上表两份备份文件即可。
附录 A：诊断结论（A 类讨论产出）¶
| 现象 | 机制归因 |
|---|---|
| "10 KB 却经常重写" | 触发阈值实为目标值 6 KB（技能「何时重写」表：> 目标值 → 强制整体重写），非 10 KB |
| token_proxy 6.8 KB vs k8s_ins 10.2 KB | 同一技能标准；token_proxy 是"10.8 KB 超限后强制瘦身"的产物，k8s_ins 未瘦到位；差异不在设定 |
| "清完还炸" | 归档落点缺失：k8s_ins 无根级 docs/SOP.md，39 个主题目录各带一份，已结案内容无法移交 → 持续回流 |
| 容量上限的依据 | 取证已证伪"防截断"：截断源是自造护栏；真实成本为重写输出 + 抖动步数，注入成本可忽略 |
附录 B：后续落地记录（第 1、2 条均已完成，见第 9 章）¶
- 第 1 条 · 补落点【已完成 2026-10-02】：k8s_ins 建可寻址归档入口，由该项目自己的会话执行（理由：压主题表需核验各主题 SOP 存档，且落点建成后要在该会话当场验证注入）。实测 10171 → 7974 B。原提示词：
【任务】重构 docs/HANDOFF.md 的归档落点，解决它长期贴 10.2 KB 硬限的问题。
背景（已诊断，勿重新分析）：
- HANDOFF 现 10171 B，贴 10240 硬限。超载源：第 2 节 3754 B（把已结案主题明细当现状写）、
3.1 里「组一 · 语义关联（已结案）」1958 B、第 4 节红线 1917 B（混入机制陷阱与踩坑记录）。
- 根因：本项目没有可寻址的归档落点（39 个主题目录各带一份 SOP.md，无根级索引），
已结案内容无法移交、持续回流。
【动作】
1. 加载 skill `writing-handoff`，按其规范执行。
2. 先备份 docs/HANDOFF.md → docs/backup/ 并登记 backup/README.md 台账。
3. 第 2 节：11 行「主题状态表」改为「主题 | 结论（一行） | SOP 路径」指针表——
已结案主题只留一行结论 + SOP 路径，明细（互跳四阶段、Kibana 面板数、19 台标签等）全部移交对应主题 SOP。
4. 删除 3.1 中「组一 · 语义关联（已结案）」整行（SOP 已有存档）。
5. 第 4 节红线中的机制性条目（`LS` 返回空、`sshpass -p`、`cmd | tail -3` 的 rc、
relabel 45~90s 延迟）移入 docs/BASELINE.md §3「机制性陷阱」；红线只保留「禁止/必须」类禁忌。
6. 压缩原则：先确认信息在对应 SOP 中确有存档，再删（技能要求「只做移交不做删除」）。
7. 第 5 节补一行主题 SOP 索引（或由第 3 步的指针表兼任）。
【验收】
- wc -c docs/HANDOFF.md ≤ 8000（暂以 8 KB 为目标）。
- 通读一遍无过时表述；所有移交内容在 SOP 中可查。
- 复跑一次零变更（幂等）。
【注意】某主题 SOP 缺失或找不到存档时，先补 SOP，不要直接删 HANDOFF 内容。不改项目代码。
- 第 2 条 · 双阈值滞回【已完成 2026-10-02】：技能「何时重写」表改为
<7 KB 定点 / 7~10 KB 定点+压缩不强制 / >10 KB 才强制整体重写；并把「目标 6 KB / 硬限 10 KB」按"内容需要"重定为「目标 7 KB / 强制重写线 10 KB」。落地明细见第 9.2。
附录 C：交付物清单¶
| 文件 | 说明 |
|---|---|
handoff-capacity-20261002/SOP.md |
本文件 |
handoff-capacity-20261002/backup/README.md |
备份台账 |
handoff-capacity-20261002/backup/.../*.bak.20261002-233019 |
两份备份（第 3 条，权限 600） |
handoff-capacity-20261002/backup/trae-cn/skills/writing-handoff/SKILL.md.bak.20261002-234237 |
第 2 条改前技能备份（权限 600） |
RUNBOOK 判定：本次变更未产生可复用交付物（仅改一处常量与一段文档），属无交付物留存的一次性动作，不出 RUNBOOK。
来源：
/home/rain/Documents/services/token_proxy/handoff-capacity-20261002/SOP.md｜ 最后更新：2026-10-02 23:54（由build/sync.py同步，请勿在站点侧修改）