内容
# cc-delegate
> WorkBuddy 指挥本机 Claude Code 干长活、还能「跨次接棒不丢记忆」的标准入口技能。
> 当前版本：**v1.10.3**（缺陷全清，46/47 测试通过）
## 一句话简介
你（在大古的电脑上用 WorkBuddy）想让另一台「施工队」——本机的 Claude Code——去干一个分好几期才能干完的活（比如剪视频、写长文档、分阶段重构代码）。
这套技能就是**包工头**：负责把活派出去、盯进度、卡死了能精准掐掉重派，最关键是——**下一期换人接手时，施工队还记得上一期干到哪了**。
## 它解决什么问题
普通方式调 Claude Code 有个硬伤：每次调用都是「断片的」，上一期干的事下一期全忘了，长任务只能一次塞完，塞不下就扯。
cc-delegate 用两种方式把记忆接上：
1. **接棒钥匙（状态化模式）**：用 WorkBuddy 的 Bash 直调本机 `claude` 命令行，首步记下它的「会话身份证号」，后续步骤拿这把钥匙 `--resume` 接手，Claude Code 原生记住跨次对话。
2. **交接字条（HANDOFF 兜底）**：每次派活，Claude Code 在目录里留一张字条，写清「这次干完没 / 干到哪了 / 下一步干啥」，抗重启、抗钥匙丢失。
再配三层保险、实时监控、会话登记本，让远程/隔天续干也不乱。
## 架构一览（30 秒看懂）
### cc-delegate = MCP 桥 + 技能智慧
| 层级 | 谁做的 | 作用 |
|------|--------|------|
| **MCP 桥** (`@steipete/claude-code-mcp`) | steipete（开源社区，MIT 协议） | 把本机 Claude Code CLI 包成一个 MCP 工具，让 WB 能调用它 |
| **cc-delegate 技能** | 我们（大古 + WB 助手） | 在桥上建整套调度系统：记忆接棒、进度监控、精准杀、会话登记、窗口轮询 |
> 打个比喻：**steipete 修了高速公路（MCP 桥），我们在上面跑智能物流系统（cc-delegate）。** 高速只管车能通，调度、追踪、防丢、续跑全是物流系统自己做的。
### 数据怎么流的
```
你的指令（"CC 去 E:/AI 生成视频脚本"）
↓
WorkBuddy 对话层
↓
┌─────────────────────┬──────────────────────┐
│ 通道① MCP │ 通道② Bash 直调 │
│ WB → MCP桥 → CC │ WB → Bash → CC │
│ 简单单次任务 │ 长任务 / 需要记忆 │
│ 参数: 只透传 │ 参数: 全部自由 │
│ prompt + workFolder │ --resume / --perm 等 │
└─────────────────────┴──────────────────────┘
↓
Claude Code CLI（本机）
↓
产物落到 workFolder 目录
```
### MCP 桥参数真相：官方 6 个，WB 只透传 2 个
MCP 桥的 `claude_code` 工具定义了 6 个参数，但 **WB 的连接器层做了白名单裁剪**：
| 参数 | 官方支持 | WB 能用？ | 怎么办 |
|------|:--:|:--:|------|
| `prompt` | ✅ | ✅ | 直接传 |
| `workFolder` | ✅ | ✅ | 指定 CC 在哪个目录干活 |
| `sessionId` | ✅ | ❌ 被裁 | → 走 Bash 通道 `claude --resume` |
| `permissionMode` | ✅ | ❌ 被裁 | 默认 bypassPermissions，通常不需要改 |
| `messages` | ✅ | ❌ 被裁 | 高级场景才用 |
| `stateless` | ✅ | ❌ 被裁 | 不设 --resume 就是无状态 |
> 📖 完整架构深度解析见 **[ARCHITECTURE.md](ARCHITECTURE.md)**。
## 功能特性
| 功能 | 说明 |
|---|---|
| 标准委托入口 | 调用即代表「要指挥 CC 干活」，全自动走完 MCP 验收 → 目录预检 → 委托 → 落点后验 → 审计汇报 |
| 状态化接棒 | Bash 直调 `claude` CLI + `--resume <sid>`，绕开 MCP 参数白名单，CC 原生记忆跨调用上下文 |
| 会话登记本 | 集中登记「项目名 → 会话号 / 工作目录 / 进度」，隔天或家外远程说「继续某项目」自动查出该 resume 哪个号，不用你重报 |
| 实时过程监控 | 派个监控看 CC 在干嘛、卡没卡、干没干完；卡死可精准 kill **只杀本次**进程，不误伤历史 |
| 强制审计 | 读取 CC 本地原始对话记录，汇报它调了哪些技能、动了哪些文件，过程可追溯 |
| 状态交接 HANDOFF | 每次派活 CC 写交接文档，单次标 `STATUS: DONE`、多步标 `IN_PROGRESS` + 下一步 |
| 窗口化轮询 | WB 在当前窗口以 30 秒粒度轮询「玻璃板」状态（DONE/需选择/进行中），长任务靠多轮拼接撑任意时长，单窗口闭环不中断 |
## 目录结构
```
cc-delegate/
├── SKILL.md # 技能主文档（使用手册 + 配置 + 踩坑录 + 迭代记录）
├── ARCHITECTURE.md # 架构总览（MCP 桥 vs 技能 / 双通道 / 参数白名单 / 决策树）
├── scripts/
│ ├── cc_delegate.py # 调用封装：拼指令(assemble) / 解析回执(parse) / 判下一步(decide) / 写玻璃板+宪章
│ ├── poll_tick.py # 窗口化轮询单次查板：读玻璃板状态 → 输出 DONE/需选择/进行中/BLOCKED/异常
│ ├── cc_monitor.py # 实时监控 CC 进度、精准 kill、提取会话号(SID)
│ └── session_registry.py # 会话登记本：register / lookup / list / close
├── references/
│ ├── audit-parsing.md # 审计解析详解（如何读 CC 原始对话记录）
│ └── monitor-reference.md # 监控脚本完整参数表与高级用法
├── mcp-config.example.json # MCP 桥配置参考模板（复制到 ~/.workbuddy/mcp.json 追加）
├── README.md
├── LICENSE
└── .gitignore
```
> 运行时产生的 `sessions.json`（登记本数据）与 `__pycache__/` 不纳入版本库，见 `.gitignore`。
## 安装
### 第一步：安装 MCP 桥（一次性）
cc-delegate 依赖 `claude-code-mcp` 这个 MCP 桥来连接 WorkBuddy 和你本机的 Claude Code。配置文件是 `~/.workbuddy/mcp.json`（⚠️ 注意：无点前缀，不是 `.mcp.json`）。
在 `mcp.json` 的 `"mcpServers"` 段里追加：
```json
"claude-code-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@steipete/claude-code-mcp@latest"],
"runtime": {"type": "node", "version": ">=20"},
"timeout": 600000,
"disabled": false
}
```
> 完整模板见仓库里的 `mcp-config.example.json`；注意别删掉已有的其他 server（如 `connector-proxy`）。
配置完成后：
1. 保存 JSON（用 `python -m json.tool` 校验合法性）
2. **重启 WorkBuddy**（MCP 工具在启动时加载，改了马上生效要重启）
3. 开新会话 → 设置里可能会有弹窗，**批准**该 server
4. 验证：在新会话里问「帮我用 ToolSearch 搜 `claude_code` 工具」，搜到说明桥通了
> 如果遇到 `npx` 超时（沙箱拦联网拉包），先本地装好：`npm install -g @steipete/claude-code-mcp`，然后把 `command` 从 `"npx"` 改成 `"node_modules/.bin/claude-code-mcp"` 的绝对路径。
### 第二步：安装技能
```bash
git clone https://github.com/gugug168/cc-delegate.git \
"$HOME/.workbuddy/skills/cc-delegate"
```
重启 WorkBuddy 后，对助手说「调 Claude Code 去干 XXX」「让 CC 接着干」「继续某项目」等即可触发。
### 前置条件总结
| 条件 | 说明 |
|------|------|
| WorkBuddy | 已安装并登录 |
| MCP 桥 | `claude-code-mcp` 已配置到 `~/.workbuddy/mcp.json` 并重启+批准 |
| Claude Code CLI | `claude` 命令在终端可用 |
| Node.js | >= 20（MCP 桥运行需要） |
| Python | 3.10+（技能脚本纯标准库，无需 pip 装包） |
## 使用方法
### 场景一：分两期干一个长活（状态化接棒）
**第一期**（无钥匙，自动开始并记下会话号）：
```bash
SID=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" \
--workfolder "<你的工作目录>" --marker "TID=demo_p1" --print-sid)
claude --dangerously-skip-permissions -p "<第一期任务 prompt>"
```
**第二期**（拿钥匙接棒，CC 记得第一期）：
```bash
claude --dangerously-skip-permissions -p "<第二期任务 prompt>" --resume "$SID"
```
### 场景二：实时监控 / 卡死精准终止
```bash
# 看 CC 在干嘛、卡没卡
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" \
--workfolder "<你的工作目录>" --marker "TID=demo_p1"
# 确认卡死且非合法长任务，精准掐掉本次（不误伤）
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" \
--workfolder "<你的工作目录>" --marker "TID=demo_p1" --kill
```
### 场景三：会话登记本（隔天续干）
```bash
# 登记本次会话
python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" \
register --project 我的项目 --sid "$SID" --workfolder "<路径>" --marker "TID=demo_p1"
# 隔天远程接入，自动查回该 resume 的会话号
SID=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" \
lookup --project 我的项目)
```
更完整的参数与决策树见 `references/monitor-reference.md` 与 `SKILL.md` 速查卡。
### 场景四：窗口化轮询（长任务单窗口闭环）
```bash
# 1. 写任务宪章（包工头带判据，被唤醒也知道何时自决、何时叫人）
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" \
write-charter --workfolder "<工作目录>" --json '{"task":"写报告","auto_actions":["IN_PROGRESS:CONTINUE"]}'
# 2. 派 CC 干活（后台），WB 在当前窗口每 30 秒查一次玻璃板
python "$HOME/.workbuddy/skills/cc-delegate/scripts/poll_tick.py" \
--workfolder "<工作目录>"
# 输出：DONE（收工）/ NEEDS_USER_INPUT（问大古）/ IN_PROGRESS（继续等）/ BLOCKED（重派）
# 3. 完工后收尾
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" \
parse --workfolder "<工作目录>" # 解析回执
python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" \
decide --workfolder "<工作目录>" # 判下一步（CONSUME=收工 / RETRY=重派 / ESCALATE=叫人）
```
> 长任务（>8 分钟）靠 WB 对话级多轮拼接撑任意时长，每轮查玻璃板硬盘状态不丢失，全程单窗口不中断。
## 许可证
[MIT](LICENSE) —— 随意用、改、再分发，留个出处就行。
