184 lines
5.8 KiB
Markdown
184 lines
5.8 KiB
Markdown
# 在新项目初始化 ack（给 Agent 的操作手册）
|
||
|
||
本文件指导 Agent 把 `ack` 接入一个目标项目。它是**执行手册**：按步骤在目标项目创建 `docs/ack/`、挂载 kit、生成项目覆盖层和任务板，并完成一次结构校验。
|
||
|
||
若只想人工核对是否接入完整，看 `adoption-checklist.md`。若要开始一个真实需求，看 `core/kickoff.md`。
|
||
|
||
---
|
||
|
||
## 0. 前提与安全边界
|
||
|
||
开始前先确认三件事：
|
||
|
||
1. 目标项目根目录：运行或读取当前环境的项目根，不要假设路径。
|
||
2. ack kit 目录：本框架目录的绝对路径，例如 `<ack_kit_path>`。
|
||
3. 分发方式：默认用**单软链接引用**，只有用户明确要求时才整份复制。
|
||
|
||
硬规则：
|
||
|
||
- 不要覆盖已有 `docs/ack/project.md`、`docs/ack/tasks.yaml` 或团队现有 `AGENTS.md`。如果文件已存在，先读内容并向用户说明差异，再询问是否合并。
|
||
- 不要把 `core/` 内容复制进项目覆盖层。项目覆盖层只写项目差异。
|
||
- 不要提交、推送或改 git 配置，除非用户明确要求。
|
||
- 不要把私有配置、token、`.env` 内容写进 `tasks.yaml` 或 `project.md`。
|
||
|
||
---
|
||
|
||
## 1. 建目录并挂载 kit
|
||
|
||
在目标项目根目录下创建推荐布局：
|
||
|
||
```text
|
||
docs/ack/
|
||
kit -> <ack_kit_path>
|
||
project.md
|
||
tasks.yaml
|
||
```
|
||
|
||
默认方式（推荐，可升级）：
|
||
|
||
```bash
|
||
mkdir -p docs/ack
|
||
ln -s <ack_kit_path> docs/ack/kit
|
||
```
|
||
|
||
如果 `docs/ack/kit` 已存在：
|
||
|
||
- 是指向同一个 ack 目录的软链接：继续。
|
||
- 是指向旧版本的软链接：报告当前指向与目标指向，询问是否更新。
|
||
- 是普通目录：不要删除；询问用户是保留、备份还是改用复制模式。
|
||
|
||
复制模式（仅用户明确要求）：
|
||
|
||
```bash
|
||
mkdir -p docs/ack
|
||
cp -R <ack_kit_path> docs/ack/kit
|
||
```
|
||
|
||
复制模式接入后，后续升级需要人工对比 `docs/ack/kit/VERSION`。
|
||
|
||
---
|
||
|
||
## 2. 生成项目覆盖层 `project.md`
|
||
|
||
从模板生成：
|
||
|
||
```bash
|
||
cp docs/ack/kit/templates/project.template.md docs/ack/project.md
|
||
```
|
||
|
||
然后填实际项目差异：
|
||
|
||
- 项目名、技术栈、运行命令、Base URL。
|
||
- 覆盖层文件路径：默认 `docs/ack/project.md`。
|
||
- 三角色模型档位：默认 Coordinator 强模型，Developer/Test 中低模型。
|
||
- 路径权限：规格文档、集成测试、复测记录、源码、单元测试、配置模板、本地私有配置。
|
||
- Developer 白盒验证命令：单测、构建、服务启动或重启。
|
||
- Test 黑盒复测命令：preflight、API smoke、浏览器回归。
|
||
|
||
如果是网站项目，务必在命令里写清：
|
||
|
||
- Developer 改完后如何重启服务或确认热更新生效。
|
||
- Test 使用哪个 Base URL。
|
||
- Test 浏览器复测入口、用例目录或手工检查路径。
|
||
|
||
可选：若希望 Agent 自动加载覆盖层，在目标项目 `AGENTS.md` 加一行指向它：
|
||
|
||
```markdown
|
||
本项目使用 ack 三角色协作协议，项目覆盖层见 `docs/ack/project.md`。
|
||
```
|
||
|
||
如果目标项目已有 `AGENTS.md`，只追加这一行或一个短小段落；不要重写原文件。
|
||
|
||
---
|
||
|
||
## 3. 生成任务板 `tasks.yaml`
|
||
|
||
从模板生成：
|
||
|
||
```bash
|
||
cp docs/ack/kit/templates/tasks.template.yaml docs/ack/tasks.yaml
|
||
```
|
||
|
||
至少替换这些字段：
|
||
|
||
- `updatedAt`：当前时间，带时区。
|
||
- `kitVersion`：读取 `docs/ack/kit/VERSION`。
|
||
- `project.name`：项目名。
|
||
- `project.repoPath`：目标项目根目录绝对路径。
|
||
- `project.baseUrl`：网站或 API 的默认访问地址；非服务项目可写 `n/a`。
|
||
- `project.devWorktree`：默认当前 worktree；如果会用独立 worktree，写实际路径。
|
||
- `project.overlayFile`：默认 `docs/ack/project.md`。
|
||
|
||
任务可以先保留一个低风险示例任务，但更推荐写入真实首个任务。每个任务的验收必须是可观测信号：
|
||
|
||
- 可见文本：页面或 CLI 输出出现什么。
|
||
- API 结果：状态码、字段、响应值。
|
||
- 交互结果：点击、跳转、提交、取消后的真实状态。
|
||
|
||
不要只写“功能正常”“体验更好”。
|
||
|
||
---
|
||
|
||
## 4. 校验结构
|
||
|
||
在目标项目根目录运行：
|
||
|
||
```bash
|
||
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||
```
|
||
|
||
通过后继续；失败则按错误修正 `tasks.yaml`，不要绕过校验。
|
||
|
||
同时人工检查：
|
||
|
||
- `docs/ack/kit` 是否能访问 `core/`、`templates/`、`scripts/`。
|
||
- `docs/ack/project.md` 是否只写项目差异，没有复制大段 core 文本。
|
||
- `docs/ack/tasks.yaml` 的 `project.overlayFile` 是否指向真实文件。
|
||
- 路径权限是否能防止 Developer 改规格、Test 改源码、多人写 `tasks.yaml`。
|
||
- 网站项目是否写清服务重启和浏览器复测方式。
|
||
|
||
---
|
||
|
||
## 5. 给用户的初始化报告
|
||
|
||
初始化完成后，Agent 应给用户一段短报告：
|
||
|
||
```text
|
||
ack 初始化完成。
|
||
|
||
创建/确认：
|
||
- docs/ack/kit -> <ack_kit_path>
|
||
- docs/ack/project.md
|
||
- docs/ack/tasks.yaml
|
||
|
||
已填项目差异：
|
||
- 技术栈：<...>
|
||
- Developer 验证命令：<...>
|
||
- Test 复测命令：<...>
|
||
- Base URL：<...>
|
||
|
||
校验：
|
||
- python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml: passed
|
||
|
||
下一步：
|
||
- 用 docs/ack/kit/core/kickoff.md 开一个真实需求；或
|
||
- 选一个低风险 bug 跑一次完整三角色闭环。
|
||
```
|
||
|
||
如果有未完成项，不要说“初始化完成”。改用：
|
||
|
||
```text
|
||
ack 初始化已部分完成，阻塞在：<具体原因>。
|
||
需要用户决定：<选项或缺失信息>。
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 一句话口令
|
||
|
||
当用户在新项目里说“初始化 ack”时，Agent 可以按下面执行：
|
||
|
||
```text
|
||
请在当前项目初始化 ack：确认项目根和 ack kit 路径；创建 docs/ack/kit 软链接；由 kit/templates 生成 docs/ack/project.md 与 docs/ack/tasks.yaml；填入项目实际路径、命令、Base URL、模型档位和首个任务；运行 validate_tasks.py；不要覆盖已有文件，不要提交或推送，完成后报告创建文件、校验结果和下一步。
|
||
```
|