Back to Details

argue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Argue — Multi-Agent Debate Engine

Argue — 多Agent辩论引擎

Structured debates where AI agents analyze independently, cross-examine across rounds, and converge on consensus through voting. Higher-confidence answers than any single model alone.
AI Agent独立分析、多轮交叉质证，并通过投票达成共识的结构化辩论。相比单一模型，能提供可信度更高的答案。

When to Use

适用场景

✅ Strategic / architectural decisions with real trade-offs, "Should we X or Y?" with real stakes, risk analysis, confirmation-bias mitigation, pre-commit quality gates on big decisions.
❌ Simple factual lookups, time-critical tasks (debates take 3–7 minutes), open-ended creative generation, questions with obvious answers.
✅ 涉及实际权衡的战略/架构决策、涉及实际风险的“我们应该选择X还是Y？”问题、风险分析、缓解确认偏差、重大决策前的预提交质量把关。
❌ 简单事实查询、时间紧迫的任务（辩论需3–7分钟）、开放式创意生成、答案明确的问题。

Pre-flight

前置准备

If 
argue
is not on PATH, install it (confirm with the user first — this is a global install):
bash
npm install -g @onevcat/argue-cli
Then verify and configure:
bash
argue version                          # verify installed (v0.2+)
argue config init --global             # ~/.config/argue/config.json — recommended for agent use
如果
argue
未在PATH中，请安装它（先确认用户同意——这是全局安装）：
bash
npm install -g @onevcat/argue-cli
然后验证并配置：
bash
argue version                          # 验证安装（v0.2+）
argue config init --global             # ~/.config/argue/config.json — 推荐Agent使用

Add at least 2 agents — 
--agent <id>
shorthand creates provider + agent in one shot

至少添加2个Agent — 
--agent <id>
简写可一次性创建提供者和Agent

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

**Why global by default**: a global config is set up once and works from any cwd, and outputs go to `~/.argue/output/<requestId>/` instead of cluttering the current project tree. Use `argue config init --local` only when a specific project needs its own dedicated agent line-up — that writes `./argue.config.json` and outputs to `./out/<requestId>/`.

For API providers, SDK adapters, roles, and system prompts, see [references/setup.md](references/setup.md).
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

**默认全局安装的原因**：全局配置只需设置一次，可在任意工作目录使用，输出文件会保存到`~/.argue/output/<requestId>/`，不会占用当前项目目录空间。仅当特定项目需要专属Agent阵容时，才使用`argue config init --local`——这会生成`./argue.config.json`并将输出保存到`./out/<requestId>/`。

关于API提供者、SDK适配器、角色和系统提示，请查看[references/setup.md](references/setup.md)。

Running Debates

运行辩论

bash
undefined
bash
undefined

Basic — 2 agents, 2-3 rounds, auto-consensus

基础用法 — 2个Agent，2-3轮，自动达成共识

argue run --task "Should we use a monorepo or polyrepo?" --verbose
argue run --task "Should we use a monorepo or polyrepo?" --verbose

With a follow-up action: representative executes once consensus is reached

带后续操作：达成共识后由指定Agent执行任务

argue run
--task "Review the API design in docs/api.md"
--action "Implement the consensus recommendation and open a PR"
--verbose
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

Useful flags (full list: `argue --help`):

| Flag                            | Purpose                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `--agents a,b`                  | Pick which agents participate (default: `defaults.defaultAgents` from config, else **all configured agents**) |
| `--min-rounds` / `--max-rounds` | Control debate depth (defaults: 2 / 3)                                                                        |
| `--threshold <0..1>`            | Consensus threshold (default: 1 = unanimous)                                                                  |
| `--action <prompt>`             | Execute task after consensus                                                                                  |
| `--view` / `--viewer-url <url>` | Open report in the hosted viewer                                                                              |
| `--input <file>`                | JSON input for complex setups                                                                                 |
| `--verbose` / `-v`              | Stream agent reasoning live                                                                                   |

Debates typically take 3–7 minutes for 2 agents × 3 rounds. Defaults are 10 min per task and 20 min per round; bump them for heavy reviews.
argue run --task "..." --view

实用参数（完整列表：`argue --help`）：

