plan-council

默认流程（light）：DeepSeek V4.1 Flash 起草一份计划，其他模型评审：

• 改动任务：GPT 6 Luna 看「约束与范围」，Muse 看「可验证性」；
• 缺陷任务：起草者先用假设表诊断根因，GPT 6 Luna 和 DeepSeek V4.1 Flash（都开最高档 max）并行做「诊断」质疑，Muse 看「可验证性」。三份缺陷草案的对比里，DeepSeek 找到的问题最多、没有一次误伤，擅长测试替身失真、出错后不落库这类漏洞；Luna 找到的少，但「按会话匹配会误停下一轮」「修完 SQL 后确认仍不查有效期」「过期清理波及所有用户」这类生命周期与影响面漏洞只有它抓到，两者互补。DeepSeek 既起草又兼一路诊断，是有意的取舍：同族自评可能共享盲区，由 Luna 补。

不做综合重写，评审意见原样交给人裁决。每份产出里的 path:line 引用都由脚本核验。编排由 scripts/council.py 完成，你只负责触发和解读结果。

改动任务一次运行 3 次模型调用，约 10–30 分钟；缺陷任务 4 次，约 15–25 分钟（两路诊断并行，等的是较慢的一路：DeepSeek 最高档实测 9–12 分钟、Luna 最高档 7–10 分钟；诊断超时单独放到 1 小时）。单文件修复不必用它。

设计原则是让模型之间做加法、不互相否定：

• 草案和评审各自独立；
• 评审只追加意见，不重写方案；
• 只有附反例的 [反驳] 能推翻方案的论断，[顾虑] 不能；
• 分歧交人裁决。

早期一次历史任务回放里，多稿综合（11.5/15）不如单份草案（13–15）：综合把写准的位置概括掉了，评审还用「测试设施不支持」这类顾虑否掉了正确的少数意见。

步骤

1. 准备简报：仓库有任务卡（如 tasks/T-xxxx.md）就直接用。否则写一份 Markdown，包含要解决的问题、已知定位、验收标准、边界（不要做什么）、相关 ADR。简报写不清的地方，计划也会写不清。

2. 缺陷任务先收集运行证据：模型只能读到代码。粗描述的缺陷只靠代码，根因很容易归错：盲测中 7 份计划全部把同一个粗描述缺陷的根因归错，原实现者是靠日志定位的。收集这几类证据，各存成文本文件：

   • 故障时间窗口内的日志片段（.local-dev/logs/ 等，按时间、请求 ID、会话 ID 截取）
   • 会话事件或工具调用记录
   • 复现步骤与实际结果

   每份不超过 64KB，脚本会自动脱敏密钥、token 和邮箱。证据里出现个人数据或客户数据时，先删掉再传。

3. 后台运行：

   plan-council run --brief <简报.md>

   缺陷任务：

   plan-council run --brief <简报.md> --kind bug --evidence <日志片段.txt> --evidence <复现记录.md>

   默认在当前仓库工作区（含未提交改动）的快照上运行。一次运行可能超过 30 分钟；macOS 下运行期间会用 caffeinate 阻止空闲睡眠（进程结束自动解除，配置 keep_awake.enabled 可关），但合盖照样睡眠，长跑时别合盖。你所在的 agent 如果会限制后台任务时长，就让它脱离运行，再轮询运行目录里的 report.md 是否生成：

   nohup plan-council run --brief <简报.md> --out <运行目录> > <运行目录>.log 2>&1 < /dev/null &

   被中途打断时，用 --resume <运行目录> 续跑，已完成的步骤会直接复用。
   • --kind bug：起草者先写「根因」：至少 3 个跨层面的假设（业务逻辑 / 提示词与规则 / 运行层），只有矛盾证据才能判不成立，缺证据的标「待查」；评审换成两路「诊断」+「可验证性」。任务卡 type: bug 时会自动识别
   • --rev <commit>：从某次提交建快照，用来回放历史任务
   • --out <目录>：指定运行目录
   • --resume <运行目录>：失败或中断后复用已完成的步骤继续
   • --stop-after draft：只要草案，不评审

4. 读 report.md（命令最后打印出它和计划的路径）。评审发现按类型分组：

   • 先核实（缺陷任务）：反驳了方案判为「成立」的假设（开头定位点名它，或论断里判它「不成立」「未裁决」等），单列在最前。一次前端缺陷回放里 GLM 就这样把正确根因打成「未裁决」：引用的位置都真实存在却不支撑结论，所附检查输出是编的，脚本核验拦不住；
   • 反驳：附了反例；
   • 被质疑但未被证伪：顾虑，以及缺反例、降级成顾虑的反驳；
   • 补充。

   缺陷任务还会列出「待查假设」和「假设复核对照」：方案原有的每个假设并排列出两份诊断评审的结论，结论不同的标「分歧」，评审新增的假设按来源分列。某一路诊断失败时报告记为缺席，另一路照常给出。

