diff --git a/multi-agent-workflow.md b/multi-agent-workflow.md
new file mode 100644
index 0000000..c1e7576
--- /dev/null
+++ b/multi-agent-workflow.md
@@ -0,0 +1,65 @@
+# 多 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 模式参数。
+