feat: add agent-collaboration-kit

2026-07-06 09:24:22 +08:00
parent f1ed320991
commit c4c68572c3
8 changed files with 970 additions and 0 deletions
@@ -0,0 +1,94 @@
 # <Project Name> Agent Protocol
 本项目使用 `docs/agent-collaboration-kit/` 中的多 Agent 协作规范。本文填入本项目自己的路径、命令和权限边界。
 ## Project Overview
 - Project: `<project_name>`
 - Stack: `<tech_stack>`
 - Main app command: `<run_command>`
 - Base URL: `<base_url>`
 - Task board: `tasks.yaml`
 ## Roles
 | Role | Responsibility | Validation |
 |------|----------------|------------|
 | Product/Test Coordinator | Defines requirements, writes task evidence, runs black-box retest, marks verified | Browser/API/integration tests |
 | Developer Worker | Implements fixes/features, writes unit tests, runs build and white-box tests | Unit tests/build/local run |
 ## Path Scoping
 | Path | Product/Test | Developer | Notes |
 |------|:------------:|:---------:|------|
 | `<spec_paths>` | R/W | Read-only | Product specs, API docs, plans |
 | `<integration_test_paths>` | R/W | Read-only | Browser/API regression |
 | `<test_records_path>` | R/W | Read-only | Run records |
 | `<source_paths>` | Read-only | R/W | Application source |
 | `<unit_test_paths>` | Read-only | R/W | Unit tests |
 | `<shared_config_templates>` | Read-only | R/W | Committable config templates |
 | `<local_config_paths>` | Read-only | Read-only | Local secrets/overrides |
 | `tasks.yaml` | R/W | Limited R/W | Product/Test owns `verified`; Developer may write implementation status/evidence |
 ## Commands
 Developer verification:
 ```bash
 <unit_test_command>
 <build_command>
 <local_run_command>
 ```
 Product/Test verification:
 ```bash
 <preflight_command>
 <api_smoke_command>
 <browser_regression_command>
 ```
 ## Task Status Lifecycle
 ```text
 open -> dispatched -> fixed_by_dev -> retesting -> verified
 ```
 Failure states:
 ```text
 blocked
 failed_retest
 leftover
 ```
 Rules:
 - `worker_done` is not completion. Product/Test must retest before `verified`.
 - Each task can be dispatched to Developer at most 3 rounds.
 - If still failing after 3 rounds, mark `leftover`, record evidence, and continue the next task.
 - Do not commit or push unless the user explicitly asks.
 ## Orca Closed Loop
 Use `docs/agent-collaboration-kit/orca-closed-loop.md` when the user asks for supervised implementation/retest loops.
 Default loop:
 ```text
 Product/Test records failure in tasks.yaml
  -> Orca task-create
  -> dispatch Developer Worker
  -> wait worker_done/escalation/decision_gate
  -> Product/Test retests
  -> verified / failed_retest / leftover
 ```
 ## Definition Of Done
 A task is done only when:
 - Developer reports files modified and verification commands.
 - Product/Test verifies in the correct worktree/service.
 - Relevant build/test/browser/API checks pass.
 - `tasks.yaml` contains final evidence.