| 参数                            | 用途                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `--agents a,b`                  | 选择参与辩论的Agent（默认：配置文件中的`defaults.defaultAgents`，否则为**所有已配置的Agent**） |
| `--min-rounds` / `--max-rounds` | 控制辩论深度（默认：2 / 3）                                                                        |
| `--threshold <0..1>`            | 共识阈值（默认：1 = 全票通过）                                                                  |
| `--action <prompt>`             | 达成共识后执行指定任务                                                                                  |
| `--view` / `--viewer-url <url>` | 在托管查看器中打开报告                                                                              |
| `--input <file>`                | 复杂场景的JSON输入                                                                                 |
| `--verbose` / `-v`              | 实时流式输出Agent的推理过程                                                                                   |

辩论通常需要3–7分钟（2个Agent × 3轮）。默认每个任务时限10分钟，每轮时限20分钟；如需处理复杂评审可延长时限。

Viewing & Acting on Results

查看结果并执行后续操作

When a run finishes, argue prints the request id and a viewer hint. Open it any time:
bash
argue view                  # most recent run
argue view <request-id>     # specific run
The hosted viewer renders 
result.json
entirely client-side (gzip + base64url in the URL fragment — nothing is uploaded). Use 
--viewer-url
to point at a self-hosted viewer.
To run a follow-up task using a debate result as context:
bash
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会打印请求ID和查看器提示。可随时打开查看：
bash
argue view                  # 查看最近一次运行结果
argue view <request-id>     # 查看指定运行结果
托管查看器完全在客户端渲染
result.json
（URL片段中包含gzip + base64url编码内容——无数据上传）。可使用
--viewer-url
指向自托管的查看器。
如需以辩论结果为上下文执行后续任务：
bash
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

Output Files

输出文件

After every run, argue writes to 
~/.argue/output/<requestId>/
(global config) or 
./out/<requestId>/
(project-local config):
  • result.json
    — full structured result
  • summary.md
    — markdown report (written on completion)
  • events.jsonl
    — event stream (written live, survives crashes — parse it for partial results if a run is killed)
  • error.json
    — error details (only on failure)
Result status: 
consensus
| 
partial_consensus
| 
unresolved
| 
failed
.
If you need to parse 
result.json
programmatically, the canonical schema lives at 
packages/argue/src/contracts/result.ts
.
每次运行后，argue会将文件写入
~/.argue/output/<requestId>/
（全局配置）或
./out/<requestId>/
（项目本地配置）：
  • result.json
    — 完整结构化结果
  • summary.md
    — Markdown报告（运行完成后生成）
  • events.jsonl
    — 事件流（实时写入，崩溃后仍保留——若运行中断可解析它获取部分结果）
  • error.json
    — 错误详情（仅运行失败时生成）
结果状态：
consensus
| 
partial_consensus
| 
unresolved
| 
failed
.
如需以编程方式解析
result.json
，标准Schema位于
packages/argue/src/contracts/result.ts
。

Tips

使用技巧

  1. Frame as decisions, not topics. "Should we use SwiftUI or UIKit?" beats "Tell me about SwiftUI".
  2. Add context. "Should we use a monorepo? Context: 8 microservices, 3 teams, Node+Go" produces sharper claims.
  3. 2–3 agents is the sweet spot. Agents in the same round are dispatched in parallel, so wall-clock is dominated by rounds rather than agent count — adding more agents barely costs time. The real cost is tokens: every extra agent produces its own claims, plus every other agent has to read them as peer context, so token usage grows roughly with N². If the user's config has more than 3 agents, pass 
    --agents a,b,c
    explicitly to pick a focused subset, or set 
    defaults.defaultAgents
    in the config file once.
  4. Use 
    --action
     when consensus should drive code changes or another real-world side-effect.
  1. 以决策而非话题为框架。“我们应该用SwiftUI还是UIKit？”比“告诉我关于SwiftUI的信息”效果更好。
  2. 添加上下文。“我们应该使用单体仓库吗？上下文：8个微服务，3个团队，技术栈Node+Go”能生成更精准的论点。
  3. 2–3个Agent是最佳选择。同一轮的Agent并行调度，因此耗时主要由轮数而非Agent数量决定——增加Agent几乎不会增加时间成本。真正的成本是Token消耗：每增加一个Agent都会生成自己的论点，且其他每个Agent都需要将其作为 peer 上下文读取，因此Token使用量大致随N²增长。如果用户配置了3个以上的Agent，可明确传递
    --agents a,b,c
    选择一组聚焦的Agent，或在配置文件中一次性设置
    defaults.defaultAgents
    。
  4. 使用
    --action
    参数    ，当共识需要驱动代码变更或其他实际业务操作时。

Troubleshooting

故障排查

For common errors and fixes, see references/troubleshooting.md.
常见错误及修复方法，请查看references/troubleshooting.md。