gitea-coordinator

Gitea 协调器

协调多个工作 Agent，从 Gitea 仓库的待办事项中实施已梳理的任务，负责任务分配、进度监控、合并协调和验证。

核心原则

协调，不负责实施。 协调器将任务分配给工作 Agent、监控其进度、协调合并并验证结果。工作 Agent 通过 gitea-workflow 技能执行实际实施工作。

快速参考

适用场景

• 使用托管在 Gitea 上的仓库
• 待办事项中有多个已准备就绪的任务需要实施
• 希望自主批量执行开发工作
• 需要协调合并以避免冲突
• 希望跟踪多个任务的进度

调用方式

/gitea-coordinator                    # Auto-discover and execute ready tasks
/gitea-coordinator TASK-001 TASK-002  # Execute specific tasks
/gitea-coordinator --dry-run          # Preview execution plan only
/gitea-coordinator --parallel         # Run workers in parallel
/gitea-coordinator --sequential       # Run workers one at a time (default)

标志

标志	描述	默认值
--sequential	一次执行一个任务	是
--parallel	并发执行任务	否
--max-workers N	并发工作 Agent 的最大数量	2
--dry-run	显示计划但不执行	否
--autonomous	在所有检查点自动继续	是
--supervised	每个任务完成后暂停	否
--verbose	显示所有工作 Agent 的更新	否
--summary-only	仅显示主要里程碑	是

---

工作流阶段

阶段 1：发现

读取待办事项，查找已准备好实施的任务。

Actions:
1. Read context/backlog/ for task files
2. Filter to status: ready
3. Parse task metadata (priority, size, dependencies)
4. Sort by priority (high → medium → low)
5. Present findings

Output: List of ready tasks with metadata

阶段 2：规划

根据任务特征制定执行计划。

Actions:
1. Determine execution mode (sequential or parallel)
2. Check for task dependencies (A must complete before B)
3. Assign tasks to workers in priority order
4. Generate worker instructions

Output: Execution plan with task assignments

检查点：TASKS_DISCOVERED

• 显示：已准备就绪的任务和拟定的执行计划
• 自动继续：如果设置了 --autonomous 标志且找到了任务
• 选项：continue、reorder、exclude [TASK-ID]、stop

阶段 3：执行

启动并监控工作 Agent。

For SEQUENTIAL mode:
  for each task in queue:
    1. Spawn worker with Task tool
    2. Worker runs gitea-workflow for the task
    3. Monitor progress via file system
    4. When complete: proceed to merge phase
    5. On failure: handle error, decide continue/stop

For PARALLEL mode:
  1. Spawn workers up to max_workers
  2. Monitor all workers concurrently
  3. As workers complete: queue their PRs for merge
  4. Spawn next worker if tasks remain
  5. Continue until all tasks processed

检查点：WORKER_COMPLETE（每个工作 Agent）

• 显示：工作 Agent 摘要、PR 编号、下一步操作
• 自动继续：如果成功且设置了 --autonomous
• 选项：continue、retry、skip、stop

阶段 4：合并

按顺序执行合并，以避免冲突。

Actions:
1. For each completed PR in merge queue:
   a. git checkout main && git pull
   b. Merge PR (via tea pulls merge or git merge)
   c. Verify merge succeeded
   d. Delete feature branch
2. If conflict: pause and alert user

Output: All PRs merged to main

阶段 5：验证

所有合并完成后，验证系统完整性。

Actions:
1. git checkout main && git pull --rebase
2. npm run build (verify build passes)
3. npm test (run full test suite)
4. Check for regressions
5. Generate verification report

Output: Verification status (PASSED/FAILED)

检查点：VERIFIED

• 显示：测试结果、构建状态
• 自动继续：如果所有测试均通过
• 选项：done、investigate、revert

阶段 6：总结

生成完整的完成报告。

Output:
- Tasks completed with PR numbers and commits
- Metrics (workers spawned, PRs merged, tests added)
- Verification status
- Remaining backlog tasks

---

工作 Agent 协议

工作 Agent 使用 Claude Code 的 Task 工具启动，并通过 gitea-workflow 执行分配的任务。

工作 Agent 指令模板

参见 templates/worker-instruction.md

对工作 Agent 的关键要求：

1. 以自主模式运行 gitea-workflow
2. 将进度写入 .coordinator/workers/{worker-id}/progress.json
3. 不要自行合并，而是发送已准备好合并的状态信号
4. 自动处理所有 gitea-workflow 检查点

进度跟踪

工作 Agent 通过文件系统报告进度：

