neal 多 agent 怎么用：planner、coder、reviewer 分工
npm 装 @navels/neal，setup 配跨厂商 planner/coder/reviewer，neal run/plan/execute/resume 跑计划驱动循环。
一个 agent 写久了会漂，自己改自己审又容易放水。neal 多 agent 怎么用：用 @navels/neal 把 planner、coder、reviewer 拆成三个可配角色，各自选厂商与模型，按 PLAN.md 驱动「规划 → 分 scope 编码 → 对抗式审查 → 最终总审」循环；状态落在仓库 .neal/，中断可 neal resume。
三个角色各管什么
neal 名字来自 anneal（退火）：多轮受控调整直到稳定。设计上有两个硬选择（README 原话）：coder 与 reviewer 必须不同 vendor，审查才是第二双眼睛；每个 scope 给 coder Fresh context，长计划不会把早期指令挤没。
neal 源于作者做大版本 Ember 升级时的手工经验：单 agent 会漂，于是把「Claude 审 Codex diff、来回粘贴直到双方满意」自动化。planner 把自然语言 PLAN 变成带 scope 的 execution shape；reviewer 跨 scope 保留上下文，coder 每 scope 清空，这是和单会话 subagent 树最大的行为差异。.neal/ 里保留 plan 修订版、每 scope diff、review 结论，比只看最终 commit message 更易 audit。
| 角色 | 典型职责 |
|---|---|
| planner | 读你的 PLAN.md，产出可执行的 scope 与实现形状 |
| coder | 按 scope 改仓库、跑验证、可 commit |
| reviewer | 只读审查，adapter 层机械禁止写文件 |
planner 默认继承 coder 的 provider 配置，也可单独指定。reviewer 在 Codex 侧走 OS sandbox，Claude 侧走 SDK tool allowlist，OpenRouter 模型用 neal 自管 jailed toolset（见仓库 SECURITY.md）。这和 Skills 和 MCP 有什么区别 里讲的 MCP 连接层不同：neal 是本地 orchestrator，底层仍调你已有的 Claude Code CLI 或 Codex CLI，不暴露新的 JSON-RPC 工具面。
安装与环境要求
npm install -g @navels/neal
neal setup
neal check
要求 Node.js >= 24.18.0。neal setup 写 ~/.neal/config.yml，典型组合是 Codex coding + Claude review：
agent:
coder:
provider: openai-codex
model: null
reviewer:
provider: anthropic-claude
model: null
model: null 表示用 provider 默认模型。无 Claude/Codex 订阅时，可选 OpenRouter 的 openai-compatible provider，跑 neal compat 对照 兼容模型白名单 再上大计划。OpenRouter 需 OPENROUTER_API_KEY 与 base_url: https://openrouter.ai/api/v1。
neal setup --provider anthropic-claude --all-roles 可脚本化三角色同厂商；--force 覆盖已有 config。neal check 在非交互 shell 只验 YAML 不 ping 模型，CI 里应分两步：先 neal check，再在允许 live call 的环境跑交互 check。Writer 命令要求仓库至少有一个 commit，空 repo 先 git commit --allow-empty 再 neal run。
从 PLAN.md 到 neal run
在 Git 仓库根（已有至少一次 commit）写计划文件，例如：
Add a "Sign in with Google" option to the login page using OAuth 2.0.
Store the resulting session the same way the existing email/password login does.
一条命令跑全程：
neal run PLAN.md
neal run 先走 planner/reviewer 细化计划，再按 scope 执行 coder/reviewer 循环，scope 通过后 commit，全部完成后还有一轮总审。想先看细化计划再动手：
neal plan PLAN.md
# 人工改 PLAN 或 neal 输出
neal execute PLAN.md
默认会把各 scope commit squash 成更少提交；保留逐 scope 历史加 --no-squash。多个计划串行：neal run tmp/A.md tmp/B.md。CI 无人值守加 --unattended，blocked 时不会等 stdin。neal status --json 可给外部 harness 读 run 阶段，neal-swebench 就是这么驱动 SWE-bench Pro 的。
planner/reviewer 循环会把你的 PLAN.md 细化成带 scope 边界的执行文档，这一步往往比单次 agent 聊天更耗 token，但能减少 coder 在错误方向上的返工。scope 过大时 coder 可拆 sub-plan，见仓库 docs/plan-format.md；你应在 PLAN 里写清验收命令（如 pnpm test、go test ./...），reviewer 才有硬门槛可卡。
resume、review 与 OpenRouter 路径
执行中断或 coder 被 blocker 卡住：
neal status
neal resume
neal resume --run <run-id> --message "只修 failing test，别动 auth 模块"
.neal/ 存 run id、scope 状态、patch 与日志；neal resume 在需要人工方向时会说明缺什么。与 agent-hop 跨工具续会话 不同：hop 搬运已有 agent 会话，neal 是计划驱动的多角色流水线，resume 续的是 neal run 状态机。
已有 commit 想做 plan-free 审查：
neal review --last 3
neal review "Focus on auth/session handling." --since origin/main
review 模式会丢弃 review 期间 worktree 里的未提交改动。OpenRouter 用户先 neal compat --model <slug> 再 neal run；免费池模型 README 警告常作 coder 失败率高。作者另维护 neal-swebench 用 SWE-bench Pro 压测角色配对，公开数字为作者自报 benchmark 结果，本文未独立复现；选型时先用你自己仓库的 neal check 与小规模 PLAN 试跑，再参考 neal-swebench 榜单。
neal review 与 plan 流程独立：适合已 merge 或本地多 commit 后做只读审计，结束时 worktree 改动会被丢弃，避免 review 讨论污染代码。--since origin/main 限定 diff 范围；--last 3 只看最近三次 commit。bounded autonomous recovery 指 neal 在 coder/reviewer 僵局时会尝试自动协商几轮，仍卡住才 exit 等你 resume --message。
适用场景与代价
适合：大 refactor、跨多文件功能、你本来就会让 Claude 审 Codex diff 的手工流程；需要 scope 自拆分（coder 发现 scope 过大可衍生 sub-plan）；要 auditable 的 .neal/ 轨迹。不适合：单文件 one-shot fix（启动三角色过重）；无法让 reviewer 访问只读 git 的环境；必须单模型闭环且不接受多 provider 账单。
plan 文件建议写验收标准而非实现细节，把「怎么做」留给 planner/coder 在仓库内 grounded 搜索。例子 repo examples/issue-triage-js 带 PLAN.md 与安全说明，clone 后 neal run PLAN.md 可 smoke。--no-squash 适合你想逐 scope review commit message 的团队；默认 squash 则像一次大提交，方便开 PR 但丢中间叙事。多 plan 串行时前一 plan 的 commit 会成为后一 plan 的 baseline，顺序写错会导致依赖颠倒。
neal 会创建真实 commit，默认 squash 仍改写历史，请在分支上跑。neal review 只读但会启动 coder 提案，注意 CI secret 不要进 prompt。Show HN 2026-08-13 帖与 GitHub 仓库同期出现，版本迭代快，具体子命令以 neal help 输出为准。若团队已深度绑定 Claude Code subagent，neal 是外挂编排层，不会替换 Claude 内置 Agent Teams，但可以 Codex 写、Claude 审这类跨栈组合。
neal compat 对 OpenRouter 模型做三轮 smoke（planner/coder/reviewer 角色各测一次），输出 PASS/FAIL 白名单，不是能力排行榜。作者用 neal-swebench 在 SWE-bench Pro 上对比角色配对，社区应把数字当「同一 harness 下的相对参考」，换仓库语言栈或测试命令后排名可能变。Node 24.18+ 是硬门槛，旧 LTS 需先升级再 npm i -g @navels/neal。
Show HN 2026-08-13 与 repo 同步亮相，MIT 许可，作者呼吁捐赠 MusiCares。生产使用前读 SECURITY.md：reviewer 只读由 adapter 机械保证，但 coder 仍有写仓库权限，plan 里别写「顺便 rot 生产密钥」类越界任务。neal squash 可在事后整理 commit，和 execute --no-squash 相对，适合 run 完成后想要干净 history 的场景。
若你已有 Claude Code auto mode 默认审批流，neal 仍独立：它是「多角色编排 + 跨厂商审稿」，不是替换 CLI 权限模式。选型时先问要不要第二家模型当 reviewer，再决定是否引入。