refactor(agent-collaboration-kit): split stable core from project overrides
- Reorganize flat files into core/ templates/ examples/ scripts/ with VERSION - Deduplicate: single-source state machine, three-round policy, acceptance signals - Abstract orchestration in closed-loop.md with manual mode; move Orca commands to orca-adapter.md - Add tasks.schema.json + validate_tasks.py (jsonschema or builtin rules, no hard deps) - Add filled examples, concurrency write rule, kitVersion tracking; unify to Chinese Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -1,94 +0,0 @@
|
|||||||
# <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.
|
|
||||||
@@ -1,68 +1,77 @@
|
|||||||
# Agent Collaboration Kit
|
# Agent Collaboration Kit
|
||||||
|
|
||||||
这是一套可复制到其他项目的多 Agent 协作规范。它把“产品/测试负责定义与验收，开发负责实现与白盒验证，协调者用 Orca 做闭环调度”的经验抽成项目无关模板。
|
一套可复用到其它项目的多 Agent 协作规范：**产品/测试负责定义与验收，开发负责实现与白盒验证，协调者做闭环调度**。
|
||||||
|
|
||||||
|
当前版本见 `VERSION`。这不是 Agent Skill（无 `SKILL.md`），不由 skiff 安装，而是复制/引用到目标项目。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 适用场景
|
## 适用场景
|
||||||
|
|
||||||
- 项目需要多个 Agent 分工协作，而不是单个 Agent 从需求写到代码。
|
- 多个 Agent 分工协作，而非单个 Agent 从需求写到代码。
|
||||||
- 需要明确区分规格、测试、实现、复测的责任边界。
|
- 需要区分规格、测试、实现、复测的责任边界。
|
||||||
- 需要把测试失败项派发给开发 Agent，等 `worker_done` 后再由测试 Agent 复测。
|
- 需要把失败项派发给开发 Agent，`worker_done` 后由测试 Agent 复测。
|
||||||
- 需要连续修复多个问题，并把三次仍未修好的问题留档。
|
- 需要连续修复多个问题，并把三轮仍未修好的问题留档。
|
||||||
|
|
||||||
## 推荐目录
|
---
|
||||||
|
|
||||||
把本目录复制到目标项目：
|
## 目录结构
|
||||||
|
|
||||||
```text
|
```text
|
||||||
docs/agent-collaboration-kit/
|
agent-collaboration-kit/
|
||||||
|
VERSION # kit 版本，接入时记入项目
|
||||||
README.md
|
README.md
|
||||||
roles-and-permissions.md
|
|
||||||
orca-closed-loop.md
|
|
||||||
task-board-template.yaml
|
|
||||||
prompt-templates.md
|
|
||||||
optimization-method.md
|
|
||||||
adoption-checklist.md
|
adoption-checklist.md
|
||||||
|
core/ # 稳定核心：跨项目通用，随 kit 升级，尽量别改
|
||||||
|
roles-and-permissions.md # 角色/权限/状态机/完成定义（SSOT）
|
||||||
|
closed-loop.md # 编排无关闭环 + 手动模式 + worktree 对齐
|
||||||
|
optimization-method.md # 验收信号 + 三轮失败策略（SSOT）
|
||||||
|
prompt-templates.md # 派发 prompt 模板
|
||||||
|
orca-adapter.md # Orca 具体命令（一种编排实现，可选）
|
||||||
|
templates/ # 项目覆盖层：复制一次并填空
|
||||||
|
AGENTS.template.md
|
||||||
|
tasks.template.yaml
|
||||||
|
tasks.schema.json # 任务板权威结构（跨语言）
|
||||||
|
examples/ # 填好的最小可跑示例
|
||||||
|
AGENTS.example.md
|
||||||
|
tasks.example.yaml
|
||||||
|
scripts/
|
||||||
|
validate_tasks.py # 校验 tasks.yaml（参考实现）
|
||||||
```
|
```
|
||||||
|
|
||||||
目标项目还应在根目录保留一个项目级 `AGENTS.md`，引用本目录并填入项目自己的路径、测试命令和运行方式。
|
**核心原则**：`core/` 是稳定核心，每个概念只定义一次；`templates/` 是项目覆盖层。二者分离，让 kit 升级和项目定制互不干扰。
|
||||||
|
|
||||||
## 核心原则
|
---
|
||||||
|
|
||||||
1. **事实源持久化**：任务、bug、验收证据写入任务板文件，不依赖聊天上下文。
|
## 分发方式（二选一）
|
||||||
2. **角色隔离**：Product/Test Agent 只定义和验证；Developer Agent 只实现和自测。
|
|
||||||
3. **worker_done 不等于完成**：开发 Agent 声称修好后，必须由 Product/Test Agent 黑盒复测。
|
|
||||||
4. **最多三轮自动修复**：同一问题三轮仍未通过，记录为遗留项，然后继续处理下一个问题。
|
|
||||||
5. **服务与 worktree 对齐**：复测前确认服务、构建产物、分支和工作树一致，避免假通过或假失败。
|
|
||||||
|
|
||||||
## 快速接入步骤
|
### 方式 A：引用稳定核心（推荐，可升级）
|
||||||
|
|
||||||
1. 复制本目录到目标项目。
|
`core/` + `scripts/` 通过 symlink / git submodule / sparse checkout 映射到项目 `docs/agent-collaboration-kit/`；项目只维护自己的 `AGENTS.md`、`tasks.yaml`。kit 升级时稳定核心自动生效，项目定制不受影响。
|
||||||
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` 执行三轮失败留档和节奏优化。
|
|
||||||
|
|
||||||
## 建议的默认口令
|
### 方式 B：整份复制（简单，手动升级）
|
||||||
|
|
||||||
|
整目录复制到 `docs/agent-collaboration-kit/`。**务必**在项目 `AGENTS.md` 与 `tasks.yaml` 的 `kitVersion` 记录来源版本，日后照 `VERSION` diff 升级 `core/`。
|
||||||
|
|
||||||
|
无论哪种方式，项目的 `AGENTS.md` 只填差异（路径、命令、handle），不复制 `core/` 内容。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 快速接入
|
||||||
|
|
||||||
|
1. 选定分发方式，把 kit 放到项目 `docs/agent-collaboration-kit/`。
|
||||||
|
2. 复制 `templates/AGENTS.template.md` → 项目根 `AGENTS.md`，填项目差异，记 `kitVersion`。
|
||||||
|
3. 复制 `templates/tasks.template.yaml` → 项目根 `tasks.yaml`，填 `project` 与首个任务。
|
||||||
|
4. 跑 `python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml` 确认结构。
|
||||||
|
5. 按 `core/closed-loop.md` 跑闭环（Orca 见 `core/orca-adapter.md`，无 Orca 用手动模式）。
|
||||||
|
6. 逐项对照 `adoption-checklist.md`。
|
||||||
|
|
||||||
|
参考 `examples/` 里填好的 `AGENTS.example.md` 与 `tasks.example.yaml`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 默认口令
|
||||||
|
|
||||||
```text
|
```text
|
||||||
用 Agent 协作闭环处理 tasks.yaml 里的未通过项；每个问题最多派发开发 Agent 修三轮，三轮仍不过就记录为遗留，然后继续下一个。
|
用 Agent 协作闭环处理 tasks.yaml 里的未通过项；每个问题最多派发开发 Agent 修三轮，三轮仍不过就记录为遗留，然后继续下一个。
|
||||||
```
|
```
|
||||||
|
|
||||||
## 与具体项目解耦
|
|
||||||
|
|
||||||
本工具包使用占位符表达项目差异：
|
|
||||||
|
|
||||||
- `<repo_path>`：仓库根目录
|
|
||||||
- `<dev_worktree>`：开发 Agent 工作树
|
|
||||||
- `<base_url>`：待测服务地址
|
|
||||||
- `<test_commands>`：项目测试命令
|
|
||||||
- `<source_paths>`：开发可改源码路径
|
|
||||||
- `<spec_paths>`：产品/测试可改规格与测试路径
|
|
||||||
|
|
||||||
复制到新项目后，应先替换这些占位符，再开始调度。
|
|
||||||
|
|||||||
@@ -0,0 +1 @@
|
|||||||
|
0.2.0
|
||||||
@@ -1,74 +1,59 @@
|
|||||||
# Adoption Checklist
|
# 接入清单
|
||||||
|
|
||||||
复制本工具包到新项目后，按这份清单接入。
|
把本工具包引用/复制到新项目后，按此清单接入。术语与规则详见 `core/`。
|
||||||
|
|
||||||
## 1. 项目级规范
|
## 1. 分发与版本
|
||||||
|
|
||||||
- [ ] 根目录存在 `AGENTS.md`。
|
- [ ] 选定分发方式（README §「分发方式」A 引用 / B 复制）。
|
||||||
- [ ] `AGENTS.md` 引用 `docs/agent-collaboration-kit/`。
|
- [ ] kit 放到 `docs/agent-collaboration-kit/`。
|
||||||
- [ ] 写清项目简介和技术栈。
|
- [ ] 项目 `AGENTS.md` 与 `tasks.yaml` 记录 `kitVersion`（对齐 kit 根 `VERSION`）。
|
||||||
- [ ] 写清本地运行命令。
|
|
||||||
- [ ] 写清构建命令。
|
|
||||||
- [ ] 写清单元测试命令。
|
|
||||||
- [ ] 写清集成测试或浏览器测试命令。
|
|
||||||
|
|
||||||
## 2. 路径权限
|
## 2. 项目级规范（覆盖层）
|
||||||
|
|
||||||
- [ ] Product/Test 可写规格路径：`<spec_paths>`。
|
- [ ] 由 `templates/AGENTS.template.md` 生成项目根 `AGENTS.md`。
|
||||||
- [ ] Product/Test 可写集成测试路径：`<integration_test_paths>`。
|
- [ ] `AGENTS.md` 引用 `docs/agent-collaboration-kit/core/`，不复制其内容。
|
||||||
- [ ] Developer 可写源码路径：`<source_paths>`。
|
- [ ] 填清项目简介、技术栈、运行/构建/单测/集成测试命令。
|
||||||
- [ ] Developer 可写单元测试路径：`<unit_test_paths>`。
|
|
||||||
- [ ] 本地私有配置标记为只读或不提交。
|
|
||||||
- [ ] 明确 `tasks.yaml` 状态字段谁可以改。
|
|
||||||
|
|
||||||
## 3. 任务板
|
## 3. 路径权限
|
||||||
|
|
||||||
- [ ] 从 `task-board-template.yaml` 创建项目根目录 `tasks.yaml`。
|
- [ ] 填实际的 Product/Test 可写路径（规格、集成测试、复测记录）。
|
||||||
|
- [ ] 填实际的 Developer 可写路径（源码、单元测试、配置模板）。
|
||||||
|
- [ ] 本地私有配置标记只读或不提交。
|
||||||
|
- [ ] 确认 `tasks.yaml` 只有 Coordinator 写（见 `core/roles-and-permissions.md`）。
|
||||||
|
|
||||||
|
## 4. 任务板
|
||||||
|
|
||||||
|
- [ ] 由 `templates/tasks.template.yaml` 生成项目根 `tasks.yaml`。
|
||||||
- [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`。
|
- [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`。
|
||||||
- [ ] 至少添加一个示例任务，验证字段结构够用。
|
- [ ] 至少加一个真实任务，验收写成可观测信号（见 `core/optimization-method.md` §1）。
|
||||||
- [ ] 约定状态：`open`、`dispatched`、`fixed_by_dev`、`retesting`、`verified`、`leftover`。
|
- [ ] 跑 `scripts/validate_tasks.py tasks.yaml` 通过。
|
||||||
|
|
||||||
## 4. Orca 编排
|
## 5. 编排
|
||||||
|
|
||||||
- [ ] `orca status --json` 可用。
|
- [ ] 决定用 Orca（`core/orca-adapter.md`）还是手动模式（`core/closed-loop.md`）。
|
||||||
- [ ] `orca terminal list --json` 能看到 Coordinator 终端。
|
- [ ] Orca：`orca status`、`terminal list` 可用，`worker_done` 能发回 Coordinator。
|
||||||
- [ ] 能创建或复用 Developer Worker。
|
- [ ] 决定用当前 worktree 还是隔离 worktree。
|
||||||
- [ ] 决定默认使用当前 worktree 还是隔离 worktree。
|
|
||||||
- [ ] 验证 `worker_done` 能发回 Coordinator。
|
|
||||||
|
|
||||||
## 5. 验证命令
|
## 6. 验证命令
|
||||||
|
|
||||||
- [ ] Product/Test 有黑盒验证命令。
|
- [ ] Product/Test 有黑盒验证命令，Developer 有白盒验证命令。
|
||||||
- [ ] Developer 有白盒验证命令。
|
- [ ] 构建产物与服务启动命令写清。
|
||||||
- [ ] 构建产物和服务启动命令写清楚。
|
- [ ] 浏览器测试 `BASE_URL` 写清，复测前能确认服务来自正确 worktree。
|
||||||
- [ ] 浏览器测试的 `BASE_URL` 写清楚。
|
|
||||||
- [ ] 复测前能确认服务来自正确 worktree。
|
|
||||||
|
|
||||||
## 6. 三轮失败策略
|
## 7. 三轮失败策略
|
||||||
|
|
||||||
- [ ] 每个任务记录 `rounds` 或等效 evidence。
|
- [ ] 每个任务记录 `dispatch.rounds`。
|
||||||
- [ ] 三轮失败后标记 `leftover`。
|
- [ ] 三轮失败标记 `leftover` 并填 `resolution.leftoverReason`。
|
||||||
- [ ] `leftover` 不阻塞继续处理其他任务。
|
- [ ] `leftover` 不阻塞其它任务；最终报告列出所有 `leftover` 与最后失败证据。
|
||||||
- [ ] 最终报告列出所有 `leftover` 和最后失败证据。
|
|
||||||
|
|
||||||
## 7. 第一次试运行
|
## 8. 第一次试运行
|
||||||
|
|
||||||
推荐选择一个低风险 bug 跑完整流程：
|
选一个低风险 bug 跑完整闭环，结束后检查是否出现：
|
||||||
|
|
||||||
1. Product/Test 写入 `tasks.yaml`。
|
|
||||||
2. 创建 Orca task。
|
|
||||||
3. 派发 Developer Worker。
|
|
||||||
4. 等待 `worker_done`。
|
|
||||||
5. Product/Test 复测。
|
|
||||||
6. 更新 `tasks.yaml`。
|
|
||||||
7. 输出总结。
|
|
||||||
|
|
||||||
试运行结束后，检查是否出现以下问题：
|
|
||||||
|
|
||||||
- Developer 修改了越权路径。
|
- Developer 修改了越权路径。
|
||||||
- worker_done 没有验证证据。
|
- worker_done 没有验证证据。
|
||||||
- Product/Test 复测到了旧服务。
|
- Product/Test 复测到了旧服务。
|
||||||
- 任务板字段不够记录失败原因。
|
- 任务板字段不够记录失败原因。
|
||||||
- 三轮失败策略没有被执行。
|
- 三轮失败策略没被执行。
|
||||||
|
|
||||||
把发现的问题回写到项目 `AGENTS.md` 或本工具包的项目副本中。
|
把发现的问题回写到项目 `AGENTS.md`；若属通用问题，回流到 kit 的 `core/` 并升 `VERSION`。
|
||||||
|
|||||||
@@ -0,0 +1,132 @@
|
|||||||
|
# 闭环流程（稳定核心，编排无关）
|
||||||
|
|
||||||
|
本文件定义**与具体编排工具无关**的协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。
|
||||||
|
|
||||||
|
原则：调度消息只是运行时载体，**所有结论都必须回写到 `tasks.yaml`**（事实源），不要把消息当最终记录。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 编排抽象
|
||||||
|
|
||||||
|
无论用什么工具，闭环都由这几个能力组成：
|
||||||
|
|
||||||
|
| 抽象动作 | 含义 | Orca 实现 | 手动实现 |
|
||||||
|
|----------|------|-----------|----------|
|
||||||
|
| `prepare(task)` | 把任务和验收标准写进 `tasks.yaml` | 同左 | 同左 |
|
||||||
|
| `dispatch(task, worker)` | 把任务连同上下文交给 Developer | `orca orchestration dispatch` | 复制 prompt 到 Developer 终端/会话 |
|
||||||
|
| `wait()` | 等待 `worker_done` / `escalation` / `decision_gate` | `orca orchestration check --wait` | 人工等待 Developer 回报 |
|
||||||
|
| `retest(task)` | Coordinator 独立黑盒复测 | 同左 | 同左 |
|
||||||
|
| `writeback(task, result)` | 把复测结果写回 `tasks.yaml` | 同左 | 同左 |
|
||||||
|
|
||||||
|
派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 标准闭环
|
||||||
|
|
||||||
|
```text
|
||||||
|
Product/Test 发现或读取 open 任务
|
||||||
|
-> prepare：写/补全 tasks.yaml 验收标准
|
||||||
|
-> dispatch 给 Developer Worker
|
||||||
|
-> wait：worker_done / escalation / decision_gate
|
||||||
|
-> retest：Coordinator 构建并独立复测
|
||||||
|
-> 通过：writeback verified
|
||||||
|
-> 失败：writeback failed_retest，追加证据，最多再派发两轮
|
||||||
|
-> 累计三轮失败：writeback leftover，继续下一个任务
|
||||||
|
```
|
||||||
|
|
||||||
|
一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 手动模式（无 Orca）
|
||||||
|
|
||||||
|
没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：
|
||||||
|
|
||||||
|
1. Coordinator 在 `tasks.yaml` 写好任务和验收标准。
|
||||||
|
2. 用 `prompt-templates.md` 的初始派发模板生成 prompt，手动发给 Developer（另一个会话/终端/人）。
|
||||||
|
3. Developer 完成后按 worker_done 模板回报（可直接贴回 Coordinator 会话）。
|
||||||
|
4. Coordinator 独立复测，回写 `tasks.yaml`。
|
||||||
|
5. 失败则用「复测失败再派发模板」继续，最多三轮。
|
||||||
|
|
||||||
|
手动模式下同样遵守：worker_done 不等于完成、只有 Coordinator 写 `tasks.yaml`、三轮失败留档。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## worker_done 后复测（编排无关）
|
||||||
|
|
||||||
|
即使 worker_done 写了"全部通过"，Coordinator 仍必须独立复测：
|
||||||
|
|
||||||
|
```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，必须**停止并重启正确服务**后再测。长跑服务或静态前端尤其要确认加载的是最新构建产物。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 结果回写
|
||||||
|
|
||||||
|
回写 `tasks.yaml` 时按状态填写（字段结构见 `templates/tasks.schema.json`）：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# 通过
|
||||||
|
status: verified
|
||||||
|
resolution:
|
||||||
|
verifiedAt: "<timestamp>"
|
||||||
|
evidence:
|
||||||
|
verification: "<commands passed>"
|
||||||
|
browser: "<snapshot or API evidence>"
|
||||||
|
```
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# 失败但未满三轮
|
||||||
|
status: failed_retest
|
||||||
|
dispatch:
|
||||||
|
rounds:
|
||||||
|
- round: 1
|
||||||
|
result: failed
|
||||||
|
evidence: "<latest evidence>"
|
||||||
|
```
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# 累计三轮失败
|
||||||
|
status: leftover
|
||||||
|
resolution:
|
||||||
|
leftoverReason: "failed after 3 supervised developer rounds"
|
||||||
|
evidence:
|
||||||
|
final: "<latest failing evidence>"
|
||||||
|
```
|
||||||
@@ -0,0 +1,148 @@
|
|||||||
|
# 优化方法（稳定核心）
|
||||||
|
|
||||||
|
减少"开发声称完成但复测不过"的循环成本。本文件是**验收信号写法**和**三轮失败策略**的 SSOT，其它文件引用这里。
|
||||||
|
|
||||||
|
复测步骤与环境对齐见 `closed-loop.md`；状态机与完成定义见 `roles-and-permissions.md`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 先把验收写成可观测信号（SSOT）
|
||||||
|
|
||||||
|
不要只写"页面可用""体验更好"。每个任务至少写三类信号：
|
||||||
|
|
||||||
|
| 类型 | 示例 |
|
||||||
|
|------|------|
|
||||||
|
| 可见文本 | 页面出现 `确认应用标签`、`取消`、`将修改` |
|
||||||
|
| API 结果 | `POST /api/...` 返回 `code=0` 且字段存在 |
|
||||||
|
| 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
|
||||||
|
|
||||||
|
好的验收：
|
||||||
|
|
||||||
|
```text
|
||||||
|
点击"预览变更"后，页面必须出现 API 返回的 diff 行：
|
||||||
|
- title
|
||||||
|
- 修改前值
|
||||||
|
- 修改后值
|
||||||
|
- coverChanged 提示
|
||||||
|
```
|
||||||
|
|
||||||
|
不好的验收：
|
||||||
|
|
||||||
|
```text
|
||||||
|
预览功能正常。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. worker_done 必须带证据，不带结论
|
||||||
|
|
||||||
|
Developer Worker 的 `worker_done` 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。
|
||||||
|
|
||||||
|
不要写：
|
||||||
|
|
||||||
|
```text
|
||||||
|
已完成，应该可以了。
|
||||||
|
```
|
||||||
|
|
||||||
|
要写：
|
||||||
|
|
||||||
|
```text
|
||||||
|
修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
|
||||||
|
手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
|
||||||
|
风险：未执行真实写文件 apply。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Product/Test 只信自己的复测
|
||||||
|
|
||||||
|
即使 worker_done 写了"全部通过"，Coordinator 仍必须独立复测。完整复测步骤与 worktree/服务对齐见 `closed-loop.md`。这可避免三类假通过：测错服务实例、测到旧构建产物、开发只验证静态文本没验证真实交互。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 三轮失败策略（SSOT）
|
||||||
|
|
||||||
|
每个任务最多自动派发三轮：
|
||||||
|
|
||||||
|
```text
|
||||||
|
round 1: 常规修复
|
||||||
|
round 2: 带复测失败证据的定向修复
|
||||||
|
round 3: 明确指出重复失败点，要求 worker 自己复现完整路径
|
||||||
|
failed after round 3: 标记 leftover，继续下一个任务
|
||||||
|
```
|
||||||
|
|
||||||
|
三轮失败后不要继续消耗同一个 worker。常见原因：验收标准需要重新设计、Worker 对问题模型理解错了、UI 自动化与实际浏览器状态有差异、需要人工观察或调试工具介入。
|
||||||
|
|
||||||
|
留档字段（结构见 `templates/tasks.schema.json`）：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
status: leftover
|
||||||
|
resolution:
|
||||||
|
leftoverReason: "failed after 3 supervised developer rounds"
|
||||||
|
dispatch:
|
||||||
|
rounds:
|
||||||
|
- 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. 把失败证据写给下一轮 worker
|
||||||
|
|
||||||
|
第二轮以后，派发 prompt 应突出"上一轮为什么没过"，而非重复原始描述。模板见 `prompt-templates.md` §「复测失败再派发模板」。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 优先让测试可执行化
|
||||||
|
|
||||||
|
如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。优先级：
|
||||||
|
|
||||||
|
1. API smoke。
|
||||||
|
2. 浏览器脚本或 case 文档。
|
||||||
|
3. 单元测试。
|
||||||
|
4. 人工检查清单。
|
||||||
|
|
||||||
|
目标不是全部自动化，而是把最容易反复误判的路径自动化。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 结束条件
|
||||||
|
|
||||||
|
一轮闭环结束时，必须能回答：
|
||||||
|
|
||||||
|
- 哪些任务 verified？哪些 leftover？
|
||||||
|
- 每个 leftover 失败了几轮？最后一轮失败证据是什么？
|
||||||
|
- 当前工作树有哪些未提交改动？
|
||||||
|
- 是否还有 open / failed_retest 未处理？
|
||||||
|
|
||||||
|
答不清楚，闭环就还没结束。
|
||||||
@@ -0,0 +1,126 @@
|
|||||||
|
# Orca 适配器（稳定核心，一种编排实现）
|
||||||
|
|
||||||
|
Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 `closed-loop.md`）；本文件只提供 Orca 的具体命令。没有 Orca 时用 `closed-loop.md` §「手动模式」。
|
||||||
|
|
||||||
|
所有结论仍以 `tasks.yaml` 为准，Orca 消息不是最终记录。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 何时用 Orca 编排
|
||||||
|
|
||||||
|
用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 `worker_done` 后再复测。
|
||||||
|
|
||||||
|
不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 运行前检查
|
||||||
|
|
||||||
|
```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 在正确 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 + verification commands>
|
||||||
|
|
||||||
|
Constraints:
|
||||||
|
- Follow AGENTS.md path scope.
|
||||||
|
- Do not write tasks.yaml, 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-templates.md` §1 的初始派发 prompt：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
orca orchestration dispatch --task <task_id> --to <developer_handle> --json
|
||||||
|
orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
|
||||||
|
<粘贴 prompt-templates.md §1 初始派发模板，已填占位符>
|
||||||
|
EOF
|
||||||
|
)" --enter --json
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 等待结果
|
||||||
|
|
||||||
|
```bash
|
||||||
|
orca orchestration check \
|
||||||
|
--terminal <coordinator_handle> \
|
||||||
|
--wait \
|
||||||
|
--types worker_done,escalation,decision_gate \
|
||||||
|
--timeout-ms 900000 \
|
||||||
|
--json
|
||||||
|
```
|
||||||
|
|
||||||
|
等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Developer 回报 worker_done
|
||||||
|
|
||||||
|
字段含义见 `prompt-templates.md` §3：
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
收到 worker_done 后，Coordinator 按 `closed-loop.md` 独立复测并回写 `tasks.yaml`。
|
||||||
@@ -0,0 +1,106 @@
|
|||||||
|
# 派发 Prompt 模板（稳定核心）
|
||||||
|
|
||||||
|
用于 Coordinator 给 Developer Worker 派发任务。复制时替换尖括号占位符。这些模板与编排工具无关：Orca 模式用 `orca-adapter.md` 的命令投递，手动模式直接把文本发给 Developer。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 初始派发模板
|
||||||
|
|
||||||
|
```text
|
||||||
|
你现在接到一个受监督的协作任务。请在 <dev_worktree> 开发工作树内完成。
|
||||||
|
|
||||||
|
任务：
|
||||||
|
- 修复 <task_id>: <task_title>
|
||||||
|
|
||||||
|
请先读取：
|
||||||
|
- AGENTS.md
|
||||||
|
- tasks.yaml
|
||||||
|
- <relevant_spec_or_test_doc>
|
||||||
|
|
||||||
|
当前失败证据：
|
||||||
|
<copy latest Product/Test evidence>
|
||||||
|
|
||||||
|
验收标准（可观测信号，见 optimization-method.md §1）：
|
||||||
|
1. <expected behavior 1>
|
||||||
|
2. <expected behavior 2>
|
||||||
|
3. <expected behavior 3>
|
||||||
|
|
||||||
|
约束：
|
||||||
|
- 只修改 Developer 可写路径（见 AGENTS.md 权限表）。
|
||||||
|
- 不要修改 Product/Test 负责的规格和集成测试文件，除非任务明确要求。
|
||||||
|
- 不要写 tasks.yaml，不要标记 verified。
|
||||||
|
- 不要提交或推送，除非用户明确要求。
|
||||||
|
- 最小 diff，避免无关重构。
|
||||||
|
|
||||||
|
完成前必须运行：
|
||||||
|
- <test command 1>
|
||||||
|
- <test command 2>
|
||||||
|
|
||||||
|
完成后回报一次 worker_done（格式见 §4）。如果阻塞，请发送 escalation 或 ask。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 复测失败再派发模板
|
||||||
|
|
||||||
|
```text
|
||||||
|
第 <n> 轮复测未通过，请继续修 <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. Developer Worker worker_done 回报格式（通用）
|
||||||
|
|
||||||
|
无论 Orca 还是手动，回报都应包含以下字段：
|
||||||
|
|
||||||
|
```text
|
||||||
|
subject: <task_id> fix ready round <n>
|
||||||
|
filesModified: [<file_a>, <file_b>]
|
||||||
|
verification:
|
||||||
|
- <command_a>: passed
|
||||||
|
- <command_b>: passed
|
||||||
|
reproduce: 我如何复现验收路径 <steps>
|
||||||
|
risk: <remaining risk or none>
|
||||||
|
```
|
||||||
|
|
||||||
|
Orca 模式下用 `orca-adapter.md` §「Developer 回报 worker_done」的命令发送同样的字段。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Coordinator 最终报告模板
|
||||||
|
|
||||||
|
```text
|
||||||
|
本轮闭环完成。
|
||||||
|
|
||||||
|
已验证：
|
||||||
|
- <task_id>: <what passed>
|
||||||
|
|
||||||
|
遗留：
|
||||||
|
- <task_id>: 三轮仍未通过，已记录为 leftover。最后失败证据：<evidence>
|
||||||
|
|
||||||
|
验证命令：
|
||||||
|
- <command>: passed
|
||||||
|
|
||||||
|
工作树状态：
|
||||||
|
- <repo_path>: <git status summary>
|
||||||
|
- <dev_worktree>: <git status summary>
|
||||||
|
```
|
||||||
+33
-41
@@ -1,6 +1,10 @@
|
|||||||
# Roles And Permissions
|
# 角色与权限（稳定核心）
|
||||||
|
|
||||||
本文件定义多 Agent 协作的责任边界。目标是让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
|
本文件是**角色模型、路径权限、任务状态机、完成定义**的单一事实源（SSOT）。其它文件只引用本文件，不重复定义。
|
||||||
|
|
||||||
|
目标：让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 角色模型
|
## 角色模型
|
||||||
|
|
||||||
@@ -10,9 +14,11 @@
|
|||||||
| Developer Worker | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格、标记 verified、绕过测试声称完成 |
|
| Developer Worker | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格、标记 verified、绕过测试声称完成 |
|
||||||
| User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
|
| User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 路径权限模板
|
## 路径权限模板
|
||||||
|
|
||||||
目标项目应在 `AGENTS.md` 中填入实际路径。
|
目标项目在自己的 `AGENTS.md` 中填入实际路径（见 `templates/AGENTS.template.md`）。
|
||||||
|
|
||||||
| 路径 | Product/Test | Developer | 说明 |
|
| 路径 | Product/Test | Developer | 说明 |
|
||||||
|------|:------------:|:---------:|------|
|
|------|:------------:|:---------:|------|
|
||||||
@@ -23,40 +29,11 @@
|
|||||||
| `<unit_test_paths>` | Read-only | R/W | 单元测试 |
|
| `<unit_test_paths>` | Read-only | R/W | 单元测试 |
|
||||||
| `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
|
| `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
|
||||||
| `<local_config>` | Read-only | Read-only | 本地私有配置，不提交 |
|
| `<local_config>` | Read-only | Read-only | 本地私有配置，不提交 |
|
||||||
| `tasks.yaml` | R/W | Limited R/W | 任务事实源；Developer 可写实现状态和证据，Product/Test 写 verified |
|
| `tasks.yaml` | R/W | Read-only | 见下方「任务板写入约定」 |
|
||||||
|
|
||||||
## Product/Test Coordinator 工作流
|
---
|
||||||
|
|
||||||
1. 读取用户目标、项目规格、任务板。
|
## 任务状态机（SSOT）
|
||||||
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
|
```text
|
||||||
open
|
open
|
||||||
@@ -71,7 +48,7 @@ open
|
|||||||
```text
|
```text
|
||||||
dispatched -> blocked
|
dispatched -> blocked
|
||||||
fixed_by_dev -> failed_retest -> dispatched
|
fixed_by_dev -> failed_retest -> dispatched
|
||||||
failed_retest x3 -> leftover
|
failed_retest（累计 3 轮） -> leftover
|
||||||
```
|
```
|
||||||
|
|
||||||
状态定义：
|
状态定义：
|
||||||
@@ -80,19 +57,34 @@ failed_retest x3 -> leftover
|
|||||||
|------|--------|------|
|
|------|--------|------|
|
||||||
| `open` | Product/Test | 已发现，等待处理 |
|
| `open` | Product/Test | 已发现，等待处理 |
|
||||||
| `dispatched` | Product/Test | 已派发给开发 Agent |
|
| `dispatched` | Product/Test | 已派发给开发 Agent |
|
||||||
| `blocked` | Product/Test 或 Developer | 需要用户决策或外部条件 |
|
| `fixed_by_dev` | Product/Test（据 worker_done 回写） | 开发声称已修复并提供验证 |
|
||||||
| `fixed_by_dev` | Developer | 开发声称已修复并提供验证 |
|
|
||||||
| `retesting` | Product/Test | 正在复测 |
|
| `retesting` | Product/Test | 正在复测 |
|
||||||
| `failed_retest` | Product/Test | 复测失败，可继续派发 |
|
| `failed_retest` | Product/Test | 复测失败，可继续派发 |
|
||||||
| `verified` | Product/Test | 复测通过 |
|
| `verified` | Product/Test | 复测通过 |
|
||||||
| `leftover` | Product/Test | 三轮仍未通过，留给人工或专项处理 |
|
| `blocked` | Product/Test | 需要用户决策或外部条件 |
|
||||||
|
| `leftover` | Product/Test | 累计 3 轮仍未通过，留给人工或专项处理 |
|
||||||
|
|
||||||
## 完成定义
|
三轮失败的处理细则见 `optimization-method.md` §「三轮失败策略」。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 任务板写入约定（并发安全）
|
||||||
|
|
||||||
|
`tasks.yaml` 是持久事实源，为避免多 Worker 并发写冲突：
|
||||||
|
|
||||||
|
- **只有 Coordinator 写 `tasks.yaml`**。Developer Worker 对它是只读的。
|
||||||
|
- Developer 的实现状态、证据通过 `worker_done` 消息回传，由 Coordinator 落盘。
|
||||||
|
- 每次写入前先读最新内容，写入后更新顶层 `updatedAt`。
|
||||||
|
- 单次写入应是一个任务的一次状态跃迁，避免整表批量重写。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 完成定义（Definition of Done）
|
||||||
|
|
||||||
一个任务只有同时满足以下条件，才能标记 `verified`：
|
一个任务只有同时满足以下条件，才能标记 `verified`：
|
||||||
|
|
||||||
- Developer 已提供修改文件和验证证据。
|
- Developer 已提供修改文件和验证证据。
|
||||||
- Product/Test 在正确 worktree 和正确服务实例上复测。
|
- Product/Test 在正确 worktree 和正确服务实例上复测（对齐检查见 `closed-loop.md`）。
|
||||||
- 相关单元测试、构建、集成或浏览器检查通过。
|
- 相关单元测试、构建、集成或浏览器检查通过。
|
||||||
- `tasks.yaml` 中记录了复测证据。
|
- `tasks.yaml` 中记录了复测证据。
|
||||||
- 用户可见行为符合验收标准。
|
- 用户可见行为符合验收标准。
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# notes-web Agent 协作协议（示例）
|
||||||
|
|
||||||
|
> 本项目基于 agent-collaboration-kit v0.2.0。
|
||||||
|
> 稳定规范引用 `docs/agent-collaboration-kit/core/`，本文件只填项目差异。
|
||||||
|
|
||||||
|
## 项目概览
|
||||||
|
|
||||||
|
- 项目：`notes-web`
|
||||||
|
- 技术栈：`TypeScript + React (Vite) + Go`
|
||||||
|
- 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
|
||||||
|
- Base URL：`http://localhost:5173`
|
||||||
|
- 任务板：`tasks.yaml`
|
||||||
|
|
||||||
|
## 稳定规范（引用，不重复）
|
||||||
|
|
||||||
|
- 角色 / 权限 / 状态机 / 完成定义：`docs/agent-collaboration-kit/core/roles-and-permissions.md`
|
||||||
|
- 闭环流程（含手动模式、worktree 对齐）：`docs/agent-collaboration-kit/core/closed-loop.md`
|
||||||
|
- 优化方法（验收信号、三轮策略）：`docs/agent-collaboration-kit/core/optimization-method.md`
|
||||||
|
- 派发 prompt 模板：`docs/agent-collaboration-kit/core/prompt-templates.md`
|
||||||
|
- Orca 编排命令：`docs/agent-collaboration-kit/core/orca-adapter.md`
|
||||||
|
|
||||||
|
## 路径权限
|
||||||
|
|
||||||
|
| 路径 | Product/Test | Developer | 说明 |
|
||||||
|
|------|:------------:|:---------:|------|
|
||||||
|
| `docs/spec/**` | R/W | Read-only | 产品规格 |
|
||||||
|
| `tests/browser/**` | R/W | Read-only | 浏览器回归用例 |
|
||||||
|
| `.qa-records/**` | R/W | Read-only | 复测记录（gitignore） |
|
||||||
|
| `web/**`、`server/**` | Read-only | R/W | 应用源码 |
|
||||||
|
| `**/*_test.go`、`web/**/*.test.tsx` | Read-only | R/W | 单元测试 |
|
||||||
|
| `config/*.example.*` | Read-only | R/W | 可提交配置模板 |
|
||||||
|
| `.env`、`config/local.*` | Read-only | Read-only | 本地私有配置 |
|
||||||
|
| `tasks.yaml` | R/W | Read-only | 只有 Coordinator 写 |
|
||||||
|
|
||||||
|
## 命令
|
||||||
|
|
||||||
|
Developer 白盒验证：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
go test ./...
|
||||||
|
npm run dev # 本地起前端
|
||||||
|
```
|
||||||
|
|
||||||
|
Product/Test 黑盒验证：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s http://localhost:5173/api/health
|
||||||
|
curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json
|
||||||
|
# 浏览器回归：tests/browser/cases/*.md
|
||||||
|
```
|
||||||
|
|
||||||
|
任务板校验：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 硬规则（其余见 core/）
|
||||||
|
|
||||||
|
- `worker_done` 不等于完成，必须独立复测后才能 `verified`。
|
||||||
|
- 只有 Coordinator 写 `tasks.yaml`。
|
||||||
|
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续。
|
||||||
|
- 不提交或推送，除非用户明确要求。
|
||||||
@@ -0,0 +1,113 @@
|
|||||||
|
# 填好的最小示例（虚构的 notes-web 项目）。可用 scripts/validate_tasks.py 校验通过。
|
||||||
|
version: 1
|
||||||
|
updatedAt: "2026-07-06T09:40:00+08:00"
|
||||||
|
source: "Product/Test Agent"
|
||||||
|
kitVersion: "0.2.0"
|
||||||
|
project:
|
||||||
|
name: "notes-web"
|
||||||
|
repoPath: "/home/dev/notes-web"
|
||||||
|
baseUrl: "http://localhost:5173"
|
||||||
|
devWorktree: "/home/dev/notes-web-wt/fix-preview"
|
||||||
|
|
||||||
|
summary:
|
||||||
|
verified: ["BUG-002"]
|
||||||
|
open: []
|
||||||
|
failedRetest: []
|
||||||
|
leftovers: ["BUG-003"]
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- id: "BUG-002"
|
||||||
|
type: "bug"
|
||||||
|
title: "预览变更点击后不显示 diff 行"
|
||||||
|
priority: "P0"
|
||||||
|
status: "verified"
|
||||||
|
assignee: "developer"
|
||||||
|
component: "web/app/fix/page.tsx"
|
||||||
|
specRefs:
|
||||||
|
- "docs/spec/fix-preview.md#preview"
|
||||||
|
testRefs:
|
||||||
|
- "tests/browser/cases/01-preview.md"
|
||||||
|
description: >
|
||||||
|
用户在 /fix 页点击“预览变更”后，确认区不渲染 API 返回的 diff。
|
||||||
|
stepsToReproduce:
|
||||||
|
- "打开 /fix?fileId=1"
|
||||||
|
- "搜索并选择候选项"
|
||||||
|
- "点击“预览变更”"
|
||||||
|
expected: >
|
||||||
|
确认区出现 title、修改前值、修改后值、coverChanged 提示四行。
|
||||||
|
actual: >
|
||||||
|
API 返回 code=0，但页面确认区为空。
|
||||||
|
evidence:
|
||||||
|
browser: "确认区 DOM 为空，无 diff 行"
|
||||||
|
api: "POST /api/fix/preview -> code=0, 含 diff 字段"
|
||||||
|
logs: "无报错"
|
||||||
|
verification:
|
||||||
|
commands:
|
||||||
|
- "npm run build"
|
||||||
|
- "curl -s -X POST localhost:5173/api/fix/preview -d @fixtures/preview.json"
|
||||||
|
browser:
|
||||||
|
page: "/fix?fileId=1"
|
||||||
|
checks:
|
||||||
|
- "预览后出现 4 行 diff：title/before/after/coverChanged"
|
||||||
|
dispatch:
|
||||||
|
taskId: "orca-task-88"
|
||||||
|
dispatchId: "orca-disp-91"
|
||||||
|
worker: "dev-worker-1"
|
||||||
|
rounds:
|
||||||
|
- round: 1
|
||||||
|
result: failed
|
||||||
|
evidence: "只渲染了 title，缺少 before/after/coverChanged"
|
||||||
|
- round: 2
|
||||||
|
result: passed
|
||||||
|
evidence: "复测 4 行 diff 全部出现，取消不触发写入"
|
||||||
|
resolution:
|
||||||
|
fixedBy: "dev-worker-1"
|
||||||
|
verifiedAt: "2026-07-06T09:38:00+08:00"
|
||||||
|
leftoverReason: null
|
||||||
|
|
||||||
|
- id: "BUG-003"
|
||||||
|
type: "bug"
|
||||||
|
title: "并发保存偶发覆盖他人修改"
|
||||||
|
priority: "P1"
|
||||||
|
status: "leftover"
|
||||||
|
assignee: "developer"
|
||||||
|
component: "server/store/notes.go"
|
||||||
|
specRefs:
|
||||||
|
- "docs/spec/concurrency.md"
|
||||||
|
testRefs: []
|
||||||
|
description: >
|
||||||
|
两个会话同时保存同一条 note 时，后写覆盖先写，无冲突提示。
|
||||||
|
stepsToReproduce:
|
||||||
|
- "会话 A、B 同时打开 note 42"
|
||||||
|
- "A 保存，B 保存"
|
||||||
|
expected: >
|
||||||
|
B 保存时应检测到版本变化并提示冲突，而非静默覆盖。
|
||||||
|
actual: >
|
||||||
|
B 直接覆盖 A 的修改，无提示。
|
||||||
|
evidence:
|
||||||
|
api: "两次 PUT /api/notes/42 均返回 200，无版本校验"
|
||||||
|
verification:
|
||||||
|
commands:
|
||||||
|
- "go test ./server/store/..."
|
||||||
|
browser:
|
||||||
|
page: "/notes/42"
|
||||||
|
checks:
|
||||||
|
- "并发保存时后写方收到冲突提示"
|
||||||
|
dispatch:
|
||||||
|
taskId: "orca-task-90"
|
||||||
|
dispatchId: "orca-disp-95"
|
||||||
|
worker: "dev-worker-1"
|
||||||
|
rounds:
|
||||||
|
- round: 1
|
||||||
|
result: failed
|
||||||
|
evidence: "加了版本号但未在写入路径校验"
|
||||||
|
- round: 2
|
||||||
|
result: failed
|
||||||
|
evidence: "校验只覆盖 API，未覆盖批量导入路径"
|
||||||
|
- round: 3
|
||||||
|
result: failed
|
||||||
|
evidence: "乐观锁与前端重试逻辑冲突，需重新设计"
|
||||||
|
resolution:
|
||||||
|
fixedBy: null
|
||||||
|
verifiedAt: null
|
||||||
|
leftoverReason: "failed after 3 supervised developer rounds; 需重新设计并发模型"
|
||||||
@@ -1,194 +0,0 @@
|
|||||||
# 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 未处理？
|
|
||||||
|
|
||||||
如果这些问题答不清楚，闭环还没有结束。
|
|
||||||
@@ -1,229 +0,0 @@
|
|||||||
# 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>"
|
|
||||||
```
|
|
||||||
@@ -1,137 +0,0 @@
|
|||||||
# 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>
|
|
||||||
```
|
|
||||||
+167
@@ -0,0 +1,167 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""校验 tasks.yaml 是否符合 agent-collaboration-kit 任务板结构。
|
||||||
|
|
||||||
|
权威结构是同目录上层的 templates/tasks.schema.json（跨语言可用）。
|
||||||
|
本脚本是参考实现：
|
||||||
|
- 若安装了 jsonschema，则用 schema 做完整校验；
|
||||||
|
- 否则回退到内置的关键规则校验（必填字段、状态枚举、三轮上限、leftover 留档）。
|
||||||
|
YAML 解析优先用 pyyaml；未安装时给出提示而非崩溃。
|
||||||
|
|
||||||
|
用法:
|
||||||
|
python3 validate_tasks.py [tasks.yaml]
|
||||||
|
python3 validate_tasks.py --schema path/to/tasks.schema.json tasks.yaml
|
||||||
|
|
||||||
|
退出码: 0 通过 / 1 校验失败 / 2 环境或用法错误。
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
STATUS_ENUM = {
|
||||||
|
"open",
|
||||||
|
"dispatched",
|
||||||
|
"fixed_by_dev",
|
||||||
|
"retesting",
|
||||||
|
"failed_retest",
|
||||||
|
"verified",
|
||||||
|
"blocked",
|
||||||
|
"leftover",
|
||||||
|
}
|
||||||
|
MAX_ROUNDS = 3
|
||||||
|
|
||||||
|
|
||||||
|
def load_yaml(path: Path) -> dict:
|
||||||
|
try:
|
||||||
|
import yaml # type: ignore
|
||||||
|
except ImportError:
|
||||||
|
sys.stderr.write(
|
||||||
|
"需要 PyYAML 才能解析 YAML：pip install pyyaml\n"
|
||||||
|
"（或把任务板导出为 JSON 后再校验）\n"
|
||||||
|
)
|
||||||
|
raise SystemExit(2)
|
||||||
|
try:
|
||||||
|
with path.open(encoding="utf-8") as fh:
|
||||||
|
data = yaml.safe_load(fh)
|
||||||
|
except yaml.YAMLError as exc: # type: ignore
|
||||||
|
sys.stderr.write(f"YAML 解析失败: {exc}\n")
|
||||||
|
raise SystemExit(1)
|
||||||
|
if not isinstance(data, dict):
|
||||||
|
sys.stderr.write("任务板顶层必须是对象（mapping）\n")
|
||||||
|
raise SystemExit(1)
|
||||||
|
return data
|
||||||
|
|
||||||
|
|
||||||
|
def validate_with_schema(data: dict, schema_path: Path) -> list[str]:
|
||||||
|
import jsonschema # type: ignore
|
||||||
|
|
||||||
|
schema = json.loads(schema_path.read_text(encoding="utf-8"))
|
||||||
|
validator = jsonschema.Draft7Validator(schema)
|
||||||
|
errors = []
|
||||||
|
for err in sorted(validator.iter_errors(data), key=lambda e: list(e.path)):
|
||||||
|
loc = "/".join(str(p) for p in err.path) or "<root>"
|
||||||
|
errors.append(f"[schema] {loc}: {err.message}")
|
||||||
|
return errors
|
||||||
|
|
||||||
|
|
||||||
|
def validate_builtin(data: dict) -> list[str]:
|
||||||
|
errors: list[str] = []
|
||||||
|
|
||||||
|
if not isinstance(data.get("version"), int) or data.get("version", 0) < 1:
|
||||||
|
errors.append("version 必须是 >=1 的整数")
|
||||||
|
project = data.get("project")
|
||||||
|
if not isinstance(project, dict) or not project.get("name"):
|
||||||
|
errors.append("project.name 必填")
|
||||||
|
|
||||||
|
tasks = data.get("tasks")
|
||||||
|
if not isinstance(tasks, list):
|
||||||
|
errors.append("tasks 必须是列表")
|
||||||
|
return errors
|
||||||
|
|
||||||
|
seen_ids: set[str] = set()
|
||||||
|
for i, task in enumerate(tasks):
|
||||||
|
where = f"tasks[{i}]"
|
||||||
|
if not isinstance(task, dict):
|
||||||
|
errors.append(f"{where}: 必须是对象")
|
||||||
|
continue
|
||||||
|
tid = task.get("id")
|
||||||
|
title = task.get("title")
|
||||||
|
status = task.get("status")
|
||||||
|
if not tid:
|
||||||
|
errors.append(f"{where}: id 必填")
|
||||||
|
else:
|
||||||
|
where = f"tasks[{i}] {tid}"
|
||||||
|
if tid in seen_ids:
|
||||||
|
errors.append(f"{where}: id 重复")
|
||||||
|
seen_ids.add(tid)
|
||||||
|
if not title:
|
||||||
|
errors.append(f"{where}: title 必填")
|
||||||
|
if status not in STATUS_ENUM:
|
||||||
|
errors.append(
|
||||||
|
f"{where}: status={status!r} 非法，应为 {sorted(STATUS_ENUM)}"
|
||||||
|
)
|
||||||
|
|
||||||
|
dispatch = task.get("dispatch") or {}
|
||||||
|
rounds = dispatch.get("rounds") or []
|
||||||
|
if isinstance(rounds, list):
|
||||||
|
if len(rounds) > MAX_ROUNDS:
|
||||||
|
errors.append(
|
||||||
|
f"{where}: 派发轮次 {len(rounds)} 超过上限 {MAX_ROUNDS}"
|
||||||
|
)
|
||||||
|
for r in rounds:
|
||||||
|
if isinstance(r, dict) and r.get("result") not in {"passed", "failed"}:
|
||||||
|
errors.append(f"{where}: round.result 必须是 passed/failed")
|
||||||
|
|
||||||
|
if status == "leftover":
|
||||||
|
resolution = task.get("resolution") or {}
|
||||||
|
if not resolution.get("leftoverReason"):
|
||||||
|
errors.append(f"{where}: leftover 必须填 resolution.leftoverReason")
|
||||||
|
|
||||||
|
return errors
|
||||||
|
|
||||||
|
|
||||||
|
def main(argv: list[str] | None = None) -> int:
|
||||||
|
parser = argparse.ArgumentParser(description="校验 tasks.yaml 结构")
|
||||||
|
parser.add_argument("tasks", nargs="?", default="tasks.yaml", help="任务板路径")
|
||||||
|
parser.add_argument("--schema", help="tasks.schema.json 路径（默认自动探测）")
|
||||||
|
args = parser.parse_args(argv)
|
||||||
|
|
||||||
|
tasks_path = Path(args.tasks)
|
||||||
|
if not tasks_path.is_file():
|
||||||
|
sys.stderr.write(f"找不到任务板文件: {tasks_path}\n")
|
||||||
|
return 2
|
||||||
|
|
||||||
|
data = load_yaml(tasks_path)
|
||||||
|
|
||||||
|
schema_path = Path(args.schema) if args.schema else (
|
||||||
|
Path(__file__).resolve().parent.parent / "templates" / "tasks.schema.json"
|
||||||
|
)
|
||||||
|
|
||||||
|
mode = "内置规则"
|
||||||
|
try:
|
||||||
|
import jsonschema # type: ignore # noqa: F401
|
||||||
|
|
||||||
|
if schema_path.is_file():
|
||||||
|
errors = validate_with_schema(data, schema_path)
|
||||||
|
mode = f"schema ({schema_path.name})"
|
||||||
|
else:
|
||||||
|
errors = validate_builtin(data)
|
||||||
|
mode = "内置规则（未找到 schema 文件）"
|
||||||
|
except ImportError:
|
||||||
|
errors = validate_builtin(data)
|
||||||
|
|
||||||
|
if errors:
|
||||||
|
sys.stderr.write(f"任务板校验失败（{mode}），共 {len(errors)} 项：\n")
|
||||||
|
for e in errors:
|
||||||
|
sys.stderr.write(f" - {e}\n")
|
||||||
|
return 1
|
||||||
|
|
||||||
|
sys.stdout.write(f"任务板校验通过（{mode}）：{tasks_path}\n")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
raise SystemExit(main())
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# <项目名> Agent 协作协议
|
||||||
|
|
||||||
|
> 本项目基于 agent-collaboration-kit v<kit_version>（见 kit 根 `VERSION`）。
|
||||||
|
> 稳定规范引用 `docs/agent-collaboration-kit/core/`，不复制其内容；本文件只填项目自己的差异。
|
||||||
|
|
||||||
|
## 项目概览
|
||||||
|
|
||||||
|
- 项目：`<project_name>`
|
||||||
|
- 技术栈：`<tech_stack>`
|
||||||
|
- 运行命令：`<run_command>`
|
||||||
|
- Base URL：`<base_url>`
|
||||||
|
- 任务板：`tasks.yaml`
|
||||||
|
|
||||||
|
## 稳定规范（不在此重复，直接引用）
|
||||||
|
|
||||||
|
- 角色模型 / 权限 / 状态机 / 完成定义：`docs/agent-collaboration-kit/core/roles-and-permissions.md`
|
||||||
|
- 闭环流程（含手动模式、worktree 对齐）：`docs/agent-collaboration-kit/core/closed-loop.md`
|
||||||
|
- 优化方法（验收信号、三轮策略）：`docs/agent-collaboration-kit/core/optimization-method.md`
|
||||||
|
- 派发 prompt 模板：`docs/agent-collaboration-kit/core/prompt-templates.md`
|
||||||
|
- Orca 编排命令（可选）：`docs/agent-collaboration-kit/core/orca-adapter.md`
|
||||||
|
|
||||||
|
## 路径权限（项目覆盖层，必须填实际路径）
|
||||||
|
|
||||||
|
| 路径 | Product/Test | Developer | 说明 |
|
||||||
|
|------|:------------:|:---------:|------|
|
||||||
|
| `<spec_paths>` | R/W | Read-only | 产品规格、API 文档、计划 |
|
||||||
|
| `<integration_test_paths>` | R/W | Read-only | 浏览器/API 回归 |
|
||||||
|
| `<test_records_path>` | R/W | Read-only | 复测记录 |
|
||||||
|
| `<source_paths>` | Read-only | R/W | 应用源码 |
|
||||||
|
| `<unit_test_paths>` | Read-only | R/W | 单元测试 |
|
||||||
|
| `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
|
||||||
|
| `<local_config_paths>` | Read-only | Read-only | 本地私有配置 |
|
||||||
|
| `tasks.yaml` | R/W | Read-only | 只有 Coordinator 写 |
|
||||||
|
|
||||||
|
## 命令（项目覆盖层）
|
||||||
|
|
||||||
|
Developer 白盒验证：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
<unit_test_command>
|
||||||
|
<build_command>
|
||||||
|
<local_run_command>
|
||||||
|
```
|
||||||
|
|
||||||
|
Product/Test 黑盒验证：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
<preflight_command>
|
||||||
|
<api_smoke_command>
|
||||||
|
<browser_regression_command>
|
||||||
|
```
|
||||||
|
|
||||||
|
任务板校验：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 硬规则（其余见 core/）
|
||||||
|
|
||||||
|
- `worker_done` 不等于完成。Product/Test 必须独立复测后才能 `verified`。
|
||||||
|
- 只有 Coordinator 写 `tasks.yaml`；Developer 通过 worker_done 回报。
|
||||||
|
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
|
||||||
|
- 不提交或推送，除非用户明确要求。
|
||||||
@@ -0,0 +1,127 @@
|
|||||||
|
{
|
||||||
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||||
|
"$id": "https://git.yumee.top/laily/skills/kits/agent-collaboration-kit/tasks.schema.json",
|
||||||
|
"title": "Agent Collaboration Kit task board",
|
||||||
|
"description": "tasks.yaml 的权威结构。跨语言可用；参考校验实现见 scripts/validate_tasks.py。",
|
||||||
|
"type": "object",
|
||||||
|
"required": ["version", "project", "tasks"],
|
||||||
|
"additionalProperties": true,
|
||||||
|
"properties": {
|
||||||
|
"version": { "type": "integer", "minimum": 1 },
|
||||||
|
"updatedAt": { "type": "string" },
|
||||||
|
"source": { "type": "string" },
|
||||||
|
"kitVersion": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "接入时所基于的 agent-collaboration-kit 版本，便于日后 diff 升级"
|
||||||
|
},
|
||||||
|
"project": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["name"],
|
||||||
|
"additionalProperties": true,
|
||||||
|
"properties": {
|
||||||
|
"name": { "type": "string" },
|
||||||
|
"repoPath": { "type": "string" },
|
||||||
|
"baseUrl": { "type": "string" },
|
||||||
|
"devWorktree": { "type": "string" }
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"summary": {
|
||||||
|
"type": "object",
|
||||||
|
"additionalProperties": true,
|
||||||
|
"properties": {
|
||||||
|
"verified": { "type": "array", "items": { "type": "string" } },
|
||||||
|
"open": { "type": "array", "items": { "type": "string" } },
|
||||||
|
"failedRetest": { "type": "array", "items": { "type": "string" } },
|
||||||
|
"leftovers": { "type": "array", "items": { "type": "string" } }
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"statusReference": { "type": "object" },
|
||||||
|
"tasks": {
|
||||||
|
"type": "array",
|
||||||
|
"items": { "$ref": "#/definitions/task" }
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"definitions": {
|
||||||
|
"status": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": [
|
||||||
|
"open",
|
||||||
|
"dispatched",
|
||||||
|
"fixed_by_dev",
|
||||||
|
"retesting",
|
||||||
|
"failed_retest",
|
||||||
|
"verified",
|
||||||
|
"blocked",
|
||||||
|
"leftover"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"round": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["round", "result"],
|
||||||
|
"additionalProperties": true,
|
||||||
|
"properties": {
|
||||||
|
"round": { "type": "integer", "minimum": 1 },
|
||||||
|
"result": { "type": "string", "enum": ["passed", "failed"] },
|
||||||
|
"evidence": { "type": "string" }
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"task": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["id", "title", "status"],
|
||||||
|
"additionalProperties": true,
|
||||||
|
"properties": {
|
||||||
|
"id": { "type": "string", "minLength": 1 },
|
||||||
|
"type": { "type": "string" },
|
||||||
|
"title": { "type": "string", "minLength": 1 },
|
||||||
|
"priority": { "type": "string" },
|
||||||
|
"status": { "$ref": "#/definitions/status" },
|
||||||
|
"assignee": { "type": "string" },
|
||||||
|
"component": { "type": "string" },
|
||||||
|
"specRefs": { "type": "array", "items": { "type": "string" } },
|
||||||
|
"testRefs": { "type": "array", "items": { "type": "string" } },
|
||||||
|
"description": { "type": "string" },
|
||||||
|
"stepsToReproduce": { "type": "array", "items": { "type": "string" } },
|
||||||
|
"expected": { "type": "string" },
|
||||||
|
"actual": { "type": "string" },
|
||||||
|
"evidence": { "type": "object" },
|
||||||
|
"verification": { "type": "object" },
|
||||||
|
"dispatch": {
|
||||||
|
"type": "object",
|
||||||
|
"additionalProperties": true,
|
||||||
|
"properties": {
|
||||||
|
"taskId": { "type": ["string", "null"] },
|
||||||
|
"dispatchId": { "type": ["string", "null"] },
|
||||||
|
"worker": { "type": ["string", "null"] },
|
||||||
|
"rounds": {
|
||||||
|
"type": "array",
|
||||||
|
"items": { "$ref": "#/definitions/round" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"resolution": {
|
||||||
|
"type": "object",
|
||||||
|
"additionalProperties": true,
|
||||||
|
"properties": {
|
||||||
|
"fixedBy": { "type": ["string", "null"] },
|
||||||
|
"verifiedAt": { "type": ["string", "null"] },
|
||||||
|
"leftoverReason": { "type": ["string", "null"] },
|
||||||
|
"evidence": { "type": "object" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"allOf": [
|
||||||
|
{
|
||||||
|
"if": { "properties": { "status": { "const": "leftover" } } },
|
||||||
|
"then": {
|
||||||
|
"properties": {
|
||||||
|
"resolution": {
|
||||||
|
"required": ["leftoverReason"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"required": ["resolution"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
+2
-11
@@ -1,6 +1,8 @@
|
|||||||
|
# 复制到项目根目录为 tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
|
||||||
version: 1
|
version: 1
|
||||||
updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
|
updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
|
||||||
source: "Product/Test Agent"
|
source: "Product/Test Agent"
|
||||||
|
kitVersion: "<接入时的 agent-collaboration-kit 版本，见 kit 根 VERSION>"
|
||||||
project:
|
project:
|
||||||
name: "<project_name>"
|
name: "<project_name>"
|
||||||
repoPath: "<repo_path>"
|
repoPath: "<repo_path>"
|
||||||
@@ -32,7 +34,6 @@ tasks:
|
|||||||
stepsToReproduce:
|
stepsToReproduce:
|
||||||
- "<step 1>"
|
- "<step 1>"
|
||||||
- "<step 2>"
|
- "<step 2>"
|
||||||
- "<step 3>"
|
|
||||||
|
|
||||||
expected: >
|
expected: >
|
||||||
<Expected behavior.>
|
<Expected behavior.>
|
||||||
@@ -64,13 +65,3 @@ tasks:
|
|||||||
fixedBy: null
|
fixedBy: null
|
||||||
verifiedAt: null
|
verifiedAt: null
|
||||||
leftoverReason: 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