# 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>`：产品/测试可改规格与测试路径

复制到新项目后，应先替换这些占位符，再开始调度。