# 多 Agent 协同工作流：CLI 作为关键基础设施

> **核心理念**：多个真实 Agent 协作开发同一个项目时，不让 Agent 彼此直连，也不依赖共享服务进程。所有协作事实都落在 Git 和代码托管平台上，平台 CLI 只作为共同操作界面。

---

## 一、测试目标

本文件不仅描述架构，也作为一次真实多 Agent 协作测试的 runbook。

本轮测试判定标准：

| 目标 | 判定方式 |
| --- | --- |
| **真实多 Agent** | 至少一个外部 Agent 参与。Codex 内部子 agent 不计为外部 Agent。 |
| **可追踪** | 每个 Agent 的动作必须留下 issue comment、branch、commit、PR 或 review comment。 |
| **边界清楚** | 每个任务明确允许修改和禁止修改的文件范围。 |
| **可集成** | Codex 只做统筹、集成、冲突处理和验收，不替代外部 Agent 完成任务。 |
| **可验证** | 最终结果必须能通过本地和 `serve-docs` 公网链接验证。 |

---

## 二、设计目标

| 目标 | 说明 |
| --- | --- |
| **解耦** | 各 Agent 之间不直接通信，避免任何一个 Agent 成为单点或瓶颈。 |
| **可独立运行** | 无需共享服务进程，每个 Agent 独立调用 CLI 或通过人工转交任务。 |
| **可观测** | 所有协作动作都落在 Git/Gitee 上：issue、branch、commit、PR、comment。 |
| **可替换** | Codex、ZCode、Qoder、GitHub Copilot CLI 等实体都可以替换。 |
| **可降级** | 某个 Agent 没有 CLI/headless 接口时，允许用人工任务包转交，但必须保留记录。 |

---

## 三、整体架构

```text
┌────────────────────┐
│ Agent A: Gameplay   │
│ ZCode / other coder │
└─────────┬──────────┘
          │ issue / branch / PR / comment
          ▼
┌────────────────────┐        ┌────────────────────┐
│ platform CLI        │───────▶│   Gitee / Gitea     │
│ shared operation    │        │ issue / branch / PR │
└────────────────────┘        └────────────────────┘
          ▲
          │ issue / branch / PR / comment
┌─────────┴──────────┐
│ Agent C: UI / CI    │
│ Qoder / other agent │
└────────────────────┘

Codex: coordinator, reviewer, integrator, final verifier.
```

**关键点**：Git + 平台 CLI 是唯一的协作总线。Agent 之间不握手、不传私有消息，而是通过 issue、branch、PR、comment 对话。

---

## 四、Preflight 检查

开始测试前，Codex 先执行并记录结果：

```powershell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
chcp 65001

git status --short
git branch --show-current
git remote -v
tea login list
tea issues list -r laidaixi/tank-battle
qodercli --help
qodercli -p "ping" -w .
```

本轮针对 `gitea.laidaixi.com/laidaixi/tank-battle` 的实测结论：

- `ge` 已登录 gitee.com，但不适配当前 Gitea 实例的 API 形态。
- `tea` 已登录 `https://gitea.laidaixi.com`，适合当前仓库的 issue、label、PR、merge 操作。
- 后续在 Gitea 仓库上统一使用 `tea`；只有目标平台是 gitee.com 时才使用 `ge`。

ZCode 已发现可脚本化入口：

```powershell
node "D:\Program Files\ZCode\resources\glm\zcode.cjs" --help
node "D:\Program Files\ZCode\resources\glm\zcode.cjs" --prompt "..." --cwd "E:\Documents\ai_share" --mode plan --no-color
```

当前注意事项：

- `ZCode.exe` 本身是 Electron 桌面入口，不适合作为 headless CLI。
- `resources\glm\zcode.cjs` 是实际 CLI，版本可用 `version` 查看。
- 当前 CLI 可通过环境变量注入 `ZCODE_MODEL`、`ZCODE_BASE_URL`、`ZCODE_API_KEY` 调用；不要把 token 写入仓库或 issue。
- 桌面端配置在 `C:\Users\Administrator\.zcode\v2\config.json`，同步 CLI 配置时必须避免泄露 token。

如果 ZCode CLI 配置未就绪，本轮按半自动 Agent 处理：

- Codex 生成 ZCode 任务包。
- 用户把任务包贴给 ZCode GUI。
- ZCode 产出 patch、commit 或分支后，Codex 再集成。
- 这仍可计入真实外部 Agent，但必须在 issue comment 中记录“人工转交”。

