feat(coordination): add atomic Gitea task workflow (phase 2)
This commit is contained in:
chengma
@@ -40,12 +40,12 @@
|
||||
读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手：
|
||||
|
||||
1. `pwd`：确认在正确的仓库根目录。
|
||||
2. 读 [`current-state.md`](current-state.md) 和 `docs/tasks/` 中 `status: DOING` 的任务文件：恢复已验证状态、下一步和当前 blocker。
|
||||
2. 读 [`current-state.md`](current-state.md) 和 `docs/tasks/` 中当前 agent 的活跃任务；启用 Gitea 时同时读对应 Issue，恢复已验证状态、claim、下一步和当前 blocker。
|
||||
3. `git log --oneline -5`：看清最近发生了什么。
|
||||
4. 运行 `./init.sh`（Windows 原生 PowerShell 用 `./init.ps1`）：统一安装、验证、打印启动命令；如果脚本提示命令未替换，先配置脚本顶部三个命令。
|
||||
5. 跑一条基础 smoke / 端到端路径，确认基线没坏。
|
||||
6. **如果基线已坏，先修基线**，不要在坏的起点上叠新功能。
|
||||
7. 基线绿了，再从 `docs/tasks/` 领取唯一任务（路线图见 [`06-tasks.md`](06-tasks.md)）。
|
||||
7. 基线绿了，再从 `docs/tasks/` 为当前 agent 领取唯一任务（路线图见 [`06-tasks.md`](06-tasks.md)）；启用 Gitea 时由 dispatcher 串行分配并取得原子 claim。
|
||||
|
||||
## 当前阶段
|
||||
|
||||
@@ -63,16 +63,17 @@
|
||||
|
||||
任务以「一任务一文件」存放在 `docs/tasks/`（约定见 [`tasks/README.md`](tasks/README.md)）：
|
||||
|
||||
- 只领取一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件，取编号最靠前的。
|
||||
- 每个 agent 只领取一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件，取编号最靠前的；项目可并行多个 `write_paths` 互不重叠的任务。
|
||||
- 若 `docs/tasks/` 暂无可领任务，先按 [`06-tasks.md`](06-tasks.md) 路线图把下一个建议任务落成任务文件，再领取。
|
||||
- 开始前把该文件 frontmatter 的 `status` 改为 `DOING`（同一时间最多 1 个）。
|
||||
- 未启用 Gitea 时，开始前在独立分支 / worktree 把该文件 frontmatter 的 `status` 改为 `DOING`。
|
||||
- 启用 Gitea 时，由 dispatcher 按 [`gitea-collaboration.md`](gitea-collaboration.md) 串行检查写路径并原子创建 `claims/T-<编号>`；worker 只接受已读回确认的分配。标签、assignee 和更新后读回不能代替同任务领取锁。
|
||||
- 本轮只完成这一个任务；验收通过后改为 `DONE`。
|
||||
- **执行记录写进该任务文件的 `## 执行记录`**（改了什么、跑了什么验证、结果、决策）。
|
||||
- 若项目现实发生变化（启动/验证路径、目录结构、blocker），覆盖更新 [`current-state.md`](current-state.md)；任务状态以任务文件 frontmatter 为准，不逐任务改写快照。
|
||||
- 若项目现实发生变化（启动/验证路径、目录结构、blocker），覆盖更新 [`current-state.md`](current-state.md)；未启用 Gitea 时以任务文件 frontmatter 为状态权威，启用后以 Issue 为实时状态，不逐任务改写快照。
|
||||
- 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)，确保下一轮无需人工修复即可开工。
|
||||
- 做完即停，汇报验证结果，等待下一步指令。
|
||||
|
||||
> 本约定单 agent 与多 agent 并发通用；并发时注意 [`tasks/README.md`](tasks/README.md) 的防撞号规则，只改自己领取的任务文件。
|
||||
> 本约定单 agent 与多 agent 并发通用；并发时遵守 [`tasks/README.md`](tasks/README.md) 的编号和写路径防撞规则，每个 agent 使用独立工作分支与 worktree。
|
||||
|
||||
如果代码实际状态和任务文件冲突，先说明冲突，不要擅自跳步或重排。
|
||||
|
||||
|
||||
+2
-2
@@ -1,12 +1,12 @@
|
||||
# 任务路线图（Roadmap）
|
||||
|
||||
> 本文是**只读路线图**：维护阶段划分、里程碑、待办池和建议拆分清单，把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。
|
||||
> 真实任务以「一任务一文件」存放在 [`tasks/`](tasks/README.md)（`docs/tasks/T-<编号>.md`），任务状态以各任务文件 frontmatter 为准；**本文不跟踪单任务状态**。
|
||||
> 真实任务以「一任务一文件」存放在 [`tasks/`](tasks/README.md)（`docs/tasks/T-<编号>.md`）。未启用 Gitea 时以任务文件 frontmatter 为状态权威；启用后以 Issue 为实时状态、合并后的任务文件为长期事实。**本文不跟踪单任务状态**。
|
||||
|
||||
## 使用规则
|
||||
|
||||
1. **开工先落文件**：从下方「建议拆分清单」把下一个任务按 [`tasks/README.md`](tasks/README.md) 落成 `docs/tasks/T-<编号>.md`（沿用建议编号），把验收要点展开成可执行、可观察的步骤，再开始实现。
|
||||
2. **一次只做一个任务**：领取、状态流转、执行记录、完成定义全部遵循 [`tasks/README.md`](tasks/README.md) 和 [编码规则](05-coding-rules.md)；`DONE` 需要可运行证据。
|
||||
2. **每个 agent 一次只做一个任务**：领取、状态流转、执行记录、完成定义全部遵循 [`tasks/README.md`](tasks/README.md) 和 [编码规则](05-coding-rules.md)；`DONE` 需要可运行证据，多 agent 只并行写路径互不重叠的任务。
|
||||
3. **不跳步**：依赖未完成的任务不能开工。
|
||||
4. **本文只在规划变化时修改**：调整阶段划分、里程碑、增删建议任务或 Backlog 条目时才动本文；单个任务开工或完成**不**修改本文。
|
||||
5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。
|
||||
|
||||
+5
-2
@@ -23,19 +23,22 @@
|
||||
- [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
|
||||
- [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。
|
||||
- [任务路线图](06-tasks.md)：阶段划分、里程碑和待办池；只读，不跟踪单任务状态。
|
||||
- [任务文件（默认）](tasks/README.md)：一任务一文件 `docs/tasks/T-<编号>.md`，任务状态以 frontmatter 为准，单/多 agent 通用，agent 每轮只做一个。
|
||||
- [任务文件（默认）](tasks/README.md)：一任务一文件 `docs/tasks/T-<编号>.md`，单/多 agent 通用，每个 agent 同时只做一个；启用 Gitea 后由 Issue 承担实时状态。
|
||||
- [已有项目接入清单](adoption-checklist.md)：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。
|
||||
- [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
|
||||
- [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。
|
||||
- [当前实现状态](current-state.md)：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。
|
||||
- [Agent 上下文清单](agent-context.md) / [`agent-context.json`](agent-context.json) / [`Schema`](agent-context.schema.json)：按任务类型选择文档、用提交 / 文件 SHA 避免重复读取。
|
||||
- [Gitea MCP 接入](gitea-mcp.md)：可选的共享文档、Issue / PR 协调、安全配置和断连降级规则。
|
||||
- [Gitea 多 Agent 协作](gitea-collaboration.md)：可选的任务映射、原子 claim、写路径防撞和 PR 状态协议。
|
||||
- [收尾检查清单](clean-state-checklist.md)：会话结束前逐项检查，保证下一轮无需人工修复即可继续。
|
||||
- [方法对照表](method-map.md)：失败模式 → 首要修复 → 工件；出问题先查这里对症补工件。
|
||||
- [评审评分表](evaluator-rubric.md)：单次会话输出的结构化评审（6 维 0-2 分 + 校准说明）。
|
||||
- [质量文档](quality-document.md)：代码库长期健康度追踪，区别于单次输出评审。
|
||||
- [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1)：标准启动与验证入口脚本（根目录），统一安装、验证和启动命令。按操作系统二选一：WSL / Git Bash / macOS / Linux 用 `init.sh`，Windows 原生 PowerShell 用 `init.ps1`；换技术栈只改脚本顶部三个命令变量；未替换前脚本会主动失败，避免把示例命令误当真实项目命令。
|
||||
- [`../scripts/validate_agent_context.py`](../scripts/validate_agent_context.py)：零第三方依赖校验上下文清单、Schema 和仓库相对路径。
|
||||
- [`../scripts/setup_gitea_labels.py`](../scripts/setup_gitea_labels.py)：默认只读预览远端差异、显式写入的 Gitea 协作标签初始化脚本。
|
||||
- [Gitea Issue 模板](../.gitea/ISSUE_TEMPLATE/task.md) / [PR 模板](../.gitea/PULL_REQUEST_TEMPLATE.md)：任务映射、写路径和验证证据字段。
|
||||
|
||||
## 任务 / 进度 / 当前状态
|
||||
|
||||
@@ -49,6 +52,6 @@
|
||||
## 维护原则
|
||||
|
||||
- 需求变化先改文档，再改代码。
|
||||
- 代码现实变化后同步 `current-state.md`；任务状态改在对应任务文件 frontmatter，执行过程写进该任务文件的 `## 执行记录`。
|
||||
- 代码现实变化后同步 `current-state.md`；任务长期状态和执行证据写进对应任务文件，启用 Gitea 时实时状态同步到 Issue。
|
||||
- API、数据模型、路由、技术栈一旦在文档中定稿，代码不得另起一套。
|
||||
- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。
|
||||
|
||||
@@ -31,6 +31,8 @@
|
||||
|
||||
推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`；`progress.md` 可选（历史归档 / 项目级大事记）。
|
||||
|
||||
需要 Gitea 多 Agent 协作时，再复制 `docs/gitea-mcp.md`、`docs/gitea-collaboration.md`、`.gitea/` 模板和 `scripts/setup_gitea_labels.py`；先只读预览远端标签差异，再由维护者显式 `--apply`。
|
||||
|
||||
## 接入步骤
|
||||
|
||||
1. 确认仓库根目录，读取已有 `README`、运行脚本、测试配置和主要入口文件。
|
||||
|
||||
@@ -43,6 +43,7 @@
|
||||
],
|
||||
"gitea": [
|
||||
"docs/gitea-mcp.md",
|
||||
"docs/gitea-collaboration.md",
|
||||
"docs/tasks/README.md",
|
||||
"docs/clean-state-checklist.md"
|
||||
]
|
||||
|
||||
@@ -12,5 +12,7 @@
|
||||
- [ ] [`current-state.md`](current-state.md) 的项目级快照与现实一致（启动/验证路径、目录要点、blocker）。
|
||||
- [ ] 没有半成品改动处于未记录状态；如有，已写明 `BLOCKED` / `PARTIAL` 和原因。
|
||||
- [ ] 代码处于可安全恢复的状态（必要时已提交，提交信息清晰）。
|
||||
- [ ] 本轮实际修改没有超出任务 `write_paths`，也没有与其他活跃任务发生路径重叠。
|
||||
- [ ] 启用 Gitea 时，Issue 的唯一 `status/*`、claim / 工作分支、PR 和任务状态彼此一致；未完成任务没有误删 claim。
|
||||
|
||||
任意一项不满足，就先补到满足，再结束会话。
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
|
||||
## 任务状态
|
||||
|
||||
任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准（可用脚本汇总成只读看板），历史执行记录见各任务文件的 `## 执行记录`。本节只写摘要：
|
||||
未启用 Gitea 时，任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准；启用 Gitea 时，Issue 是实时状态权威，合并到默认分支的任务文件保存长期状态和执行证据。本节只写项目级摘要：
|
||||
|
||||
- 已完成：【列出 DONE 任务】。
|
||||
- 正在进行：【如有，列出 DOING 任务】。
|
||||
@@ -60,8 +60,8 @@
|
||||
1. 读仓库级 agent 规则文件（如有）。
|
||||
2. 读 `docs/00-ai-start-here.md`。
|
||||
3. 读 `docs/05-coding-rules.md`。
|
||||
4. 在 `docs/tasks/` 取第一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件；暂无可领任务时，先按 `docs/06-tasks.md` 路线图落成任务文件。
|
||||
5. 将该任务文件 frontmatter 的 `status` 改为 `DOING`。
|
||||
4. 在 `docs/tasks/` 找到 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件；暂无任务时，先按 `docs/06-tasks.md` 路线图落成任务文件。
|
||||
5. 未启用 Gitea 时，在独立分支 / worktree 把任务改为 `DOING`；启用 Gitea 时，先按 `gitea-collaboration.md` 由 dispatcher 完成原子 claim 和路径分配，worker 读回成功后再开始。
|
||||
|
||||
## 维护规则
|
||||
|
||||
@@ -69,11 +69,11 @@
|
||||
|
||||
- 新增或移动入口文件。
|
||||
- 初始化框架或模块。
|
||||
- 任务从 `TODO` 进入 `DOING` 或 `DONE`。
|
||||
- 新增可运行命令。
|
||||
- 发现文档和代码现实不一致。
|
||||
- 阶段、项目级 blocker 或可领取任务摘要发生需要跨会话保留的变化。
|
||||
|
||||
同时注意：
|
||||
|
||||
- 任务状态变化改在对应任务文件的 frontmatter；每轮执行记录、验证命令、阻塞点和关键决策写进该任务文件的 `## 执行记录`。
|
||||
- 本文件只保留当前快照，不保留完整历史。
|
||||
- 任务长期状态改在对应任务文件的 frontmatter；启用 Gitea 时实时状态同步到 Issue。每轮执行记录、验证命令、阻塞点和关键决策写进该任务文件的 `## 执行记录`。
|
||||
- 本文件只保留当前快照，不保留完整历史。
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
# Gitea 多 Agent 协作协议
|
||||
|
||||
> 本协议是可选增强。启用 Gitea 协作时，任务规格留在 Git，实时协调放在 Issue / PR；未启用时继续使用 [`tasks/README.md`](tasks/README.md) 的本地流程。
|
||||
|
||||
## 工件与权威来源
|
||||
|
||||
| 工件 | 保存什么 | 不保存什么 |
|
||||
| --- | --- | --- |
|
||||
| `docs/tasks/T-<编号>.md` | 任务规格、依赖、允许写路径、验收标准、可审计执行证据 | Token、实例地址、临时聊天 |
|
||||
| Gitea Issue | 实时状态、领取者、阻塞、结构化 claim / 续租记录 | 需求正文的唯一副本 |
|
||||
| `claims/T-<编号>` 分支 | 唯一领取锁；分支存在表示任务已被领取 | 工作提交 |
|
||||
| `agent/<agent-id>/T-<编号>` 分支 | 单个 agent 的任务提交 | 其他任务的顺手修改 |
|
||||
| Pull Request | 评审、验证证据、合并决策 | 未进入 Git 的隐含上下文 |
|
||||
|
||||
同一个任务只能映射一个任务文件和一个主 Issue。Issue 标题、工作分支和 PR 标题都以 `[T-<编号>]` 开头；Issue 正文保存任务文件路径，PR 同时链接任务文件和 Issue。
|
||||
|
||||
## 状态与标签
|
||||
|
||||
推荐标签：
|
||||
|
||||
- 类型：`kind/task` 标识可执行任务，并从 `type/docs`、`type/code` 中选择一个主要变更类型。
|
||||
- 状态：`status/todo`、`status/doing`、`status/blocked`、`status/review`、`status/done`。
|
||||
- 优先级：`priority/p0`、`priority/p1`、`priority/p2`。
|
||||
|
||||
`status/*`、`type/*`、`priority/*` 分别使用 Gitea exclusive scoped labels，同一分组任一时刻最多一个；`kind/task` 为普通标签。
|
||||
|
||||
状态映射：
|
||||
|
||||
| 阶段 | 任务文件 | Issue | 分支 / PR |
|
||||
| --- | --- | --- | --- |
|
||||
| 待领取 | `TODO` | open + `status/todo` | 无 claim 分支 |
|
||||
| 开发中 | 工作分支上 `DOING` | open + `status/doing` | claim 与工作分支存在 |
|
||||
| 阻塞 | `BLOCKED` | open + `status/blocked` | 默认保留 claim，避免误领 |
|
||||
| 评审中 | 已写完整证据 | open + `status/review` | PR open |
|
||||
| 已完成 | 合入默认分支的 `DONE` | closed + `status/done` | PR merged；claim 可清理 |
|
||||
|
||||
Issue 是实时状态权威；默认分支尚未合入工作提交时，其任务文件仍可能显示 `TODO`，这不是冲突。合并后，任务文件成为长期审计事实。
|
||||
|
||||
## 任务进入可领取队列
|
||||
|
||||
1. 先创建任务文件，写清规格、依赖和初始 `write_paths`，合入默认分支；此时 `issue`、`context_ref`、claim / 工作分支均为 `null`。
|
||||
2. 用 Issue 模板创建唯一主 Issue。新 Issue 只有 `kind/task`，尚未带 `status/todo`。
|
||||
3. 把 Issue 编号回填任务文件，并让 Issue 链接该文件；映射提交合入默认分支后，再选择 `type/*`、`priority/*` 和 `status/todo`。
|
||||
|
||||
因此 dispatcher 能从默认分支可靠定位任务 ↔ Issue；没有双向映射或没有 `status/todo` 的任务都不可领取。
|
||||
|
||||
## 串行分配与原子领取
|
||||
|
||||
仅修改 assignee / `status/doing` 再读回不是原子操作：两个 agent 可能先后覆盖并各自读到成功。MVP 指定一个 dispatcher（主 agent 或维护者）串行执行分配；worker 不并发自选任务。dispatcher 再使用 Gitea “同名分支只能创建一次”的约束，防止同一任务因重试或旁路操作被重复领取：
|
||||
|
||||
1. 读取默认分支任务文件和对应 Issue，确认双向映射、依赖均为 `DONE`、Issue 为 `status/todo`，且目标 worker 没有其他活跃任务。
|
||||
2. 读取默认分支头提交 SHA，记为 `context_ref`。串行检查所有活跃预留的 `write_paths`，不得与本任务重叠。
|
||||
3. 从精确的 `context_ref` 原子创建 `claims/T-<编号>`。创建成功者获得该任务锁；收到 `409` 或“分支已存在”即停止，不得仅因分支 SHA 相同就判定成功。
|
||||
4. 创建 `agent/<agent-id>/T-<编号>` 工作分支，更新 Issue 为 `status/doing`，按项目规则设置 assignee，并追加结构化 claim 评论。
|
||||
5. dispatcher 读回 Issue 和两个分支；不一致时先修复协调状态，不把任务交给 worker。
|
||||
6. worker 在独立 worktree 读回分配结果，再把工作分支任务文件更新为 `DOING`，写入 `context_ref`、claim / 工作分支和已接受的 `write_paths`；提交只触碰允许路径。
|
||||
|
||||
不同任务的“扫描路径后分别创建各自 claim”本身不具备原子性，因此不得让多个 worker 并发执行步骤 1～5。若团队不使用单一 dispatcher，路径检查只能视为乐观预检，任务必须事先由维护者分配互不重叠的范围，不能宣称有强互斥。
|
||||
|
||||
结构化 claim 评论至少包含：
|
||||
|
||||
```text
|
||||
CLAIM
|
||||
task: T-123
|
||||
claimed_by: 【agent-id】
|
||||
allocated_by: 【dispatcher-id】
|
||||
context_ref: 【40 位提交 SHA】
|
||||
claim_branch: claims/T-123
|
||||
work_branch: agent/【agent-id】/T-123
|
||||
write_paths: 【仓库相对路径列表】
|
||||
claimed_at: 【RFC 3339 时间】
|
||||
lease_until: 【RFC 3339 时间】
|
||||
```
|
||||
|
||||
断线重连时，只有 Issue 最新有效 claim 的 `claimed_by`、工作分支和当前 agent 全部一致，才可把已有 claim 当作自己的恢复现场；仅比较 SHA 不足以证明所有权。
|
||||
|
||||
## 写路径防撞
|
||||
|
||||
- 默认分支任务文件定义初始 `write_paths`；领取后，最新被 dispatcher 接受的结构化 claim / scope 评论与工作分支任务文件共同定义活跃预留。二者不一致时暂停工作。
|
||||
- `write_paths` 必须列出任务文件本身及预期修改的文件或目录；共享配置、锁文件、导航文件也要列入。
|
||||
- 两条路径相同，或一条是另一条的目录前缀，视为重叠；活跃任务不得存在重叠路径。
|
||||
- 发现必须修改范围外文件时，先停止并在 Issue 提议扩展范围；dispatcher 串行复查其他活跃预留，接受后追加结构化 scope 评论，worker 同步更新工作分支任务文件，二者都完成后才能继续。
|
||||
- 活跃任务由 Issue 的 `status/doing`、`status/blocked`、`status/review` 判定。每个 agent 同时最多一个活跃任务；项目可以并行多个写路径互不重叠的任务。
|
||||
|
||||
建议 worktree 命令：
|
||||
|
||||
```powershell
|
||||
git fetch origin
|
||||
git worktree add ../【项目】-T-123 -b agent/【agent-id】/T-123 origin/agent/【agent-id】/T-123
|
||||
```
|
||||
|
||||
不要让多个 agent 共用同一 worktree，也不要在 claim 分支提交工作代码。
|
||||
|
||||
## PR 与完成
|
||||
|
||||
1. 在任务文件 `## 执行记录` 写入实际验证命令和结果，完成标准满足后更新状态。
|
||||
2. PR 使用 `.gitea/PULL_REQUEST_TEMPLATE.md`，链接 `Closes #【Issue 编号】`、任务文件、`context_ref`、写路径和验证证据。
|
||||
3. 创建 PR 后把 Issue 切到唯一 `status/review`；评审失败则把 Issue 和工作分支任务状态一起回到 doing / blocked。
|
||||
4. PR 合并、默认分支任务文件为 `DONE` 后，Issue 才切到 `status/done` 并关闭。
|
||||
5. MCP 当前没有删除分支工具。清理 claim 前先确认 PR 已合并、Issue 已完成且无恢复需要，再由维护者通过 Gitea UI 或受控 REST 操作删除。
|
||||
|
||||
## 过期 claim 与断连
|
||||
|
||||
- agent 应在 `lease_until` 前用新评论续租；续租不更换 claim 分支。
|
||||
- claim 过期不等于可以自动抢占。维护者先检查 Issue 最后活动、工作分支新提交和 PR，再评论回收原因并人工删除 claim 分支。
|
||||
- Gitea / MCP 断连时，只能继续已经确认归属自己的任务；不能领取新任务、释放锁或猜测远端状态。
|
||||
|
||||
## 初始化标签
|
||||
|
||||
先预览，再显式写入：
|
||||
|
||||
```powershell
|
||||
python scripts/setup_gitea_labels.py --repo 【owner/repo】
|
||||
python scripts/setup_gitea_labels.py --repo 【owner/repo】 --apply
|
||||
```
|
||||
|
||||
脚本从环境变量读取 `GITEA_URL`、`GITEA_TOKEN`；HTTP 仍要求 `GITEA_ALLOW_INSECURE_HTTP=1`。默认命令会连接目标仓库做只读比较，显示 create / update / unchanged；`--apply` 会把同名标签的颜色、描述和 exclusive 属性校正为本模板值。MCP 没有创建标签工具，因此标签初始化使用 Gitea REST API 或由维护者在 UI 中完成。
|
||||
|
||||
## 并发验收
|
||||
|
||||
在专用测试任务上让两个进程同时创建同一个临时 claim 分支，验收结果必须是恰好一个 `201`、另一个 `409`。测试前后均需人工确认分支名，清理由受控 REST / UI 完成；不得在业务任务上试验。
|
||||
@@ -88,3 +88,12 @@ tool_timeout_sec = 60
|
||||
4. 保存 `read_file` 返回的文件 SHA；同一会话内 SHA 未变化时复用内容。
|
||||
|
||||
Gitea 中的文件与本地 `docs/` 是同一 Git 工件的远端与 checkout，不要再创建第三份人工同步副本。
|
||||
|
||||
## Issue / PR 协调
|
||||
|
||||
多 agent 协作时遵循 [`gitea-collaboration.md`](gitea-collaboration.md)：
|
||||
|
||||
- 任务文件保存规格和长期证据，Issue 保存实时状态，PR 保存评审与合并决策。
|
||||
- 领取互斥依赖唯一 `claims/T-<编号>` 分支；assignee、`status/doing` 和读回仅作状态确认。
|
||||
- MVP 由单一 dispatcher 串行分配任务并检查 `write_paths`，每个 worker 使用 `agent/<agent-id>/T-<编号>` 和独立 worktree；每任务 claim 只解决同任务重复领取，不单独保证跨任务路径互斥。
|
||||
- MCP 可创建 claim / 工作分支，但当前没有创建标签或删除分支工具。标签用 `python scripts/setup_gitea_labels.py --repo 【owner/repo】 --apply` 幂等初始化；过期 claim 由维护者通过 UI 或受控 REST 人工回收。
|
||||
|
||||
@@ -15,7 +15,10 @@
|
||||
| 评审主观 | 质量判断靠个人记忆和感觉，agent 容易自我说服通过 | 用固定维度做评分 | [`evaluator-rubric.md`](evaluator-rubric.md) |
|
||||
| 代码库悄悄退化 | 速度上去了，但几轮会话后代码越来越难审、边界越来越糊 | 定期给代码库健康度打分 | [`quality-document.md`](quality-document.md) |
|
||||
| 文档堆叠失控 | 入口文件越来越长，"每次失败加一句" | 渐进披露，入口保持薄 | [`00-ai-start-here.md`](00-ai-start-here.md) + 拆分到具体文档 |
|
||||
| 每轮全量重读 | 多 agent 反复拉取全部文档，慢且容易混入无关上下文 | 用任务路由和提交 / 文件 SHA 增量读取 | [`agent-context.md`](agent-context.md) + [`agent-context.json`](agent-context.json) |
|
||||
| 多 agent 抢改任务文件 | 多个 agent 并发时抢改同一个看板/进度文件，出现"读到旧版本"、ID 撞号、合并冲突 | 一任务一文件（默认模式已内建），执行记录进任务文件，不逐任务改共享收尾文件 | [`tasks/README.md`](tasks/README.md) |
|
||||
| 多 agent 重复领取 | 两个 agent 同时把同一 Issue 改为 doing，读回后都以为成功 | 用唯一 claim 分支做原子锁，标签只展示状态 | [`gitea-collaboration.md`](gitea-collaboration.md) |
|
||||
| 多 agent 写路径碰撞 | 不同任务同时修改同一目录或共享配置，合并时才发现冲突 | dispatcher 串行声明 / 比较 `write_paths`，worker 使用独立 worktree | [`gitea-collaboration.md`](gitea-collaboration.md) + [`tasks/README.md`](tasks/README.md) |
|
||||
|
||||
## 使用原则
|
||||
|
||||
|
||||
+24
-3
@@ -27,6 +27,13 @@ phase: 1 # 所属阶段，沿用路线图的 Phase 编号
|
||||
deps: [T-100] # 依赖的任务 ID
|
||||
status: TODO # TODO | DOING | DONE | BLOCKED
|
||||
created: 【日期】
|
||||
issue: null # Gitea Issue 编号；未启用 Gitea 时保持 null
|
||||
context_ref: null # 领取时默认分支提交 SHA
|
||||
claim_branch: null
|
||||
work_branch: null
|
||||
write_paths: # 允许修改的仓库相对路径
|
||||
- docs/tasks/T-101.md
|
||||
- 【path/to/module】
|
||||
---
|
||||
|
||||
## 问题 / 背景
|
||||
@@ -38,12 +45,25 @@ created: 【日期】
|
||||
|
||||
## 领取 / 完成流程
|
||||
|
||||
- 状态：`TODO` · `DOING`（同一时间最多 1 个）· `DONE` · `BLOCKED`。
|
||||
- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
|
||||
- 状态：`TODO` · `DOING` · `DONE` · `BLOCKED`。每个 agent 同时最多一个活跃任务；项目可以并行多个写路径互不重叠的任务。
|
||||
- 每个 agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
|
||||
- `write_paths` 必须在动手前写清。两个活跃任务路径相同，或一条是另一条的目录前缀，均视为冲突，不能并行。
|
||||
- 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
|
||||
- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。
|
||||
- **只改自己那个任务文件**；不要编辑别人正在做的任务文件。
|
||||
|
||||
未启用 Gitea 时，在独立分支 / worktree 中把任务文件从 `TODO` 改为 `DOING` 即可。启用 Gitea 时，必须先按 [`../gitea-collaboration.md`](../gitea-collaboration.md) 原子创建唯一 `claims/T-<编号>` 分支；assignee、标签和“更新后读回”都不能代替领取锁。
|
||||
|
||||
## 与 Gitea Issue / PR 的映射（可选）
|
||||
|
||||
- 一个任务文件对应一个主 Issue；Issue 负责实时领取、阻塞和评审状态，任务文件负责版本化规格和长期证据。
|
||||
- 先把任务文件合入默认分支，再创建 Issue；随后把 Issue 编号回填任务文件并合入默认分支，最后才添加 `status/todo`。映射未完成的 Issue 不可领取。
|
||||
- Issue、claim 分支、工作分支和 PR 都携带同一个 `T-<编号>`；不得用一个 PR 顺带完成多个任务。
|
||||
- 工作分支命名为 `agent/<agent-id>/T-<编号>`，每个 agent 使用独立 worktree。
|
||||
- MVP 由一个 dispatcher / 主 agent 串行分配任务。唯一 claim 分支保证同一任务不被重复领取，dispatcher 的串行检查保证不同任务的 `write_paths` 不冲突。
|
||||
- 进入评审后 Issue 使用唯一 `status/review`；PR 合并且默认分支任务文件为 `DONE` 后，Issue 才能关闭并标记 `status/done`。
|
||||
- 领取、结构化 claim 评论、过期锁回收和分支清理的完整规则见 [`../gitea-collaboration.md`](../gitea-collaboration.md)。
|
||||
|
||||
## 用户指令暗语（可选约定）
|
||||
|
||||
> 用户的工作流通常固定为：提 bug/需求 → 讨论定案 → 落成任务文件 → 提交 → 实现 → 提交。
|
||||
@@ -72,6 +92,7 @@ created: 【日期】
|
||||
|
||||
## 与路线图和共享文件的关系
|
||||
|
||||
- [`../06-tasks.md`](../06-tasks.md)：只读路线图（Phase 划分、里程碑、Backlog、建议拆分清单）；真实任务状态一律以本目录任务文件的 frontmatter 为准。
|
||||
- [`../06-tasks.md`](../06-tasks.md)：只读路线图（Phase 划分、里程碑、Backlog、建议拆分清单）；未启用 Gitea 时以任务文件 frontmatter 为准，启用后以 Issue 为实时状态、合并后的任务文件为长期事实。
|
||||
- `../../progress.md`：可选工件，用作历史归档或项目级大事记；执行记录写各任务文件，不逐任务追加。
|
||||
- [`../current-state.md`](../current-state.md)：项目级快照（启动/验证路径、目录要点、blocker）；任务状态不在此维护，可由脚本汇总 frontmatter 生成。
|
||||
- [`../gitea-collaboration.md`](../gitea-collaboration.md)：启用 Gitea 时的任务映射、原子领取、写路径防撞和 PR 状态协议。
|
||||
|
||||
@@ -5,6 +5,13 @@ phase: 1
|
||||
deps: []
|
||||
status: TODO
|
||||
created: 【日期】
|
||||
issue: null
|
||||
context_ref: null
|
||||
claim_branch: null
|
||||
work_branch: null
|
||||
write_paths:
|
||||
- docs/tasks/T-XXX.md
|
||||
- 【允许修改的仓库相对路径】
|
||||
---
|
||||
|
||||
## 问题 / 背景
|
||||
@@ -23,6 +30,10 @@ created: 【日期】
|
||||
|
||||
（明确不碰的模块/流程）
|
||||
|
||||
## 协作约束
|
||||
|
||||
（启用 Gitea 时填写对应 Issue、领取时的 `context_ref`、claim / 工作分支；任何新增写路径先检查与其他活跃任务是否重叠。）
|
||||
|
||||
## 执行记录
|
||||
|
||||
（做完在此记录：改了哪些文件、跑的验证命令与结果、阻塞、关键决策。
|
||||
|
||||
Reference in New Issue
Block a user