docs: add multi-agent workflow

multi-agent-workflow.md

@@ -0,0 +1,189 @@
+# 多 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 自动交接上下文。