# Agent Arena

> Agent Arena 是实验性功能。它在显示模式与会话管理方面存在已知限制。

- 网址：https://funcoding.ai/agents/qwen-code/users/features/arena/
- 来源：Qwen Code 官方文档原文（中文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://qwenlm.github.io/qwen-code-docs/zh/users/features/arena

---
> 同时调度多个 AI 模型执行同一任务，并排比较它们的解决方案，然后选择最佳结果应用到你的工作区。

<div class="callout callout-warning">

Agent Arena 是实验性功能。它在显示模式与会话管理方面存在[已知限制](#limitations)。

</div>

Agent Arena 让你在同一任务上让多个 AI 模型相互竞争。每个模型都在自己独立的 Git 工作树中作为一个完全独立的代理运行，因此文件操作永远不会相互干扰。当所有代理完成后，你可以比较结果并选择一个胜者，将其合并回主工作区。

与[子代理](https://funcoding.ai/agents/qwen-code/users/features/sub-agents/)不同，子代理是在单个会话中委派聚焦的子任务，而 Arena 代理是完整的、顶级的代理实例——每个代理都有自己的模型、上下文窗口和完整的工具访问权限。

本页涵盖：

- [何时使用 Agent Arena](#when-to-use-agent-arena)
- [启动 Arena 会话](#start-an-arena-session)
- [与代理交互](#interact-with-agents)，包括显示模式和导航
- [比较结果并选择胜者](#compare-results-and-select-a-winner)
- [最佳实践](#best-practices)

## 何时使用 Agent Arena

Agent Arena 在你希望**评估或比较**不同模型如何处理同一问题时最为有效。最适用的场景包括：

- **模型基准测试**：在实际代码库中评估不同模型在真实任务上的能力，而非使用合成基准
- **最佳选择 (Best-of-N)**：获取多个独立解决方案，然后挑选出最佳实现
- **探索方法**：观察不同模型如何推理并解决同一个问题——对学习和获取洞察很有帮助
- **降低风险**：对于关键变更，在提交前验证多个模型是否趋近于相似的实现方案

Agent Arena 比单个会话消耗更多 token（每个代理都有自己的上下文窗口和模型调用）。当比较的价值能证明成本合理时，它才最为有用。对于日常任务，如果你信任默认模型，单个会话效率更高。

## 启动 Arena 会话

使用 `/arena` 斜杠命令启动一个会话。指定要竞争的模型和任务：

```
/arena --models qwen3.5-plus,glm-5,kimi-k2.5 "将认证模块重构为使用 JWT 令牌"
```

如果省略 `--models`，将会出现交互式模型选择对话框，让你从已配置的提供商中选择。

### 启动时发生什么

1. **工作树设置**：Qwen Code 为每个代理在 `~/.qwen/arena/<session-id>/worktrees/<model-name>/` 下创建隔离的 Git 工作树。每个工作树精确镜像你当前工作目录的状态——包括暂存的更改、未暂存的更改以及未跟踪的文件。
2. **代理生成**：每个代理在自己的工作树中启动，拥有完整的工具访问权限及其配置的模型。代理按顺序启动，但并行执行。
3. **执行**：所有代理独立工作，无共享状态或通信。你可以监控它们的进度，并与其中任何一个交互。
4. **完成**：当所有代理完成（或失败）后，进入结果比较阶段。

## 与代理交互

### 显示模式

Agent Arena 目前支持**进程内模式**，所有代理在同一终端进程内异步运行。终端底部的标签栏允许你在代理之间切换。

<div class="callout callout-note">

**分屏显示模式计划在未来实现。** 我们打算支持基于 tmux 和 iTerm2 的分屏布局，每个代理拥有独立的终端面板，实现真正的并排查看。目前仅支持进程内标签切换。

</div>

### 在代理间导航

在进程内模式下，使用键盘快捷键切换代理视图：

| 快捷键    | 操作                        |
| :-------- | :-------------------------- |
| `右方向键` | 切换到下一个代理标签        |
| `左方向键` | 切换到上一个代理标签        |
| `上方向键` | 将焦点切换到输入框          |
| `下方向键` | 将焦点切换到代理标签栏      |

标签栏显示每个代理的当前状态：

| 指示符 | 含义              |
| :----- | :---------------- |
| `●`    | 运行中或空闲      |
| `✓`    | 成功完成          |
| `✗`    | 失败              |
| `○`    | 已取消            |

### 与单个代理交互

当查看某个代理的标签时，你可以：

- **发送消息** — 在输入区域输入内容，向代理发送额外指令
- **批准工具调用** — 如果代理请求工具批准，确认对话框会在其标签内显示
- **查看完整历史** — 滚动浏览代理的完整对话，包括模型输出、工具调用和结果

每个代理都是一个完整的、独立的会话。你能对主代理做的任何事情，都能对 Arena 代理做。

## 比较结果并选择胜者

当所有代理完成后，Arena 进入结果比较阶段。你会看到：

- **状态摘要**：哪些代理成功、失败或已取消
- **执行指标**：每个代理的持续时间、推理轮数、token 使用量和工具调用次数
- **Arena 比较摘要**：共同更改的文件与仅由某个代理更改的文件、行变更数量、token 效率，以及基于每个代理的 diff、指标和对话历史生成的高级方法摘要

一个选择对话框会列出成功的代理。选择一个将其更改应用到你的主工作区，或者放弃所有结果。按 `p` 键可以快速预览高亮代理的结果，按 `d` 键可以在选择胜者前切换查看该代理的详细 diff。

### 选择胜者后发生什么

1. 胜出代理的更改会被提取为相对于基准的 diff
2. diff 会被应用到你的主工作目录
3. 所有工作树和临时分支会自动清理

如果你想在决定前检查完整的推理路径，选择对话框激活时，每个代理的完整对话历史仍可通过标签栏查看。

## 配置

Arena 的设置嵌套在
[settings.json](https://funcoding.ai/agents/qwen-code/users/configuration/settings/) 的 `agents.arena` 下。该 schema 接受
`maxRoundsPerAgent` 和 `timeoutSeconds`，但 CLI 在构建 `/arena` 使用的配置时会丢弃这两个
值。因此，设置其中任何字段都不会限制 `/arena` 的运行。

| 设置                          | 描述                                                                                          | 默认值                         |
| :---------------------------- | :-------------------------------------------------------------------------------------------- | :----------------------------- |
| `agents.arena.worktreeBaseDir`   | Arena worktree 的自定义基目录。使用绝对路径；`~` 不会被展开。                | Qwen 主目录下的 `arena` 目录 |
| `agents.arena.maxRoundsPerAgent` | schema 接受，但当前不会转发给 `/arena`；设置它不会对运行产生任何影响 | 未设置                           |
| `agents.arena.timeoutSeconds`    | schema 接受，但当前不会转发给 `/arena`；设置它不会对运行产生任何影响 | 未设置                           |

## 最佳实践

### 选择互补的模型

当你比较具有显著不同优势的模型时，Arena 最有价值。例如：

```
/arena --models qwen3.5-plus,glm-5,kimi-k2.5 "优化数据库查询层"
```

比较同一模型家族的三个版本，其洞察力不如跨提供商比较。

### 保持任务自包含

Arena 代理独立工作，彼此无通信。任务应能在提示中完整描述，无需来回讨论：

**好的示例**：「将支付模块重构为使用策略模式。更新所有测试。」

**效果较差的示例**：「我们来讨论一下如何改进支付模块」——这需要对话，更适合单个会话。

### 限制代理数量

最多可以同时运行 5 个代理。实际上，2-3 个代理能在比较价值与资源成本之间取得最佳平衡。更多代理意味着：

- 更高的 token 成本（每个代理都有自己的上下文窗口）
- 总执行时间更长
- 需要比较的结果更多

先从 2-3 个开始，只有当比较价值能够证明增加数量是合理的时候再扩展。

### 在影响重大的决策中使用 Arena

当任务重要性足以证明运行多个模型是合理的时候，Arena 能大显身手：

- 为新模块选择架构
- 为复杂重构选择实现方案
- 从多个角度验证关键 Bug 修复

对于像重命名变量或更新配置文件这样的常规更改，单个会话更快、更划算。

## 故障排除

### 代理启动失败

- 确认 `--models` 中的每个模型都已正确配置，且 API 凭据有效
- 检查你的工作目录是否是一个 Git 仓库（工作树需要 Git）
- 确保你对 Qwen 主目录
  目录下的 `arena` 目录（默认 worktree 基目录）有写入权限

### 工作树创建失败

- 运行 `git worktree list` 检查是否有来自之前会话的过期工作树
- 使用 `git worktree prune` 清理过期工作树
- 确保你的 Git 版本支持工作树（`git --version`，需要 Git 2.5+）

### 代理耗时过长

- 降低任务复杂性——Arena 任务应聚焦且定义清晰
- 使用更少的代理或延迟更低的模型
- 如果某个代理耗时过长，手动停止 Arena 运行

### 应用胜者失败

- 检查主工作目录中是否有未提交的更改可能导致冲突
- diff 以补丁形式应用——如果在会话期间你的工作目录发生了变化，可能会产生合并冲突

## 限制

Agent Arena 是实验性功能。当前限制包括：

- **仅限进程内模式**：尚不支持通过 tmux 或 iTerm2 进行分屏显示。所有代理在单个终端窗口内运行，通过标签切换。
- **选择前无 diff 预览**：你可以查看每个代理的对话历史，但在选择胜者前没有统一的 diff 查看器来并排比较解决方案。
- **不保留工作树**：选择后工作树始终会被清理。没有保留它们以供进一步检查的选项。
- **无法恢复会话**：退出后无法恢复 Arena 会话。如果在会话中途关闭终端，工作树会留在磁盘上，必须通过 `git worktree prune` 手动清理。
- **最多 5 个代理**：5 个并发代理的硬限制无法更改。
- **需要 Git 仓库**：Arena 需要 Git 仓库来实现工作树隔离。无法在非 Git 目录中使用。

## 与其他多代理模式比较

Agent Arena 和实验性的 Agent Team 运行时服务于不同的多代理工作流。Agent Swarm 仍为计划中的模式。

|                   | **Agent Arena**                                        | **Agent Team**                                     | **Agent Swarm**（计划中）                                |
| :---------------- | :----------------------------------------------------- | :------------------------------------------------- | :------------------------------------------------------- |
| **目标**          | 竞争性：寻找同一_任务_的最佳解决方案                     | 协作性：共同处理_不同_方面                           | 批处理并行：动态生成工作线程处理批量任务                   |
| **代理**          | 预配置的模型独立竞争                                     | teammate 协作，分配角色                              | 按需生成工作线程，完成后销毁                               |
| **通信**          | 无代理间通信                                             | 直接点对点消息传递                                   | 单向：父代理汇总结果                                       |
| **隔离性**        | 完全隔离：独立的 Git worktree                            | 进程内 teammate，共享任务列表                        | 每个工作线程拥有轻量级临时上下文                           |
| **输出**          | 选择一个解决方案应用到工作区                             | 综合来自多个视角的结果                               | 汇总并行处理的结果                                         |
| **最佳用途**      | 基准测试，在模型方案之间做选择                           | 研究、复杂协作、跨层工作                             | 批量操作、数据处理、Map-Reduce 任务                        |

## 下一步

探索与并行和委派工作相关的其他方法：

- **轻量级委派**：[子代理](https://funcoding.ai/agents/qwen-code/users/features/sub-agents/)在你的会话中处理聚焦的子任务——当你不需要模型比较时更合适
- **协作执行**：[多代理协调](https://funcoding.ai/agents/qwen-code/users/features/multi-agent-coordination/)使用 Agent Team 进行共享任务和 teammate 消息传递
- **手动并行会话**：自己在不同终端中运行多个 Qwen Code 会话，配合 [Git 工作树](https://git-scm.com/docs/git-worktree)实现完全手动控制