135 lines
5.3 KiB
Markdown
135 lines
5.3 KiB
Markdown
# 在新项目初始化 ACK
|
||
|
||
本文件说明如何把 ACK 的项目状态初始化到目标项目。ACK Skill 自身已经通过 Agent
|
||
的 Skill 机制安装；项目不复制、不链接 Skill 内容。
|
||
|
||
## 前提与边界
|
||
|
||
开始前确认：
|
||
|
||
1. 目标项目根目录。
|
||
2. ACK Skill 已全局安装或安装到当前项目。
|
||
3. `skiff` 命令可用。
|
||
|
||
不要覆盖已有的 `docs/ack/project.md`、`docs/ack/tasks.yaml`、
|
||
`docs/ack/knowledge.yaml`、`AGENTS.md` 或其它 Agent 指令文件。ACK 不会自动
|
||
修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。不要把 token、`.env`
|
||
内容或其它私有配置写入 ACK 项目状态。
|
||
|
||
## 初始化
|
||
|
||
在目标项目执行：
|
||
|
||
```bash
|
||
skiff init ack
|
||
```
|
||
|
||
或显式指定项目：
|
||
|
||
```bash
|
||
skiff init ack --project <project-root>
|
||
```
|
||
|
||
命令从 ACK Skill 自带的 `templates/` 生成：
|
||
|
||
```text
|
||
docs/ack/
|
||
├── project.md
|
||
├── tasks.yaml
|
||
└── knowledge.yaml
|
||
```
|
||
|
||
如果任一目标文件已经存在，命令会拒绝覆盖。初始化过程不会创建 `kit`、
|
||
`framework` 或其它指向 Skill 的软链接。
|
||
|
||
### 旧项目补充知识库
|
||
|
||
旧项目已经有 `project.md` 和 `tasks.yaml`、但没有 `knowledge.yaml` 时，不要重跑
|
||
`skiff init ack`。先检查现有文件并向用户报告缺失项；用户授权后，只从
|
||
`templates/knowledge.template.yaml` 生成 `docs/ack/knowledge.yaml`，替换项目名和
|
||
当前时间，保留 `entries: []`。如果现有任务板缺少
|
||
`project.knowledgeFile`，同一次授权只补
|
||
`knowledgeFile: docs/ack/knowledge.yaml`，不改写其它项目状态。生成后运行任务板、
|
||
知识库和跨文件引用校验。
|
||
|
||
## 完善项目覆盖层
|
||
|
||
编辑 `docs/ack/project.md`，填入：
|
||
|
||
- 项目名、技术栈、运行命令和 Base URL。
|
||
- Coordinator、Developer、Test 的实际模型档位。
|
||
- 规格、集成测试、源码、单元测试和私有配置的路径权限。
|
||
- Developer 白盒验证命令。
|
||
- Test 黑盒复测命令。
|
||
|
||
无法从项目证据确定的值写为 `n/a`，不要猜测。
|
||
|
||
## 完善任务板
|
||
|
||
编辑 `docs/ack/tasks.yaml`：
|
||
|
||
- `ackVersion` 使用 ACK Skill 的合法 SemVer `VERSION`；从 `0.10.0` 起
|
||
`project.orchestration` 与顶层 `workerReceipts` 必须同时存在。
|
||
- `updatedAt` 使用当前带时区时间。
|
||
- `project.name`、`repoPath`、`devWorktree`、`overlayFile` 和 `knowledgeFile` 使用
|
||
真实值。
|
||
- `project.orchestration.allowedWorktrees` 使用已核对的绝对 worktree；模型
|
||
allowlist、profiles 和 defaults 使用项目实际允许值。不要把完整启动命令、
|
||
`extraArgs`、`env` 或任意 executable 写进任务板。
|
||
- 非服务项目的 `baseUrl` 写为 `n/a`。
|
||
- 没有真实任务时使用 `tasks: []`，不要保留或虚构示例任务。
|
||
|
||
每个真实任务的验收必须是可观测信号，例如可见文本、API 状态和字段，或明确的交互
|
||
结果；不要只写“功能正常”。
|
||
|
||
## 初始化项目知识
|
||
|
||
新项目的 `docs/ack/knowledge.yaml` 保持 `verificationRegistry: {}` 与
|
||
`entries: []`。不要从聊天、README、issue 或单次失败中猜测并激活知识。
|
||
|
||
项目运行 ACK 后，Developer 和 Test 可以通过回报提名 `knowledgeCandidates`；
|
||
candidate 留在任务证据中，不会被派发。只有 Test 独立验证且 Coordinator gate
|
||
通过后，Coordinator 才能把它写成 `active` 条目。全项目范围的强制或权限类规则
|
||
还需要 User / Decision Owner 确认。
|
||
|
||
知识条目只引用项目已审查的 `verification.ref`。对应入口保存在
|
||
`knowledge.yaml.verificationRegistry`，只允许仓库内相对 path 和结构化 args，
|
||
不保存或自动执行自由 shell 命令。需要执行时只把 registry ID 交给
|
||
`<ack-skill-dir>/scripts/run_verification.py`，不直接运行 path/args。关键约束应
|
||
最终下沉为测试、lint、CI 或正式规范。
|
||
|
||
## 校验
|
||
|
||
Agent 从当前 `SKILL.md` 解析 ACK Skill 目录后运行：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||
python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml
|
||
```
|
||
|
||
同时确认：
|
||
|
||
- `project.md`、`tasks.yaml` 和 `knowledge.yaml` 没有未替换的 `<...>` 占位符。
|
||
- `project.overlayFile` 指向真实文件。
|
||
- `project.knowledgeFile` 指向 `docs/ack/knowledge.yaml`。
|
||
- Developer 与 Test 的验证命令可执行。
|
||
- `project.orchestration` 的 profile/allowlist/defaults 通过校验，自动模式只允许
|
||
`read-only` 或 `workspace-write`；旧任务板未迁移时保持手动模式。
|
||
- 顶层 `workerReceipts` 和 `dispatch.developer/test` 的 task/role/profile/attempt
|
||
引用一致；`receiptId` 与 `attemptId` 同时为空或同时填写。持久 receipt 只作审计，
|
||
v0.10 不自动复用旧终端。
|
||
- 网站或 API 项目写清服务启动、重启和 Base URL。
|
||
- 任务中的固定 revision `knowledgeRefs` 都能解析，非 `active` 条目没有被派发。
|
||
|
||
## 初始化报告
|
||
|
||
完成后报告：
|
||
|
||
- 创建或确认的三个项目文件。
|
||
- 检测到的技术栈和验证命令。
|
||
- 任务板和项目知识校验结果。
|
||
- 仍需用户补充的值。
|
||
|
||
只有结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”，并列出
|
||
具体阻塞项。除非用户明确要求，不提交、不推送。
|