# 多 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 自动交接上下文。