AgentHub — 多智能体协作 是做什么的?
生成 N 个并行 AI 代理,它们竞争完成同一个任务。每个代理在独立的 Git worktree 中工作。协调器评估结果并合并获胜者。
斜杠命令
| 命令 | 描述 |
|---|---|
/hub:init | 创建新的协作会话 — 任务、代理数量、评估标准 |
/hub:spawn | 在隔离的 worktree 中启动 N 个并行子代理 |
/hub:status | 显示 DAG 状态、代理进度、分支状态 |
/hub:eval | 通过指标或 LLM 评判器对代理结果进行排名 |
/hub:merge | 合并获胜分支,归档失败分支 |
/hub:board | 读写代理消息白板 |
/hub:run | 一次性生命周期:初始化 → 基准 → 生成 → 评估 → 合并 |
代理模板
使用 --template 生成代理时,代理将遵循预定义的迭代模式:
| 模板 | 模式 | 用例 |
|---|---|---|
optimizer | 编辑 → 评估 → 保留/丢弃 → 重复 x10 | 性能、延迟、大小 |
refactorer | 重构 → 测试 → 迭代直至绿色 | 代码质量、技术债务 |
test-writer | 编写测试 → 测量覆盖率 → 重复 | 测试覆盖缺口 |
bug-fixer | 复现 → 诊断 → 修复 → 验证 | 错误修复方法 |
模板定义在 references/agent-templates.md 中。
激活条件
触发短语:
- "尝试多种方法"
- "让代理竞争"
- "并行优化"
- "生成 N 个代理"
- "比较不同解决方案"
- "扇出" 或 "锦标赛"
- "生成内容变体"
- "比较不同草稿"
- "A/B 测试文案"
- "探索多种策略"
协调器协议
主 Claude Code 会话作为协调器。它遵循以下生命周期:
INIT → DISPATCH → MONITOR → EVALUATE → MERGE
1. 初始化
运行 /hub:init 创建会话。这将生成:
.agenthub/sessions/{session-id}/config.yaml— 任务配置.agenthub/sessions/{session-id}/state.json— 状态机.agenthub/board/— 消息白板通道
2. 分派
运行 /hub:spawn 启动代理。对于每个代理 1..N:
- 将任务分配发布到
.agenthub/board/dispatch/ - 通过 Agent 工具启动,设置
isolation: "worktree" - 所有代理在单条消息中启动(并行)
3. 监控
运行 /hub:status 检查进度:
dag_analyzer.py --status --session {id}显示分支状态- 白板
progress/通道包含代理更新
4. 评估
运行 /hub:eval 对结果进行排名:
- 指标模式:在每个 worktree 中运行评估命令,解析数值结果
- 评判器模式:读取差异,由协调器根据质量排名
- 混合模式:先看指标,指标相同时用 LLM 评判器打破平局
5. 合并
运行 /hub:merge 完成:
git merge --no-ff将获胜者合并到基准分支- 标记失败者:
git tag hub/archive/{session}/agent-{i} - 清理 worktree
- 将合并摘要发布到白板
代理协议
每个子代理接收以下提示模式:
你是 hub 会话 {session-id} 中的 agent-{i}。
你的任务:{任务描述}
说明:
1. 在 .agenthub/board/dispatch/{seq}-agent-{i}.md 中读取你的任务分配
2. 在你的 worktree 中工作 — 做出更改、运行测试、迭代
3. 使用描述性消息提交所有更改
4. 将你的结果摘要写入 .agenthub/board/results/agent-{i}-result.md
5. 完成后退出
代理之间不会看到彼此的工作。它们不会相互通信。它们只写入白板供协调器读取。
DAG 模型
分支命名
hub/{session-id}/agent-{N}/attempt-{M}
- 会话 ID:基于时间戳(
YYYYMMDD-HHMMSS) - 代理 N:顺序编号(1 到代理数量)
- 尝试 M:重试时递增(通常为 1)
前沿检测
前沿 = 没有子分支的分支提示。等同于 AgentHub 的 "leaves" 查询。
python scripts/dag_analyzer.py --frontier --session {id}
不可变性
DAG 仅支持追加:
- 永远不要 rebase 或 force-push 代理分支
- 永远不要删除提交(归档后仅删除分支引用)
- 每次尝试都通过 git 标签保留
消息白板
位置:.agenthub/board/
通道
| 通道 | 写入者 | 读取者 | 用途 |
|---|---|---|---|
dispatch/ | 协调器 | 代理 | 任务分配 |
progress/ | 代理 | 协调器 | 状态更新 |
results/ | 代理 + 协调器 | 所有人 | 最终结果 + 合并摘要 |
发布格式
---
author: agent-1
timestamp: 2026-03-17T14:30:22Z
channel: results
parent: null
---
## 结果摘要
- **方法**:将 O(n²) 排序替换为哈希映射
- **更改的文件**:3
- **指标**:142ms(基准:180ms,差值:-38ms)
- **置信度**:高 — 所有测试通过
白板规则
- 仅追加:永不编辑或删除帖子
- 唯一文件名:
{seq:03d}-{author}-{timestamp}.md - 所有帖子必须包含 YAML 前置元数据
评估模式
基于指标
最适合:基准测试、测试通过率、文件大小、响应时间。
python scripts/result_ranker.py --session {id} \
--eval-cmd "pytest bench.py --json" \
--metric p50_ms --direction lower
排行器在每个代理的 worktree 目录中运行评估命令,并从标准输出中解析指标。
LLM 评判器
最适合:代码质量、可读性、架构决策。
协调器读取每个代理的差异(git diff base...agent-branch)并根据以下标准排名:
- 正确性(是否解决了任务?)
- 简洁性(首选更改较少的行)
- 质量(清晰的执行、良好的结构)
混合模式
先运行指标。如果顶级代理之间的差距在 10% 以内,则使用 LLM 评判器打破平局。
会话生命周期
init → running → evaluating → merged
→ archived (若无获胜者)
状态转换由 session_manager.py 管理:
| 从 | 到 | 触发条件 |
|---|---|---|
init | running | /hub:spawn 完成 |
running | evaluating | 所有代理返回 |
evaluating | merged | /hub:merge 完成 |
evaluating | archived | 无获胜者/全部失败 |
主动触发
当出现以下信号时,协调器应执行相应操作:
| 信号 | 操作 |
|---|---|
| 所有代理崩溃 | 发布失败摘要,建议使用不同约束重试 |
| 基线无改进 | 归档会话,建议不同方法 |
| 检测到孤立 worktree | 运行 session_manager.py --cleanup {id} |
会话卡在 running 状态 | 检查白板进度,考虑超时 |
安装
# 复制到你的 Claude Code 技能目录
cp -r engineering/agenthub ~/.claude/skills/agenthub
# 或者通过 ClawHub 安装
clawhub install agenthub
脚本
| 脚本 | 用途 |
|---|---|
hub_init.py | 初始化 .agenthub/ 结构和会话 |
dag_analyzer.py | 前沿检测、DAG 图、分支状态 |
board_manager.py | 消息白板 CRUD(通道、帖子、线程) |
result_ranker.py | 根据指标或差异质量对代理排名 |
session_manager.py | 会话状态机和清理 |
相关技能
- autoresearch-agent — 单代理优化循环(当需要 N 个代理竞争时使用 AgentHub)
- self-improving-agent — 自我修改代理(当需要外部竞争时使用 AgentHub)
- git-worktree-manager — Git worktree 工具(AgentHub 内部使用 worktree)