5.8 KiB
5.8 KiB
在新项目初始化 ack（给 Agent 的操作手册）
本文件指导 Agent 把 ack 接入一个目标项目。它是执行手册：按步骤在目标项目创建 docs/ack/、挂载 kit、生成项目覆盖层和任务板，并完成一次结构校验。
若只想人工核对是否接入完整，看 adoption-checklist.md。若要开始一个真实需求，看 core/kickoff.md。
0. 前提与安全边界
开始前先确认三件事：
- 目标项目根目录：运行或读取当前环境的项目根，不要假设路径。
- ack kit 目录：本框架目录的绝对路径，例如
<ack_kit_path>。 - 分发方式：默认用单软链接引用，只有用户明确要求时才整份复制。
硬规则：
- 不要覆盖已有
docs/ack/project.md、docs/ack/tasks.yaml或团队现有AGENTS.md。如果文件已存在，先读内容并向用户说明差异，再询问是否合并。 - 不要把
core/内容复制进项目覆盖层。项目覆盖层只写项目差异。 - 不要提交、推送或改 git 配置，除非用户明确要求。
- 不要把私有配置、token、
.env内容写进tasks.yaml或project.md。
1. 建目录并挂载 kit
在目标项目根目录下创建推荐布局：
docs/ack/
kit -> <ack_kit_path>
project.md
tasks.yaml
默认方式（推荐，可升级）：
mkdir -p docs/ack
ln -s <ack_kit_path> docs/ack/kit
如果 docs/ack/kit 已存在：
- 是指向同一个 ack 目录的软链接：继续。
- 是指向旧版本的软链接：报告当前指向与目标指向，询问是否更新。
- 是普通目录：不要删除；询问用户是保留、备份还是改用复制模式。
复制模式（仅用户明确要求）：
mkdir -p docs/ack
cp -R <ack_kit_path> docs/ack/kit
复制模式接入后，后续升级需要人工对比 docs/ack/kit/VERSION。
2. 生成项目覆盖层 project.md
从模板生成：
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 加一行指向它：
本项目使用 ack 三角色协作协议，项目覆盖层见 `docs/ack/project.md`。
如果目标项目已有 AGENTS.md，只追加这一行或一个短小段落；不要重写原文件。
3. 生成任务板 tasks.yaml
从模板生成：
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. 校验结构
在目标项目根目录运行：
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 应给用户一段短报告：
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 跑一次完整三角色闭环。
如果有未完成项，不要说“初始化完成”。改用：
ack 初始化已部分完成，阻塞在：<具体原因>。
需要用户决定：<选项或缺失信息>。
6. 一句话口令
当用户在新项目里说“初始化 ack”时，Agent 可以按下面执行：
请在当前项目初始化 ack：确认项目根和 ack kit 路径；创建 docs/ack/kit 软链接；由 kit/templates 生成 docs/ack/project.md 与 docs/ack/tasks.yaml；填入项目实际路径、命令、Base URL、模型档位和首个任务；运行 validate_tasks.py；不要覆盖已有文件，不要提交或推送，完成后报告创建文件、校验结果和下一步。