skills-win/claude-brain/SKILL.md

name, description

name

description

claude-brain

"大脑 + 手脚" 多 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 的就是未完成的），新起一个大脑（这是接替，不是第二个），让它通读该目录后给出下一轮决策，轮次编号接着往下排。