# 在新项目初始化 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；不要覆盖已有文件，不要提交或推送，完成后报告创建文件、校验结果和下一步。
```