@@ -0,0 +1,68 @@
 # Agent Collaboration Kit
 这是一套可复制到其他项目的多 Agent 协作规范。它把“产品/测试负责定义与验收，开发负责实现与白盒验证，协调者用 Orca 做闭环调度”的经验抽成项目无关模板。
 ## 适用场景
 - 项目需要多个 Agent 分工协作，而不是单个 Agent 从需求写到代码。
 - 需要明确区分规格、测试、实现、复测的责任边界。
 - 需要把测试失败项派发给开发 Agent，等 `worker_done` 后再由测试 Agent 复测。
 - 需要连续修复多个问题，并把三次仍未修好的问题留档。
 ## 推荐目录
 把本目录复制到目标项目：
 ```text
 docs/agent-collaboration-kit/
  README.md
  roles-and-permissions.md
  orca-closed-loop.md
  task-board-template.yaml
  prompt-templates.md
  optimization-method.md
  adoption-checklist.md
 ```
 目标项目还应在根目录保留一个项目级 `AGENTS.md`，引用本目录并填入项目自己的路径、测试命令和运行方式。
 ## 核心原则
 1. **事实源持久化**：任务、bug、验收证据写入任务板文件，不依赖聊天上下文。
 2. **角色隔离**：Product/Test Agent 只定义和验证；Developer Agent 只实现和自测。
 3. **worker_done 不等于完成**：开发 Agent 声称修好后，必须由 Product/Test Agent 黑盒复测。
 4. **最多三轮自动修复**：同一问题三轮仍未通过，记录为遗留项，然后继续处理下一个问题。
 5. **服务与 worktree 对齐**：复测前确认服务、构建产物、分支和工作树一致，避免假通过或假失败。
 ## 快速接入步骤
 1. 复制本目录到目标项目。
 2. 基于 `roles-and-permissions.md` 在目标项目根目录创建或更新 `AGENTS.md`。
 3. 基于 `task-board-template.yaml` 创建 `tasks.yaml`。
 4. 在 `AGENTS.md` 中写清：
   - 项目运行命令
   - 单元测试命令
   - 构建命令
   - 集成/浏览器测试命令
   - Product/Test 与 Developer 的路径权限
 5. 使用 `orca-closed-loop.md` 的流程派发修复。
 6. 按 `optimization-method.md` 执行三轮失败留档和节奏优化。
 ## 建议的默认口令
 ```text
 用 Agent 协作闭环处理 tasks.yaml 里的未通过项；每个问题最多派发开发 Agent 修三轮，三轮仍不过就记录为遗留，然后继续下一个。
 ```
 ## 与具体项目解耦
 本工具包使用占位符表达项目差异：
 - `<repo_path>`：仓库根目录
 - `<dev_worktree>`：开发 Agent 工作树
 - `<base_url>`：待测服务地址
 - `<test_commands>`：项目测试命令
 - `<source_paths>`：开发可改源码路径
 - `<spec_paths>`：产品/测试可改规格与测试路径
 复制到新项目后，应先替换这些占位符，再开始调度。
