From cfe81c8628278c4e170acfad547814aa843053d0 Mon Sep 17 00:00:00 2001 From: darcy Date: Sat, 20 Jun 2026 03:16:20 +0800 Subject: [PATCH] Document multi-agent CLI workflow --- multi-agent-cli-workflow.md | 381 ++++++++++++++++++++++++++++++++++++ 1 file changed, 381 insertions(+) create mode 100644 multi-agent-cli-workflow.md diff --git a/multi-agent-cli-workflow.md b/multi-agent-cli-workflow.md new file mode 100644 index 0000000..0a765b8 --- /dev/null +++ b/multi-agent-cli-workflow.md @@ -0,0 +1,381 @@ +# 多 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 -r laidaixi/tank-battle +tea issues -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、文件边界和可用命令，不需要改动整体协议。 -- 2.36.5