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,68 +1,77 @@
|
||||
# Agent Collaboration Kit
|
||||
|
||||
这是一套可复制到其他项目的多 Agent 协作规范。它把“产品/测试负责定义与验收，开发负责实现与白盒验证，协调者用 Orca 做闭环调度”的经验抽成项目无关模板。
|
||||
一套可复用到其它项目的多 Agent 协作规范：**产品/测试负责定义与验收，开发负责实现与白盒验证，协调者做闭环调度**。
|
||||
|
||||
当前版本见 `VERSION`。这不是 Agent Skill（无 `SKILL.md`），不由 skiff 安装，而是复制/引用到目标项目。
|
||||
|
||||
---
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 项目需要多个 Agent 分工协作，而不是单个 Agent 从需求写到代码。
|
||||
- 需要明确区分规格、测试、实现、复测的责任边界。
|
||||
- 需要把测试失败项派发给开发 Agent，等 `worker_done` 后再由测试 Agent 复测。
|
||||
- 需要连续修复多个问题，并把三次仍未修好的问题留档。
|
||||
- 多个 Agent 分工协作，而非单个 Agent 从需求写到代码。
|
||||
- 需要区分规格、测试、实现、复测的责任边界。
|
||||
- 需要把失败项派发给开发 Agent，`worker_done` 后由测试 Agent 复测。
|
||||
- 需要连续修复多个问题，并把三轮仍未修好的问题留档。
|
||||
|
||||
## 推荐目录
|
||||
---
|
||||
|
||||
把本目录复制到目标项目：
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
docs/agent-collaboration-kit/
|
||||
agent-collaboration-kit/
|
||||
VERSION # kit 版本，接入时记入项目
|
||||
README.md
|
||||
roles-and-permissions.md
|
||||
orca-closed-loop.md
|
||||
task-board-template.yaml
|
||||
prompt-templates.md
|
||||
optimization-method.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. 复制本目录到目标项目。
|
||||
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` 执行三轮失败留档和节奏优化。
|
||||
`core/` + `scripts/` 通过 symlink / git submodule / sparse checkout 映射到项目 `docs/agent-collaboration-kit/`；项目只维护自己的 `AGENTS.md`、`tasks.yaml`。kit 升级时稳定核心自动生效，项目定制不受影响。
|
||||
|
||||
## 建议的默认口令
|
||||
### 方式 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
|
||||
用 Agent 协作闭环处理 tasks.yaml 里的未通过项；每个问题最多派发开发 Agent 修三轮，三轮仍不过就记录为遗留，然后继续下一个。
|
||||
```
|
||||
|
||||
## 与具体项目解耦
|
||||
|
||||
本工具包使用占位符表达项目差异：
|
||||
|
||||
- `<repo_path>`：仓库根目录
|
||||
- `<dev_worktree>`：开发 Agent 工作树
|
||||
- `<base_url>`：待测服务地址
|
||||
- `<test_commands>`：项目测试命令
|
||||
- `<source_paths>`：开发可改源码路径
|
||||
- `<spec_paths>`：产品/测试可改规格与测试路径
|
||||
|
||||
复制到新项目后，应先替换这些占位符，再开始调度。
|
||||
|
||||
Reference in New Issue
Block a user