| name | agent-brainstorm |
| metadata | {"version":"0.1.3"} |
| description | Multi-agent brainstorming: async opinion collision with expert personas. Mixed Codex/Claude Code engine. Use when multiple AI agents need to collaboratively discuss, debate, and converge on solutions through structured dialog. Triggers: brainstorm, multi-perspective discussion, opinion collision, expert debate, war room, collective intelligence, 头脑风暴, 多视角讨论, 集思广益. |
Agent 头脑风暴技能 — 异步观点碰撞空间
核心概念
你负责编排一场多 Agent 头脑风暴。不同于任务编排（每个 Agent 独立执行任务），
头脑风暴的 Agent 通过一个共享讨论空间异步交换观点、质疑与建设性辩论，最终收敛到高质量方案。
支持两种 Agent 引擎：
- Codex SDK (
@openai/codex-sdk) — OpenAI Codex 代理
- Claude Agent SDK (
@anthropic-ai/claude-agent-sdk) — Anthropic Claude Code 代理
架构:
你 (Orchestrator)
│
├── 启动 Brainstorm Engine (Node.js HTTP Server + Web 面板)
│ └── 讨论空间 API: 供 Agent 发表/阅读/回应观点
│
├── 派发 N 个 Agent (每个可独立选择 Codex 或 Claude Code 引擎)
│ └── 每个 Agent 通过运行时生成的 discuss.py CLI 与讨论空间交互
│
└── 讨论结束后生成 synthesis.md 综合报告
与 agent-task-orchestration 的区别:
| 维度 | 任务编排 | 头脑风暴 |
|---|
| Agent 关系 | 独立执行，互不通信 | 共享空间，互相响应 |
| 成功标准 | 每个任务通过测试 | 讨论收敛到共识 |
| 产出物 | 代码文件 | 方案文档 (synthesis.md) |
| 节奏控制 | DAG 拓扑排序 | 异步自治 + 收敛检测 |
| Agent 引擎 | Codex 专用 | Codex 或 Claude Code |
Fan-out / Fan-in（观点发散 → 综合收敛）
- Fan-out：每个 Agent 独立阅读代码/资料，先产出"立场明确 + 有证据"的首轮观点（opinion）。
- 碰撞：通过
challenge/build/respond 机制让观点互相校正，而不是并列堆叠。
- Fan-in：由 Orchestrator 生成
synthesis.md，把共识/分歧/决策点收敛成一个可执行结论。
前置条件
运行需要 Node.js ≥18.0.0 和至少一个引擎已认证。
cd <SKILLS_DIR>/agent-brainstorm && npm install
引擎认证 (至少完成一个):
- Claude: 在终端运行
claude 完成交互登录，或 export ANTHROPIC_API_KEY='sk-ant-...'
- Codex: 运行
codex login，或 export OPENAI_API_KEY='sk-...'
工具
node <SKILLS_DIR>/agent-brainstorm/scripts/brainstorm.mjs <session-file> [options]
node <SKILLS_DIR>/agent-brainstorm/scripts/brainstorm.mjs <session-file> --engine claude [options]
node <SKILLS_DIR>/agent-brainstorm/scripts/brainstorm.mjs --list --cwd <project-dir>
node <SKILLS_DIR>/agent-brainstorm/scripts/brainstorm.mjs --status --cwd <project-dir>
node <SKILLS_DIR>/agent-brainstorm/scripts/brainstorm.mjs --clean --cwd <project-dir>
工作流
Phase 1: 理解需求 & 设计讨论
理解用户想讨论什么。关键问题:
- 议题是什么？技术选型？架构设计？产品方向？
- 需要哪些视角？架构师、安全专家、产品经理？
- 有什么约束？技术栈限制、时间限制、预算限制？
- 代码上下文？哪些代码/文档与讨论相关？
Phase 2: 创建 Session 配置
创建 JSON 配置文件（建议放在 .brainstorm/ 或项目根目录下的临时文件）:
{
"topic": {
"title": "NightOwl 事件调度架构选型",
"context": "我们正在构建一个 24/7 AI 代理系统……",
"goals": ["选择最适合的事件调度模型"],
"constraints": ["必须使用嵌入式 SQLite"]
},
"agents": [
{
"id": "architect",
"name": "系统架构师",
"expertise": "系统设计、事件驱动架构",
"engine": "claude"
},
{
"id": "reliability",
"name": "可靠性工程师",
"expertise": "容错设计、重试策略"
},
{
"id": "devil",
"name": "魔鬼代言人",
"expertise": "寻找方案漏洞",
"engine": "codex"
}
],
"config": {
"codebase_paths": ["packages/daemon/src/"]
}
}
引擎选择规则:
- 每个 agent 可通过
"engine": "codex" 或 "engine": "claude" 指定引擎
- 未指定则继承 CLI 的
--engine 参数（默认 codex）
- 支持混合模式：同一场讨论中不同 agent 使用不同引擎
- 引擎降级：若指定引擎不可用，自动切换所有受影响 Agent 到可用引擎（而非阻断）
Agent 数量建议: 3-5 个。太少缺乏碰撞，太多产生噪声。
角色设计关键:
- 每个角色代表一个独立视角，避免重叠
- 至少包含一个"挑战者"角色（如
devil），专门找漏洞
- 角色的
expertise 字段要具体，引导 Agent 的分析方向
常用角色参考: 阅读 references/agent-protocol.md
Phase 3: 启动讨论
node <SKILLS_DIR>/agent-brainstorm/scripts/brainstorm.mjs \
.brainstorm/session.json \
--cwd <project-dir> \
--approval-mode full-auto \
--timeout 30 \
--port 8899
参数说明:
| 参数 | 默认 | 说明 |
|---|
--cwd | 当前目录 | Agent 的工作目录（项目根目录） |
--port | 随机 | 讨论服务端口 |
--timeout | 30 | 最大讨论时间（分钟） |
--engine | codex | 默认 Agent 引擎，每个 agent 可在 JSON 中通过 engine 字段覆盖 |
--approval-mode | full-auto | Agent 执行策略 |
--dry-run | false | 预览不执行 |
⚠️ 关键：此命令是阻塞式的 — 进程在所有 Agent 完成讨论并生成 synthesis.md 后才退出。
你不需要手动轮询状态、不需要 sleep/wait、不需要后台运行。直接执行并等待命令返回即可。
这意味着：无论你是 Codex、Claude Code 还是其他 Agent 引擎，只要执行此命令并等待退出，一切都由引擎自动处理。
启动后引擎内部流程:
- 开启 HTTP 讨论服务 + 自动打开浏览器面板（用户可实时监控）
- 动态生成
discuss.py CLI 工具到 .brainstorm/
- 按需加载 SDK，并行派发所有 Agent
- Agent 自主讨论（Session Renewal Loop 确保全员同开同停）
- 多数投票 conclude → 生成
synthesis.md → 进程退出
Phase 4: 等待完成
引擎进程会自动阻塞直到讨论结束，你只需等待 Phase 3 的命令返回。
- 进程退出码
0 = 讨论正常完成
- 进程退出码
1 = 有 Agent 失败
- 超时兜底：到达
--timeout 后引擎自动强制结束并退出
禁止：不要把引擎命令放到后台然后手动轮询。这会浪费 Agent turns 且容易出错。
正确做法：直接执行命令，让它阻塞到完成。引擎内部已包含所有监控、续期、超时逻辑。
Phase 5: 交付报告
讨论结束后，Engine 自动生成 .brainstorm/<session-id>/synthesis.md，包含:
- 各 Agent 的核心观点
- 提出的方案
- 总结投票
- 完整讨论日志
向用户汇报时:
- 阅读
synthesis.md
- 提炼出关键共识和分歧
- 给出你作为 Orchestrator 的最终建议
- 如果有未解决的分歧，明确列出供用户决策
讨论空间机制
Agent 如何交互
每个 Agent 通过运行时生成的 discuss.py CLI 工具参与讨论:
python3 .brainstorm/discuss.py <agent_id> <command> [args...]
命令:
topic — 查看议题和当前状态posts — 查看所有已发表观点new — 只查看新观点post <content> — 发表意见respond <post_id> <content> — 回应某个观点propose <content> — 提出方案agree <post_id> — 同意challenge <post_id> <reason> — 质疑build <post_id> <addition> — 扩展conclude <summary> — 投票结束status — 查看收敛状态
收敛检测
Discussion Space 自动追踪讨论阶段:
exploring → 所有 Agent 至少发布 1 个 opinion
debating → 回应数 ≥ Agent 数 且 agree > challenge
converging → 过半 Agent 投 conclude 票
concluded → 所有 Agent 完成或超时
异步时间差处理
核心设计: Agent 不需要同步。每个 Agent 按自己的节奏:
- 花时间阅读代码（可能 2-5 分钟）
- 发表深度观点
- 检查他人观点并回应
- 循环直到满意
先完成的 Agent 的观点自动进入讨论空间，后到的 Agent 能看到所有前序观点。
这种异步模式比同步更好——允许每个 Agent 充分思考。
安全阀
| 阀 | 值 | 触发后 |
|---|
| 全局超时 | --timeout (默认 30min) | 强制 concluded |
| SIGINT 保护 | 3 次 Ctrl+C | 讨论中 Ctrl+C 被拦截，3 次强制退出（保存状态） |
| 引擎降级 | 自动 | 一个引擎不可用时自动切换到另一可用引擎 |
| Agent session 上限 | SDK 内部控制 | Agent 自然结束 |
| 最终产出 | synthesis.md | 即使讨论不完美也有记录 |
故障诊断
| 症状 | 原因 | 解决 |
|---|
Cannot find module | npm 依赖未安装 | cd <SKILLS_DIR>/agent-brainstorm && npm install |
Preflight failed | CLI 未安装或未认证 | 见"前置条件"完成认证 |
| Agent 长时间 0 posts | 模型不兼容标准工具集 | 确认 Claude Code 使用官方模型（非第三方代理模型） |
API Error 400 | Agent 使用了不存在的工具 | 同上，模型兼容性问题 |
| SIGINT 被拦截 | 讨论中 Ctrl+C 保护 | 连按 3 次 Ctrl+C 强制退出 |
| 引擎降级日志 | 指定引擎不可用 | 正常行为，已自动切换 |
参考文档
输出约定
- 思考/规划/报告: 中文
- 代码/命令/文件名: English
- Session 配置: JSON (中英混合)
- Agent prompt: 中文为主 (让 Agent 更自然地思考)
