01 · 系统架构多 agent 协作的拓扑、共享层、数据流

协作拓扑

👤 用户 自然语言 PM (Hermes) 派活/收活 Developer commit/push GitHub Repo read Reviewer verdict PM 汇报 👤 拍板

用户在关键节点(PR review、合/不合)参与,其余时间 PM 后台调度。

分层结构

层组成职责
用户层 你(通过微信/飞书/终端) 提需求、看 PR、拍板决策
PM 层 Hermes(我) 理解需求、拆任务、派活、跟踪状态、汇报、整理
Agent 层 Developer / Reviewer / Merger(各为 OpenCode session) 执行具体任务(写代码 / 审代码 / 合 PR)
运行时层 OpenCode serve :4096(localhost only) 管理所有 agent session、调用 LLM、提供工具
模型层 DeepSeek / GLM / MiniMax / Kimi(走 opencode-go 通道) 实际推理(每个 agent 独立选 model)
存储层 GitHub(代码)
本地 ~/agent-workspace/<project>/.pm/(任务索引)
本地 ~/agent-workspace/logs/(日志)		 代码权威源在 GitHub,任务元数据在项目内 .pm/
保活层 ~/agent-workspace/scripts/keepalive.sh(tmux + 循环) opencode serve 挂掉 10s 内自启

数据流(单次迭代)

1. 用户微信发需求
     ↓
2. PM 拆任务(写入 .pm/iterations.json,创建 iter-XXX)
     ↓
3. PM 派 developer agent(在 iter-XXX 的 worktree 里)
     ↓
4. Developer 写代码 → commit → push → 开 PR
     ↓
5. PM 收到 PR URL,发微信通知用户 + 启动 reviewer
     ↓
6. Reviewer 读 PR diff → 留 GitHub comment → 给 PM 结构化 verdict
     ↓
7. PM 根据 verdict 判断:
     ├─ approved → 通知用户"可以合"
     └─ changes_requested → 让 developer 改(在同一个 worktree)
     ↓
8. 用户说"合" → PM 派 merger
     ↓
9. Merger merge PR → 清理 worktree + branch → 标记 iter done
     ↓
10. PM 更新 .pm/iterations.json,汇报总结

关键约定

OpenCode serve 共享 所有 agent(developer / reviewer / merger)都连同一个 localhost:4096 进程。每个 agent 是独立的 session,模型/工具/工作目录可不同。互不干扰。
代码真值在 GitHub 本地 ~/agent-workspace/<project> 是 GitHub 仓库的 mirror,agent 的所有写操作最终 push 到 GitHub。本地只缓存。
main 分支保护 任何 agent 都不能直接 commit 到 main,必须通过 PR。GitHub 上要设 branch protection rule(必须 1 review,status checks pass)。

目录结构

~/agent-workspace/
├── rules/                    # 本目录:规则文档
├── scripts/                  # PM 工具集
│   ├── pm_opencode.py        # 派活客户端
│   └── keepalive.sh          # opencode serve 保活
├── logs/                     # 全局日志
│   ├── keepalive.log
│   └── opencode-serve.log
└── <project>/                # 每个项目一个目录
    ├── .pm/                  # PM 维护的任务索引(项目内)
    │   ├── iterations.json
    │   ├── sessions/         # session 详情备份
    │   └── notes.md
    ├── .git/                 # git 仓库
    └── src/ ...              # 项目源码

多项目支持

每个项目一个目录,对应一个 GitHub repo。PM 在 .pm/ 目录下管理各自项目的迭代。各项目之间完全隔离,但共用 opencode serve、PM 调度逻辑、保活脚本。