71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# 接入清单
|
||
|
||
把本工具包引用/复制到新项目后，按此清单接入。术语与规则详见 `core/`。
|
||
|
||
## 1. 分发与版本
|
||
|
||
- [ ] 选定分发方式（README §「分发方式」A 单软链接 / B 复制）。
|
||
- [ ] 在 `docs/ack/` 下建单软链接 `kit`（指向本框架）。
|
||
- [ ] 覆盖层文件与 `tasks.yaml` 记录 `kitVersion`（对齐 `kit/VERSION`）。
|
||
|
||
## 2. 项目级规范（覆盖层）
|
||
|
||
- [ ] 由 `kit/templates/project.template.md` 生成覆盖层文件（默认 `docs/ack/project.md`，**不占用 `AGENTS.md`**）。
|
||
- [ ] 在 `tasks.yaml` 的 `project.overlayFile` 记录覆盖层实际路径。
|
||
- [ ] 覆盖层引用 `docs/ack/kit/core/`，不复制其内容。
|
||
- [ ] 填清项目简介、技术栈、运行/构建/单测/集成测试命令。
|
||
- [ ] 若要 Agent 自动加载覆盖层：在 `AGENTS.md` 加一行指向它，或直接命名为 `AGENTS.md`（可选）。
|
||
|
||
## 2b. 模型档位
|
||
|
||
- [ ] Coordinator 默认强模型且不亲自跑测试。
|
||
- [ ] Test、Developer 默认中低模型。
|
||
- [ ] 记录升级规则：三轮失败升级 Coordinator 复盘；复杂实现升级 Developer 档位（见 `kit/core/model-routing.md`）。
|
||
|
||
## 3. 路径权限
|
||
|
||
- [ ] 填实际的 Coordinator (PM) 可写路径（规格）。
|
||
- [ ] 填实际的 Test 可写路径（集成测试、复测记录）。
|
||
- [ ] 填实际的 Developer 可写路径（源码、单元测试、配置模板）。
|
||
- [ ] 本地私有配置标记只读或不提交。
|
||
- [ ] 确认 `tasks.yaml` 只有 Coordinator 写（见 `kit/core/roles-and-permissions.md`）。
|
||
|
||
## 4. 任务板
|
||
|
||
- [ ] 由 `kit/templates/tasks.template.yaml` 生成 `docs/ack/tasks.yaml`。
|
||
- [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`、`overlayFile`。
|
||
- [ ] 至少加一个真实任务，验收写成可观测信号（见 `kit/core/optimization-method.md` §1）。
|
||
- [ ] 跑 `python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml` 通过。
|
||
|
||
## 5. 编排
|
||
|
||
- [ ] 决定用 Orca（`kit/core/orca-adapter.md`）还是手动模式（`kit/core/closed-loop.md`）。
|
||
- [ ] Orca：`orca status`、`terminal list` 可用，Coordinator / Developer / Test 三个终端都在，回报能发回 Coordinator。
|
||
- [ ] 决定子任务放当前 worktree 起子 agent，还是新建隔离 worktree（决策速查见 `kit/core/closed-loop.md` §「子任务放哪」）。
|
||
- [ ] 多 worktree 时确认 `tasks.yaml`（SSOT）只保留一个权威副本，由 Coordinator 单写。
|
||
|
||
## 6. 验证命令
|
||
|
||
- [ ] Test 有黑盒复测命令，Developer 有白盒验证命令。
|
||
- [ ] 构建产物与服务启动命令写清。
|
||
- [ ] 浏览器测试 `BASE_URL` 写清，复测前能确认服务来自正确 worktree。
|
||
|
||
## 7. 三轮失败策略
|
||
|
||
- [ ] 每个任务记录 `dispatch.rounds`。
|
||
- [ ] 三轮失败标记 `leftover` 并填 `resolution.leftoverReason`。
|
||
- [ ] `leftover` 不阻塞其它任务；最终报告列出所有 `leftover` 与最后失败证据。
|
||
|
||
## 8. 第一次试运行
|
||
|
||
选一个低风险 bug 跑完整闭环，结束后检查是否出现：
|
||
|
||
- Developer 修改了越权路径，或 Test 改了源码。
|
||
- worker_done 或复测报告没有验证证据。
|
||
- Test 复测到了旧服务。
|
||
- Coordinator 没做终检就直接 verified。
|
||
- 任务板字段不够记录失败原因。
|
||
- 三轮失败策略没被执行。
|
||
|
||
把发现的问题回写到项目覆盖层文件；若属通用问题，回流到 kit 的 `kit/core/` 并升 `VERSION`。
|