6.9 KiB

Raw Blame History Unescape Escape

多 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 的结果做复核

核心原则

Gitea 仓库是唯一代码事实来源。
Issue 是需求事实来源，所有需求变更必须记录在 Issue 评论中。
PR 是交付事实来源，所有实现结果都通过 PR 汇总、审查和合并。
每个 Agent 只在自己的分支上直接提交，避免多人同时修改同一分支。
同步优先自动化，人工只在冲突、权限、需求不清或最终合并时介入。

分支约定

类型	命名格式	示例
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 在开始工作前执行：

git fetch --all --prune
git checkout main
git pull --ff-only origin main
git checkout -b agent/<agent-name>/issue-<id>-<topic>

工作中定期推送自己的分支：

git add .
git commit -m "issue #<id>: <summary>"
git push -u origin agent/<agent-name>/issue-<id>-<topic>

如果需要同步其他 Agent 的进展，只拉取对方分支或集成分支，不直接改写对方分支：

git fetch origin
git checkout agent/<agent-name>/issue-<id>-<topic>
git merge origin/integration/issue-<id>

状态同步

每个 Issue 下使用固定格式评论状态，便于其他 Agent 或脚本读取：

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 支持编辑评论，则优先编辑同一条评论；不支持时新增评论，并以最新时间为准。

任务同步

复杂任务在仓库中维护一个轻量任务文件：

.agents/tasks/issue-<id>.md

推荐格式：

# Issue <id> Agent Tasks

## TODO
- [ ] codex: 完成基础实现
- [ ] claude: 审查方案和边界条件
- [ ] qodercli: 在远程环境跑验证

## Decisions
- 2026-06-21: 使用 Gitea Issue 评论作为跨机器状态同步通道。

## Blockers
- 无

当 Agent 无法读取彼此本地状态时，以该任务文件和 Issue 评论为准。

qodercli 远程机器同步方案

qodercli 与 codex、claude code 不在同一台电脑上，因此不能依赖本地文件、终端会话或共享工作区。推荐使用以下同步顺序：

远程机器只通过 Gitea 拉取仓库和 Issue 信息。
qodercli 开始前先运行 git fetch --all --prune，确保看到最新远端分支。
qodercli 读取 Issue 评论和 .agents/tasks/issue-<id>.md，确认当前任务状态。
qodercli 在自己的分支上完成修改并推送。
qodercli 在 Issue 评论中写明分支、状态、验证命令和结果。
主开发机上的协调者拉取 qodercli 分支，合并到集成分支或要求 qodercli 调整。

这样即使无法完全同步本地环境，也能保证需求、代码、状态和验证结果都能从远端仓库恢复。

尽量减少人工介入的策略

使用 Issue 评论作为消息总线

Agent 不直接互相通信时，通过 Issue 评论传递状态：

谁在处理什么。
分支在哪里。
当前是否阻塞。
跑过哪些验证。
需要其他 Agent 接手什么。

使用集成分支降低冲突

多个 Agent 的成果不直接互相覆盖，而是由协调者或自动脚本合入 integration/issue-<id>。如果发生冲突，只需要人工处理集成分支上的冲突，不需要追踪多个本地工作区。

使用固定命令模板

每个 Agent 完成任务前至少输出以下信息：

Validation:
- `git status --short`: clean
- `<test command>`: passed

Changed:
- <file>: <summary>

Next:
- none | waiting for review | blocked by <reason>

固定格式可以让后续 Agent 快速判断是否能继续工作。

冲突处理

谁发现冲突，谁在 Issue 中标记 Status: blocked。
协调者在 integration/issue-<id> 上解决冲突。
冲突解决后推送集成分支。
其他 Agent 重新拉取 integration/issue-<id> 并继续。

不建议让多个 Agent 同时在各自分支上独立解决同一个冲突，否则会产生重复工作和不一致结果。

验收标准

一个 Issue 可以进入最终 PR 的条件：

每个参与 Agent 都已在 Issue 评论中给出最新状态。
所有相关分支都已推送到远端。
集成分支可以从干净环境拉取并构建或打开。
必要测试、脚本或人工检查结果已记录。
没有未说明的阻塞项。

最小人工介入闭环

在工具能力足够时，可以把人工介入压缩到三次：

人工确认 Issue 需求和优先级。
人工处理无法自动解决的冲突或需求歧义。
人工最终审查并合并 PR。

除此之外，Agent 通过分支、Issue 评论、任务文件和 PR 自动交接上下文。

6.9 KiB Raw Blame History Unescape Escape