docs: separate agent collaboration kit from skills
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -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"
|
||||
Reference in New Issue
Block a user