feat: add init-new-project

kits/ack/README.md

@@ -21,6 +21,7 @@
 ack/
   VERSION                       # kit 版本，接入时记入项目
   README.md
+  init-new-project.md           # 给 Agent 的新项目初始化手册
   adoption-checklist.md
   core/                         # 稳定核心：跨项目通用，随 kit 升级，尽量别改
     kickoff.md                  #   如何开始一个需求（启动手册 + 开场指令模板）
@@ -84,6 +85,8 @@ ln -s <此框架绝对路径> <project>/docs/ack/kit
 
 ## 快速接入
 
+让 Agent 在新项目执行初始化时，优先给它 `init-new-project.md`。
+
 1. 建 `docs/ack/`，按方式 A 建单软链接 `kit`。
 2. 复制 `kit/templates/project.template.md` → `docs/ack/project.md`，填项目差异与模型档位，记 `kitVersion`。
 3. 复制 `kit/templates/tasks.template.yaml` → `docs/ack/tasks.yaml`，填 `project`（含 `overlayFile`）与首个任务。
@@ -150,6 +153,7 @@ python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
 | 验收信号写法、三轮失败策略 | `core/optimization-method.md` |
 | 派发/复测/回报的 prompt 文案 | `core/prompt-templates.md` |
 | Orca 具体命令 | `core/orca-adapter.md` |
+| 让 Agent 在新项目初始化 ack | `init-new-project.md` |
 | 新项目接入步骤 | `adoption-checklist.md` |
 
 ---

kits/ack/VERSION

@@ -1 +1 @@
-0.8.0
+0.8.1

kits/ack/examples/project.example.md

@@ -1,6 +1,6 @@
 # notes-web Agent 协作协议（示例，项目覆盖层）
 
-> 本项目基于 ack v0.8.0。
+> 本项目基于 ack v0.8.1。
 > 稳定规范引用 `docs/ack/kit/core/`，本文件只填项目差异。
 > 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
 > 目录下只有一个软链接 `kit/` + `project.md` + `tasks.yaml`。

kits/ack/init-new-project.md

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