5. 读 plan.md：标了【核验失败】或【核验警告】的条目不能直接当事实用。评审全文在 critiques/*.md。

6. 逐条核实再交给用户：

   • 先核实与反驳：亲自复现反例（读引用的代码、实际跑一遍），成立才改计划；脚本只核验引用存在，不核验引用是否支撑结论；
   • 被质疑但未被证伪：方案的论断保留，把顾虑连同消除办法列给用户；
   • 补充：核实后并入计划；
   • 待查假设：列出要补的证据。

   评审建议若与简报的验收标准或边界冲突，一律交用户裁决，不要自行采纳。

在不同 agent 里调用

本技能目录放进 agent 的全局技能目录（如 ~/.agents/skills/plan-council，再从 ~/.claude/skills、~/.pi/agent/skills 等处链接过去）后，Claude Code、Codex、pi、kimi、WorkBuddy、CodeBuddy、zcode、Command Code 等 agent 都能看到。不管从哪个 agent 调用，前提相同：

• 命令：plan-council，即本技能的 bin/plan-council，安装时链接进 PATH（如 ~/.local/bin）。agent 的 shell 没加载这个 PATH 时，用它的完整路径。它会自己找 Python 3.9+（PLAN_COUNCIL_PYTHON 可指定）。
• 要联网、要能起 sandbox-exec：模型经 pi 走网络；模型的读权限靠 macOS sandbox-exec 隔离。在自带沙箱的 agent（如 Codex）里，按该 agent 的方式申请放开沙箱或提权运行本命令。沙箱起不来时 run 开头会直接报错并说明原因，不会让每次模型调用都白等重试。
• 跑得久：一次 10–40 分钟。会限制命令时长的 agent 用上面的 nohup … & 写法后台运行，再轮询运行目录里的 report.md。
• 第一次在某个 agent 里用：先跑 plan-council doctor，确认模型能调通、思考档位有效。

配置

council.json 只用 pi，只用这五个模型：pi 里 opencode-go 的 DeepSeek V4.1 Flash、Muse Spark 1.3 Contributor、GLM-5.3-Flash、GPT 6 Luna，以及 minimax-cn 的 MiniMax-M3.1-Flash。这是作者定的模型白名单：不要擅自加别的模型或别的 provider；要换模型，先问用户，得到同意再改 council.json 并跑 doctor。

• models：每个模型定义一次，只有一条路由。
• light：默认流程的起草者和评审视角，按名字引用 models；bug_critics 是缺陷任务的评审视角。评审模型一般不同于起草模型；例外是缺陷诊断里 DeepSeek 兼一路（作者定的），另一路必须是别的模型。
  • 一个视角可以写成列表，同一角色卡、同一提示词并行跑多份，例如 "diagnosis": [{"use": "gpt6luna", "thinking": "max"}, {"use": "deepseek", "thinking": "max"}]；{"use": 名字, 覆盖字段} 复用 models 里的定义、只改思考档位。
• roles：--mode full 的实验性多稿流水线。回放里效果不如单稿，用户没要求就不用。
• rate_limit.waits：临时限流（429 rate limit、overloaded、503）或接口报错（API error、网络错误、流式响应中断、空响应）时按这些秒数等待，再对同一模型原样重试；额度用尽（usage limit 等）直接失败，不换模型。只有输出格式不合格才带「请重写」反馈重试。

改完配置先运行：

plan-council doctor

它会让每个模型读出 AGENTS.md 的第一行，以此确认模型能调通、读文件工具真正生效；再按 pi 模型库核对每个模型配置的思考档位是否有效。

坑

• pi 必须加 --no-extensions。装了扩展时 --tools 白名单不生效，工具列表变成 (none)，模型就会编造路径（实测出现过 paymentService.ts:47 这类不存在的引用）。
• 在脚本里调用 pi -p 要把 stdin 接到 /dev/null，否则会卡在读管道输入上。
• 思考档位各模型不同，配错了 pi 不报错：会悄悄换成最近的有效档（先往上找）。opencode-go 上 GLM-5.3-Flash 只有 low / high / max，配 medium 实际按 high 跑；GPT 6 Luna 有 off / low / medium / high / xhigh / max。档位以 ~/.pi/agent/models-store.json 的 thinkingLevelMap 为准（标 null 的无效），doctor 和 run 开头都会提示。
• MiniMax-M3.1-Flash（minimax-cn）已不在默认流程里，换回来用时注意：同时调用多路会被限流（实测 6 路并发全部返回 429 已达到 Token Plan 速率限制（2062）），回放要一个接一个跑；偶尔连续返回空响应（实测连续三次、第四次才成），默认重试次数因此放到四次；平时 4–6 分钟，但有一次跑了 46 分钟仍无产出（进程一直在收发数据），只能手动停掉。它的高档与最高档得分几乎一样，用高档即可。
• 模型的读文件工具能读快照以外的路径（实测会读 ../brief.md）。macOS 下默认用 sandbox-exec 限制读权限：源仓库、其他运行目录（~/.cache/plan-council 与本次运行目录的上一级）、各编码助手的会话记录（codex、Claude、pi、kimi、workbuddy、commandcode、opencode、omp）都不可读，只能读本次运行目录；规则写在运行目录的 sandbox.sb。非 macOS 没有这层保护。
• 会话记录必须封：一次回放时原修复的 codex 会话就在 ~/.codex/sessions 里，模型的读文件工具读得到；GLM 也实测 grep 过 home 下 pi 的安装目录。新装了别的编码助手，把它的会话目录加进 council.py 的 AGENT_SESSION_DIRS。
• 快照里没有 .git，模型看不到提交历史。回放历史任务（--rev）时，评分标准、原始任务卡、含答案的较新快照不要放进运行目录或它的上一级；放在别处时，加进配置的 sandbox.deny_read。
• 每一步的完整命令保存在运行目录的 raw/<步骤>.sh，可以单独重跑；原始输出在 raw/<步骤>.out / .err。