78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# Agent Collaboration Kit
|
||
|
||
一套可复用到其它项目的多 Agent 协作规范，默认三个独立角色：**Coordinator (PM) 拆解需求并调度闭环，Developer 实现与白盒验证，Test 独立黑盒复测**。关键属性是验证者 ≠ 实现者。
|
||
|
||
当前版本见 `VERSION`。这不是 Agent Skill（无 `SKILL.md`），不由 skiff 安装，而是复制/引用到目标项目。
|
||
|
||
---
|
||
|
||
## 适用场景
|
||
|
||
- 多个 Agent 分工协作，而非单个 Agent 从需求写到代码。
|
||
- 需要区分规格、测试、实现、复测的责任边界（Coordinator / Test / Developer 三角色）。
|
||
- 需要把失败项派发给 Developer，`worker_done` 后由独立的 Test 复测、Coordinator 终检。
|
||
- 需要连续修复多个问题，并把三轮仍未修好的问题留档。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
agent-collaboration-kit/
|
||
VERSION # kit 版本，接入时记入项目
|
||
README.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（参考实现）
|
||
```
|
||
|
||
**核心原则**：`core/` 是稳定核心，每个概念只定义一次；`templates/` 是项目覆盖层。二者分离，让 kit 升级和项目定制互不干扰。
|
||
|
||
---
|
||
|
||
## 分发方式（二选一）
|
||
|
||
### 方式 A：引用稳定核心（推荐，可升级）
|
||
|
||
`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
|
||
用三角色协作闭环处理 tasks.yaml 里的未通过项：Coordinator 派发给 Developer 修复，再交给 Test 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。
|
||
```
|