12 KiB

Raw Blame History Unescape Escape

多 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 接口时，允许用人工任务包转交，但必须保留记录。

三、整体架构

┌────────────────────┐
│ 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 先执行并记录结果：

[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 已发现可脚本化入口：

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
状态	`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`

八、领取任务协议

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

示例：

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 无法继续：

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

完成任务并准备 review：

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：

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

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

十、Issue 模板

创建 issue 时使用固定结构：

## 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 必须包含：

## Changed files

## Commands run

## Manual verification

## Known risks

## Linked issue
Closes #N

Review comment 建议结构：

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

或：

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 中记录了测试或人工验证结果。
本地工作区没有无关脏改被混入。

推荐合并前检查：

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

十三、协作流程

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 验证

最终验收必须检查：

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

验收记录写入 PR 或 issue comment：

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

推荐最小闭环：

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

十六、当前限制与后续

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

12 KiB Raw Blame History Unescape Escape