workbuddy-context-handoff

WorkBuddy 上下文 handoff 门禁

Purpose

在 WorkBuddy 桌面端搭一条"上下文快满 -> 强制产出 handoff 文档 -> 新会话自动续接"的流水线。

• 触发端：Stop hook，按 transcript 里的 token 用量判断是否到阈值，到了就用 {"continue": false, "reason": "..."} 强制模型先写 handoff。
• 注入端：SessionStart hook，把本项目最新未被消费的 handoff 注入新会话上下文。
• 附带用途：解释/排查 WorkBuddy 的自动压缩阈值、hooks 事件与 transcript 用量计算。

When to Use

• 用户要"上下文到 N% 自动生成 handoff / 交接文档 / 新会话续接"。
• 用户问 WorkBuddy hooks 怎么配、为什么自动压缩了、上下文用量怎么算。
• 需要定位 WorkBuddy 桌面端的运行时行为（阈值、config option、hook 事件）。
• 触发词：上下文交接、handoff、上下文压缩、自动压缩、hooks 配置、新会话续接、 context handoff、auto compact。

When NOT to Use

• 用户只是想知道"我现在用了多少上下文" -> 直接按 transcript 算一次回答，不必配 hook。
• 目标运行时不是 WorkBuddy 桌面端（路径、事件名、环境变量都不同）-> 不适用，先确认运行时。
• 用户要的是一份手工交接文档 -> 直接写，不需要这套门禁。

Workflow

1. 确认位置与备份：定位 settings（用户级 ~/.workbuddy/settings.json 或项目级 <proj>/.workbuddy/settings.json），先备份，再读现有 hooks 键。
2. 写三个脚本到 ~/.workbuddy/hooks/：handoff-trigger.mjs（Stop）、 handoff-resume.mjs（SessionStart）、run-hook.sh。各文件职责与防死循环要求见 references/hook-implementation.md。
3. 注册 hooks（合并进 settings 的 hooks 键，不要整体覆盖）：

"hooks": {
  "Stop": [
    { "hooks": [ { "type": "command", "command": "<abs>/run-hook.sh <abs>/handoff-trigger.mjs", "timeout": 15 } ] }
  ],
  "SessionStart": [
    { "matcher": "startup|clear",
      "hooks": [ { "type": "command", "command": "<abs>/run-hook.sh <abs>/handoff-resume.mjs", "timeout": 15 } ] }
  ]
}

1. 校验 JSON：用 JSON.parse 解析整个 settings 文件，确认其余键未丢。
2. 实测触发：手动复现单个 hook —— echo '<payload json>' | /bin/bash -lc '<command>'， 再跑一轮真实会话确认 handoff 产出与注入都发生。
3. 清理测试产物：删掉 hooks/state/ 与 handoffs/ 下的测试文件。

Decision Rules

• 触发点只能选 Stop：它是唯一能强制模型继续的事件；注入点只能选 SessionStart：它的 stdout 或 hookSpecificOutput.additionalContext 是唯一能进新会话上下文的位置。PreCompact 不能当 handoff 触发器（stdout 只进压缩指令，exit 2 只给用户看消息）。
• 阈值调整优先级：先看是不是被内置 50% pre-message 压缩截断 —— 开桌面端 Max Mode， 或设 CODEBUDDY_PRE_MESSAGE_COMPACT_PCT=80；确认能到目标比例后，再调 handoff.config.json 里的 handoff 阈值。
• contextWindow 兜底顺序：handoff.config.json.contextWindow 留 null 时依次取 settings.autoCompactWindow -> CODEBUDDY_AUTO_COMPACT_WINDOW -> 200000。
• 需要确认事件名 / matcher 语义 / hook 入参 / 阈值常量 -> 读 references/runtime-facts.md。
• 要写或改 hook 脚本本身 -> 读 references/hook-implementation.md。
• hook 不触发 / 到不了阈值 / 搜不到字符串 -> 见 ## Troubleshooting。