| name | cc-delegate |
| description | WorkBuddy 通过 claude-code-mcp 委托本机 Claude Code 干活的「唯一标准入口」。 自包含封装：① MCP 打通配置与验证（~/.workbuddy/mcp.json 的 claude-code-mcp）； ② 委托前预检 workFolder 防家目录回退 bug；③ 委托后验落点； ④ 强制审计（读 CC 本地 transcript，汇报调了哪些技能/工具/文件）； ⑤ 实时过程监控（派一个监控看 CC 在干嘛/卡没卡/要不要杀，STUCK 可精准 kill 本次进程）； ⑥ 状态交接 HANDOFF（每次派活 CC 写交接文档：单次标 STATUS:DONE、多步标 IN_PROGRESS+下一步，并记录上次对话 transcript 路径兜底；多步接力自动读交接+上次原始对话）； ⑦ **v1.6.0 状态化委托模式**：WB 用 Bash 工具直调本机 `claude` CLI + `--resume <sid>`，让 CC 原生记住跨调用对话上下文（绕开 MCP 参数白名单裁剪，实测可用）；HANDOFF 作为抗重启/抗 session 丢失的兜底，二者混合。 ⑧ **v1.7.0 会话登记本**：集中登记 `<项目名>→<sid, workFolder, 进度, marker>` 到 `~/.workbuddy/skills/cc-delegate/sessions.json`，**跨天 / 家外远程接入时自动查到"继续某项目"该 resume 哪个 sid**，无需用户重报 SID（状态化模式的「记忆索引」）。 调用此技能即代表「要指挥 CC 去干活」，自动走全套流程，无需用户重复嘱咐。
触发词：调 claude code / 委派 CC / 让 CC 干活 / 用 CC 干活 / mcp 调 claude / claude_code / 跨仓库指挥 CC / 让云代码干活 / 派 CC 去 / 调用这个技能（上下文含 CC）/ 监控 CC / 看 CC 在干嘛 / CC 卡死了 / 杀掉 CC 进程 / 精准终止 claude / 状态化委托 / --resume / 让 CC 记住上下文 / 会话登记本 / 继续项目 / 接着干 / 隔天续干。
|
| triggers | ["调 claude code","委派 CC","让 CC 干活","用 CC 干活","mcp 调 claude","claude_code","跨仓库指挥 CC","派 CC 去","让云代码干活","状态化委托","会话登记本","继续项目","接着干"] |
| metadata | {"agent_created":true,"version":"1.12.1","updated":"2026-07-13"} |
cc-delegate —— WorkBuddy → Claude Code 指挥手册（自包含·可迭代）
定位：本技能是「让 Claude Code 干活」的唯一标准入口。调用它，就代表要指挥 CC 去某仓库执行任务。
技能内部自动完成：MCP 验收 → 目录预检 → 委托 → 落点后验 → 过程审计 → 汇报。
用户不必每次重复说明配置细节；所有规则、配置、踩坑、迭代记录都固化在本文件内。
速查卡（先读这个）
| 项 | 值 |
|---|
| MCP server 名 | claude-code-mcp（包 @steipete/claude-code-mcp@latest，现 friendship-ai/claude-code-mcp） |
| 配置文件 | $HOME\.workbuddy\mcp.json（无点前缀，官方用户级路径） |
| 工具名（调用时） | mcp__claude-code-mcp__claude_code |
| 工具真实参数 | 仅 prompt + workFolder（实测：传 sessionId/permissionMode 会校验失败） |
| 防 bug 口诀 | 调前查目录，调后验落点；目录不存在 → 先问用户再 mkdir -p |
| 审计位置 | $HOME\.claude\projects\<编码workFolder>\<session>.jsonl |
| 实时监控 | python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "<workFolder>"（看 CC 在干嘛/卡没卡/DONE；交接文档在子目录时加 --handoff-dir "<子目录>"，懒人用 --recursive；完整参数见 references/monitor-reference.md） |
| 精准 kill | 派活 prompt 嵌入唯一 marker，监控 --marker <同标识> --kill 只杀本次 CC 进程 |
| 状态化模式(1.6.0) | WB 用 Bash 工具直调本机 claude CLI（非 MCP）：claude --dangerously-skip-permissions -p "<prompt>"（首步，自动持久化）；后续步加 --resume <sid> 接上下文。绕开 MCP 参数白名单，CC 原生记忆跨调用对话 |
| SID 提取(1.6.0) | 首步后：python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "<workFolder>" --marker "<同标识>" --print-sid → 输出 session ID（= transcript 文件名）；传给下一步 --resume |
| 状态化监控(1.6.0) | python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "<workFolder>" --session "<sid>"（已知 SID 直接锁定 transcript，最精确，并发也不怕） |
| 会话登记本(1.12.0) | 跨天/远程续干「记忆索引」：register 登记，lookup 取 sid/workFolder/marker，claim --owner <窗口ID> 成功后才允许 resume，结束后 release，收工 close。写操作原子锁超时即中止，绝不无锁覆盖；读操作不重写文件。数据存 ~/.workbuddy/skills/cc-delegate/sessions.json。 |
| 状态交接 | HANDOFF.md + result.json（交接目录 = WB 每次派活显式声明，CC 不得自定位置，skill 不绑定任务类型）：单次标 STATUS:DONE、多步标 IN_PROGRESS+下一步；并记录 LAST_TRANSCRIPT（上次对话原始 jsonl 路径）兜底 |
| PowerShell prompt | cc_delegate.py assemble ... --output-file "<prompt.txt>" 只输出单行文件路径；再用 Get-Content -Raw 取得单个字符串传给 claude -p |
| verification 对账 | cc_delegate.py parse/decide ... --transcript "<session.jsonl>"；自报命令与真实 Bash 不一致时 MISMATCH → ESCALATE，monitor 返回退出码 4 |
| 禁忌 | 不裸调工具；不手改第三方 server 源码；不把文件建到未授权目录 |
| 超时≠失败 | 报 -32001 Request timed out 时，CC 往往后台已跑完；先查 workFolder 产物 + transcript 再下结论。但⚠️「超时≠失败」非绝对——若 Write 尚未发出就被掐断（transcript 停在 Read/Bash 没 Write），产物可能真没生成（M5 实证），必须核对 transcript 末次 Write 是否命中目标文件（监控已内置该判据） |
第零章：MCP 打通（自包含配置与验证）
目的：让本技能在任何新环境/重装后都能复现「WorkBuddy 能调 CC」。配置写进技能，改 MCP 时以这里为准。
0.1 配置内容（写入 ~/.workbuddy/mcp.json 的 mcpServers）
"claude-code-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@steipete/claude-code-mcp@latest"],
"runtime": {"type": "node", "version": ">=20"},
"timeout": 600000,
"disabled": false
}
- 保留原文件其他 server（如
connector-proxy），只增不删。
- 备份习惯：
cp ~/.workbuddy/mcp.json ~/.workbuddy/mcp.json.bak.<日期>。
- ⚠️ workBuddy 读的是无点
mcp.json，不是带点 .mcp.json（那是 Claude Code/Cursor 格式，WorkBuddy 不读） —— 这是本技能最早踩的大坑，改配置务必认准路径。
0.2 启用步骤
- 写入上面配置 → 保存（JSON 须合法，可用
python -m json.tool 校验）。
- 重启 WorkBuddy（MCP 工具在会话启动时固化，当前会话看不到新 server）。
- 开新会话 → 设置里可能弹窗批准该 server（首次需确认）。
- 验证见 0.3。
0.3 验证 MCP 已通（每次怀疑挂了就跑这个）
然后做一次最小实测：委托 CC 在某已存在目录写个文件，看返回值与产物落点。
0.4 故障排查（实测踩过的坑）
| 现象 | 原因 | 解法 |
|---|
| 连接器面板看不到这个 MCP | 自定义 stdio server 不显示在连接器面板（只列 connector: 远程连接器） | 正常，验证标准是 ToolSearch 能搜到工具，不是面板 |
| 工具搜不到 | 没重启 / 没开新会话 / 没批准 | 重启 + 新会话 + 批准 |
| 调用报「启动失败/超时」 | WorkBuddy 沙箱拦 npx 联网拉包 | 本地 npm i -g @steipete/claude-code-mcp，把 command 改指向本地 node_modules/.bin（绕过 npx） |
| 文件悄悄建到家目录 | workFolder 目录不存在 → CC 静默回退 | 见第一章 PRE-FLIGHT 防 bug 流程 |
| 报「must NOT have additional properties」 | 传了 sessionId/permissionMode 等额外参数 | 只传 prompt+workFolder（见速查卡） |
启动警告 ~/.claude/local/claude not found | server 首选路径不存在，自动 fallback 到 PATH 的 claude | 无害，实测 PATH 上有 claude 可正常调 |
0.5 快速上手 + 配合 MCP 的架构规划（先看这段再干活）
这个技能解决什么：WorkBuddy（你，总指挥）要远程/异步指挥家里那台电脑上的 Claude Code（worker）干长任务，而且要让它有跨调用记忆、可监控、可续干、不丢状态。MCP（claude-code-mcp）是打通「WB 能调 CC」的桥，本技能是「怎么调才稳」的方法论 + 工具箱。
两条委托通道（配合 MCP 怎么选）
| 通道 | 怎么调 | 会话连续性 | 适用 |
|---|
① MCP claude_code（无状态） | 经 MCP 工具派活，WB 连接器只透传 prompt+workFolder | ❌ 无（每次全新进程） | 单次、独立、不怕重启的任务；默认通道 |
② Bash 直调 claude CLI + --resume（状态化） | WB 用 Bash 工具直调本机 claude，绕过 MCP 参数裁剪 | ✅ 原生（CC 记得前文） | 多步、需跨调用上下文、长任务接力 |
关键认知：MCP 通道的 worker CC 与你在终端打开的交互式 CC 能力完全对等（Skill / Subagent / Hook / MCP 全可用，1.7.2 已活体验证）。差别只在「有没有会话连续性」与「WB 能不能传更多参数」。
标准架构（推荐落地姿势）
- 默认走 MCP 无状态派活（通道①）：简单、可重试、WB 崩溃不影响 CC 后台跑；每步让 CC 写
HANDOFF.md + result.json 做状态交接（文件接力兜底）。
- 多步/长任务切 Bash 状态化通道②：首步
claude -p "<marker>\n<prompt>" 起手 → cc_monitor --print-sid 提 SID → 后续步 --resume <sid> 接力；marker 贯穿全程用于监控/精准 kill。
- 跨天/远程续干用「会话登记本」：首步提完 SID 立刻
session_registry register，之后任何 WB 窗口/家外手机说「继续 <项目>」→ lookup 取 sid+workFolder+marker → --resume 接力，像坐在电脑前。
- 三层保险：登记本索引 /
--resume 真连续性 / HANDOFF.md 兜底（抗 WB 重启、抗 SID 丢失）。
- 监控与审计随行：派活后
cc_monitor --workfolder 看实时三态（RUNNING/DONE/STUCK）→ 卡死用 marker 精准 kill；干完查 ~/.claude/projects/.../<session>.jsonl transcript 做 AUDIT。
最小上手路径
# 0) 打通 MCP（一次性）：~/.workbuddy/mcp.json 加 claude-code-mcp server → 重启 WB → 新会话批准
# 1) 无状态派活（最常用）：直接经 MCP 工具 mcp__claude-code-mcp__claude_code 派 prompt，workFolder 指向已存在目录
# 2) 想看进度/卡没卡：另开 shell
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "<workFolder>"
# 3) 多步需记忆：切 Bash 状态化（第一章 P0 节）
# 4) 隔天续干：session_registry lookup --project <项目> 取 sid → claude ... --resume <sid>
详细分步、决策树、参数表见各章；速查卡见上方表格。脚本调用统一用绝对路径（见各代码块 ⚠️ 提示）。
第一章：标准委托流程（每次必走）
步骤 0：解析意图
workFolder：目标仓库/目录（必填）。用户没给 → 先问清，不瞎猜。task_prompt：让 CC 具体干什么。- 意图若涉及「持续多轮同仓库」→ 用同一
workFolder + 走「模式二·多步」（见状态交接章节）。注意 CC 本身无会话连续性（每次调用是全新无状态会话，详见第三章与状态交接章节），多步靠 HANDOFF.md 接力，不能指望它记起上次聊天。
步骤 1：PRE-FLIGHT 预检目录（强制·防 bug 核心）
test -d "<workFolder>" && echo EXISTS || echo MISSING
- EXISTS → 步骤 2。
- MISSING → 严格执行（用户明确要求）：
- 告诉用户：「⚠️ 目标目录
<workFolder> 不存在，CC 直接调会静默把文件建到家目录（bug）。」
- 问：「要我
mkdir -p 新建吗？还是你换路径？」
- 用户确认前，绝不允许调
claude_code。
- 确认后
mkdir -p "<workFolder>"，进入步骤 2。
- （若用户已授权「可自动建目录」，可跳过询问直接建，但回复须说明「目录已新建」。）
步骤 2：调用 claude_code（只传两个字段）
{
"prompt": "<task_prompt>。\n请在当前工作目录内完成，不要改动其他目录。交接目录固定为 <HANDOFF_DIR>，不得另放。完成后：\n1) 把结果写入 <HANDOFF_DIR>/result.json（严格 JSON：{\"status\":\"DONE|IN_PROGRESS|BLOCKED|NEEDS_USER_INPUT|ERROR\",\"summary\":\"...\",\"artifacts\":[\"相对路径\"],\"issues\":[],\"next_suggestions\":[]}）；\n2) 同时写 <HANDOFF_DIR>/HANDOFF.md（模板见「状态交接协议」章节）：填目标/进度/产出文件/下一步，STATUS 按本次填 DONE 或 IN_PROGRESS。\n（若是多步接力，我已在 prompt 开头附了「先读 HANDOFF.md 接进度」，你照做即可。）",
"workFolder": "<已确认存在的 workFolder>"
}
- 只传
prompt + workFolder，任何额外 key 都会校验失败。
- prompt 内明令「在当前目录完成，不动其他目录」，二次防回退。
- 无论一次还是多次，都要求 CC 把完整、清晰的信息写进 HANDOFF.md（用户明确要求：一次完成也要写，便于以后追问/改时 CC 有背景）——这是状态交接的核心。
步骤 3：POST-FLIGHT 后验落点（强制）
ls -la "<workFolder>/<artifact>" 2>&1
ls -la "$HOME/<artifact>" 2>&1 || echo "家目录无残留 OK"
- 产物在
workFolder → 通过。
- 落在家目录 → 判定 bug：删家目录误落文件 → 报告用户 → 回步骤 1 重跑（目录已存在，应落对）。
步骤 4：AUDIT 审计（核心能力，见第二章）
委托完成后必须读 transcript 提取行动摘要并向用户汇报。
步骤 5：汇报
向用户简洁汇报：做了啥、产物在哪、CC 的 status、审计摘要（调了哪些技能/工具）、下一步建议。
状态化委托模式（Bash 直调 + --resume · 1.6.0 核心新增）
解决什么：v1.4/1.5 的 HANDOFF 接力靠"文件传上下文"，CC 不真正记得对话。
P0 实测结论（见 test_lab/P0_SESSIONID_VERIFICATION.md）：经 MCP claude_code 传 sessionId 被 WorkBuddy 参数白名单裁剪（additionalProperties:false，只透传 prompt+workFolder）；但 WB 的 Bash 工具能直调本机 claude CLI（2.1.204，原生支持 --resume），从而让 CC 跨调用原生记住对话上下文。
本模式 = "用 Bash 调 claude --resume"，绕开 MCP 裁剪，拿到真·会话连续性。
何时用（模式选择决策）
| 场景 | 用哪种 |
|---|
| 同一任务流要多步接力且需 CC 记住前文（如"先设计数据层，再基于它设计接口层"） | ✅ 状态化模式（Bash + --resume） |
| 单步一次性任务 | 两种都行；想简单用 MCP 也行，想统一用状态化也行 |
WB 环境被限、Bash 调 claude 不通 | 退回 HANDOFF 无状态模式（MCP，v1.5 既有） |
| 跨仓库不同任务 | 各自独立 workFolder，互不干扰 |
默认推荐：多步同仓库接力 → 状态化模式；其余 → 现有 MCP 无状态模式。二者产物/HANDOFF/监控完全兼容。
Driver 算法（WB 即 driver）
- 生成 per-task marker（同任务所有步一致，用于精准 kill + 监控锁定）：
TID=cc_v16_<任务id>_<随机>，嵌入每步 prompt。
- 首步（无状态起手）：Bash 直调
claude，让 CC 自动持久化会话：
cd "<workFolder>" && claude --dangerously-skip-permissions -p "<marker>\n<prompt>。在当前目录完成，不动其他目录。交接目录固定为 <HANDOFF_DIR>；完成后把 HANDOFF.md（STATUS 按本次填 DONE/IN_PROGRESS）与 result.json（{\"status\":\"DONE|IN_PROGRESS|BLOCKED|NEEDS_USER_INPUT|ERROR\",\"summary\":\"...\",\"artifacts\":[...],\"issues\":[],\"next_suggestions\":[]}）都写入该目录，不得另放。"
- 提取 SID（首步后立刻做，driver 负责，CC 不用管）：
SID=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" \
--workfolder "<workFolder>" --marker "TID=cc_v16_<任务id>_<随机>" --print-sid)
内部：find_transcript() 按 marker 锁定本次 jsonl，--print-sid 打印其 basename 去 .jsonl。
⚠️ 脚本调用用 $HOME 占位路径（跨机器自动适配家目录；在 WB Bash 里用 $HOME 而非 ~ 波浪号，后者会被解析到错误盘符导致脚本找不到）。首次使用可定义 SK="$HOME/.workbuddy/skills/cc-delegate/scripts" 变量，下文所有 python "...cc_monitor.py" 等改为 python "$SK/cc_monitor.py" 即可。
3.5. 登记到会话登记本（v1.7.0 关键）：把 <项目名>→<sid, workFolder, marker> 写进 sessions.json，供隔天 / 家外远程续干自动查到（详见「会话登记本」章节）：
python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" register \
--project <项目名> --sid "$SID" --workfolder "<workFolder>" \
--desc "<任务说明>" --marker "TID=cc_v17_<任务id>_<随机>"
- 后续步（resume 接上下文）：在首步 SID 基础上接力，CC 原生记得前文：
cd "<workFolder>" && claude --dangerously-skip-permissions -p "<marker>\n<本步新指令>。接上之前对话继续，不要重做已完成的。" --resume "$SID"
- 每步都沿用同一
SID + 同一 marker → 全程同一 transcript、同一 CC 会话。
- HANDOFF 仍写（兜底）：每步照旧让 CC 写 HANDOFF.md；状态化模式下它作为抗 WB 重启 / 抗 SID 丢失的备份——若某天
--resume 因 session 文件没了而失败，退回"读 HANDOFF.md 接进度"的无状态接力即可。
监控 / kill（与无状态模式共用 cc_monitor）
- 最精确：已知 SID 后，
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "<workFolder>" --session "$SID" 直接锁定该 transcript（并发同目录也不怕）。
- 按 marker：
--marker "TID=cc_v16_..." 同样能锁定（首步 prompt 已把 marker 写进 transcript 首段）。
- 精准 kill：
--marker "TID=cc_v16_..." --kill 仍只杀本次 claude.exe（Bash 直调的进程命令行里也含该 marker）。
与 MCP 无状态模式的关键区别
| 维度 | 无状态（MCP claude_code） | 状态化（Bash + --resume） |
|---|
| 会话连续性 | ❌ 无（每次全新进程） | ✅ 原生（CC 记得前文） |
| 多步上下文传递 | HANDOFF.md 文件接力 | CC 对话记忆 + HANDOFF 兜底 |
| 参数限制 | 受 WB 白名单裁剪（仅 prompt+workFolder） | 绕开裁剪，能用 CLI 全部参数 |
| 调用通道 | MCP 工具 | WB Bash 工具 |
| 超时 | 受 -32001 调用层上限 | Bash 工具独立超时（更长，但长任务仍建议拆小步） |
注意事项
claude CLI 须在本机 PATH（P0 实测 claude --version = 2.1.204，可用）；若 Bash 调不通，退回 MCP 无状态模式并报告用户。- 首步必须先提取 SID 再进后续步；若
--print-sid 返回 NONE，说明 transcript 没生成 → 查首步 Bash 是否报错，不要盲目 --resume。
- session 持久化依赖
~/.claude/projects/，别删这个目录；若 SID 丢失，用 HANDOFF 兜底接力。
调用封装模板（cc_delegate.py · 1.9.0 新增）
把「拼 prompt + 解析 result.json + 决定下一步」三件事做成可复用、可单测的模块，WB（driver）派活前后调用，避免散落各处的字符串拼接与易错手写判据。脚本位置：$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py（随技能自包含，换机器改前缀即可）。
① assemble — 拼最终 prompt
PY="$HOME/.workbuddy/binaries/python/versions/3.13.12/python.exe"
PROMPT=$( "$PY" "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" assemble \
--base "<你的任务 prompt>" --workfolder "<workFolder>" \
--handoff-dir "<HANDOFF_DIR>" --marker "TID=cc_v19_<id>_<rand>" )
规则：若 <HANDOFF_DIR>/HANDOFF.md 存在且 STATUS 非 DONE → 自动在 prompt 开头注入接干 preamble；同时把「result.json + HANDOFF.md 必须写入 HANDOFF_DIR」契约和 marker 拼入 prompt。workFolder 与 HANDOFF_DIR 必须预先存在。
PowerShell 不要把多行 stdout 变量直接传给 claude -p（会被拆成参数数组）。使用 --output-file：
$promptFile = python -X utf8 "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" assemble `
--base "<任务 prompt>" --workfolder "<workFolder>" --handoff-dir "<HANDOFF_DIR>" `
--marker "<marker>" --output-file "$env:TEMP\cc-delegate-prompt.txt"
$prompt = Get-Content -Raw -LiteralPath $promptFile
claude --dangerously-skip-permissions -p $prompt
② parse — 解析 result.json 回执
"$PY" "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" parse \
--workfolder "<workFolder>" --handoff-dir "<HANDOFF_DIR>" \
--transcript "<本次 transcript.jsonl>"
归一化字段：status 大小写/别名都认（如 completed→DONE、needs_user_input→NEEDS_USER_INPUT）；无回执→NO_RECEIPT、坏文件→BAD_RECEIPT。
③ decide — 决策下一步
ACTION=$( "$PY" "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" decide \
--workfolder "<workFolder>" --handoff-dir "<HANDOFF_DIR>" \
--transcript "<本次 transcript.jsonl>" \
--retry <已重试次数> )
decide 也兼容直接传 --status。若提供 --workfolder，它先读取声明交接目录中的状态；提供 transcript 时，还会把 result.json.verification.command 与 transcript 中真实 Bash 命令精确对账。MISMATCH / NO_TRANSCRIPT / REPORTED_FAILURE 一律返回 ESCALATE，之后才应用 BRIEFING.md 和内置阈值。
动作含义见「回传决策阈值」章节。driver 拿到 ACTION 后：
CONTINUE → 下一段 prompt 走 assemble（自动注入接干 preamble）RETRY → 重新派活（同通道再发一次，可带澄清）；仅 BLOCKED 用，且只 1 次POLL → 绝不重新派活！只重跑 cc_monitor --show / 看 transcript 确认 CC 是不是自己跑完了（防 -32001 误判失败 + 避免重复 spawn 浪费/污染）；确认真挂才升级ESCALATE → 立刻升级用户、绝不替用户拍板（NEEDS_USER_INPUT / BAD_RECEIPT / 重试耗尽）CONSUME → 任务完成，按需进入后续排期步
回传决策阈值（1.9.0 固化）
CC 每步写 result.json（schema 见第一章 Driver 算法第 2 步）。driver 用 cc_delegate.py decide 把 status 映射到动作。核心原则：模糊的、需要人做业务判断的，一律升级用户，绝不替用户猜。
| status | 含义 | 自动处理 | 重试上限 | 升级用户 |
|---|
DONE | 任务完成 | ✅ 消费结果 | 0 | 否 |
IN_PROGRESS | 部分完成、需续干 | ✅ 自动 CONTINUE（assemble 注入接干 preamble） | 0 | 否 |
BLOCKED | 硬阻塞（缺依赖/工具失败/鉴权） | 先 RETRY 1 次（带澄清 prompt） | 1 | 第 2 次仍 BLOCKED → 升级 |
NEEDS_USER_INPUT | 需人做业务决策（歧义/取舍） | ❌ 不猜测 | 0 | 立即升级 |
ERROR | CC 崩溃/异常 | POLL_RETRY（轮询 transcript 确认是否真挂） | 3 | 3 次仍失败 → 升级 |
TIMEOUT | 调 -32001 超时（回执没回） | POLL_RETRY（跑 cc_monitor --show 看是否自己跑完） | 3 | 3 次仍无回执 → 升级 |
NO_RECEIPT | 没写 result.json | POLL_RETRY（同上） | 3 | 3 次仍无 → 升级 |
BAD_RECEIPT | result.json 损坏 | ❌ | 0 | 立即升级 |
UNKNOWN | 未知 status | POLL_RETRY | 3 | 3 次仍 → 升级 |
边界约定：
NEEDS_USER_INPUT 与 BAD_RECEIPT 是「绝不自动处理」档——任何需要人判断或数据不可信的情况，直接抛给用户。BLOCKED 只自动重试 1 次：硬阻塞往往不是重试能解，再卡就让人看。ERROR/TIMEOUT/NO_RECEIPT 走「轮询重试」而非立即升级：先靠 cc_monitor 确认 CC 是不是自己跑完了（踩过「-32001 误判失败、其实产物已写完」的坑），确认真挂才升级。
会话登记本（跨天 / 远程续干 · 1.7.0 核心新增）
解决什么：v1.6 状态化模式让 CC 用 --resume <sid> 记住跨调用对话，但 sid 散落在各 workFolder 的 .sid 文件里。
你三天后在家外用手机说"继续 Alpha 项目"，WB 根本不知道该 resume 哪个 sid → 又得你手动报 SID。
本登记本 = 状态化模式的「记忆索引」：把 <项目名> → <sid, workFolder, 进度, marker> 集中存进用户级技能目录的 sessions.json。
任何新 WB 会话（含家外远程）都能查到续干入口，像坐在电脑前一样接着干。
存哪（随技能迁移，用户级持久）
~/.workbuddy/skills/cc-delegate/sessions.json
与 SKILL.md 同技能目录 → 账号迁移不破；WB 重启 / 新会话自动可读。
命令一览（driver 自动调用，无需用户手敲）
| 命令 | 作用 |
|---|
register --project <名> --sid <sid> --workfolder "<路径>" --desc "<说明>" --marker "<TID>" [--force] | 登记 / 更新一个项目会话（状态化首步提取 sid 后自动调）；同名不同 workFolder 冲突时默认拒绝，加 --force 强制覆盖 |
lookup --project <名> | 默认打印 sid（干净单行，供 $() 捕获）；找不到打印 NONE |
lookup --project <名> --field workFolder|marker|status|desc | 取指定字段 |
lookup --project <名> --json | 打印完整条目 |
list | 列出所有项目（active 在前） |
claim --project <名> --owner <窗口ID> [--ttl 900] | resume 前取得限时项目租约；其他窗口持有未过期租约时返回 LEASED |
release --project <名> --owner <窗口ID> | 本轮完成/停止后释放租约 |
touch --project <名> | 更新 last_active |
set-sid --project <名> --sid <sid> | 更新 sid（如 resume 后 CC 新开会话） |
close --project <名> | 标记 done（保留 sid 供查 transcript 归档） |
reopen --project <名> | 重新激活 done 项目 |
show --project <名> | 打印完整条目 |
Driver 算法补强（状态化模式续干闭环）
- 首步后登记：v1.6 的「提取 SID」之后，driver 立刻
register：
SID=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" \
--workfolder "<workFolder>" --marker "TID=cc_v17_<id>_<rand>" --print-sid)
python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" register \
--project <项目名> --sid "$SID" --workfolder "<workFolder>" \
--desc "<任务说明>" --marker "TID=cc_v17_<id>_<rand>"
- 隔天 / 远程续干（用户说"继续 <项目> / 接着干 <项目>"）：
SID=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" lookup --project <项目名>)
WF=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" lookup --project <项目名> --field workFolder)
MK=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" lookup --project <项目名> --field marker)
拿到后先生成当前窗口唯一 OWNER，执行 claim --project <项目名> --owner "$OWNER"；只有返回 CLAIMED 才允许 claude ... --resume "$SID"。返回 LEASED 表示另一窗口正在驱动，禁止并发 resume。
- 每步续干后
touch 更新 last_active，随后 release --project <项目名> --owner "$OWNER" 释放租约。
- 项目收工
close：归档但保留 sid，并自动清除租约。
与 HANDOFF 的关系（三层保险）
| 层 | 角色 | 跨天/远程可用？ |
|---|
① 会话登记本 sessions.json | 记忆索引：指向该项目的 sid + workFolder | ✅ 任何新 WB 会话自动可读 |
② CC --resume <sid> | 真·对话连续性（CC 原生记忆） | ✅ 只要 ~/.claude/projects/ 未删 |
| ③ HANDOFF.md | 抗 SID 丢失 / session 文件损坏的兜底（文件接力学） | ✅ 磁盘持久 |
正常链路：① 查到 sid → ② resume 接着干。万一 sid 失效（session 文件没了），退回 ③ 读 HANDOFF.md 接力——永远断不了线索。
注意事项
- 项目名要稳定且唯一：
register 与 lookup 用同一个 --project 键（建议短 slug，如 alpha / video-x）。driver 也可从 workFolder 末段自动派生，但显式命名更利于远程识别；多窗口/多助手并发 publish 时务必保证项目名全局唯一——同名不同 workFolder 会被 register 拦截（CONFLICT），需换名或 --force，否则会续错项目（v1.7.1 加固）。
- 登记本只存索引，不存对话内容；对话在
~/.claude/projects/ 的 transcript 里。
- 多条活跃项目并存没问题（
list 一目了然）；互不干扰，各自 resume 各自 sid。
- 多 WorkBuddy 窗口/多助手共享同一登记本：写操作使用原子锁和临时文件替换；取锁超时会中止，绝不降级无锁写。读取命令不再重写登记本。同一项目由
claim/release 租约强制单窗口驱动，避免同一 sid 被两个 CC 进程同时 resume。
第二章：审计能力（查证 CC 干了啥、调了哪些技能）
为什么需要：claude_code 工具的返回值只是 CC 最后一段总结文本，不含内部 tool_use 明细。
想查「CC 有没有调技能、做了什么事、过程记录有没有」——必须读 CC 本地 transcript。
2.1 transcript 位置
$HOME\.claude\projects\<编码后的workFolder>\<session>.jsonl
- 目录编码：
/ 与特殊字符编码为连字符，可读子串保留（如 orchestrator-guard-demo）。
- ⚠️ 下划线也会变成连字符（如
demo_handoff → 目录 demo-handoff）。手动 find 时用连字符形态；脚本 find_transcript() 已自动兼容 {原名} 与 {下划线转连字符} 两种 glob。
- 逐行 JSON，记录每次
tool_use（含 Skill 技能调用 / Write / Bash / Read / ToolSearch）与 tool_result。
Skill 调用作为一条 tool_use 被完整记录 → 可审计「CC 调了哪个技能」。
2.2 定位本次 transcript 并提取审计摘要
完整解析脚本见 references/audit-parsing.md（含 transcript 编码规则、定位命令、Python 审计提取器）。核心动作：
- 按 workFolder 末段模糊匹配，取最新
.jsonl（并发同目录时务必带 marker 锁定，见 references/monitor-reference.md 的 P7 限制）。
- 用 Python 逐行读 jsonl，汇总
Skill/Write/Read/Bash 工具集合 → 回答用户「CC 调了哪些技能、做了哪些事」。
超时与重试（重要实战坑 · 1.2.0 新增）
实测结论：WorkBuddy 这层对单次 claude_code MCP 调用有固定超时上限（远短于 server 侧 600000ms）。
重任务（列技能+调多个Skill+改写+写多文件）会触发 -32001 Request timed out，
但 CC 进程往往已在后台跑完并写了产物——超时只是「回执没传回来」，不是「活没干」。
触发表现
Error: MCP error -32001: Request timed out
正确处置流程（不要直接当失败）
- 不要立刻重跑（重跑会重复劳动、可能产生重复文件）。
- 去
workFolder 查产物是否已生成。
- 去 transcript（第二章 2.1/2.2）确认 CC 实际做了哪些 tool_use：
- 若 transcript 末尾已有
Write 写入目标文件 + result.json → 任务已完成，只是回执超时。
- 若 transcript 停在
ToolSearch/Bash/Read 还没 Write → 确实被打断（见下 P3 风险）。
- 已完成 → 直接读产物 + 走 AUDIT 汇报，告知用户「调用超时但 CC 已后台完成」。
- 确实中断 → 拆小步重试（见下），避免单次任务过重。
6. 派单后「轮询直到完成」（判断 CC 是否还在跑）
把上面第2-4步的「查一次」升级成「轮询循环」，彻底实现"还在跑就继续等"：
- 触发：调用返回 -32001，或你想主动不等回执直接确认。
- 循环（最多 N=20 次，间隔 15s）：
- 查 workFolder 产物是否出现 → 出现即「完成」，读产物走 AUDIT 汇报。
- 否则读本项目最新 transcript 的 mtime：
- mtime 在最近 60s 内且在增长 → 「仍在运行」，continue 下一轮。
- mtime 超过 120s 无变化且无产物 → 「疑似卡死/真中断」，跳出循环，按下面「确实中断」处理（拆小步重试）。
- 关键认知：-32001 只是 WorkBuddy 这层掐断了回执连接，CC 进程本身独立继续跑，不会因超时停止。所以"让它继续运行"天然成立——我们要做的只是别重跑、耐心轮询等它写完。
- 此循环已替代"手动 sleep 等"，固化进本技能后，超时任务可一键自动等到完成。
- 现成监控脚本：
~/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py 可直接当"进程监控器"——派完活后另开 shell 跑 python 该脚本 --workfolder "<workFolder>"，实时打印 RUNNING（含最近动作）/ DONE（读 result.json 回执）/ STUCK。报 -32001 后立刻跑它，就能看着 CC 自己跑完。
- 关于"直接监控 OS 进程"：claude 是
claude.exe，Get-Process claude 能看到；但本机实测常驻多个好几天前的遗留 claude.exe 进程，光看进程名分不清哪个是本次调用，无法精确定位。故以 transcript 文件监控为准（1:1 对应本次会话、实时增长），OS 进程数仅作参考（脚本也顺带打印）。
规避：把重任务拆小步（P3 硬规则）
P3 风险（M5 实证）：「超时≠失败」非绝对。若 -32001 在 CC 发出末次 Write 之前掐断，产物会真没生成（transcript 停在 Read、无 Write）。监控脚本已内置判据：完成信号除「文件存在」外，还要求「本次 transcript 末次 Write 命中目标产物或文件 mtime 晚于监控启动」，杜绝读到历史残留误判完成。
- ❌ 反例（易超时/易静默失败）：一次 prompt 让 CC「列技能 + 调多个 Skill + 改写 + 写 v2 + 写 result.json」。
- ✅ 正例（稳健）：
- 步1（轻）：只让 CC 列技能写
skills_inventory.json（已验证可成）。
- 步2（轻）：我读清单，挑 1~2 个最相关技能，让 CC 单独调它优化写
v2。
- 步3（轻）：让 CC 写
result.json 回执（或并入步2）。
- 硬规则（v1.5.0 固化）：单 prompt 控制在「1 个 Skill 调用 + 1 读 + 1 写」以内最稳；大任务必拆多步 HANDOFF 接力，绝不一口气塞满。
进阶（待验证）
- 若频繁超时影响体验，可在
~/.workbuddy/mcp.json 的 claude-code-mcp 段加 "timeout" 更大值（已在 0.1 设 600000，但 WorkBuddy 调用层上限可能独立生效，非 server 侧可控；server 侧调大只是给长任务留进程余量，不解决 -32001）。
- 或改用「异步派单」模式：派任务后不阻塞等返回，直接去 workFolder 轮询产物（本质是 POST-FLIGHT 主动化）。
窗口化轮询（本窗口多轮拼接 · 1.10.0 新增 · 推荐主路径）
解决什么：上面「派单后轮询」把"查一次"升级成"循环查"，但仍是在单次 Bash 调用里 sleep 15s×N——期间 WB 被阻塞，用户消息进不来、任务完成也要等本轮循环结束。
用户拍板（2026-07-12）的更好姿势：把「窗口大小」和「查的频次」分开——
- 窗口 = 架构上限：平台单次 Bash 硬上限约 8–10 分钟（-32001），用来拼接无限时长（多轮拼接无理论上限，已实测 10/20/30/32 分钟全过）。
- 查的频次 = 30 秒：窗口里面每 30 秒抬头看一眼玻璃板，不要等满窗口。
即在本窗口内用「
sleep 30 + 读玻璃板 + 决策」循环（每轮一个独立 Bash 调用，只阻塞 30 秒），WB 每 30 秒都有完整控制权。
为什么是 30 秒而不是 8 分钟
- 单脚本窗口（sleep 480 内嵌 30 秒循环）虽能细查，但 WB 在整个窗口期间被 Bash 阻塞，用户消息最坏延迟 = 窗口大小（8 分钟）。
- 改用 WB 主导的 30 秒粒度循环（每轮独立
sleep 30 + 查板）：每轮只阻塞 30 秒，轮次间隙 WB 自然能读到用户新消息、能立刻决策。
- 效果：任务完成 / 需人选择 / 用户发消息，最坏响应延迟从 8 分钟降到 ≤30 秒；而 30 秒远小于平台 8–10 分钟上限，绝对安全。
标准件（poll_tick.py · v1.11.0 统一版）
$HOME/.workbuddy/skills/cc-delegate/scripts/poll_tick.py <workFolder> [--handoff-dir <DIR>] [--recursive] —— 单次读交接文档并输出一行状态，WB 循环调用它。v1.11.0 起与 cc_monitor 同源：直接读 result.json 的 status 字段 + HANDOFF.md 的 STATUS: 行（弃用旧版 status.json 玻璃板预期——CC 按本技能模板只写 result.json+HANDOFF.md，从不写 status.json，旧版永远 MISSING）。
DONE → 任务完成，消费结果走 AUDIT 汇报NEEDS_USER_INPUT|<summary>|| → 需人做业务决策，立刻升级用户（summary 取自 result.json，绝不替用户猜）IN_PROGRESS|elapsed=<秒> → 还在跑，继续下一 tickMISSING → 交接文档还没生成（CC 可能还没起手/写完），继续等BAD_BOARD → 回执不可解析 / status 异常（ERROR/UNKNOWN/坏文件），升级用户BLOCKED → CC 自报卡死，升级用户（绝不替用户重启/改向，交人拍板）
Driver 循环（WB 即 driver，本窗口内）
loop:
1. Bash: sleep 30 && python poll_tick.py <workFolder> # 只阻塞 30 秒
2. 读 stdout 状态:
- DONE -> break，走 AUDIT + 汇报
- NEEDS_USER_INPUT -> break，把问题+选项抛给用户问选择（ESCALATE）
- IN_PROGRESS/MISSING -> 检查「用户是否发了新消息」（WB 本轮间隙自然能看到）
· 有消息 -> 处理/汇报/问选择（用户优先）
· 无消息 -> continue 下一轮
- BAD_BOARD -> ESCALATE 用户
- 长任务：循环持续多轮（每轮 30 秒），自动拼接成任意时长；中途若用户插话或 CC 标 NEEDS_USER_INPUT，立刻响应，不傻等。
- 短任务：约第 N 轮（N×30s 处）发现 DONE，立刻回报，不用等满任何窗口（实测：2 分钟短任务第 4 轮即发现完成，见
test_lab/poll30/）。
WB 操作协议（照做清单 · 1.10.0 主路径）
下面是你（WB）每次接活后逐条照做的步骤，含真实命令。把 <workFolder> 换成实际任务目录（建议每次派活用独立子目录，如 test_lab/run_001）。
① 派活前 —— 写任务宪章（M3），让轮询中的你不瞎猜
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" write-charter ^
--workfolder "<workFolder>" ^
--json "{\"task_id\":\"run_001\",\"original_request\":\"...\",\"key_decisions\":[\"...\"],\"constraints\":[\"不改动源数据\"],\"autonomy_rules\":[{\"when\":\"status==IN_PROGRESS\",\"action\":\"CONTINUE\"}],\"escalation_rules\":[{\"when\":\"status==BLOCKED\",\"action\":\"ESCALATE\"}]}"
宪章缺失时 WB 走保守策略：一律 ESCALATE 叫人，绝不擅自动（见错误矩阵 5.2）。
② 派活 —— 长/短任务选通道
③ 进入窗口化轮询 —— 本窗口内每 30 秒一轮
每轮只发一条 Bash（只阻塞 30 秒），轮次间隙你自然能读到用户新消息：
sleep 30 && python "$HOME/.workbuddy/skills/cc-delegate/scripts/poll_tick.py" \
--workfolder "<workFolder>" --handoff-dir "<HANDOFF_DIR>"
④ 读输出分支处置（每轮都做）
| poll_tick 输出 | 你的动作 |
|---|
DONE | 消费 result.json，向用户汇报摘要（AUDIT） |
NEEDS_USER_INPUT|<summary>|| | 在原窗口把摘要抛给用户问选择（ESCALATE），绝不替用户猜 |
BLOCKED | 升级用户：说明 CC 自报卡死，请人拍板（重启 / 改向 / 中止） |
IN_PROGRESS|elapsed=... | 检查用户是否发了新消息 → 有则优先处理；无则继续下一轮 |
MISSING | 交接文档还没生成（CC 可能刚起手），继续下一轮 |
BAD_BOARD | 回执损坏/不可解析，升级用户 |
⑤ 用户插话优先 —— 任何一轮间隙若用户发来新消息，立刻停下手头循环、优先处理用户指令（问选择 / 改向 / 中止），处理完再决定是否继续轮询。
这套协议已在 test_lab/poll30/ 实测：30 秒粒度轮询发现 2 分钟短任务 DONE（第 4 轮）、32 分钟长任务持续不中断（5 轮×8 分钟拼接）。详见 cc-delegate-watchdog-impl-plan.md 第 7.5 验收清单。
长/短任务判断（driver 接活时先定）
- 短任务（预期 < 几分钟、单步）：直接派活 + 本循环轮询，DONE 即收。
- 长任务（可能超平台单次上限 / 需多步接力）：状态化模式（
--resume）+ 本循环轮询；每轮间隙 WB 既能看进度、也能接用户指令或 CC 的 NEEDS_USER_INPUT。
与「派单后轮询」章节的关系
- 旧版（上节）适用于「另开 shell 跑 cc_monitor 旁观」或脚本内 sleep 循环；
- 本版（1.10.0）是主路径：WB 在本窗口内 30 秒粒度主导循环，响应更快、能接用户消息。二者监控判据同源（都看玻璃板 / HANDOFF / transcript）。
开头总览 + 阶段→轮询间隔 + STUCK 调参 + 收尾 checklist（v1.11.0 固化）
以上来自 EP25 全流程复盘的实战补强：把「容易忘的步骤」固化为必做项，把「凭感觉的轮询频率」固化为映射表。
① 开头总览（长任务派活后、进监控前必给）：用 2-3 句话给大古「预计阶段 + 监控频率 + 何时会停下问你」三段式，避免一来就闷头轮询、大古不知道何时该介入。例：「CC 跑 Phase 3 编码→4 审查→10 渲染，每 60-90s 看一眼，到检查点会停下交你拍板。」
② 阶段 → 轮询间隔映射（避免间隔乱飘）：
| 阶段 | 轮询间隔 | 说明 |
|---|
| 轻量（读/规划/写单文件） | 30s | 动作快，细看不亏 |
| 编码（多场景/多文件生成） | 60s | 单文件生成几十秒，60s 刚好 |
| 渲染 / 长命令（remotion render / ffmpeg / tsc） | 90–120s | 长任务 transcript 暂停更新属正常，间隔拉长少打扰 |
| 生成长文档（visual-plan.md 等长文） | 拉高 --stale 至 300s | 见下 ③ |
③ STUCK 阈值按阶段调（防误报）：默认 --stale 120s 对「CC 在 LLM 推理生成长文档 / 跑长命令」会误报 STUCK（transcript 暂停更新是正常的）。这类阶段主动拉高 cc_monitor --stale 300（或 --recursive --stale 300）。决策树「STUCK? 先观察一轮」仍有效——误报时查 transcript 末行确认真在推理而非真卡。
④ 收尾 checklist（DONE 后必做，漏一项都不算完）：
- 独立核验 DONE：不盲信 CC 自报，独立跑产物核验；同时执行
parse/decide --transcript，把 verification.command 与真实 Bash tool_use 对账。MISMATCH 时禁止收工。
session_registry.py close --project <项目> 归档（保留 sid 供查 transcript）——EP25 曾漏此步。- 多维度交叉验证 CC 状态（transcript 末行 + 进程数 + result.json + HANDOFF 四种信号），STUCK 触发时主动查 transcript 确认真在推理而非真卡。
- POST-FLIGHT 落点校验：产物在声明目录、家目录无残留（防回退 bug）。
- 跨会话/隔天续干的任务，派活前
write-charter 写任务宪章（模式二多步尤甚），让轮询中的你不瞎猜。
实时过程监控（派一个监控看 CC 在干嘛/卡没卡/要不要杀）
核心认知：CC 每次调用都把全过程实时写进 transcript(jsonl)，与本次会话 1:1 对应、边跑边写。监控 transcript = 监控 CC 进程在干嘛。这比直接看 OS 进程可靠——本机常驻多个历史遗留 claude.exe，光看进程名分不清哪个是本次（见下「为什么不直接杀进程」）。
⚠️ P7 已知限制（并发同 workFolder）：同目录并发派多个活时，两个会话的 jsonl 落在同一 projects 子目录；若不传 --marker，find_transcript() 按"最新 mtime"会错配到别的任务 → 监控假阳性（误判 DONE 早退 / 读错进度）。规避：① 每次派活带唯一 --marker（脚本据此锁定本次 transcript）；② 或给每次派活用独立子目录（如 test_lab/run_001、run_002）。完整说明见 references/monitor-reference.md。
何时用
- 派了个重任务，想实时看进度（在调哪个技能、写哪个文件、跑什么命令）。
- 调用报
-32001 超时，想知道 CC 到底还在跑没跑完。
- 怀疑 CC 卡死/死循环，要判断「要不要把它杀掉」。
标准用法（派活后另开 shell 跑）
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "<workFolder>"
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "<workFolder>" --handoff-dir "<你派活指定的目录>"
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "<workFolder>" --recursive
实时输出：[RUNNING] / [DONE] / [STATE] / [STUCK?] / [STUCK]。若回执声明 verification.command 但与 transcript 不一致，输出 [VERIFY-MISMATCH] 并返回退出码 4，不输出 DONE。
只看一眼：python ...cc_monitor.py --workfolder "..." [--handoff-dir "..."] --show。
完整参数表、精准 kill 调参、marker 嵌入示例、决策树见 references/monitor-reference.md。
决策树：RUNNING → DONE / STUCK → 杀不杀
- RUNNING 且 mtime 很新 → 正常推进，继续等，无需干预。
- DONE（完成标记出现）→ 读回执，走 AUDIT 汇报。
- STUCK?（静止 > stale 默认 120s） → 先观察一轮，可能是 CC 在跑长命令（如渲染）暂时没写 transcript。
- STUCK（静止 > kill-after 默认 300s）且确认不是合法长任务 → 决定「杀掉本次进程」：用精准 kill（见下），只杀本次、不误伤历史进程。杀完重派（拆小步）。
精准 kill 本次 CC 进程（重点）
为什么能精准？ 因为 claude-code-mcp server 启动 CC 的命令行是：
const claudeProcessArgs = ['--dangerously-skip-permissions', '-p', prompt];
spawn(claudeCliPath, claudeProcessArgs, { cwd: effectiveCwd })
我们的 prompt 文本完整出现在本次 CC 进程的命令行里。所以：
- 派活时，在 prompt 里嵌入一个唯一标识，如：
任务唯一标识 TID=cc_20260711_ab12 （用于进程监控与精准终止，勿改）
- 监控时传同一个标识：
--marker "TID=cc_20260711_ab12" --kill。
- 脚本用 PowerShell 抓所有
claude.exe 的 CommandLine，只匹配含该 marker 的 PID 终止。
- 历史遗留的 claude.exe 命令行里没有这个 marker → 绝不被误杀。
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" --workfolder "..." \
--marker "TID=cc_20260711_ab12" --kill
（stale/kill-after 调小用于演示/紧急；生产默认 120/300 给合法长任务留余地。完整调参见 references/monitor-reference.md。）
为什么不直接杀 OS 进程 / 为什么需要 marker
claude 是 claude.exe，Get-Process claude 能看到，但本机实测常驻多个好几天前的遗留 claude.exe（7/8、7/9 启动的还在），光看进程名分不清哪个是本次调用，无法定位、不能瞎杀。- MCP server 自己是个 node 进程（server.js），不是干活的 worker，杀了它会断掉整个 MCP。
- 故以 transcript 监控为准（1:1 对应、实时增长）+ marker 精准定位本次 worker，OS 进程数仅作参考（脚本顺带打印）。
安全边界
- 仅用
--kill 终止带本次 marker 的 claude.exe；禁止无条件 taskkill claude.exe（会误杀历史进程/他人会话）。
- 杀前脚本会打印
KILL-CANDIDATE pid=.. cmd=..（cmd 含 marker 片段）供你核对，再加 --kill 才真正终止。
- 不确定时先不加
--kill 跑一次，看候选 PID 与命令行，确认无误再杀。
状态交接协议（HANDOFF · 1.4.0 新增 · 解决 CC 无会话连续性）
核心问题：实测确认 claude_code 每次调用都是全新无状态会话（server.ts:293 拼的命令行无 --session-id/--resume），CC 不记得上一次聊了啥（我们实测它亲口说"不记得"）。
但"不记得聊天"≠"啥都不记得"：磁盘上的文件、CLAUDE.md 常驻规则、CC 自己的 auto-memory 都跨调用持久化。
可靠解法 = 交接文档（HANDOFF）+ 原始对话兜底：让 CC 每次把"干了啥/做到哪/下一步"写成文档；多步接力时，下一棒先读它（和上次 transcript 原始记录）。不靠 CC 记忆，靠它留的字条。
两种模式（用户拍板：不管一次还是多次，都写清晰文档）
| 模式 | 适用 | HANDOFF STATUS | 下次是否先读交接 |
|---|
| 模式一·单次 one-shot | 预期一次干完 | DONE | 可选（追问/改时读，有背景） |
| 模式二·多步 multi-step | 活大/预判分几次 | IN_PROGRESS | 必读（技能自动在 prompt 开头拼「先读 HANDOFF.md 接进度」） |
关键共识：两种模式都写 HANDOFF.md——因为"一次完成"的活，过阵子你可能追问"把刚才那个改一下"，那时 CC 同样需要背景，没字条就得从头摸。区别只在标 DONE 还是 IN_PROGRESS。
交接目录契约（v1.11.0 固化 · v1.11.1 去硬编码）
核心：result.json + HANDOFF.md 是 WB↔CC 之间的交接契约，位置必须 WB 每次派活时显式声明、双方共用同一个 pin，不能让 CC 按自己 pipeline 约定随意放，也不要在 skill 里硬编码「某类任务 → 某目录」的映射。
EP25 实测踩坑：CC 按 110-视频 pipeline 把交接写在 projects/<id>/ 子目录，而 monitor 钉在 workFolder 根 → 两个 pin 不一致 → 完成判据永远 False、全程误判 RUNNING。v1.11.0 用 --handoff-dir 解决；v1.11.1 进一步去掉「按任务类型推断目录」的假设——目录由 WB 每次派活时直接指定，skill 不绑定任何任务类型。
规则（driver = WB 拥有 pin 的所有权）：
- 派活时 WB 显式指定交接目录
$HANDOFF_DIR = 你告诉 CC「派发到哪个目录」的那个目录（可以是 workFolder 根，也可以是其中子目录，由你每次定，CC 不替你选）。
- 零推断：不要依赖「推断 pipeline 类型 → 猜目录」；目录由你拍板，CC 照做。你做什么活（视频/文档/代码/分析）都不影响这条规则。
- prompt 明写契约：「
result.json + HANDOFF.md 必须写在 <$HANDOFF_DIR>，这是交接位，不得另放」——CC 只是执行方，没有自选位置的自由度。
- monitor 读同一个
$HANDOFF_DIR：cc_monitor --handoff-dir "<$HANDOFF_DIR>"（懒人用 --recursive 边界递归自动找，仅作 WB 忘 pin 时的兜底，不是主路径）。
- 委托前 pre-flight 校验该目录存在/可写（不存在先
mkdir -p 或问用户）。
--handoff-dir 只负责锁定交接位置，不会绕过状态与本次运行证据：result.json.status 必须精确等于 DONE，且文件须晚于监控启动，或完整路径被本次 transcript 的 Write 命中，或文件时间不早于本次 transcript 创建时间。历史 DONE、IN_PROGRESS、NOT_DONE 均不得完成。
这条契约把「监控对子目录产物的适配」从「使用规范 + 脚本小增强」升格为架构级 pin——CC 不再能随意改位置，monitor 永远读得准；且因为目录由 WB 每次显式指定、skill 不绑定任务类型，换个活照样用，不用改 skill。
HANDOFF.md 模板（放 WB 声明的 HANDOFF_DIR，人看 AI 看都清楚）
# HANDOFF — <任务名>
## 目标
<这次要干啥>
## 当前状态
STATUS: DONE | IN_PROGRESS
## 进度
<做到了哪、关键结论>
## 产出文件
- <path1>
- <path2>
## 下一步
<IN_PROGRESS 写清接啥；DONE 写"无">
## 原始对话记录（兜底，摘要不够用时读这个）
LAST_TRANSCRIPT: $HOME/.claude/projects/<编码workFolder>/<session>.jsonl
TRANSCRIPT_HISTORY:
- <session1>.jsonl （步骤1）
- <session2>.jsonl （步骤2）
分工（CC 写摘要，driver 自动补 transcript 路径）
- CC 写：目标 / 进度 / STATUS / 产出文件 / 下一步（它最懂任务上下文）。
- driver（本技能/WorkBuddy）自动补
LAST_TRANSCRIPT：派活后用 find_transcript()（见第二章 2.2，并发时带 marker 锁定）定位那次 jsonl，直接 append 进 HANDOFF.md。CC 不用去猜自己那个诡异编码路径。
- 多步模式每接力一次，
TRANSCRIPT_HISTORY 累加一条，整条链都能回溯。
多步接力实操（模式二）
- 步1 派活：prompt 含「写 HANDOFF.md，STATUS: IN_PROGRESS，下一步写清」。CC 完成后 driver 补
LAST_TRANSCRIPT。
- 步2 派活（下一棒）：本技能自动在 prompt 开头拼：
先读 HANDOFF.md 接上上次进度（尤其看「下一步」与 LAST_TRANSCRIPT 原始对话），再执行：<本次新指令>。
- CC 读 HANDOFF + 上次 jsonl → 确定性接上，不怕
-32001 超时（文件落盘即状态），也不依赖 CC 记不记得。
- 末步 STATUS 改
DONE，收工。
完成判定升级（配合监控脚本 · P2/P3 加固）
cc_monitor.py 的完成信号同时识别 ① --product（默认 result.json）出现 ② HANDOFF.md 含 STATUS: DONE（1.4.0 起）。- P2 加固（v1.12.0）：传
--marker 后，find_transcript() 按"首段含 marker"精确锁定本次 transcript；找不到 marker 时返回 NONE，绝不回退其他最新会话。
- P3 加固（v1.12.0）：完成判据要求精确
DONE，并校验完整目标路径及本次运行时间证据，避免同名文件、历史残留和 IN_PROGRESS 假完成。
- 多步/单步的统一可靠信号 = HANDOFF.md 的
STATUS: DONE，比死盯 result.json 干净（result.json 是持久文件，易被旧值误判，我们踩过坑）。
第三章：多仓库与会话连续性
- 跨仓库：靠
workFolder 区分即可（不同仓库传不同路径）。
- 会话连续性（重要·已实测纠正，v1.6.0 更新）：
- 经 MCP
claude_code：WB 对工具参数有白名单裁剪（additionalProperties:false，仅透传 prompt+workFolder），sessionId 传不进去，且 server 每次 claude -p 全新起进程 → MCP 通道下 CC 无会话连续性，不记得上一次（实测亲口说"不记得"）。多步接力靠 HANDOFF.md + 上次 transcript 路径（见状态交接章节）。
- 经 Bash 直调
claude CLI（--resume，v1.6.0 状态化模式）：本机 claude 2.1.204 原生支持 --resume <sid>，P0 实测 CC 能跨调用凭对话记忆答出前文（如"记住的 42"），会话连续性生效 ✅。这是绕开 MCP 裁剪拿到真·连续性的正解。
- 能跨调用持久化的：磁盘文件、CLAUDE.md 常驻规则、CC 自身 auto-memory、以及
--resume 的 session 对话历史；HANDOFF 仍作为抗重启/抗 session 丢失的兜底。
- 推荐维护一张
workFolder 记录表（项目级或记忆里），方便追溯各仓库委托历史与产物：
| workFolder | 用途 |
|---|
E:/AI/<repoX> | 视频工程 X（CC 全流程含渲染，乙方案） |
E:/个人仓库/100-产品/115-mcp-claudecode | 本协作工具项目 |
第三章附：MCP 派生的 CC 能力范围（与交互式 CC 对等 · 2026-07-11 澄清）
核心结论：经 claude-code-mcp 派出来的 worker CC，就是同一个 claude 二进制、读同一套 ~/.claude/ 配置，能力与你终端/Power Share 里亲手开的 CC 完全对等。claude-code-mcp 只是以 claude --dangerously-skip-permissions -p "<prompt>"（cwd=workFolder）非交互式起进程，不阉割任何原生能力。
- skills / hooks / subagents / CLAUDE.md / CC 自带 MCP 都是 Claude Code 原生能力，从
~/.claude/（用户级）与 <workFolder>/.claude/（项目级）自动加载；不是需要单独接线的 MCP。MCP 桥只需把 claude 跑起来，这些能力自动跟着来。
- 本机实锤（2026-07-11 核查）：
~/.claude/skills/（copywriting/hyperframes/douyin-data-fetch/agent-reach…）、~/.claude/agents/（code-reviewer/security-auditor/karpathy…）、~/.claude/settings.json 全套 hooks（PreToolUse/PostToolUse/SessionStart/Stop：evolver-observe、vault-boundary-gate、settings-guard…）、~/.claude/CLAUDE.md、~/.claude/.mcp.json 均在。
- 活证据：本技能早期经 MCP 调 CC 写故事，transcript 中实打实出现 CC 调
copywriting 技能的 Skill tool_use —— skill 经 MCP 可用已实锤。
- 真·不同（4 点，指挥时记牢）：
- 经 MCP 通道无会话连续性（每次全新进程，CC 不记得上文）→ 用 Bash
--resume 状态化模式解决（见状态化委托章节）；
- 无交互确认：worker 以
--dangerously-skip-permissions 跑 = 全自动批准所有工具（写文件/跑命令全放行）→ 能力全开但无安全闸，须锁死 WB 访问 + 限定 workFolder（安全红线）；
- 无 TTY/交互 UI：需中途打字/点允许的东西用不了；programmatic 的 skill/hook/subagent/MCP 照常跑；
- CC 自带 MCP 中需浏览器 OAuth 登录的，无头
-p 模式可能起不来（无浏览器），其余本地 MCP server 正常。
- 范围：用户级（
~/.claude/）配置任何 workFolder/任何 WB 窗口都带得动；项目级（<workFolder>/.claude/）仅当 workFolder 是该仓库时加载。
- 对「军团」意义：worker CC 是满血 CC，不是阉割版——技能/护栏/并行 subagent/CC 自带 MCP 全在。
活体验证记录（2026-07-11 · 四类能力全部实锤）
为彻底回应"经 MCP 调的 CC 和 Power Share 里开的是否一样"，用 Bash 直调本机 claude CLI（--dangerously-skip-permissions -p，cwd=E:/test_verify_wf，等价 MCP 通道）跑了两轮验证，直接查 ~/.claude/projects/E--test-verify-wf/*.jsonl transcript 与 ~/.claude/.../observations/ hook 产物取证：
| 能力 | 验证动作 | transcript / 产物硬证据 |
|---|
| Skill | 调 copywriting 技能 | session1 transcript "name":"Skill"×1；copywriting 字样 26 次；report.md 确认 |
| Subagent | 派 general-purpose subagent 算 2^10 | session1 transcript "name":"Agent"×1；返回 1024 落地；observations Agent×1 |
| Hook | 写 verify.txt/report.md 触发 Pre/PostToolUse | observations/b61ea836/2026-07-11.jsonl 359 行观察（本次 session，22:03 写入），含 Agent×1、Write×1 痕迹；SessionStart hook 注入 CLAUDE.md/currentDate 已被 CC 自述确认 |
| MCP（加载） | 查可用工具集 | session1 transcript 工具列表完整含 mcp__context7__*、mcp__chrome-devtools__*、mcp__mem0__*、mcp__xapi__*、mcp__zai-mcp-server__*、mcp__zread__*、mcp__web-reader__* 等十几套 server |
| MCP（调用成功） | 调 chrome-devtools.list_pages | session2 transcript "name":"mcp__chrome-devtools__list_pages"×1；真实返回浏览器页面 localhost:3002/.../SC02.html |
结论：经 MCP 派生的 worker CC 与交互式 CC 能力完全对等——skill/hook/subagent/CC 自带 MCP 一个不少，且 MCP 不仅能加载、更能实际调用成功。注意点：① 单个 MCP server（如 context7）可能因运行时连接/拉包失败报"未注册"，但这是该 server 可用性问题，非 CC 缺能力（其工具仍在列表里）；② 用户级 ~/.claude/ 下的 skill/hook/subagent/MCP 任何 workFolder 都带得动。
第四章：边界与禁忌
- 禁止在
workFolder 不存在时直接调工具（先走 PRE-FLIGHT）。
- 我们不在调用里加
bypassPermissions；但须如实告知：claude-code-mcp server 源码硬编码了 --dangerously-skip-permissions 启动 CC（src/server.ts:293）——即本 MCP 模式下 CC 始终以跳过权限方式运行，这是 server 行为、非我们可控。若你合规要求严格（如禁止自动写文件/执行命令），需评估或换包，不能靠"不传参"规避。
- 禁止把产物建到用户未授权目录。
claude_code 是第三方包（friendship-ai/claude-code-mcp）暴露，不修改其源码；要改能力 → 改本技能或换包版本（见第五章）。- 用户分工铁律提示：Codex 管视觉/制作、Claude Code 管数据/文本、WorkBuddy 管编排；CC 干视频时若涉及渲染视觉，按约定转交 Codex（乙方案当前由 CC 全流程含渲染，属特例，以用户当时指令为准）。
第五章：版本与迭代管理（本技能会随使用进化）
用户明示：随着调用进化，MCP 和本 skill 都可能修改完善。所有变更记录在此章，
更新迭代时以这里为唯一依据，不靠口头记忆。
5.1 当前版本
- skill 版本：
1.12.1（2026-07-13）
- 关联 MCP 包：
@steipete/claude-code-mcp@latest（实测版本 1.10.12，npm 源 npmmirror）
- 底包维护者：
friendship-ai（原 steipete/claude-code-mcp 已迁移）
- 状态化模式依赖：本机
claude CLI 2.1.204（PATH 可用，原生 --resume）
5.2 CHANGELOG
| 版本 | 日期 | 变更 |
|---|
| 1.0.0 | 2026-07-10 | 初版：PRE-FLIGHT 防回退 + POST-FLIGHT 验落点 + AUDIT 审计 |
| 1.1.0 | 2026-07-10 | 整合 MCP 打通配置(0章)、审计立为第二章核心、加版本迭代章；修正工具仅 prompt+workFolder；修正 sessionId 由 server 内部维护 |
| 1.2.0 | 2026-07-10 | 新增「超时与重试」章节：实测 WorkBuddy MCP 调用层有固定超时(-32001)，CC 往往后台跑完；超时≠失败，先查产物+transcript；重任务须拆小步 |
| 1.2.1 | 2026-07-11 | 超时处置升级为「轮询直到完成」循环(判断CC是否仍在运行再决定等/重试)；mcp.json server 侧 timeout 由 300000 上调至 600000 |
| 1.2.2 | 2026-07-11 | 新增 cc_monitor.py 进程监控脚本(transcript实时监控=监控CC进程)；澄清"直接看OS进程"不可靠(本机常驻遗留claude.exe,无法定位本次调用) |
| 1.3.0 | 2026-07-11 | 监控升级为一等公民：① 富化"最近在干嘛"展示；② 新增 STUCK→精准 kill 能力(marker 嵌 prompt，PowerShell 抓 CommandLine 只杀本次 claude.exe，误杀防护)；③ 新增「实时过程监控」章节+决策树+安全边界；④ 如实记录 server 硬编码 --dangerously-skip-permissions |
| 1.4.0 | 2026-07-11 | 新增「状态交接协议(HANDOFF)」章节：① CC 无会话连续性→靠交接文档接力；② 两种模式(单次DONE/多步IN_PROGRESS)，共识=无论一次多次都写HANDOFF.md；③ HANDOFF.md 模板含 LAST_TRANSCRIPT 兜底；④ driver 自动补 transcript 路径；⑤ 监控完成信号新增识别 STATUS:DONE；⑥ 纠正第三章"server维护连续性"错误结论 |
| 1.5.0 | 2026-07-11 | 测试暴露 P1–P7 全修：① P2 marker 反查锁定本次 transcript（根治同 workFolder 并发错配假阳性）；② P3 完成判据加固（要求 transcript 末次 Write 命中目标产物 / mtime 晚于启动，防静默失败与历史残留误判）+ 固化「单 prompt ≤1 Skill+1读+1写」拆小步硬规则；③ P1 仅 result.json 模式读回执，HANDOFF 模式不再显示 status=None；④ P4 PowerShell 输出解码顺序 utf-8→gb18030→latin-1 防中文乱码/崩溃；⑤ P5 监控脚本迁入技能自身 scripts/cc_monitor.py 自包含可移植（原 orchestrator/ 副本移除）；⑥ P6 审计解析脚本与监控完整参数抽至 references/ 分包，SKILL.md 保持 lean；⑦ P7 监控章节加 ⚠️ 并发同 workFolder 限制与规避说明 |
| 1.6.0 | 2026-07-11 | 新增状态化委托模式（Bash 直调 + --resume）：① 新增专门章节，WB 用 Bash 工具直调本机 claude CLI 绕过 MCP 参数白名单裁剪，让 CC 原生跨调用记忆对话（P0 实测 42 记忆有效）；② driver 算法：首步无 resume 调起→--print-sid 提取 SID→后续步 --resume <sid> 接力，per-task marker 贯穿全程；③ HANDOFF 降级为抗重启/抗 SID 丢失兜底；④ cc_monitor 增 --session（已知 SID 直接锁定 transcript，最精确）与 --print-sid（仅打印 SID 供 driver 提取）；⑤ 修正第三章会话连续性表述（MCP 通道无状态、Bash 通道有原生连续性）；⑥ 速查卡/默认行为总结补模式选择决策。测试中发现并修复 2 个监控 bug（已并入本版交付物）：(a) --print-sid 误把启动横幅打进 stdout 污染 $() 捕获的 SID → 已改为纯净单行输出；(b) done_h 完成判据只用了 mtime>start_time 守卫、缺 last_write_targets 兜底（而 done_p 有），导致"CC 刚写完 HANDOFF 后启动监控"误判 RUNNING → 已补 transcript 末次 Write 命中兜底，两条监控通道（--session / --marker）均正确识别 HANDOFF STATUS:DONE |
| 1.7.0 | 2026-07-11 | 新增「会话登记本」（跨天/远程续干记忆索引）：① 新增 scripts/session_registry.py，集中登记 <项目名>→<sid, workFolder, 进度, marker> 到用户级技能目录 sessions.json（register/lookup[--field|--json]/list/touch/set-sid/close/reopen/show）；② 状态化模式 driver 算法在「提取 SID」后新增「register 登记」步骤，并新增「用户说'继续<项目>'→lookup 取 sid+workFolder+marker→--resume 接力」的隔天/家外续干闭环；③ 明确三层保险（登记本索引 / --resume 真连续性 / HANDOFF 兜底）；④ 速查卡/默认行为总结/触发词同步更新。目标：家外远程说"继续 Alpha 项目"即可像坐在电脑前接着干，无需重报 SID |
| 1.7.1 | 2026-07-11 | 会话登记本并发加固（应对多 WB 窗口/多助手同时 publish）：① session_registry.py 所有读-改-写经 _reg_transaction() 加跨平台原子锁文件（O_EXCL 独占 + 陈旧锁自动清理）+ 临时文件原子替换写，杜绝多窗口并发写花/丢失更新；② register 新增同名不同 workFolder 冲突拦截（默认 CONFLICT 拒绝静默覆盖，加 --force 才允许），防跨窗口命名撞车导致续错项目；③ 寄存本存于用户级技能目录，故 A/B/C 多窗口共享同一 sessions.json，C 窗口可跨窗口续 A、B 的活。用户场景：A 窗口发 alpha、B 窗口发 beta、C 窗口续 alpha/beta 均成立 |
| 1.7.2 | 2026-07-11 | 活体验证固化「能力对等」结论：用 Bash 直调本机 claude CLI（等价 MCP 通道）跑两轮验证，查 transcript + observations 产物取证，确认经 MCP 派生的 worker CC 与交互式 CC 四类能力完全对等且均可实际调用——Skill（copywriting 被调）、Subagent（general-purpose 派发算 2^10=1024）、Hook（evolver-observe 落 359 行观察、SessionStart 注入 CLAUDE.md）、MCP（工具集完整加载含 context7/chrome-devtools/mem0/xapi/zai/zread/web-reader 等十几套，且 chrome-devtools.list_pages 实际调用成功返回真实页面）。澄清：单个 MCP server（如 context7）可能因运行时连接/拉包失败报"未注册"，但该 server 工具仍在列表，属可用性问题非能力缺失。验证细节写入「第三章附」活体验证记录小节 |
| 1.8.0 | 2026-07-12 | 审计加固 + 文档路径修正（把技能从「能用」推向「严谨」）：① 修复 session_registry._load() 静默清空 bug——JSON 损坏时原 except: pass 返回空结构，后续 _reg_transaction 会整体覆盖丢失全部登记；改为先备份损坏字节到 sessions.json.corrupt.bak 再抛 RegistryError，main() 捕获后干净退出（码2）且绝不写入覆盖，保护跨天/远程续干索引不丢；② 修复 cc_monitor.recent_actions() 的 .replace(')', '') 丑陋 hack（原是掩盖 f-string 多打一个 ) 的权宜），改为干净 f-string，文件名含 ) 不再被误删；③ 修正 SKILL.md 全部 python ~/.workbuddy/... 调用示例——WB Bash 的 ~ 会解析到错误盘符导致脚本找不到（T-B 实测 SID 提取因此失败），统一改为绝对路径 $HOME/.workbuddy/skills/cc-delegate/scripts/...；④ 补「如何使用 + 配合 MCP 架构规划」说明与全面测试报告（test_lab/V18_TEST.md） |
| 1.9.0 | 2026-07-12 | 调用封装模板 + 回传决策阈值（填补最后两块拼图）：① 新增 scripts/cc_delegate.py——把「拼 prompt（自动注入 HANDOFF 接干 preamble + marker）/ 解析 result.json 回执 / 按阈值决策下一步」做成可复用可单测模块（assemble/parse/decide 三子命令），driver 不再手写字符串拼接与易错判据；② 固化「回传决策阈值」表：status 枚举（DONE/IN_PROGRESS/BLOCKED/NEEDS_USER_INPUT/ERROR/TIMEOUT/NO_RECEIPT/BAD_RECEIPT/UNKNOWN）→ 动作（CONTINUE/RETRY/ESCALATE/CONSUME）；核心原则=模糊需人判的（NEEDS_USER_INPUT/BAD_RECEIPT）立即升级不猜测、BLOCKED 仅自动重试1次、ERROR/TIMEOUT/NO_RECEIPT 先轮询重试3次（防 -32001 误判失败）再升级；③ 第一章 Driver 第2步 result.json schema 升级为标准枚举；④ 5.4 已知待办两项（调用封装/回传决策）标 [x] 完成。全面测试见 test_lab/V19_TEST.md |
| 1.9.1 | 2026-07-12 | 深度测试（v1.9.0 整体回归 + 真 bug 修复）：① 修复 decide_next 动作词汇过粗——原把 BLOCKED 的 RETRY（重新派活）与 ERROR/TIMEOUT/NO_RECEIPT/UNKNOWN 的 POLL（仅重查监控、绝不重新派活）合并成同一个 RETRY 令牌，导致 driver 在超时场景会重复 spawn CC 进程（浪费 + 污染产物），正是文档反复警告的「-32001 误判失败」陷阱。改为区分 RETRY（仅 BLOCKED，重试1次）与 POLL（超时族，仅重跑 cc_monitor --show 确认 CC 是否自己跑完，重试3次），动作词汇扩充为 CONTINUE/RETRY/POLL/ESCALATE/CONSUME，调用封装章节与决策阈值表同步；② 深度回归（详见 test_lab/V20_TEST.md）：T-A 核心通道经 MCP 派活端到端、T-B 状态化 --resume 接力、T-C 登记本跨项目、T-D monitor 实跑、T-E 损坏保护、T-F 标签容错、T-G 全新集成链路（assemble→真派 CC→parse→decide→续干循环全跑通）、T-H 决策分支（BLOCKED 重试边界 / NEEDS_USER_INPUT 立即升级 / TIMEOUT 走 POLL 不重新派活）全绿 |
| 1.10.0 | 2026-07-12 | 窗口化轮询（本窗口多轮拼接 · 推荐主路径）：① 落实用户拍板的「窗口大小与查频次分离」策略——窗口=平台单次 Bash 硬上限(~8-10min)用于拼接无限时长、窗口内每 30 秒查玻璃板而非等满窗口；② 新增标准件 scripts/poll_tick.py（单次读板输出 DONE/NEEDS_USER_INPUT/IN_PROGRESS/MISSING/BAD_BOARD 一行状态，WB 循环调用）；③ Driver 改用 WB 主导 30 秒粒度循环（每轮独立 sleep 30+查板，WB 每 30 秒有完整控制权）：任务完成/需人选择/用户发消息最坏响应延迟从 8 分钟降到 ≤30 秒；④ 固化「长/短任务判断→给窗口→窗口内 30 秒细查→三类事件响应」闭环；实测 2 分钟短任务第 4 轮即发现 DONE（见 test_lab/poll30/） |
| 1.10.1 | 2026-07-12 | 发布前跨平台修复（对外发布测试方案 C-05/D-02）：① C-05 修复：cc_monitor.py 原硬编码 PROJECTS = "C:/Users/Administrator/.claude/projects"（仅 Windows 可用，非 Windows 直接失效=发布阻塞项），改为 os.path.expanduser("~/.claude/projects") 跨平台自适应；② D-02 修复：SKILL.md 全部示例命令的 C:/Users/Administrator/... 绝对路径改写为 $HOME/... 占位（跨机器可移植），并修订「脚本调用一律用绝对路径」旧提示为「用 $HOME 而非 ~ 波浪号」，消除粉丝换机不可用的障碍；③ 同步将 cc_delegate/poll_tick 的真实调用示例统一为 $HOME 占位。属发布质量门禁前置修复，未改功能逻辑 |
| 1.10.2 | 2026-07-12 | 发布前缺陷修复（测试方案 D-06）：cc_delegate.py 的 write-charter 子命令对 --json 参数原直接 json.loads 未捕获异常，传入坏 JSON 时向用户抛未捕获 Python 栈（违背门禁 E-01「绝不向用户抛未捕获栈」）。现加 try/except：坏 JSON / 非对象 → 输出可读中文错误并退出码 2（与 argparse 错误一致），不再抛栈。属发布质量门禁前置修复，未改功能逻辑 |
| 1.10.3 | 2026-07-12 | 发布前缺陷修复（测试方案 E-07）：cc_delegate.py 的 write-status / write-charter 写盘操作原裸奔 os.replace / open 无异常捕获，遇只读盘 / 磁盘满 / 权限不足时向用户抛未捕获 OSError 栈（违背门禁 E-01/E-07）。现引入 BoardWriteError，写盘失败抛受控异常，CLI 层捕获后输出可读中文错误并退出码 1（不再抛栈）。确定性测试 E-07 由 FAIL 转 PASS |
| 1.11.0 | 2026-07-13 | 监控子目录产物适配 + 复盘改进（EP25 全流程复盘落地）：① 新增「交接目录契约」——result.json+HANDOFF.md 是 WB↔CC 交接契约，位置由 WB 一次性声明为 $HANDOFF_DIR pin（默认 workFolder 根，子目录 pipeline 如 110-视频用 projects/<id>/），CC 不得自定位置，monitor 读同一 pin；② cc_monitor 新增 --handoff-dir（指定交接目录，强信号：存在即 DONE）+ --recursive（边界递归自动找产物，跳过 node_modules/.git，偏离根即视为强信号）；③ poll_tick 重写统一为读 result.json status + HANDOFF STATUS（弃用 status.json 玻璃板预期，旧版永远 MISSING），与 cc_monitor 同源；④ 固化「开头总览 + 阶段→轮询间隔映射(30/60/90-120s) + STUCK 阶段调参(--stale 300) + 收尾 checklist(独立核验 DONE/close 登记本/交叉验证/POST-FLIGHT/charter)」；⑤ 速查卡/状态交接/实时监控用法同步更新 |
| 1.11.1 | 2026-07-13 | 交接目录契约去硬编码（用户拍板修正）：v1.11.0 的契约仍隐含「按 pipeline 类型推断目录」（通用→根、110-视频→projects/<id>/）。用户指出自己做的事不固定（视频/文档/代码/分析……），硬编码「类型→目录」映射一旦任务类型变了就失效、又得改 skill。修正：handoff 目录 = 派活时 WB 显式指定的「派发目录」，零推断、skill 不绑定任何任务类型；--recursive 降级为「WB 忘 pin 时的兜底」而非主路径。监控 --handoff-dir 强信号逻辑与 poll_tick 同源不变 |
| 1.12.0 | 2026-07-13 | 状态协议与并发修复：① 新增 cc_protocol.py，统一 result.json/HANDOFF.md/handoff-dir 解析；② monitor 仅精确 DONE 才完成，NOT_DONE 不再误判；③ marker 找不到时失败关闭，不再回退其他最新 transcript；④ transcript Write 改为完整路径核验，并拒绝无本次证据的历史 DONE；⑤ cc_delegate assemble/parse/decide/matches 全部支持 handoff-dir，BRIEFING 规则接入 decide，status.json 降级为兼容命令；⑥ session registry 锁超时中止写入，读取不再触发保存，并新增 claim/release 项目租约；⑦ README/ARCHITECTURE/参考文档同步；⑧ 提交 Python 标准库回归测试。 |
| 1.12.1 | 2026-07-13 | 真实 E2E 暴露项修复：① assemble --output-file 原子写 UTF-8 prompt 并只输出单行路径，PowerShell 用 Get-Content -Raw 避免多行 stdout 被拆为参数数组；② read_result 保留 verification 字段；③ 新增 transcript Bash 命令提取与 verification.command 精确对账；④ parse --transcript 输出 verification_audit；⑤ decide --transcript 在 MISMATCH/NO_TRANSCRIPT/REPORTED_FAILURE 时返回 ESCALATE；⑥ monitor 对账失败返回退出码 4；⑦ 使用真实 Claude Code 双阶段 resume transcript 回归。 |
5.3 如何迭代更新
- 改本 skill：直接用 Edit 改此
SKILL.md（不可手搓新文件，须用 SkillManage 改 agent_created:true 的技能），改完在 5.2 CHANGELOG 追加一行，并升 version。
- 改 MCP 配置：
- 换包版本 → 改
mcp.json 里 args 的 @steipete/claude-code-mcp@latest 为指定版本或本地路径；
- 沙箱拦 npx → 本地预装后把
command 从 npx 改为本地 node_modules/.bin/claude-code-mcp；
- 改完重启 WorkBuddy 验证（0.3）。
- 新增能力（如：结构化 result.json schema 升级、多 Worker 并行、Codex 互调）→ 在此文件加章节，并在 CHANGELOG 记录。
5.3.1 发布前验证
python -m unittest discover -s tests -v
python -m compileall -q scripts
回归测试必须覆盖：精确 DONE、marker 失败关闭、完整路径 Write、handoff-dir 贯通、PowerShell prompt 文件模式、verification transcript 对账、README CLI 示例、登记本锁失败不写与 claim/release 冲突。
5.4 已知待办 / 开放问题
调用本技能的默认行为总结
用户说「调用这个技能 / 让 CC 干活 / 调 claude code」→ 我自动：
- 确认 MCP 已通（0.3，怀疑时才跑）；
- 解析 workFolder + 任务 + 选模式：
- 多步同仓库接力且需 CC 记住前文 → 状态化模式（Bash 直调 +
--resume，见状态化委托章节）；
- 单步 / Bash 调
claude 不通 → 退回 MCP 无状态模式（HANDOFF 接力）；
- 用户说"继续 <项目> / 接着干 <项目>" → 走「会话登记本续干」：先
session_registry.py lookup --project <项目> 取 sid + workFolder + marker，再 --resume <sid> 接力（详见「会话登记本」章节）；lookup 返回 NONE 则退回 HANDOFF 兜底或询问用户；
- PRE-FLIGHT 查目录：确认 workFolder 与本次显式声明的 HANDOFF_DIR 都存在、可写（不存在先问用户或按授权创建）；
- 派活前生成唯一 per-task marker（如
TID=cc_v17_<任务id>_<随机>），嵌入每步 prompt（用于后续精准 kill + 锁定本次 transcript）；
- 调 CC：
- 状态化模式：Bash 直调
claude --dangerously-skip-permissions -p "<marker>\n<prompt>"（首步）→ 提取 SID（marker 找不到则失败，不回退）→ session_registry.py register 登记项目；后续 resume 前先 claim --owner <窗口ID>，成功后才 --resume <sid>，本轮结束 release；prompt 内要求 CC 把 HANDOFF.md + result.json 写入同一 HANDOFF_DIR；
- 无状态模式（MCP）：调
claude_code（只 prompt+workFolder），多步接力本棒 prompt 开头自动拼「先读 HANDOFF.md 接上进度，再看 LAST_TRANSCRIPT 原始对话」；
- 单 prompt 严守 ≤1 Skill+1读+1写 拆小步硬规则（P3）；
- 项目收工 →
session_registry.py close --project <项目> 归档（保留 sid 供查 transcript）；
- POST-FLIGHT 验落点（防家目录回退）；
- 补 LAST_TRANSCRIPT：派活后用
find_transcript()（带 marker / 状态化模式可带 --session）把本次 jsonl 路径 append 进 <HANDOFF_DIR>/HANDOFF.md；
- 实时监控：使用同一
--handoff-dir "<HANDOFF_DIR>"；只有精确 DONE + 本次运行证据才收工，状态化模式优先 --session <sid>；
- 若 STUCK 且确认卡死 → 用
cc_monitor.py --marker <同标识> --kill 精准终止本次进程，再拆小步重派；
- AUDIT 读 transcript 汇报调了哪些技能/工具，并对账
verification.command；不一致时 ESCALATE，绝不自动 CONSUME；
- 简洁汇报结果 + 下一步。
全过程用户无需重复说明配置细节——本文件即权威手册。
