# 多 Agent 协作流程 UML

说明：上一轮实现中，Codex 实际调用的是 Codex 环境内的 worker 子 agent，并不等同于真实调用 `zcode(glm-5.2)` 和 `qoder(qwen3.7-max)`。这不满足“不同 agent 实体协作”的测试目标。

本机当前探测结果：

- `qoder` 可通过命令行调用，并支持 `qoder chat`。
- `ZCode.exe` 存在于 `D:\Program Files\ZCode\ZCode.exe`，但未发现可用的命令行 chat/help 接口。
- 因此，真正的三 agent 协作建议用 Git/Gitea 做中枢：Codex 创建 issue/分支和验收标准，Qoder 可由 CLI 接收任务，ZCode 需要通过 GUI 或你提供的 CLI 入口接收任务。

## 正确的真实协作流程

```plantuml
@startuml
title 真实三 Agent 协作流程：Codex + ZCode + Qoder

actor User as 用户
participant Codex as "Codex\n统筹/集成/验收"
participant ZCode as "ZCode(glm-5.2)\n真实外部 Agent"
participant Qoder as "Qoder(qwen3.7-max)\n真实外部 Agent"
participant Local as "E:\\Documents\\ai_share\n工作目录"
participant Gitea as "Gitea\nlaidaixi/tank-battle"
participant Web as "splan.laidaixi.com/docs\n在线验证"

用户 -> Codex: 定义目标和验收标准
Codex -> Local: 检查项目状态
Codex -> Gitea: 创建/更新 issue 和分支

Codex -> Gitea: 创建 gameplay 任务单
Codex -> Gitea: 创建 ui 任务单

par 外部 Agent 并行工作
  用户 -> ZCode: 在 ZCode 中打开 gameplay 任务\n处理 src/game.js
  Codex -> Qoder: 通过 qoder chat 发送 UI 任务\n处理 index.html / src/styles.css
end

ZCode -> Gitea: 提交 gameplay 分支或补丁
Qoder -> Gitea: 提交 ui 分支或补丁

Codex -> Gitea: 拉取两个分支
Codex -> Local: 合并、解决冲突、统一接口
Codex -> Web: 在线验证页面和游戏交互
Web --> Codex: 返回验证结果

Codex -> Gitea: 合并到 main 并推送
Codex -> 用户: 交付链接、提交记录、验证结果

@enduml
```

## 推荐任务边界

- Codex：项目骨架、issue/branch、集成、测试、Gitea 推送。
- ZCode：核心玩法逻辑，写入 `src/game.js`，不改 UI 样式和 Git 配置。
- Qoder：页面结构和视觉体验，写入 `index.html`、`src/styles.css`，不改核心玩法算法。

## 当前限制

如果要让 Codex 直接调起 ZCode 工作，需要提供 ZCode 的可脚本化入口，例如：

- CLI 命令格式；
- 可接收 prompt 的本地 API；
- MCP/server 接口；
- 或 ZCode 支持的 headless/agent 模式参数。