137 lines
13 KiB
Markdown
137 lines
13 KiB
Markdown
---
|
||
name: claude-brain
|
||
description: >
|
||
"大脑 + 手脚" 多 agent 协作模式：唯一的主 agent（Claude Fable 5.1，"大脑"）只做分析和决策，
|
||
不执行任何操作；所有实际动作（读代码、改文件、跑命令、调 MCP、烧板子……）都派给任务子 agent
|
||
（默认 Opus 5.5，大脑可按难度改选 Sonnet/Haiku）去做。子 agent 做完把结果写成报告回给大脑，
|
||
大脑再分析、再派活，循环直到大脑判定完成。双方的全部交互记录都以 md 形式只存放在 ./Notes/auto 下。
|
||
只要用户说 "claude-brain"、"用大脑模式"、"brain 模式"、"让 Fable 当主 agent"、"Fable 规划 Opus 执行"、
|
||
"主 agent 只分析不动手"、"主从 agent 循环做这个任务"、"大脑分析、子 agent 执行"、
|
||
"use claude-brain"、"brain/worker loop"，就必须使用这个 skill —— 哪怕他们只说了
|
||
"用 brain 跑一下这个任务"、"让大脑来拆解这个活"。
|
||
---
|
||
|
||
# claude-brain：大脑分析，子 agent 执行
|
||
|
||
## 三个角色
|
||
|
||
| 角色 | 谁 | 数量 | 模型 | 能做什么 |
|
||
|---|---|---|---|---|
|
||
| **大脑（brain）** | 一个持续存活的子 agent | 全程**唯一一个** | **只有它**用 Fable 5.1（`fable`） | 读 `./Notes/auto` 里的记录（必要时只读查看文件），分析、决策、写任务单。不改任何东西、不跑命令 |
|
||
| **任务子 agent（worker）** | 每个任务派一个新的 | 任意多个，可并行 | 默认 Opus 5.5（`opus`）；大脑可按难度指定 `sonnet` / `haiku`，**不能**用 `fable` | 执行任务单，把结果写成报告 |
|
||
| **调度员（dispatcher）** | 当前这个 Claude Code 会话（就是你） | 一个 | 会话本身的模型 | 只做机械转递：启动大脑、把大脑的任务单发给 worker、把报告路径交回大脑、写记录文件、替大脑问用户 |
|
||
|
||
为什么要有调度员：大脑的工具被限制为只读，它不能自己派 agent、也不能写文件；而嵌套派 agent 在 Claude Code 里也不可靠。所以"手"一律由会话来转递。
|
||
|
||
**调度员的纪律**：你不是第二个大脑。不要自己分析任务、不要改写或"优化"大脑的任务单、不要替大脑判断完成与否、不要自己动手干活（哪怕看起来一行命令就能搞定）。你只照抄、转递、存档。如果大脑的指令有明显问题（比如路径不存在），把问题原样反馈给大脑让它重新决定，而不是自己修。
|
||
|
||
## 交互记录：只放在 ./Notes/auto
|
||
|
||
所有大脑与 worker 之间的交互 md 都只能写在**当前工程根目录**下的 `./Notes/auto/` 里（每次运行一个子目录）。不要写到 `Notes/` 其它位置、工程其它目录或临时目录。worker 执行任务本身需要改的工程文件（包括工程里的 .md 文档）不受此限——这条约束针对的是"协作记录"。
|
||
|
||
```
|
||
./Notes/auto/<YYYYMMDD-HHMM>-<短slug>/
|
||
├── 00-goal.md # 用户原始任务 + 约束（调度员写）
|
||
├── log.md # 每轮一行流水：轮次/动作/状态（调度员追加）
|
||
├── R01-brain.md # 第 1 轮大脑决策原文（调度员照抄写入）
|
||
├── R01-T1-task.md # 第 1 轮任务 1 的任务单（调度员从大脑决策中原样抽出）
|
||
├── R01-T1-report.md # worker 写的执行报告
|
||
├── R01-T2-task.md / R01-T2-report.md ...
|
||
├── R02-brain.md ...
|
||
├── Rxx-user.md # 大脑要问用户时：问题与用户回答
|
||
├── agents.md # 子 agent 名册：每个 agent 的角色/任务/模型/状态（调度员维护）
|
||
└── FINAL.md # 大脑判定完成后的总结（调度员照抄）
|
||
```
|
||
|
||
模板见 `references/templates.md`，第一次运行时读一下。
|
||
|
||
## 子 agent 名册：每新增一个 agent，就把全表亮一遍
|
||
|
||
用户看不到后台 agent 的内部，他需要随时知道"现在有哪些 agent、各用什么模型、谁在跑谁跑完了"。所以调度员维护 `agents.md`，并且**每次启动一个新 agent（大脑或 worker）之后，以及每次有 agent 结束之后，都在对用户的回复里把整张表完整打印一遍**——不是只报新增的那一行。表格很短，重复打印的成本远低于用户去翻历史消息的成本。
|
||
|
||
表的列：`#`、`角色/任务`、`模型（指定）`、`状态`、`启动`、`结束`、`报告`。状态只用四个词：`运行中`、`完成`、`失败/受阻`、`已接替`（大脑被新实例接替时旧行标此状态）。大脑永远是第 1 行，模型一栏写 `fable`；worker 按派出顺序编号。模板见 `references/templates.md`。
|
||
|
||
"模型（指定）"是调度员传给 Agent 工具的 `model` 参数。要核实实际生效的模型，跑 `scripts/check_models.sh`（读本地 subagent 转录里每条回复的 `"model"` 字段）；在 FINAL 汇报时附上一次核实结果，这样每次运行都有"大脑确实是 Fable、worker 确实没有用 Fable"的审计证据。
|
||
|
||
## 流程
|
||
|
||
### 0. 准备
|
||
|
||
1. 确认工程根目录（当前工作目录）。创建 `./Notes/auto/<YYYYMMDD-HHMM>-<slug>/`，写 `00-goal.md`：用户的原话 + 你从对话里知道的约束（不要加自己的分析）。
|
||
2. 确保大脑的 agent 定义已安装：把本 skill 的 `agents/claude-brain.md` 复制到 `~/.claude/agents/claude-brain.md`（不存在或内容不同时覆盖）。这个定义把大脑的工具锁成 `Read, Glob, Grep`，从机制上保证它"只分析不动手"。
|
||
- 若本次会话里 `claude-brain` 这个 subagent_type 还不可用（新装的定义可能要重启会话才生效），就退回用 `general-purpose`，并在提示词里写明工具限制（见 `agents/claude-brain.md` 正文，原样附上）。告诉用户：下次重启后就会是硬限制。
|
||
|
||
### 1. 启动唯一的大脑
|
||
|
||
用 Agent 工具：`subagent_type: "claude-brain"`（或退回 `general-purpose`），**`model: "fable"`**（显式传，别依赖默认），`description: "claude-brain 主 agent"`。提示词给出：
|
||
- 运行目录的绝对路径，让它读 `00-goal.md`
|
||
- 让它按 `agents/claude-brain.md` 里的决策格式回复第 1 轮决策
|
||
|
||
记下这个 agent 的 ID/名字，在 `agents.md` 写入第 1 行并向用户打印全表。**之后每一轮都用 SendMessage 把消息发给同一个大脑**，不要新建大脑——全程只有一个大脑，它的上下文就是它对任务的理解。（SendMessage 是延迟加载工具，先 `ToolSearch("select:SendMessage")`。）
|
||
|
||
只有当大脑确实无法再联系上（报错、被终止）时，才新起一个来**接替**：提示它先通读整个运行目录恢复状态。任何时刻都不能同时存在两个大脑。
|
||
|
||
### 2. 每一轮的循环
|
||
|
||
收到大脑的决策后：
|
||
|
||
1. 把决策原文写入 `Rnn-brain.md`，在 `log.md` 追加一行。
|
||
2. 看决策里的 `状态`：
|
||
- **CONTINUE**：对每个任务，把任务单原样写入 `Rnn-Tk-task.md`，然后派 worker（下一节）。大脑标为可并行的任务在同一条消息里一起派出；有依赖的按顺序派。
|
||
- **ASK_USER**：用 AskUserQuestion（或直接在对话里）把大脑的问题原样问用户，问答写入 `Rnn-user.md`，然后把文件路径发回大脑。
|
||
- **DONE**：把大脑的总结写入 `FINAL.md`，向用户汇报（第 4 步）。
|
||
3. 本轮所有 worker 结束后，SendMessage 给大脑：`第 nn 轮报告已就绪：<各 report.md 的绝对路径>。请阅读后给出第 nn+1 轮决策。` 不要附上你自己的摘要或评价——让大脑自己读原始报告。
|
||
|
||
### 3. 派 worker
|
||
|
||
Agent 工具，`subagent_type: "general-purpose"`，`model` 取任务单里大脑指定的模型（缺省 `opus`；若写了 `fable` 视为无效，改回 `opus` 并在 log 里记一笔，因为 Fable 只属于大脑）。提示词：
|
||
|
||
```
|
||
你是 claude-brain 流程中的任务子 agent。
|
||
请先读任务单：<Rnn-Tk-task.md 绝对路径>，按其中的目标、背景和验收标准完成任务。
|
||
- 只做任务单要求的事，不扩大范围；遇到任务单没覆盖的关键决策，停下并在报告里写明，而不是自己拍板。
|
||
- 不要再派生子 agent。
|
||
- 完成（或失败/受阻）后，按任务单末尾给的报告格式，把报告写到：<Rnn-Tk-report.md 绝对路径>
|
||
- 报告要写事实：做了什么、改了哪些文件、命令输出/测量值等证据、验收标准逐条是否满足、遗留问题。失败就如实写失败。
|
||
- 这份报告是唯一会被交回大脑的东西，除此之外不要在 ./Notes/auto 以外创建协作用的 md。
|
||
```
|
||
|
||
每派出一个（或一批）worker，立刻在 `agents.md` 追加行、向用户打印全表。
|
||
|
||
worker 返回后，确认报告文件确实存在；不存在就把 worker 的最终回复原文写进该报告文件，并注明"worker 未按要求写报告，以下为其最终回复原文"。然后更新 `agents.md` 中该行的状态/结束时间/报告路径，再向用户打印全表。
|
||
|
||
### 4. 结束
|
||
|
||
大脑给出 DONE 后，向用户汇报：任务结果（引用 FINAL.md 的要点）、共几轮、`agents.md` 全表、`scripts/check_models.sh` 的实际模型核实结果、运行目录路径。
|
||
|
||
### 自主模式：用户说"别问我"
|
||
|
||
用户可能在启动时或中途说"不要停下来问我"、"所有问题主 agent 自己定"。这时调度员把这句话记入 `Rnn-user.md`，并告诉大脑：**ASK_USER 状态不再可用**，worker 报告里"需要用户决定"的点和大脑原本想问的事项全部由大脑裁定。为了用户事后能复核，要求大脑在每轮"分析"里把替用户做的裁定单列为"大脑裁定（原拟问用户）"，并在 DONE 的总结里汇总这些裁定及依据。调度员自己也不再用 AskUserQuestion，但仍照常向用户打印名册和进展。
|
||
|
||
## 30 分钟巡检：不让子 agent 空等
|
||
|
||
Worker 在等待长任务（仿真、编译、Monitor）时很容易"睡死"：等待事件到期或触发后它没有被唤醒，就一直停在那里，没人知道。实际运行里出现过 worker 停了 5 个多小时、仿真早就跑完却没人收尾的情况。所以调度员必须定时巡检，而且巡检结果要带时间打印给用户看。
|
||
|
||
**为什么是调度员而不是大脑做**：大脑的工具是只读的，看不到 agent 进程、也发不了消息；巡检是"手"的活。但"要不要改派、改派成什么"仍然是大脑的判断——调度员只做唤醒和事实汇报。
|
||
|
||
### 怎么做
|
||
|
||
1. **启动大脑之后立刻建一个每 30 分钟的巡检**（CronCreate，`recurring: true`，分钟选 `*/30` 之外的错峰值，如 `7,37 * * * *`；提示词写明"claude-brain 巡检"和运行目录）。cron 只在会话空闲时触发，这正好是 worker 可能空等的时段。到 DONE 时用 CronDelete 删掉。注意 cron 任务 7 天后自动过期。
|
||
2. **每次巡检**在工程根目录跑 `scripts/check_agents.sh <运行目录>`：它扫描本会话所有子 agent 的转录文件，列出每个 agent 的 ID、角色描述、最近一次活动时间、空闲分钟数、最后一个动作是否是"等待"（如 Monitor/后台任务），并按阈值标出 `空闲超限`。
|
||
3. **把结果带时间戳打印给用户**：一行 `巡检 HH:MM`，然后是 `agents.md` 全表，再加一张"运行中 agent 的空闲时长"小表。大脑在等报告属于正常空闲，不算超限；worker 空闲才算。
|
||
4. **发现 worker 空闲 ≥ 30 分钟且报告文件还不存在，立即介入**，按梯度：
|
||
- 第一步（唤醒）：调度员先用只读手段核实它在等的事情现在怎样了（报告文件、它等待的进程/日志/输出文件是否已到终态），然后 SendMessage 给该 worker：说明"你自 HH:MM 起没有动作"、把核实到的事实告诉它、要求按原任务单继续并写报告。只陈述事实，不替它做任务。在 `log.md` 记一行 `dispatcher | 巡检唤醒 Tk`。
|
||
- 第二步（上报）：下一次巡检它仍然没有任何新动作，或者它返回了但没有报告，就把它在 `agents.md` 标成 `失败/受阻`，把"worker 无响应，以下为其已有产物/最终回复"写进它的报告文件，然后 SendMessage 给大脑：报告路径 + "该 worker 两次巡检无响应"的事实，让大脑决定改派还是放弃。
|
||
- 调度员**不要**自己把活接过来做完，也不要擅自派新 worker——那是大脑的决定。
|
||
5. Worker 自己也要少睡：派 worker 的提示词里已经要求用 Monitor 等待而不是 sleep 循环，但 Monitor 最长 30 分钟就到期，worker 必须自己重挂；巡检就是兜这个底的。
|
||
|
||
### 防止空转
|
||
|
||
- 默认上限 **15 轮**。到了上限先暂停，把现状和大脑的最新判断告诉用户，问是否继续。
|
||
- 如果同一任务连续 3 轮失败、而大脑的新决策基本是重复派同样的活，把这一情况告诉大脑（事实陈述，不给建议），让它换思路或转 ASK_USER。
|
||
- 用户随时插话时：把用户的话原样写入 `Rnn-user.md` 并转给大脑，由大脑决定如何调整。
|
||
|
||
## 恢复上次中断的运行
|
||
|
||
用户说"继续上次的 brain 任务"时：在 `./Notes/auto/` 里找最近的运行目录（看 `log.md` 最后一行，没有 FINAL.md 的就是未完成的），新起一个大脑（这是接替，不是第二个），让它通读该目录后给出下一轮决策，轮次编号接着往下排。
|