AgentHub：5 个 AI Agent 并行改同一仓库，消息路由、文件锁与崩溃恢复怎么落地
单个 Agent 串行推进项目，上下文窗口和等待时间都是瓶颈：先写后端、再写前端、再补数据库迁移，一轮下来时间全花在来回切换上。一旦想并行，问题立刻变成三个：两个人同时改 src/api.py 会冲突；消息重发或超时会让同一个任务被执行两遍；Router 崩了，任务状态、谁做到哪一步全部丢失。AgentHub 是一个开源的多 Agent 编排框架，用消息路由 + 文件锁 + 持久化日志把这三件事分开处理。
项目信息
- 仓库：https://github.com/Dmatut7/AgentHub
- 设计文档：docs/design.md
- 主从协作流程：docs/main-members-workflow.md
- 示例：EXAMPLES.md
一条命令拉起一支完整队伍：1 个协调者（MAIN）+ 4 个执行者（A/B/C/D）。
./scripts/start_team.sh
脚本会自动启动 Router（默认端口 8765）、打开 5 个独立终端窗口、生成标准文档模板，并把各角色的 AI prompt 注入进去。
分工表
| 角色 | 定位 | 职责 |
|---|---|---|
| MAIN | Coordinator | 任务规划、设计评审、问题决策 |
| A | Frontend Expert | UI/UX，React、Vue、CSS、组件、页面 |
| B | Backend Expert | API，FastAPI、业务逻辑、服务 |
| C | Database Expert | 数据，模型、迁移、查询 |
| D | Support Expert | DevOps，测试、文档、部署 |
消息协议
成员之间不直接对话，所有消息都经过 MAIN 收口：
| 消息类型 | 方向 | 用途 |
|---|---|---|
| review | MAIN → 成员 | 评审文档/代码 |
| report | 成员 → MAIN | 反馈评审结果 |
| assign | MAIN → 成员 | 分配任务 |
| clarify | 成员 → MAIN | 提问 |
| answer | MAIN → 成员 | 回答问题 |
| verify | MAIN → 成员 | 验证改动 |
| done | 成员 → MAIN | 任务完成 |
| fail | 成员 → MAIN | 任务失败 |
协作流程是一条固定链：
analyze -> design -> confirm -> schedule -> execute -> aggregate
对应项目分析与影响评估、设计文档生成、契约优先的任务拆分、并行执行与协调、结果聚合。设计阶段先产出接口契约，再进入编码，这样 A/B/C/D 之间的调用面是提前对齐的。
不打架靠什么
投递层：ACK 双确认 + 重试 + 幂等
消息投递要过两道确认：投递层收到消息回一次 ACK，应用层真正处理完再回一次 ACK。中间任何一环没回，就按指数退避策略重试，并带超时检测。重试本身会带来重复投递，所以收发两端都做幂等去重，保证同一条消息不会被当作两个任务执行。
状态层：JSONL 日志 + session/epoch
消息以 JSONL 格式落盘，inbox 状态单独持久化，进程崩溃后可自动恢复。session/epoch 用来区分不同的运行周期，避免恢复时把上一轮的残留状态当成当前任务。想回放一整条协作链，可以直接查：
team trace --task T1
资源层：文件锁 + 变更广播
改动前先占锁，把要动的文件显式声明出来：
team lock --files "src/api.py" --task TASK-001
接口发生变化时广播给所有相关方，触发下游同步：
team notify --task TASK-001 --interface "POST /api/login" --change-type modify
配合进度板和依赖跟踪，被阻塞的任务会在板上暴露出来：
team board
team progress --task TASK-001 --percent 50 --step "implementing API"
常用命令
# 生命周期
./scripts/start_team.sh
./scripts/status_team.sh
./scripts/stop_team.sh
# 分析 / 设计 / 执行
team analyze --path . --feature "new feature"
team design --requirement "feature description"
team run --task "feature" --design-approved
team schedule --task "feature description"
# 协作与调度
team board
team progress --task T1 --percent 50 --step "..."
team lock --files "src/api.py" --task T1
team notify --task T1 --interface "API" -c modify
team say --from MAIN --to A --text "Start task"
team review --to A,B,C,D --task T1 --file doc.md
team assign --to B --task T1 --files "src/*"
team status --tasks
team trace --task T1
# 直接查 Router 状态
curl http://127.0.0.1:8765/status | jq
配置
| 环境变量 | 说明 | 默认值 |
|---|---|---|
| TERMINAL_ADAPTER | 终端类型（terminal / iterm） | terminal |
| CODEX_PATH | AI CLI 可执行文件路径 | codex |
框架不绑定某一家模型，Codex、Claude Code 等兼容的 CLI 都可以接入，成员数量也可调整。
边界与取舍
运行环境目前只有 macOS，Linux 和 Windows 支持仍在计划中；依赖 Python 3.8+、Terminal.app 或 iTerm2，以及一个可用的 AI CLI。仓库 stars 约 40，属于早期项目，协议和脚本仍在快速变动。Roadmap 里尚未完成的部分包括 Web 监控面板、跨机器的分布式 Agent、自定义协议插件系统，以及 GPT-4、Claude、Gemini 等更多模型接入。也就是说，当前这套机制解决的是单机、单仓库、多 Agent 并行时的冲突与状态问题，跨节点扩展还没有落地。