agent_collab

# 智能体协作 [](https://github.com/lauriparviainen/agent_collab/actions/workflows/ci.yml) **跨厂商AI生成代码的评审循环。生成代码廉价，但评审是瓶颈。** 我的编码智能体比我能可靠评审的代码量还要多。我不再假装同一个模型的另一次通过就能解决这个问题。于是，我将有限的人类注意力集中在关键路径上——同时，也半开玩笑地对其他部分睁一只眼闭一只眼，让不同厂商的智能体自行解决。 `agent-collab` 是我使用的临时解决方案：它为不同厂商的智能体提供有限次数的检查同一份工作的机会，记录它们的操作过程，并留下一份人类可以审计的记录。在我的经验中，不同厂商的智能体从不同角度接近同一份代码，并发现不同的问题，使综合评审更加有用。它们的分歧也暴露了值得检查的假设。关于[多样化模型协作](https://aclanthology.org/2024.acl-long.381/) 和[聚合独立代码评审](https://arxiv.org/abs/2509.01494) 的研究也指向同一方向，尽管它并不能证明这种特定的工作流程一定更好。 > 我们的赌注很简单：覆盖范围来自分歧，而不仅仅是更多的检查。  *一个编码智能体通过 agent-collab 的 MCP 服务器启动了内置的 `dual-review` 工作流程；Claude Opus 和 Codex 然后独立评审同一份代码。* ## 工作原理 ```mermaid flowchart LR H["您<br>(CLI / TUI)"] M["您的编码智能体<br>(MCP)"] D["本地 agent-collab 守护进程"] W["有限评审工作流程"] A["Claude"] B["Codex"] O["其他已配置的智能体"] T["实时事件 + 可审计的记录"] H --> D M --> D D --> W W --> A W --> B W --> O A --> T B --> T O --> T T --> H T --> M ``` 有两种接入方式：您可以通过 CLI 和 TUI 使用终端，也可以通过 MCP 让您的编码智能体接入同一个守护进程。不管哪种方式，守护进程都拥有每个会话并运行所选的工作流程。提供商后端启动已配置的智能体，每个结果都通过一个事件流返回，并保存为 JSONL 和可读的 Markdown。参见[架构指南](doc/daemon-architecture.md) 以获取详细设计。 ## 安装 您需要 Python 3.10 或更新版本。 ```bash git clone https://github.com/lauriparviainen/agent_collab.git cd agent_collab ./agent_collab.sh install ``` 此命令将当前 checkout 安装到 `~/.agent-collab/venv` 并通过 `~/.local/bin` 暴露 `agent-collab` 控制台命令。安装过程会显示每个步骤及其成功状态。如果 `~/.local/bin` 不在 `PATH` 中，安装程序会打印您需要进行的更改；它永远不会编辑 shell 启动文件，也不会替换无关命令（错误信息会告诉您确切要删除的内容）。 在每次安装或升级的最后，安装程序会检查每个全局启用的智能体所选的后端。它会打印一个对齐的表格，显示命令或 SDK 依赖状态、最佳努力凭证证据和版本。这些检查永远不会进行模型调用；缺少的提供商是可行的设置警告，而不是安装失败。 现在，您可以从任何目录运行 TUI 或其他命令： ```bash agent-collab tui agent-collab --help ``` > **两个入口点 — 请知道您正在输入哪一个。** > `./agent_collab.sh`（下划线）是 checkout 脚本：请将其用于 `install`、`uninstall` 和 `git pull` 后的升级——通常不需要其他操作。`agent-collab`（连字符）是已安装的命令，用于日常使用：守护进程、会话、TUI 和配置。已安装的命令故意没有 `install` 子命令；如果您输入 `agent-collab install`，它会告诉您在哪里可以找到。 辅助程序安装所有提供商 SDK（`all` 额外），因此 `sdk` 后端开箱即用。直接使用软件包的 `pip install` 不附带 SDK — `cli` 后端驱动提供商命令行工具，不需要厂商 SDK — 并通过单独的厂商额外功能启用 `sdk` 后端，从 checkout 安装： ```bash pip install '.[claude]' # claude_sdk pip install '.[codex]' # codex_sdk pip install '.[antigravity]' # antigravity_sdk pip install '.[xai]' # xai_sdk pip install '.[all]' # everything ``` > **此软件包不在 PyPI 上。** 目前，`pip install agent-collab` 安装的是一个无关的、相同名称的软件包，来自不同的作者。在变更日志中宣布 PyPI 版本发布之前，请仅从此存储库安装——基于克隆的命令。 缺少的 SDK 永远不会使守护进程崩溃：后端会报告自己不可用，并附带相应的安装提示。 ## 安装评审技能 此存储库附带两个薄技能，教导编码智能体评审工作流程： - `agent-collab-solo-review` 运行独立评审（一个提供商回合）。 - `agent-collab-dual-review` 并行运行两个评审者，并让调用智能体协调他们的发现（两个提供商回合）。 要实际运行评审，他们需要守护进程正在运行，并且 agent-collab MCP 服务器已注册到您的编码智能体中，如[给您的编码智能体第二个意见](#给您的编码智能体第二个意见) 中所述。技能要求您在请求不明确时选择评审模型，并显示有效的模型、后端和选项以进行确认，然后再进行提供商调用。 主 `./agent_collab.sh install` 故意不将技能复制到其他工具的配置文件中。技能安装是此单独的显式步骤： ```bash ./agent_collab.sh skills install codex ``` 将 `codex` 替换为 `claude`、`antigravity` 或 `grok`。省略客户端以安装所有列出的客户端。在 `git pull` 后重新运行命令以升级托管的副本。使用以下显式命令删除它们： ```bash ./agent_collab.sh skills uninstall codex ``` 同样， `./agent_collab.sh skills uninstall` 删除所有四个客户端的托管副本。 该命令保留本地修改或未托管的技能目录。它的目标是： | 客户端 | 用户技能目录 | | --- | --- | | Claude Code | `~/.claude/skills/` | | Codex | `~/.agents/skills/` | | Antigravity 和 Antigravity CLI | `~/.gemini/config/skills/` | | Grok | `~/.grok/skills/` | Claude Code 还可以从此存储库的市场安装： ```text /plugin marketplace add lauriparviainen/agent_collab /plugin install agent-collab@agent-collab ``` 当checkout命令无法使用时，可以使用手动复制： ```bash cp -R skills/agent-collab-solo-review skills/agent-collab-dual-review \ ~/.agents/skills/ ``` ## 升级 安装也是升级命令。在每次 `git pull` 后，请重新运行： ```bash git pull ./agent_collab.sh install ``` 每次运行都会将checkout重新安装到venv中，将您的用户配置迁移到当前模式（首先写入 `config.toml.bak` 备份；保留注释和格式），并在安装前守护进程正在运行时重启它。重启会中断活动会话；`~/.agent-collab/data` 下的会话历史记录和所有配置都将保留。如果您的配置有问题，安装时会以警告或错误的形式通知您，并显示文件路径。如果您使用[评审技能](#安装评审技能)，也请重新运行 `./agent_collab.sh skills install`——托管的副本不会自行升级。 ## 卸载 ```bash ./agent_collab.sh uninstall ``` 此命令停止守护进程，禁用自动启动，删除 `~/.agent-collab/venv` 和 `~/.local/bin/agent-collab` 命令。您的配置和会话数据保留在 `~/.agent-collab` 下；该命令会打印路径，以便您可以在需要时自行删除。已安装的[评审技能](#安装评审技能) 也会保留；请先使用 `./agent_collab.sh skills uninstall` 删除它们，同时checkout仍然有效。 作为标准打包替代方案，`pipx install '.[all]'` 也会安装声明的控制台命令在隔离环境中。计划推出 Docker 镜像，但目前不可用。 ## 给您的编码智能体第二个意见 最有用的设置是MCP：您的当前编码智能体可以在完成之前要求另一个厂商的智能体检查其工作。 启动本地守护进程： ```bash agent-collab daemon start ``` 在 Linux 上使用 systemd 用户管理器，您可以改为将守护进程注册为随登录会话启动： ```bash agent-collab daemon autostart enable agent-collab daemon autostart status ``` 服务使用已安装的持久化命令，因此请先运行 `./agent_collab.sh install`。启用自动启动是一个单独的、需要用户主动选择的操作步骤：安装本身永远不会启动或注册服务。禁用它不会删除配置或记录： ```bash agent-collab daemon autostart disable ``` 这是登录时间启动。命令故意不启用 systemd 的“lingering”功能，这将在登录前从启动用户管理器开始运行。需要此机器级策略的用户可以单独启用它，并考虑凭证可用性和资源使用情况。macOS LaunchAgent 注册目前不支持。 在首次启动时，守护进程会在 `~/.agent-collab/config.toml` 中生成一个永久的 bearer token；它在守护进程重启时保持有效（参见[运行时布局](doc/runtime-layout.md) 以获取语义和轮换）。 然后使用以下命令将 agent-collab 注册到您的 MCP 客户端。**直接 Streamable HTTP 是首选传输方式**：它直接连接客户端到守护进程，不需要每个客户端的适配器进程。守护进程必须先运行： ```bash agent-collab daemon start ``` 对于 Claude Code，请将永久令牌作为 HTTP 头部传递： ```bash claude mcp add --transport http agent-collab http://127.0.0.1:8765/mcp \ --header "Authorization: Bearer <your [daemon].token value>" ``` 对于 Codex，请配置相同的 Streamable HTTP URL 和头部。 [`http_headers` setting](https://learn.chatgpt.com/docs/config-file/config-reference#configtoml) 是 Codex 的 MCP HTTP 配置的一部分： ```toml [mcp_servers.agent_collab] url = "http://127.0.0.1:8765/mcp" http_headers = { Authorization = "Bearer <your [daemon].token value>" } tool_timeout_sec = 60 enabled = true ``` 这些客户端配置包含凭证；请保持它们私密。Codex 还支持 `bearer_token_env_var` 或 `env_http_headers`，如果您更喜欢从环境中获取令牌而不是存储在 `config.toml` 中。 如果您不想配置直接 HTTP 头部，请使用次要的 stdio 适配器。它从 agent-collab 配置中读取守护进程 URL 和令牌，并且仍然需要守护进程正在运行。在 Claude Code 中： ```bash claude mcp add agent-collab -- agent-collab mcp ``` 或者在 Codex 配置中： ```toml [mcp_servers.agent_collab] command = "agent-collab" args = ["mcp"] startup_timeout_sec = 10 tool_timeout_sec = 60 enabled = true ``` 对于 Antigravity，请将此服务器合并到 `~/.gemini/config/mcp_config.json` 中： ```json { "mcpServers": { "agent-collab": { "command": "agent-collab", "args": ["mcp"] } } } ``` 对于 Grok，请将其添加到 `~/.grok/config.toml` 中： ```toml [mcp_servers.agent_collab] command = "agent-collab" args = ["mcp"] ``` 现在询问您的编码智能体： > 使用 agent-collab 对当前 diff 获取第二个意见。让评审者关注正确性、安全性和缺少的测试。 智能体可以发现已配置的评审者，启动会话，跟随其事件，并将发现结果带回您已经在进行的对话中。您不需要学习第二个交互式工具来使用它。 [安装的评审技能](#安装评审技能) 封装了此工作流程：它们教您的智能体发现已配置的评审者，与您确认模型和选项，并对发现结果进行分类。 ## 无需提供商帐户即可查看其工作原理 从终端运行模拟会话。这样不会调用任何模型： ```bash agent-collab --mock --workdir . \ "Review this repository and identify the highest-risk change" ``` 您将看到裁判在智能体之间传递任务并打印每个事件。 可读的 Markdown 转换记录和原始 JSONL 事件将写入 `~/.agent-collab/data/sessions/` 下。 ## 并行运行独立评审 内置的 `dual-review` 工作流程同时启动 Claude 和 Codex 以获取相同的冻结任务上下文——这也是 `agent-collab-dual-review` 技能驱动的工作流程。安装并登录到 Claude Code 和 Codex CLIs，然后指向您关心的代码。守护进程将两个评审者的属性事件合并到一个光标流中，并在它们稳定时发出一个结构化阶段摘要： ```bash agent-collab start --workflow dual-review --watch --workdir /path/to/project \ "Independently review the current diff for correctness, security, and missing tests." ``` 并行评审是非交互式的。每个评审者都有自己的回合截止日期；一个运行时故障会使整个评审组降级而不是丢弃已完成的同行评审。会话在至少一个评审者完成并生成消息时完成，而在没有完成时失败。 调用人类或智能体仍然是协调者——它应该检查阶段摘要并决定采纳哪些发现。 ## 运行真正的跨评审 默认的 `cross-review` 工作流程顺序运行相同的已登录 CLI，因此评审者看到并挑战彼此的答案： ```text Claude drafts/reviews → Codex challenges → Claude revises ``` ```bash agent-collab --workflow cross-review --workdir /path/to/project \ "Review the current git diff. Prioritize correctness, security, and missing tests." ``` 智能体在选定的项目目录中运行。他们可以检查实际的存储库，而不是接收粘贴的摘录，并且有界的工作流程在配置的回合后结束。 已经只使用一个提供商？内置的 `solo-claude-cli` 和 `solo-codex-cli` 工作流程对于监督运行很有用，但跨厂商评审理念是此项目存在的原因。 ## 保持会话运行 一次性模式是最短的路径。本地守护进程添加持久会话、交互式终端 UI 和来自 MCP 客户端的访问： ```bash agent-collab daemon start agent-collab start --watch --workdir /path/to/project \ "Review the current changes and call out anything I should not ship" agent-collab tui ``` 一个守护进程可以为多个项目服务。每个会话都有自己的 `workdir`，它选择项目配置并成为智能体的工作目录。项目配置可以重命名全局已知的智能体并组合工作流程，但所有执行相关的设置都位于用户全局 `[backends.*]` 部分。可选的全局 `[workdir].restrict_workdir_roots` 列表可以限制会话，同时仍然列出特定的例外目录。省略键是不受限制的；空列表也意味着无限制。 ## 您获得的内容 - **不同的评审者，一个有限的会话。** 工作流程定义了哪些智能体顺序运行或在单个并发评审组中运行。 - **可见的执行。** 消息、工具调用、命令、状态和错误被规范化为一个事件流。 - **明确的回合结果。** 每个新的后端调用记录一个 `completed`、`cancelled`、`interrupted`、`timed_out`、`refused` 或 `failed` 结果。会话详细信息和事件轮询公开了打包的回合历史记录和规范的结构化故障；客户端永远不需要从提供商的文本或进程退出推断成功。 - **终端关闭后提供证据。** 每个会话都写入 JSONL 和 Markdown 转换记录。完成的会话默认保留 30 天；请在用户配置中设置 `[sessions] retention_days` 以保留更长时间，或设置为 `0` 以禁用自动修剪，并使用 `agent-collab sessions prune` 手动预览或清理。 - **本地会话控制。** 守护进程默认绑定到环回，并将其状态保留在 `~/.agent-collab/` 下。 - **CLI、TUI 和 MCP 访问。** 人类和编辑智能体可以观察同一个守护进程拥有的会话。 - **提供商选择，无中心化硬编码选项表。** 每个后端都拥有其选项架构、验证、健康检查和命令预览。 ## 集成与后端 每个提供商都通过两个后端支持：`cli` 运行提供商自己的命令行工具作为子进程，而 `sdk` 则在进程中调用其 Python SDK。后端 `cli` 可与基本安装一起使用；每个后端 `sdk` 都需要其提供商的可选依赖项（请参阅[安装](#安装)）。 > **SDK 状态：** SDK后端是实验性的。基本的进程内调用和提供商会话身份验证已经实现，但原声会话恢复、提供商确认的中断和交互式工具审批尚未完全实现；功能标志仍然保守。请在 [issue #20](https://github.com/lauriparviainen/agent_collab/issues/20) 中关注设计更新和完整的SDK功能实现。 | 提供商 | CLI后端 | SDK后端 | 默认启用 | | --- | --- | --- | --- | | Claude (Claude 代码) | `claude_cli` | `claude_sdk` | 是 | | Codex | `codex_cli` | `codex_sdk` | 是 | | Google Antigravity（一个托管工具，不是模型供应商） | `antigravity_cli` | `antigravity_sdk` | 需要选择 | | xAI（Grok Build CLI，远程聊天 SDK） | `xai_cli` | `xai_sdk` | 需要选择 | Claude 和 Codex 支持内置工作流；Antigravity 和 xAI 是可选的，因此干净的安装不会假装凭证或本地运行时存在。 有关提供商设置、后端选择、类型选项、自定义代理和自定义工作流，请参阅 [代理配置](doc/agent-configuration.md)。每个后端还会在 `agent_collab/backends/<provider>_<backend>/README.md` 中记录其自身。 ## 成本、隐私和诚实限制 - `agent-collab` 不提供或代理模型帐户。每个提供商的 CLI 或 SDK 都需要其自己的凭证。 - 具有三个代理回合的工作流大约消耗三个回合的提供商使用额度。平行组也会并发运行这些回合。在添加更多审阅者之前，请先使用 Claude 和 Codex。 - 守护进程是本地的，但它启动的提供商工具可能会向其供应商发送提示和存储库内容。他们的 数据政策仍然适用。 - 默认情况下，守护进程不是一个持久的存档：30 天以上的终端会话会自动被修剪。在依赖旧记录作为证据之前，请在 `~/.agent-collab/config.toml` 中提高 `[sessions] retention_days`（或将其设置为 `0` 以禁用修剪）。只有 `data/sessions/` 目录中的记录才会被删除；正在运行的会话和自定义日志目录永远不会被触及。 - 代理审阅是咨询性的。它不能取代对关键代码、测试、安全审阅或人为责任的理解。 - 不同的供应商仍然可能犯相同的错误。该项目使分歧可检查；它不保证这一点。 - Antigravity 是一个托管工具，不是模型供应商。它可以运行 Gemini、Claude 或其他支持的模型，因此在调用跨供应商工作流之前，请检查所选模型。 - 这是一个活跃的原型。功能标志和健康检查报告保守，而不是根据提供商名称推断。 配置可以是全局或项目特定的。守护进程的 `options` 命令报告有效的工作流、选定的后端、接受的值、健康证据和补救措施，而无需进行模型调用。有关完整的设置和工具合同，请参阅 [代理配置](doc/agent-configuration.md) 和 [MCP 指南](agent_collab/mcp-guidance.md)。 ## 与 David AI 一起构建 `agent-collab` 是一个小型、可检查的项目，专注于一个问题：当代理生成的代码多于人类可阅读的代码时，如何获得更有用的审阅。 我还构建了 [David AI](https://ai.david.fi/)，它的更大姐妹项目。David AI 是一个有治理的、自托管的平台，用于连接代理到公司实际运行的系统——工单、知识、云和基础设施——同时凭证、范围、风险操作审批和审计轨迹仍在人类控制之下。 它们共享相同的起点：模型能力越来越强；难点在于围绕它们构建控制、审阅和信任。 `agent-collab` 独立存在，不需要 David AI。在另一个方向上，正在进行集成：David AI 正在获得链接正在运行的 `agent-collab` 守护进程的能力 - 最终是多个守护进程 - 以便其用户可以从托管平台调用审阅工具。在此功能发布之前，请将两者视为独立项目。 由 [Lauri Parviainen](https://github.com/lauriparviainen) 构建。 ## 文档 README 故意简短。详细的行为记录在以下文档中： - [代理和后端配置](doc/agent-configuration.md) - [运行时文件和配置优先级](doc/runtime-layout.md) - [守护进程、会话、CLI 和 MCP 架构](doc/daemon-architecture.md) - [MCP 工具指南](agent_collab/mcp-guidance.md) - [生成的 HTTP API 参考](doc/daemon_api_doc/http-api.md) - [开发和验证](doc/development.md) - [当前实现笔记](doc/implementation-notes.md) - [设计和任务索引](doc/README.md) ## 开发 从源码开始： ```bash ./agent_collab_dev.sh test ./agent_collab_dev.sh build --check ``` 另外两个检查服务于不同的目的： ```bash ./agent_collab_dev.sh smoke ./agent_collab_dev.sh integration-test claude_cli ``` `smoke` 是一个快速的模拟会话：无需凭证，无需模型调用。`integration-test` 运行真正的提供商/后端传输检查，可能需要凭证或产生提供商使用。运行实时集成之前，请参阅 [开发笔记](doc/development.md)。 ## 贡献和安全 欢迎提交拉取请求；[CONTRIBUTING.md](CONTRIBUTING.md) 涵盖了所需的检查和约定。请根据 [SECURITY.md](SECURITY.md) 中描述的漏洞私密报告。 ## 许可证 `agent-collab` 在 [Apache License 2.0](LICENSE) 下许可。