|
|
|
|
@ -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 <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、文件边界和可用命令，不需要改动整体协议。
|