@@ -0,0 +1,74 @@
 # Adoption Checklist
 复制本工具包到新项目后，按这份清单接入。
 ## 1. 项目级规范
 - [ ] 根目录存在 `AGENTS.md`。
 - [ ] `AGENTS.md` 引用 `docs/agent-collaboration-kit/`。
 - [ ] 写清项目简介和技术栈。
 - [ ] 写清本地运行命令。
 - [ ] 写清构建命令。
 - [ ] 写清单元测试命令。
 - [ ] 写清集成测试或浏览器测试命令。
 ## 2. 路径权限
 - [ ] Product/Test 可写规格路径：`<spec_paths>`。
 - [ ] Product/Test 可写集成测试路径：`<integration_test_paths>`。
 - [ ] Developer 可写源码路径：`<source_paths>`。
 - [ ] Developer 可写单元测试路径：`<unit_test_paths>`。
 - [ ] 本地私有配置标记为只读或不提交。
 - [ ] 明确 `tasks.yaml` 状态字段谁可以改。
 ## 3. 任务板
 - [ ] 从 `task-board-template.yaml` 创建项目根目录 `tasks.yaml`。
 - [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`。
 - [ ] 至少添加一个示例任务，验证字段结构够用。
 - [ ] 约定状态：`open`、`dispatched`、`fixed_by_dev`、`retesting`、`verified`、`leftover`。
 ## 4. Orca 编排
 - [ ] `orca status --json` 可用。
 - [ ] `orca terminal list --json` 能看到 Coordinator 终端。
 - [ ] 能创建或复用 Developer Worker。
 - [ ] 决定默认使用当前 worktree 还是隔离 worktree。
 - [ ] 验证 `worker_done` 能发回 Coordinator。
 ## 5. 验证命令
 - [ ] Product/Test 有黑盒验证命令。
 - [ ] Developer 有白盒验证命令。
 - [ ] 构建产物和服务启动命令写清楚。
 - [ ] 浏览器测试的 `BASE_URL` 写清楚。
 - [ ] 复测前能确认服务来自正确 worktree。
 ## 6. 三轮失败策略
 - [ ] 每个任务记录 `rounds` 或等效 evidence。
 - [ ] 三轮失败后标记 `leftover`。
 - [ ] `leftover` 不阻塞继续处理其他任务。
 - [ ] 最终报告列出所有 `leftover` 和最后失败证据。
 ## 7. 第一次试运行
 推荐选择一个低风险 bug 跑完整流程：
 1. Product/Test 写入 `tasks.yaml`。
 2. 创建 Orca task。
 3. 派发 Developer Worker。
 4. 等待 `worker_done`。
 5. Product/Test 复测。
 6. 更新 `tasks.yaml`。
 7. 输出总结。
 试运行结束后，检查是否出现以下问题：
 - Developer 修改了越权路径。
 - worker_done 没有验证证据。
 - Product/Test 复测到了旧服务。
 - 任务板字段不够记录失败原因。
 - 三轮失败策略没有被执行。
 把发现的问题回写到项目 `AGENTS.md` 或本工具包的项目副本中。
@@ -0,0 +1,194 @@
 # Optimization Method
 本文件记录更稳的多 Agent 协作方法，目标是减少“开发声称完成但复测不过”的循环成本。
 ## 1. 先把验收写成可观测信号
 不要只写“页面可用”“体验更好”。每个任务至少写三类信号：
 | 类型 | 示例 |
 |------|------|
 | 可见文本 | 页面出现 `确认应用标签`、`取消`、`将修改` |
 | API 结果 | `POST /api/...` 返回 `code=0` 且字段存在 |
 | 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
 好的验收：
 ```text
 点击“预览变更”后，页面必须出现 API 返回的 diff 行：
 - title
 - 修改前值
 - 修改后值
 - coverChanged 提示
 ```
 不好的验收：
 ```text
 预览功能正常。
 ```
 ## 2. worker_done 必须带证据，不带结论
 Developer Worker 的 `worker_done` 应该报告：
 - 改了哪些文件。
 - 跑了哪些命令。
 - 自己如何复现验收路径。
 - 仍可能有的风险。
 不要让 Developer Worker 写：
 ```text
 已完成，应该可以了。
 ```
 要写：
 ```text
 修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
 手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
 风险：未执行真实写文件 apply。
 ```
 ## 3. Product/Test 只信自己的复测
 即使 worker_done 写了“全部通过”，Coordinator 仍必须重新：
 1. 确认 worktree。
 2. 构建或重启服务。
 3. 执行验收命令。
 4. 浏览器或 API 复测。
 5. 更新任务板。
 这可以避免三类假通过：
 - 测错服务实例。
 - 测到旧构建产物。
 - 开发只验证静态文本，没有验证真实交互。
 ## 4. 三轮失败策略
 每个任务最多自动派发三轮。
 ```text
 round 1: 常规修复
 round 2: 带复测失败证据的定向修复
 round 3: 明确指出重复失败点，要求 worker 自己复现完整路径
 failed after round 3: 标记 leftover，继续下一个任务
 ```
 三轮失败后不要继续消耗同一个 worker。常见原因是：
 - 验收标准需要重新设计。
 - Worker 对问题模型理解错了。
 - UI 自动化与实际浏览器状态有差异。
 - 需要人工观察或调试工具介入。
 留档字段建议：
 ```yaml
 status: leftover
 leftoverReason: "failed after 3 supervised developer rounds"
 attempts:
  - round: 1
    result: failed
    evidence: "<why failed>"
  - round: 2
    result: failed
    evidence: "<why failed>"
  - round: 3
    result: failed
    evidence: "<why failed>"
 ```
 ## 5. 任务排序
 推荐排序：
 1. P0 阻塞主流程。
 2. P1 高频用户路径。
 3. P1/P2 体验改进。
 4. 重构和内部质量。
 三轮失败的 P0 可以留档，但最终发布前需要人工决策：
 - 降级范围。
 - 改验收标准。
 - 换新 Agent / 新 worktree 重做。
 - 人工修复。
 ## 6. 每轮派发只修一个明确问题
 不要一次让 Developer Worker 修太多失败项，除非它们共享同一根因。推荐：
 ```text
 one dispatch = one bug = one acceptance path
 ```
 优点：
 - 复测更快。
 - 失败原因更清楚。
 - 三轮失败留档更准确。
 ## 7. 复测前强制记录运行环境
 每轮复测前记录：
 ```text
 repo:
 worktree:
 branch:
 commit:
 server command:
 BASE_URL:
 frontendDir:
 test commands:
 ```
 如果服务是长跑进程，确认它加载的是最新构建产物。静态前端项目尤其要注意是否重新 `build`。
 ## 8. 把失败证据写给下一轮 worker
 第二轮以后，派发 prompt 不应重复原始描述为主，而应突出“上一轮为什么没过”。
 模板：
 ```text
 上一轮不是完全失败，以下部分已通过：
 - <passed checks>
 仍失败：
 - <missing checks>
 直接 API/底层验证：
 - <api result>
 请重点排查：
 - <suspected area>
 ```
 ## 9. 优先让测试可执行化
 如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。优先级：
 1. API smoke。
 2. 浏览器脚本或 case 文档。
 3. 单元测试。
 4. 人工检查清单。
 目标不是所有东西都自动化，而是把最容易反复误判的路径自动化。
 ## 10. 结束条件
 一轮闭环结束时，必须能回答：
 - 哪些任务 verified？
 - 哪些任务 leftover？
 - 每个 leftover 失败了几轮？
 - 最后一轮失败证据是什么？
 - 当前工作树有哪些未提交改动？
 - 是否还有 open / failed_retest 未处理？
 如果这些问题答不清楚，闭环还没有结束。
@@ -0,0 +1,229 @@
 # Orca Closed Loop Workflow
 Orca orchestration 是运行时调度层，`tasks.yaml` 是持久事实源。不要把 Orca 消息当成最终记录；所有结论都要回写任务板。
 ## 什么时候使用 Orca 编排
 使用：
 - 用户要求监督、等待结果、闭环修复、三轮重试。
 - 有多个 bug 或多个可独立派发的任务。
 - Product/Test 与 Developer 需要明确分工。
 - 需要 `worker_done` 后再复测。
 不使用：
 - 单次问答。
 - 用户只是要求完整 handoff，不需要你监督。
 - 不需要测试和复测的小改动。
 ## 标准闭环
 ```text
 Product/Test 发现或读取 open 任务
  -> 写入/补全 tasks.yaml 验收标准
  -> 创建 Orca task
  -> dispatch 给 Developer Worker
  -> 等待 worker_done / escalation / decision_gate
  -> Product/Test 构建并复测
  -> 通过：verified
  -> 失败：failed_retest，追加证据，最多再派发两轮
  -> 三轮失败：leftover，继续下一个任务
 ```
 ## 运行前检查
 ```bash
 orca status --json
 orca terminal list --json
 orca orchestration task-list --json
 orca orchestration inbox --limit 20 --json
 ```
 确认：
 - Orca runtime 可达。
 - Coordinator 终端和 Developer Worker 终端都存在。
 - Developer Worker 在正确 worktree。
 - 当前没有会冲突的活跃编排任务。
 ## 创建父任务
 ```bash
 orca orchestration task-create --spec "$(cat <<'EOF'
 Goal: Complete <release_or_feature> with supervised Product/Test -> Developer loop.
 Coordinator:
 - Owns task board, black-box tests, retest, final verification.
 Developer:
 - Owns implementation and white-box verification.
 Policy:
 - Each issue can be dispatched at most 3 rounds.
 - If still failing after 3 rounds, record as leftover and continue next issue.
 - worker_done is not final completion.
 EOF
 )" --json
 ```
 ## 创建子任务
 ```bash
 orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
 Fix <task_id>: <title>
 Repository:
 - Path: <repo_path>
 - Worktree: <dev_worktree>
 Read:
 - AGENTS.md
 - tasks.yaml
 - <relevant_spec_or_test_doc>
 Failure evidence:
 - <copy latest Product/Test evidence>
 Acceptance:
 - <copy expected behavior>
 - <copy verification commands>
 Constraints:
 - Follow AGENTS.md path scope.
 - Do not mark verified.
 - Do not commit or push unless user asks.
 EOF
 )" --json
 ```
 ## 派发给 Developer Worker
 如果终端是 Orca 可识别的 Agent CLI：
 ```bash
 orca orchestration dispatch \
  --task <task_id> \
  --to <developer_handle> \
  --inject \
  --json
 ```
 如果不能 `--inject`，先登记 dispatch，再手动发送带上下文的 prompt：
 ```bash
 orca orchestration dispatch \
  --task <task_id> \
  --to <developer_handle> \
  --json
 ```
 ```bash
 orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
 You are receiving a supervised Orca task.
 taskId: <task_id>
 dispatchId: <dispatch_id>
 coordinator: <coordinator_handle>
 Task:
 - Fix <task_id>: <title>
 Acceptance:
 - <expected behavior>
 Verification:
 - <test_commands>
 When done, send exactly one worker_done:
 orca orchestration send --to <coordinator_handle> --type worker_done --subject "<task_id> fixed" --body "<summary>" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","filesModified":["<paths>"],"verification":["<commands>"]}' --json
 EOF
 )" --enter --json
 ```
 ## 等待结果
 ```bash
 orca orchestration check \
  --terminal <coordinator_handle> \
  --wait \
  --types worker_done,escalation,decision_gate \
  --timeout-ms 900000 \
  --json
 ```
 等待超时不等于失败。长任务可以继续等待，或检查 worker 终端活性。
 ## worker_done 后复测
 Product/Test 必须自己验证：
 ```bash
 git status --short
 <test_commands>
 curl -s <base_url>/health-or-summary
 ```
 浏览器复测建议记录：
 ```text
 BASE_URL:
 page:
 steps:
 expected:
 actual:
 snapshot evidence:
 ```
 ## 服务与 worktree 对齐
 复测前记录：
 ```bash
 pwd
 git rev-parse --abbrev-ref HEAD
 git rev-parse --short HEAD
 ```
 记录服务：
 ```text
 serverPid:
 serverCommand:
 BASE_URL:
 frontendDir:
 worktreePath:
 ```
 如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须停止并重启正确服务后再测。
 ## 结果回写
 通过：
 ```yaml
 status: verified
 verifiedAt: "<timestamp>"
 evidence:
  verification: "<commands passed>"
  browser: "<snapshot or API evidence>"
 ```
 失败但未满三轮：
 ```yaml
 status: failed_retest
 attempts:
  - round: 1
    result: failed
    evidence: "<latest evidence>"
 ```
 三轮失败：
 ```yaml
 status: leftover
 leftoverReason: "failed after 3 supervised developer rounds"
 evidence:
  final: "<latest failing evidence>"
 ```
@@ -0,0 +1,137 @@
 # Prompt Templates
 这些模板用于 Coordinator 给 Developer Worker 派发任务。复制时替换尖括号占位符。
 ## 1. 初始派发模板
 ```text
 你现在接到一个受监督的 Orca 编排任务。请在 <dev_worktree> 开发工作树内完成。
 编排上下文：
 - taskId: <orca_task_id>
 - dispatchId: <orca_dispatch_id>
 - coordinator: <coordinator_handle>
 任务：
 - 修复 <task_id>: <task_title>
 请先读取：
 - AGENTS.md
 - tasks.yaml
 - <relevant_spec_or_test_doc>
 当前失败证据：
 <copy latest Product/Test evidence>
 验收标准：
 1. <expected behavior 1>
 2. <expected behavior 2>
 3. <expected behavior 3>
 约束：
 - 只修改 Developer 可写路径。
 - 不要修改 Product/Test 负责的规格和集成测试文件，除非任务明确要求。
 - 不要标记 verified。
 - 不要提交或推送，除非用户明确要求。
 - 最小 diff，避免无关重构。
 完成前必须运行：
 - <test command 1>
 - <test command 2>
 - <test command 3>
 完成后发送一次 worker_done：
 orca orchestration send --to <coordinator_handle> --type worker_done --subject "<task_id> fix ready round <n>" --body "<三句话内：修了什么、验证、风险>" --payload '{"taskId":"<orca_task_id>","dispatchId":"<orca_dispatch_id>","filesModified":["<paths>"],"verification":["<commands>"]}' --json
 如果阻塞，请发送 escalation 或 ask。
 ```
 ## 2. 复测失败再派发模板
 ```text
 第 <n> 轮 QA 未通过，请继续修 <task_id>。
 上一轮开发声称：
 <worker_done summary>
 Product/Test 独立复测结果：
 - 运行命令：<commands>
 - 失败页面/API：<page or endpoint>
 - 仍缺失：<missing expected checks>
 - 实际观察：<actual evidence>
 关键提示：
 - 不要只满足静态文案，必须满足交互后的真实状态。
 - 如果后端/API 正常而 UI 不更新，请优先排查事件链、状态重置、异步请求、构建产物和服务 worktree。
 - 修复后请自己用浏览器或脚本复现 Product/Test 的完整步骤。
 验收不变：
 <copy acceptance criteria>
 完成后发送 worker_done，subject 使用：
 "<task_id> fix ready round <n>"
 ```
 ## 3. 三轮失败留档模板
 ```text
 <task_id> 已完成 3 轮受监督修复，但仍未通过 Product/Test 复测。
 最终状态：
 - status: leftover
 - reason: failed after 3 supervised developer rounds
 保留证据：
 - round 1: <summary>
 - round 2: <summary>
 - round 3: <summary>
 - final failing evidence: <latest evidence>
 处理策略：
 - 不再自动派发同一问题。
 - 继续处理下一个 open / failed_retest 任务。
 - 该问题留给人工专项检查或后续重新设计。
 ```
 ## 4. Developer Worker worker_done 模板
 ```bash
 orca orchestration send \
  --to <coordinator_handle> \
  --type worker_done \
  --subject "<task_id> fix ready round <n>" \
  --body "<修了什么。跑了哪些验证。还有什么风险。>" \
  --payload '{
    "taskId": "<orca_task_id>",
    "dispatchId": "<orca_dispatch_id>",
    "filesModified": [
      "<file_a>",
      "<file_b>"
    ],
    "verification": [
      "<command_a>: passed",
      "<command_b>: passed"
    ],
    "risk": "<remaining risk or none>"
  }' \
  --json
 ```
 ## 5. Coordinator 最终报告模板
 ```text
 本轮闭环完成。
 已验证：
 - <task_id>: <what passed>
 遗留：
 - <task_id>: 三轮仍未通过，已记录为 leftover。最后失败证据：<evidence>
 验证命令：
 - <command>: passed
 工作树状态：
 - <repo_path>: <git status summary>
 - <dev_worktree>: <git status summary>
 ```
@@ -0,0 +1,98 @@
 # Roles And Permissions
 本文件定义多 Agent 协作的责任边界。目标是让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
 ## 角色模型
 | 角色 | 主要职责 | 验证方式 | 不应做的事 |
 |------|----------|----------|------------|
 | Product/Test Coordinator | 需求拆解、任务记录、黑盒测试、复测验收、调度开发 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、凭 worker_done 直接标记完成 |
 | Developer Worker | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格、标记 verified、绕过测试声称完成 |
 | User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
 ## 路径权限模板
 目标项目应在 `AGENTS.md` 中填入实际路径。
 | 路径 | Product/Test | Developer | 说明 |
 |------|:------------:|:---------:|------|
 | `<spec_paths>` | R/W | Read-only | PRD、API spec、设计文档 |
 | `<integration_test_paths>` | R/W | Read-only | 浏览器用例、API smoke、回归清单 |
 | `<test_records_path>` | R/W | Read-only | 复测记录，通常可 gitignore |
 | `<source_paths>` | Read-only | R/W | 应用源码 |
 | `<unit_test_paths>` | Read-only | R/W | 单元测试 |
 | `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
 | `<local_config>` | Read-only | Read-only | 本地私有配置，不提交 |
 | `tasks.yaml` | R/W | Limited R/W | 任务事实源；Developer 可写实现状态和证据，Product/Test 写 verified |
 ## Product/Test Coordinator 工作流
 1. 读取用户目标、项目规格、任务板。
 2. 用黑盒方式复现问题或验证需求。
 3. 在 `tasks.yaml` 写入任务：
   - 复现步骤
   - 预期结果
   - 实际结果
   - 证据
   - 验收命令或验收页面
 4. 创建 Orca 编排任务并派发 Developer Worker。
 5. 等待 `worker_done` / `escalation` / `decision_gate`。
 6. 重新构建和复测。
 7. 通过则标记 `verified`；失败则追加证据并继续派发，最多三轮。
 8. 三轮失败则标记为遗留项，继续下一个任务。
 ## Developer Worker 工作流
 1. 读取 `AGENTS.md`、`tasks.yaml` 和相关规格。
 2. 只修改 Developer 可写路径。
 3. 做最小正确修改，避免顺手重构。
 4. 为非平凡逻辑补充或更新单元测试。
 5. 运行项目要求的验证命令。
 6. 完成后发送一次 `worker_done`，包含：
   - 修改文件
   - 验证命令和结果
   - 剩余风险
 7. 不标记 `verified`，也不提交或推送，除非用户明确要求。
 ## 状态机
 推荐 `tasks.yaml` 使用以下状态：
 ```text
 open
  -> dispatched
  -> fixed_by_dev
  -> retesting
  -> verified
 ```
 失败分支：
 ```text
 dispatched -> blocked
 fixed_by_dev -> failed_retest -> dispatched
 failed_retest x3 -> leftover
 ```
 状态定义：
 | 状态 | 写入者 | 含义 |
 |------|--------|------|
 | `open` | Product/Test | 已发现，等待处理 |
 | `dispatched` | Product/Test | 已派发给开发 Agent |
 | `blocked` | Product/Test 或 Developer | 需要用户决策或外部条件 |
 | `fixed_by_dev` | Developer | 开发声称已修复并提供验证 |
 | `retesting` | Product/Test | 正在复测 |
 | `failed_retest` | Product/Test | 复测失败，可继续派发 |
 | `verified` | Product/Test | 复测通过 |
 | `leftover` | Product/Test | 三轮仍未通过，留给人工或专项处理 |
 ## 完成定义
 一个任务只有同时满足以下条件，才能标记 `verified`：
 - Developer 已提供修改文件和验证证据。
 - Product/Test 在正确 worktree 和正确服务实例上复测。
 - 相关单元测试、构建、集成或浏览器检查通过。
 - `tasks.yaml` 中记录了复测证据。
 - 用户可见行为符合验收标准。