---

## 五、Agent 角色和边界

| 角色 | 实体候选 | 职责 | 允许修改 | 禁止修改 |
| --- | --- | --- | --- | --- |
| Agent A: Gameplay | ZCode (glm-5.2) | 核心玩法、碰撞、敌人 AI、胜负状态 | `src/game.js` | `index.html`、`src/styles.css`、Git 配置 |
| Agent B: Review/Integration | Codex | issue 编排、review、冲突合并、验收 | 全仓，但只做集成和必要修复 | 代替外部 Agent 完成其任务 |
| Agent C: UI/CI | Qoder CLI (`qodercli`) | 页面结构、HUD、响应式、视觉体验、部署检查 | `index.html`、`src/styles.css` | `src/game.js` 核心玩法算法 |

---

## 六、平台 CLI 接口契约

所有 Agent 尽量通过同一个平台 CLI 与托管平台交互；当前 Gitea 仓库使用 `tea`。最小命令集：

| 命令 | 作用 | 典型调用方 |
| --- | --- | --- |
| `tea issues create` | 创建任务单，包含验收标准和文件边界 | Codex / 统筹 |
| `tea issues list` | 拉取待处理 issue | 任意 Agent |
| `tea comment` | 记录领取、进度、阻塞、交接信息 | 任意 Agent |
| `tea issues edit --add-labels/--remove-labels` | 更新任务状态和归属 | 任意 Agent |
| `tea pulls create` | 从 feature 分支发起 PR | Coder Agent |
| `tea comment` | 记录 review 结论或验证结果 | Codex / Review Agent |
| `tea pulls merge` | 合并通过审查和验证的 PR | Codex / CI Agent |

**约束**：CLI 只做对托管平台的原子动作，不包含业务编排。编排逻辑放在 Agent prompt、脚本或本 runbook 中。

---

## 七、Label 和状态协议

不要只依赖中文状态文本。所有状态必须落成 label。

推荐 label：

| 类型 | Label |
| --- | --- |
| 状态 | `status:todo`、`status:doing`、`status:review`、`status:changes-requested`、`status:done`、`status:deployed` |
| Agent | `agent:zcode`、`agent:qoder`、`agent:codex` |
| 领域 | `area:gameplay`、`area:ui`、`area:integration` |
| 风险 | `risk:conflict`、`risk:manual-handoff`、`risk:needs-verification` |

状态机：

```text
issue: status:todo -> status:doing -> status:review -> status:done -> status:deployed
                                └──-> status:changes-requested -> status:doing

pr:    draft -> review -> approved -> merged
             └-> changes-requested -> draft/review
```

规则：

- 谁改状态谁写 comment，说明为什么改。
- 合并前必须重新拉取 issue/PR 最新状态，避免覆盖他人结论。
- `status:changes-requested` 未清除前不能合并。

---

## 八、领取任务协议

Agent 领取任务时必须写入 comment，并更新 label。

示例：

```bash
tea comment -r laidaixi/tank-battle 12 "CLAIM agent=qoder scope=index.html,src/styles.css"
tea issues edit 12 --remove-labels status:todo --add-labels status:doing,agent:qoder,area:ui -r laidaixi/tank-battle
```

如果 Agent 无法继续：

```bash
tea comment -r laidaixi/tank-battle 12 "BLOCKED agent=qoder reason='缺少设计边界或命令失败' next='等待 Codex 补充说明'"
```

完成任务并准备 review：

```bash
tea comment -r laidaixi/tank-battle 12 "READY_FOR_REVIEW agent=qoder branch=agent/qoder/ui-issue-12 checks='manual UI smoke test passed'"
tea issues edit 12 --remove-labels status:doing --add-labels status:review -r laidaixi/tank-battle
```

---

## 九、分支和 Worktree 规范

每个 Agent 使用独立分支，避免直接改 `main`。

| 用途 | 分支 |
| --- | --- |
| ZCode gameplay | `agent/zcode/gameplay-issue-N` |
| Qoder UI | `agent/qoder/ui-issue-N` |
| Codex integration | `integration/codex-issue-N` |

建议 Codex 集成时使用独立 worktree：

```bash
git fetch --all
git worktree add ../ai_share-integration integration/codex-issue-N
```

如果多个 PR 修改同一文件，Codex 负责集成分支里的冲突解决，并把冲突原因写回 PR comment。