// .coordinator/workers/worker-1/progress.json
{
  "worker_id": "worker-1",
  "task_id": "TASK-006",
  "status": "in_progress|completed|failed|ready-to-merge",
  "phase": "implement|review|pr-prep|pr-complete",
  "pr_number": null,
  "branch": "task/TASK-006-description",
  "last_update": "2026-01-20T10:15:00Z",
  "milestones": [
    {"phase": "implement", "timestamp": "..."},
    {"phase": "review", "timestamp": "..."}
  ]
}

---

状态跟踪

协调器在 .coordinator/state.json 中维护状态：

{
  "session_id": "coord-2026-01-20-abc123",
  "state": "EXECUTING",
  "config": {
    "execution_mode": "sequential",
    "autonomy_level": "autonomous"
  },
  "tasks": {
    "queued": ["TASK-008"],
    "in_progress": ["TASK-007"],
    "completed": ["TASK-006"],
    "failed": []
  },
  "workers": [...],
  "merge_queue": [],
  "verification": null
}

详情请参见 references/state-tracking.md。

---

故障处理

故障类型	检测方式	恢复措施
工作 Agent 失败	进度显示 failed	提供重试、跳过或中止选项
测试失败	npm test 退出状态非零	工作 Agent 最多重试 2 次
合并冲突	git merge 失败	暂停并提醒用户
验证失败	合并后测试失败	提供调查或回滚选项

详情请参见 references/failure-handling.md。

---

与 gitea-workflow 集成

协调器会启动工作 Agent，由其执行 gitea-workflow：

gitea-coordinator (orchestrator)
    │
    ├── Worker 1 → gitea-workflow --task TASK-006
    ├── Worker 2 → gitea-workflow --task TASK-007
    └── Worker 3 → gitea-workflow --task TASK-008

关键集成点：

• 工作 Agent 以自主模式运行 gitea-workflow
• 协调器负责合并（工作 Agent 创建 PR，但不进行合并）
• 通过文件系统同步进度
• 所有合并完成后，协调器运行验证

---

反模式

AP1：并行合并

模式：同时合并多个 PR 问题：产生合并冲突，破坏主分支 解决方法：始终按顺序合并，每次合并前都先拉取更新

AP2：Worker 自行合并

模式：Worker 合并自己的 PR 问题：出现竞态条件，合并缺乏协调 解决方法：Worker 发出可合并信号，由协调器执行合并

AP3：不进行验证

模式：跳过合并后的验证 问题：回归问题无法及时发现 解决方法：合并完成后始终运行完整测试套件

---

交互示例

User: /gitea-coordinator

Coordinator: Discovering ready tasks...

Found 2 ready tasks:
1. TASK-006 - Persistent Message Status (medium priority, medium size)
2. TASK-007 - Add Unit Tests (high priority, large size)

Execution Plan:
- Mode: sequential
- Order: TASK-006 → TASK-007

Proceed? [continue/reorder/stop]

User: continue

Coordinator: Starting TASK-006...
[Spawns Worker 1]

**Milestone**: TASK-006 - PR #123 created, CI passing

Coordinator: Merging PR #123...
**Milestone**: TASK-006 complete (commit abc123)

Coordinator: Starting TASK-007...
[Spawns Worker 2]

**Milestone**: TASK-007 - PR #124 created, CI passing

Coordinator: Merging PR #124...
**Milestone**: TASK-007 complete (commit def456)

Coordinator: Running verification...
- Build: PASSED
- Tests: 47/47 passing
- Coverage: 82%

## Summary
Tasks completed: 2
- TASK-006: PR #123 merged (commit abc123)
- TASK-007: PR #124 merged (commit def456)

Verification: PASSED

---

集成关系图

入站（来自其他技能）

来源技能	触发条件	操作
requirements-elaboration	任务梳理完成	协调器可以执行
gitea-agile	待办事项就绪	协调器发现任务

出站（指向其他技能）

此操作	触发技能	用途
启动 Worker	gitea-workflow	实现任务
验证失败	research	调试调查

互补技能

技能	关系
gitea-workflow	Worker 执行此技能
gitea-agile	管理此技能读取的待办事项

---

设计约束

• 需要使用 Claude Code 的 Task 工具来启动 Worker
• Worker 之间无法直接通信
• 使用文件系统协调进度
• 仅按顺序合并（禁用并行合并）
• 假定存在 context network 待办事项结构

你不会做什么

• 直接实现任务（由 Worker 完成）
• 并行合并 PR（始终按顺序合并）
• 跳过验证（合并后始终进行验证）
• 未经用户同意，在发生严重故障后继续操作