@@ -0,0 +1,76 @@
 version: 1
 updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
 source: "Product/Test Agent"
 project:
  name: "<project_name>"
  repoPath: "<repo_path>"
  baseUrl: "<base_url>"
  devWorktree: "<dev_worktree>"
 summary:
  verified: []
  open: []
  failedRetest: []
  leftovers: []
 tasks:
  - id: "BUG-001"
    type: "bug"
    title: "<short title>"
    priority: "P0"
    status: "open"
    assignee: "developer"
    component: "<source file or module>"
    specRefs:
      - "<docs/spec.md#section>"
    testRefs:
      - "<tests/browser/cases/01-case.md>"
    description: >
      <What is wrong, in user-visible terms.>
    stepsToReproduce:
      - "<step 1>"
      - "<step 2>"
      - "<step 3>"
    expected: >
      <Expected behavior.>
    actual: >
      <Actual behavior observed by Product/Test.>
    evidence:
      browser: "<snapshot text, screenshot path, or UI finding>"
      api: "<curl result or API mismatch>"
      logs: "<relevant log line if any>"
    verification:
      commands:
        - "<unit/build command>"
        - "<browser/API smoke command>"
      browser:
        page: "<page path>"
        checks:
          - "<visible text or interaction expected>"
    dispatch:
      taskId: null
      dispatchId: null
      worker: null
      rounds: []
    resolution:
      fixedBy: null
      verifiedAt: null
      leftoverReason: null
 statusReference:
  open: "Product/Test found issue; not dispatched yet"
  dispatched: "Sent to Developer Worker"
  fixed_by_dev: "Developer claims fixed and provides verification"
  retesting: "Product/Test is verifying"
  failed_retest: "Product/Test verification failed"
  verified: "Product/Test verification passed"
  blocked: "Needs user or external decision"
  leftover: "Failed after 3 developer rounds; preserved for later manual review"