argue

Argue — 多 Agent 辩论引擎

结构化辩论：AI Agent 独立分析、跨轮交叉质询，并通过投票达成共识。答案的置信度高于任何单个模型。

适用场景

✅ 有实际权衡的战略或架构决策、有重大影响的“应该选 X 还是 Y？”问题、风险分析、缓解确认偏误，以及重大决策的预先质量门禁。

❌ 简单的事实查询、时间紧迫的任务（辩论需要 3–7 分钟）、开放式创意生成，以及答案显而易见的问题。

运行前准备

如果 argue 不在 PATH 中，请安装（先征得用户同意——这是全局安装）：

npm install -g @onevcat/argue-cli

然后验证并配置：

argue version                          # verify installed (v0.2+)
argue config init --global             # ~/.config/argue/config.json — recommended for agent use

# Add at least 2 agents — `--agent <id>` shorthand creates provider + agent in one shot
argue config add-provider --id codex  --type cli --cli-type codex  --model-id gpt-5.4 --agent codex-agent
argue config add-provider --id gemini --type cli --cli-type gemini --model-id gemini-3.1-pro-preview --agent gemini-agent

默认采用全局配置的原因：全局配置只需设置一次，即可从任何 cwd 使用；输出会写入 ~/.argue/output/<requestId>/，不会让当前项目目录变得杂乱。只有当特定项目需要专属的 Agent 阵容时，才使用 argue config init --local——该命令会写入 ./argue.config.json，并将输出写入 ./out/<requestId>/。

有关 API 提供商、SDK 适配器、角色和系统提示词，请参阅 references/setup.md。

运行辩论

# Basic — 2 agents, 2-3 rounds, auto-consensus
argue run --task "Should we use a monorepo or polyrepo?" --verbose

# With a follow-up action: representative executes once consensus is reached
argue run \
  --task "Review the API design in docs/api.md" \
  --action "Implement the consensus recommendation and open a PR" \
  --verbose

# Open the rendered report in the hosted viewer when the run finishes
argue run --task "..." --view

常用标志（完整列表：argue --help）：

标志	用途
--agents a,b	选择参与辩论的 Agent（默认使用配置中的 defaults.defaultAgents，若未设置则使用所有已配置的 Agent）
--min-participants <n>	继续辩论所需的最少存续参与者数量（默认：2）
--on-insufficient-participants interrupt|fail	参与者数量不足时，选择发出 interrupted（默认）或直接失败
--min-rounds / --max-rounds	控制辩论深度（默认值：2 / 3）
--threshold <0..1>	共识阈值（默认：1 = 全票通过）
--action <prompt>	达成共识后执行任务
--view / --viewer-url <url>	在托管查看器中打开报告
--input <file>	为复杂配置提供 JSON 输入
--verbose / -v	实时输出 Agent 的推理过程

2 个 Agent 进行 3 轮辩论通常需要 3–7 分钟。每轮默认超时上限为 20 分钟（每个任务也一样，默认跟随每轮的超时上限）；对于耗时较长的审查，请调高 --per-round-timeout-ms。

查看结果并执行操作

运行完成后，argue 会显示请求 ID 和查看器提示。你可以随时打开：

argue view                  # most recent run
argue view <request-id>     # specific run

托管查看器完全在客户端渲染 result.json（通过 gzip + base64url 编码放在 URL 片段中——不会上传任何内容）。使用 --viewer-url 指向可自托管的查看器。

若要将辩论结果作为上下文执行后续任务：

argue act --result ~/.argue/output/<requestId>/result.json --task "Write a summary blog post"
argue act --result ./out/<requestId>/result.json --task "Implement the changes" --agent codex-agent

输出文件

每次运行后，argue 都会将文件写入 ~/.argue/output/<requestId>/（全局配置）或 ./out/<requestId>/（项目本地配置）：

• result.json — 完整的结构化结果
• summary.md — Markdown 报告（完成时写入）
• events.jsonl — 事件流（实时写入，崩溃后仍会保留 — 如果运行被终止，可解析此文件获取部分结果）
• error.json — 错误详情（仅在失败时写入）

结果状态：consensus | partial_consensus | unresolved | interrupted | failed。

如果辩论参与者人数低于要求，应优先采用默认的 interrupted 路径，以便下游工具仍能获取结构化结果。只有当调用方明确需要旧版硬失败语义时，才强制设置 onInsufficientParticipants: "fail"。

如果需要以编程方式解析 result.json，规范的架构位于 packages/argue/src/contracts/result.ts。

提示

1. 围绕决策来提问，而不是讨论主题。“我们应该用 SwiftUI 还是 UIKit？”比“告诉我有关 SwiftUI 的信息”更好。
2. 补充背景信息。“我们应该使用 monorepo 吗？背景：8 个微服务、3 个团队、Node+Go”能得到更有针对性的论点。
3. 2–3 个 Agent 效果最佳。同一轮中的 Agent 会并行调度，因此总耗时主要取决于轮数，而不是 Agent 数量 — 增加 Agent 几乎不会增加耗时。真正的成本是令牌：每个额外的 Agent 都会提出自己的论点，其他每个 Agent 还必须将这些论点作为同伴上下文来阅读，因此令牌用量大致随 N² 增长。如果用户的配置中有 3 个以上 Agent，请显式传入 --agents a,b,c 以选取一组精简的 Agent，或在配置文件中设置一次 defaults.defaultAgents。
4. 当达成共识后需要驱动代码更改或其他现实世界的副作用时，使用 --action。

故障排除

常见错误及其修复方法，请参见 references/troubleshooting.md。