---

## 十、Issue 模板

创建 issue 时使用固定结构：

```markdown
## Goal

## Scope

## Files allowed
- `src/game.js`

## Files forbidden
- `index.html`
- `src/styles.css`
- `.gitignore`

## Acceptance checks
- [ ] ...

## Handoff notes
- Agent: zcode
- Branch: agent/zcode/gameplay-issue-N
- Integration owner: codex
```

---

## 十一、PR 模板

每个 PR 必须包含：

```markdown
## Changed files

## Commands run

## Manual verification

## Known risks

## Linked issue
Closes #N
```

Review comment 建议结构：

```text
REVIEW agent=codex result=changes-requested
findings:
- ...
required:
- ...
```

或：

```text
REVIEW agent=codex result=approved
checks:
- local smoke test passed
- docs preview reachable
```

---

## 十二、Review Gate

合并前必须满足：

- PR 不是合并者自己创建的，除非用户明确授权。
- 没有未解决的 `changes-requested`。
- PR head 是最新的，合并前已 `git fetch`。
- 任务 issue 有明确验收标准。
- PR comment 中记录了测试或人工验证结果。
- 本地工作区没有无关脏改被混入。

推荐合并前检查：

```bash
git status --short
git fetch --all
tea pulls <id> -r laidaixi/tank-battle
tea issues <issue-id> -r laidaixi/tank-battle
```

---

## 十三、协作流程

```mermaid
sequenceDiagram
    autonumber
    participant U as 用户
    participant Codex as Codex(统筹/集成/验收)
    participant Z as ZCode(Gameplay)
    participant Q as Qoder(UI/CI)
    participant CLI as platform CLI
    participant G as Gitee/Gitea
    participant Web as serve-docs

    U->>Codex: 定义目标和验收标准
    Codex->>Codex: Preflight 检查
    Codex->>CLI: 创建 gameplay issue
    CLI->>G: issue + labels
    Codex->>CLI: 创建 UI issue
    CLI->>G: issue + labels

    par 外部 Agent 并行工作
        Codex-->>Z: 任务包或 CLI issue
        Z->>G: branch/commit/PR/comment
        Codex->>Q: qodercli -p 发送 UI 任务
        Q->>G: branch/commit/PR/comment
    end

    Codex->>G: 拉取分支和 PR
    Codex->>Codex: 集成、冲突处理、review
    Codex->>Web: 本地和公网验证
    Web-->>Codex: 验证结果
    Codex->>G: comment 验证结果，合并通过的 PR
    Codex->>U: 交付链接、提交记录、风险说明
```

---

## 十四、serve-docs 验证

最终验收必须检查：

```text
http://localhost:18080
https://splan.laidaixi.com/docs
```

验收记录写入 PR 或 issue comment：

```text
VERIFY agent=codex
local=http://localhost:18080 status=200
public=https://splan.laidaixi.com/docs status=ok
checks='movement, fire, collision, HUD, pause/restart'
```

---

## 十五、本项目测试计划：tank-battle

推荐最小闭环：

1. Codex 创建两个 issue：
   - `area:gameplay`：交给 ZCode，范围 `src/game.js`。
   - `area:ui`：交给 Qoder，范围 `index.html`、`src/styles.css`。
2. Qoder 通过 `qodercli -p "..." -w E:\Documents\ai_share` 接收任务并产出分支或 patch。
3. ZCode 通过 `resources\glm\zcode.cjs --prompt "..." --cwd ... --mode yolo` 接收任务并产出 patch。
4. Codex 拉取两个结果到 `integration/codex-issue-N`。
5. Codex 解决冲突、review、写回 comment。
6. Codex 通过 `serve-docs` 验证本地和公网链接。
7. Codex 合并并向用户交付验证结果。

---

## 十六、当前限制与后续

1. **ZCode CLI 配置需受控**：可通过环境变量注入模型和 API 配置，禁止把 token 写入仓库、issue 或 PR。
2. **平台 CLI 要按仓库选择**：当前 Gitea 仓库使用 `tea`；gitee.com 仓库才使用 `ge`。
3. **并发冲突仍需集成者处理**：CLI 不自动解决代码冲突。
4. **中文编码需固定为 UTF-8**：否则 Agent 读取 issue/comment 可能出现乱码。
5. **后续可扩展 Agent**：文档、安全、性能 Agent 只需声明 label、文件边界和可用命令，不需要改动整体协议。