agenthub

AgentHub — 多 Agent 协作

生成 N 个并行 AI Agent，让它们在同一任务上相互竞争。每个 Agent 都在隔离的 git worktree 中工作。协调者评估结果并合并获胜者。

斜杠命令

命令	描述
/hub:hub-init	创建新的协作会话——任务、Agent 数量、评估标准
/hub:spawn	在隔离的 worktree 中启动 N 个并行子 Agent
/hub:hub-status	显示 DAG 状态、Agent 进度、分支状态
/hub:eval	按指标或 LLM 评审对 Agent 结果排序
/hub:merge	合并获胜分支，归档落选分支
/hub:board	读取/写入 Agent 消息看板
/hub:run	一键完成生命周期：init → baseline → spawn → eval → merge

Agent 模板

使用 --template 启动时，Agent 会遵循预定义的迭代模式：

模板	模式	适用场景
optimizer	编辑 → 评估 → 保留/丢弃 → 重复 x10	性能、延迟、体积
refactorer	重构 → 测试 → 迭代直至全部通过	代码质量、技术债务
test-writer	编写测试 → 测量覆盖率 → 重复	测试覆盖率缺口
bug-fixer	复现 → 诊断 → 修复 → 验证	Bug 修复方案

模板定义在 references/agent-templates.md 中。

何时激活此技能

触发短语：

• "try multiple approaches"
• "have agents compete"
• "parallel optimization"
• "spawn N agents"
• "compare different solutions"
• "fan-out" 或 "tournament"
• "generate content variations"
• "compare different drafts"
• "A/B test copy"
• "explore multiple strategies"

协调者协议

主 Claude Code 会话即为协调者。它遵循以下生命周期：

INIT → DISPATCH → MONITOR → EVALUATE → MERGE

1. 初始化

运行 /hub:hub-init 创建会话。这将生成：

• .agenthub/sessions/{session-id}/config.yaml — 任务配置
• .agenthub/sessions/{session-id}/state.json — 状态机
• .agenthub/board/ — 消息看板频道

2. 派发

运行 /hub:spawn 启动 Agent。对于每个 Agent 1..N：

• 将任务分配发布到 .agenthub/board/dispatch/
• 通过 Agent 工具启动，并设置 isolation: "worktree"
• 所有 Agent 在同一条消息中并行启动

3. 监控

运行 /hub:hub-status 检查进度：

• dag_analyzer.py --status --session {id} 显示分支状态
• 看板 progress/ 频道包含 Agent 的更新

4. 评估

运行 /hub:eval 对结果排序：

• 指标模式：在每个 worktree 中运行评估命令，解析数值结果
• 评审模式：读取 diff，由协调者按质量排序
• 混合模式：先看指标，平局时由 LLM 评审裁定

5. 合并

运行 /hub:merge 完成收尾：

• 使用 git merge --no-ff 将获胜者合并到基础分支
• 为落选者打标签：git tag hub/archive/{session}/agent-{i}
• 清理 worktree
• 将合并摘要发布到看板

Agent 协议

每个子 Agent 收到的提示词遵循以下模式：

You are agent-{i} in hub session {session-id}.
Your task: {task description}

Instructions:
1. Read your assignment at .agenthub/board/dispatch/{seq}-agent-{i}.md
2. Work in your worktree — make changes, run tests, iterate
3. Commit all changes with descriptive messages
4. Write your result summary to .agenthub/board/results/agent-{i}-result.md
5. Exit when done

Agent 之间互不可见对方的工作，也不相互通信。它们只向看板写入内容，供协调者读取。

DAG 模型

分支命名

hub/{session-id}/agent-{N}/attempt-{M}

• 会话 ID：基于时间戳（YYYYMMDD-HHMMSS）
• Agent N：顺序编号（1 至 agent-count）
• Attempt M：重试时递增（通常为 1）

前沿检测

前沿 = 没有子分支的分支末端。等同于 AgentHub 的 "leaves" 查询。

python scripts/dag_analyzer.py --frontier --session {id}

不可变性

DAG 只能追加：

• 绝不对 Agent 分支执行 rebase 或强制推送
• 绝不删除提交（仅在归档后删除分支引用）
• 每种方案都通过 git 标签保留

消息看板

位置：.agenthub/board/

频道

频道	写入者	读取者	用途
dispatch/	协调者	Agent	任务分配
progress/	Agent	协调者	状态更新
results/	Agent + 协调者	所有人	最终结果与合并摘要

发布格式

---
author: agent-1
timestamp: 2026-03-17T14:30:22Z
channel: results
parent: null
---

## Result Summary

- **Approach**: Replaced O(n²) sort with hash map
- **Files changed**: 3
- **Metric**: 142ms (baseline: 180ms, delta: -38ms)
- **Confidence**: High — all tests pass

看板规则

• 仅追加：不得编辑或删除帖子
• 文件名唯一：{seq:03d}-{author}-{timestamp}.md
• 所有帖子都必须包含 YAML frontmatter

评估模式

基于指标

适用于：基准测试、测试通过率、文件大小、响应时间。

python scripts/result_ranker.py --session {id} \
  --eval-cmd "pytest bench.py --json" \
  --metric p50_ms --direction lower

ranker 会在每个 Agent 的 worktree 目录中运行评估命令，并从标准输出中解析指标。

LLM 评审

适用于：代码质量、可读性、架构决策。

coordinator 会读取每个 Agent 的 diff（git diff base...agent-branch），并按以下顺序排名：

1. 正确性（是否解决了任务？）
2. 简洁性（改动行数越少越好）
3. 质量（执行干净、结构良好）

混合模式

先运行指标评估。如果排名靠前的 Agent 之间相差在 10% 以内，则使用 LLM 评审来打破平局。

会话生命周期

init → running → evaluating → merged
                            → archived (if no winner)

状态转换由 session_manager.py 管理：

从	到	触发条件
init	running	/hub:spawn 完成
running	evaluating	所有 Agent 返回结果
evaluating	merged	/hub:merge 完成
evaluating	archived	无获胜者 / 全部失败

主动触发条件

coordinator 应在以下情况下采取行动：

信号	操作
所有 Agent 均已崩溃	发布失败摘要，建议使用不同约束重试
相比基线没有提升	归档会话，建议尝试其他方法
检测到孤立的 worktree	运行 session_manager.py --cleanup {id}
会话长时间停留在 running	检查看板进展，考虑设置超时

安装

# Copy to your Claude Code skills directory
cp -r engineering/agenthub ~/.claude/skills/agenthub

# Or install via ClawHub
clawhub install agenthub

脚本

脚本	用途
hub_init.py	初始化 .agenthub/ 结构和会话
dag_analyzer.py	前沿检测、DAG 图、分支状态
board_manager.py	消息看板的增删改查（频道、帖子、线程）
result_ranker.py	按指标或 diff 质量对 Agent 排名
session_manager.py	会话状态机与清理

相关 Skills

• autoresearch-agent — 单 Agent 优化循环（当你希望多个 Agent 相互竞争时，使用 AgentHub）
• self-improving-agent — 自我修改的 Agent（当你希望引入外部竞争时，使用 AgentHub）
• git-worktree-manager — Git worktree 工具（AgentHub 内部使用 worktree）