|
|
# 多 Agent 协作工作流
|
|
|
|
|
|
本文档描述 codex、claude code（deepseek-v4-pro）和 qodercli（qwen3.7-max）在同一 Gitea 仓库中协作的推荐流程。目标是在 qodercli 不与另外两个 Agent 位于同一台电脑的情况下，仍然通过仓库、Issue、PR 和约定文件完成尽量低人工介入的同步。
|
|
|
|
|
|
## 角色分工
|
|
|
|
|
|
| Agent | 位置 | 主要职责 | 适合处理的任务 |
|
|
|
| --- | --- | --- | --- |
|
|
|
| codex | 主开发机 | 代码修改、调试、测试、落地实现 | 小到中等规模改动、修 bug、补测试、整理文档 |
|
|
|
| claude code（deepseek-v4-pro） | 主开发机 | 方案设计、复杂问题拆解、代码审查 | 架构建议、长上下文分析、PR review、风险排查 |
|
|
|
| qodercli（qwen3.7-max） | 远程机器 | 独立实现、交叉验证、备用执行环境 | 独立分支开发、远端测试、对 codex/claude 的结果做复核 |
|
|
|
|
|
|
## 核心原则
|
|
|
|
|
|
1. Gitea 仓库是唯一代码事实来源。
|
|
|
2. Issue 是需求事实来源，所有需求变更必须记录在 Issue 评论中。
|
|
|
3. PR 是交付事实来源，所有实现结果都通过 PR 汇总、审查和合并。
|
|
|
4. 每个 Agent 只在自己的分支上直接提交，避免多人同时修改同一分支。
|
|
|
5. 同步优先自动化，人工只在冲突、权限、需求不清或最终合并时介入。
|
|
|
|
|
|
## 分支约定
|
|
|
|
|
|
| 类型 | 命名格式 | 示例 |
|
|
|
| --- | --- | --- |
|
|
|
| codex 实现分支 | `agent/codex/issue-<id>-<topic>` | `agent/codex/issue-5-workflow-doc` |
|
|
|
| claude 分析或审查分支 | `agent/claude/issue-<id>-<topic>` | `agent/claude/issue-5-review` |
|
|
|
| qodercli 实现分支 | `agent/qodercli/issue-<id>-<topic>` | `agent/qodercli/issue-5-sync-plan` |
|
|
|
| 集成分支 | `integration/issue-<id>` | `integration/issue-5` |
|
|
|
|
|
|
默认情况下，Agent 不直接向 `main` 推送。需要汇总多个 Agent 结果时，由协调者创建或更新 `integration/issue-<id>`，再发起最终 PR。
|
|
|
|
|
|
## 同步机制
|
|
|
|
|
|
### 代码同步
|
|
|
|
|
|
所有 Agent 在开始工作前执行：
|
|
|
|
|
|
```bash
|
|
|
git fetch --all --prune
|
|
|
git checkout main
|
|
|
git pull --ff-only origin main
|
|
|
git checkout -b agent/<agent-name>/issue-<id>-<topic>
|
|
|
```
|
|
|
|
|
|
工作中定期推送自己的分支：
|
|
|
|
|
|
```bash
|
|
|
git add .
|
|
|
git commit -m "issue #<id>: <summary>"
|
|
|
git push -u origin agent/<agent-name>/issue-<id>-<topic>
|
|
|
```
|
|
|
|
|
|
如果需要同步其他 Agent 的进展，只拉取对方分支或集成分支，不直接改写对方分支：
|
|
|
|
|
|
```bash
|
|
|
git fetch origin
|
|
|
git checkout agent/<agent-name>/issue-<id>-<topic>
|
|
|
git merge origin/integration/issue-<id>
|
|
|
```
|
|
|
|
|
|
### 状态同步
|
|
|
|
|
|
每个 Issue 下使用固定格式评论状态，便于其他 Agent 或脚本读取：
|
|
|
|
|
|
```markdown
|
|
|
Agent: codex
|
|
|
Branch: agent/codex/issue-5-workflow-doc
|
|
|
Status: working | blocked | ready-for-review | done
|
|
|
Updated: 2026-06-21 18:30 +0800
|
|
|
Notes:
|
|
|
- 已完成文档初稿
|
|
|
- 等待 claude code review
|
|
|
```
|
|
|
|
|
|
状态变化时只新增或更新一条最新状态评论。若 Gitea API 或 CLI 支持编辑评论，则优先编辑同一条评论；不支持时新增评论，并以最新时间为准。
|
|
|
|
|
|
### 任务同步
|
|
|
|
|
|
复杂任务在仓库中维护一个轻量任务文件：
|
|
|
|
|
|
```text
|
|
|
.agents/tasks/issue-<id>.md
|
|
|
```
|
|
|
|
|
|
推荐格式：
|
|
|
|
|
|
```markdown
|
|
|
# Issue <id> Agent Tasks
|
|
|
|
|
|
## TODO
|
|
|
- [ ] codex: 完成基础实现
|
|
|
- [ ] claude: 审查方案和边界条件
|
|
|
- [ ] qodercli: 在远程环境跑验证
|
|
|
|
|
|
## Decisions
|
|
|
- 2026-06-21: 使用 Gitea Issue 评论作为跨机器状态同步通道。
|
|
|
|
|
|
## Blockers
|
|
|
- 无
|
|
|
```
|
|
|
|
|
|
当 Agent 无法读取彼此本地状态时，以该任务文件和 Issue 评论为准。
|
|
|
|
|
|
## 推荐协作流程
|
|
|
|
|
|
1. 协调者在 Issue 中确认需求范围和验收标准。
|
|
|
2. codex 从 `main` 创建实现分支，完成第一版修改并推送。
|
|
|
3. claude code 拉取 codex 分支或查看 PR，进行方案审查、风险分析和必要修改建议。
|
|
|
4. qodercli 在远程机器拉取同一仓库，基于 `main` 或集成分支创建自己的分支，执行独立验证或补充实现。
|
|
|
5. 协调者将可用改动合并到 `integration/issue-<id>`。
|
|
|
6. 三个 Agent 分别在 Issue 评论中更新状态为 `ready-for-review` 或 `done`。
|
|
|
7. 协调者从 `integration/issue-<id>` 创建 PR，完成测试、审查和合并。
|
|
|
8. PR 合并后关闭 Issue，并在 Issue 中记录最终提交或 PR 链接。
|
|
|
|
|
|
## qodercli 远程机器同步方案
|
|
|
|
|
|
qodercli 与 codex、claude code 不在同一台电脑上，因此不能依赖本地文件、终端会话或共享工作区。推荐使用以下同步顺序：
|
|
|
|
|
|
1. 远程机器只通过 Gitea 拉取仓库和 Issue 信息。
|
|
|
2. qodercli 开始前先运行 `git fetch --all --prune`，确保看到最新远端分支。
|
|
|
3. qodercli 读取 Issue 评论和 `.agents/tasks/issue-<id>.md`，确认当前任务状态。
|
|
|
4. qodercli 在自己的分支上完成修改并推送。
|
|
|
5. qodercli 在 Issue 评论中写明分支、状态、验证命令和结果。
|
|
|
6. 主开发机上的协调者拉取 qodercli 分支，合并到集成分支或要求 qodercli 调整。
|
|
|
|
|
|
这样即使无法完全同步本地环境，也能保证需求、代码、状态和验证结果都能从远端仓库恢复。
|
|
|
|
|
|
## 尽量减少人工介入的策略
|
|
|
|
|
|
### 使用 Issue 评论作为消息总线
|
|
|
|
|
|
Agent 不直接互相通信时，通过 Issue 评论传递状态：
|
|
|
|
|
|
- 谁在处理什么。
|
|
|
- 分支在哪里。
|
|
|
- 当前是否阻塞。
|
|
|
- 跑过哪些验证。
|
|
|
- 需要其他 Agent 接手什么。
|
|
|
|
|
|
### 使用集成分支降低冲突
|
|
|
|
|
|
多个 Agent 的成果不直接互相覆盖，而是由协调者或自动脚本合入 `integration/issue-<id>`。如果发生冲突，只需要人工处理集成分支上的冲突，不需要追踪多个本地工作区。
|
|
|
|
|
|
### 使用固定命令模板
|
|
|
|
|
|
每个 Agent 完成任务前至少输出以下信息：
|
|
|
|
|
|
```markdown
|
|
|
Validation:
|
|
|
- `git status --short`: clean
|
|
|
- `<test command>`: passed
|
|
|
|
|
|
Changed:
|
|
|
- <file>: <summary>
|
|
|
|
|
|
Next:
|
|
|
- none | waiting for review | blocked by <reason>
|
|
|
```
|
|
|
|
|
|
固定格式可以让后续 Agent 快速判断是否能继续工作。
|
|
|
|
|
|
## 冲突处理
|
|
|
|
|
|
1. 谁发现冲突，谁在 Issue 中标记 `Status: blocked`。
|
|
|
2. 协调者在 `integration/issue-<id>` 上解决冲突。
|
|
|
3. 冲突解决后推送集成分支。
|
|
|
4. 其他 Agent 重新拉取 `integration/issue-<id>` 并继续。
|
|
|
|
|
|
不建议让多个 Agent 同时在各自分支上独立解决同一个冲突，否则会产生重复工作和不一致结果。
|
|
|
|
|
|
## 验收标准
|
|
|
|
|
|
一个 Issue 可以进入最终 PR 的条件：
|
|
|
|
|
|
- 每个参与 Agent 都已在 Issue 评论中给出最新状态。
|
|
|
- 所有相关分支都已推送到远端。
|
|
|
- 集成分支可以从干净环境拉取并构建或打开。
|
|
|
- 必要测试、脚本或人工检查结果已记录。
|
|
|
- 没有未说明的阻塞项。
|
|
|
|
|
|
## 最小人工介入闭环
|
|
|
|
|
|
在工具能力足够时，可以把人工介入压缩到三次：
|
|
|
|
|
|
1. 人工确认 Issue 需求和优先级。
|
|
|
2. 人工处理无法自动解决的冲突或需求歧义。
|
|
|
3. 人工最终审查并合并 PR。
|
|
|
|
|
|
除此之外，Agent 通过分支、Issue 评论、任务文件和 PR 自动交接上下文。
|
