laily
ef22c6829e
Move mode-specific steps into references so SKILL.md only keeps routing and fail-closed rules.
107 lines
8.8 KiB
Markdown
107 lines
8.8 KiB
Markdown
---
|
||
name: ack
|
||
description: >-
|
||
初始化、检查并运行 ACK 三角色闭环。仅在用户显式调用 /ack 或 $ack，并要求
|
||
初始化 ACK、检查 .pouch/ack、按 ACK 做需求或修 bug、指挥
|
||
Coordinator/Developer/Test、配置或运行测试环境与发版、或跑回归时使用。
|
||
---
|
||
|
||
# ACK 项目协作入口
|
||
|
||
项目只在 `.pouch/ack/` 保存 `project.md`、`tasks.yaml`、`knowledge.yaml`、
|
||
`delivery.yaml` 和 `regression.yaml`。不要复制 Skill 内容，不要修改 `AGENTS.md`、
|
||
`CLAUDE.md`。
|
||
|
||
开始时解析当前 `SKILL.md` 所在目录为 `<ack-skill-dir>`。优先
|
||
`git rev-parse --show-toplevel` 作为项目根。
|
||
|
||
## 选择模式
|
||
|
||
- 初始化、接入 ACK：执行「初始化」。
|
||
- 检查配置是否完整：执行「检查」。
|
||
- 做需求、修 bug 或继续任务：执行「工作」。修 bug 不写大 PRD。
|
||
- 增改关闭交付、说明怎么布测试环境或发版：执行「交付配置维护」。
|
||
- 部署或重布测试环境：执行「运行测试环境」（加载 deployer，不复制 compose）。
|
||
- 发布版本：执行「运行版本发布」。回归：执行「运行回归」。
|
||
- 任务板使用 Orca 时，编排命令见 [orca-adapter.md](references/orca-adapter.md)。
|
||
|
||
## 边界
|
||
|
||
- 不覆盖已有 `.pouch/ack`；除用户确认的任务或 delivery profile 外，不擅自提交、推送、创建终端、新 worktree、发布或部署。
|
||
- 不猜测命令、地址、worker handle 或模型名；无法确定写 `n/a`。
|
||
- 不把完整 `tasks.yaml` / `knowledge.yaml` / `regression.yaml` 注入上下文；用对应 `select_*.py`。写回前跑完整校验。
|
||
- 只有 Coordinator 写任务板、知识库、回归目录、`deliveryRuns` 和 `regressionRuns`。`delivery.yaml` 只在「交付配置维护」中改。见 [roles-and-permissions.md](references/roles-and-permissions.md)。
|
||
- 知识检查只经 `run_verification.py` 的 registry ID；不把知识正文拼成 shell。
|
||
- 自动 worker 禁止 full-access、bypass、关闭 sandbox、Grok `--yolo` / bypassPermissions。OMP `--approval-mode yolo` 只用于 OMP 审批（workspace-write → yolo，read-only → always-ask），禁止 `--auto-approve`，不适用于其它 backend。
|
||
- 无清理证明不复用 worker；无密钥 `receiptHash` 或 Orca live metadata 不能授权复用。当前 Orca 走 fresh。`indeterminate` / `reconcile required` 不直接重试。
|
||
- 产品失败才占三轮；环境失败写 `environmentIncidents`。见 [optimization-method.md](references/optimization-method.md) §4。
|
||
|
||
## 初始化
|
||
|
||
1. 确认 `pouch` 可执行。`.pouch/ack` 不存在则 `pouch init ack --project <project-root>`；已存在则不覆盖、转入「检查」。
|
||
2. 按 [init-new-project.md](references/init-new-project.md) 完善项目状态。不从 README/CI 猜测并启用交付或知识；初始化 **不** 自动初始化 deployer 或 builder。
|
||
3. 运行：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/validate_tasks.py .pouch/ack/tasks.yaml
|
||
python3 <ack-skill-dir>/scripts/validate_knowledge.py .pouch/ack/knowledge.yaml \
|
||
--tasks .pouch/ack/tasks.yaml
|
||
python3 <ack-skill-dir>/scripts/validate_delivery.py .pouch/ack/delivery.yaml \
|
||
--tasks .pouch/ack/tasks.yaml --project-root <project-root>
|
||
python3 <ack-skill-dir>/scripts/validate_regression.py .pouch/ack/regression.yaml \
|
||
--tasks .pouch/ack/tasks.yaml
|
||
```
|
||
|
||
4. 检查上述文件是否仍有 `<...>` 占位符。结构校验通过且必填项目事实完整才称「完成」。除非用户明确要求，不提交、不推送。
|
||
|
||
```text
|
||
## ack 初始化：完成 | 部分完成 | 阻塞
|
||
|
||
已具备: …
|
||
待配置: 路径 + 字段 + 可粘贴示例 + 缺了会挡住哪步
|
||
工具链: pouch …
|
||
下一步: 一句话
|
||
```
|
||
|
||
## 检查
|
||
|
||
只读，不自动修复。核对清单见 [adoption-checklist.md](references/adoption-checklist.md)。用 `select_tasks.py` 看配置；跑与「初始化」相同的四个校验器。对比 `VERSION` 与 `ackVersion`（旧 `kitVersion` 仍可读）；从 `0.10.0` 起 `project.orchestration` 与 `workerReceipts` 必须同时存在。旧项目可无 delivery/regression，存在或被引用时必须校验。若有 `bugIntake` 再跑 `feishu_bug_intake.py check`。若测试环境走 deployer，只读跑其 `check.py`；未通过列入待配置，不要复制 compose 或静默初始化 deployer。用同一报告格式，标题改为 `## ack 检查：…`。
|
||
|
||
## 工作
|
||
|
||
1. `.pouch/ack` 不存在：停止并建议先 `/ack` 初始化；不要静默初始化。
|
||
2. 读 `project.md`；用 `select_tasks.py`（已知任务加 `--task-id`）和 `select_knowledge.py` 取当前任务相关 `active` 条目。超预算时缩小选择，不回退为完整 yaml。
|
||
3. 新需求或尚未确认的计划：读 [kickoff.md](references/kickoff.md)。修 bug 写短问题说明、复现和可观测验收，不写大 PRD。
|
||
4. 用户已确认后按 [closed-loop.md](references/closed-loop.md) 执行。当前会话担任 Coordinator，不亲自写代码或跑测试。
|
||
5. 存在 `project.bugIntake` 时先完成「飞书收件」。创建或更换 worker 走「启动 worker」。若 `intents.testEnvironment` 已启用，派 Test 前先走「运行测试环境」。
|
||
6. 知识 `verification.ref` 只经 `run_verification.py`。不把 `worker_done` 或 Test 自报成功当作完成。环境失败先有界恢复并报告 `userAction`；三轮产品失败记 `leftover`。
|
||
7. 任务 `verified` 且改了可见行为或 API 后，转入「运行回归」收获用例。若本次计划含交付，再走对应交付模式；默认最多到 `validation_ready` 或 `review_ready`。
|
||
8. 整轮完成后 `reclaim_workers.py` 先 dry-run 再 `--apply`，只回收仅属于 `verified` 任务的 worker。关闭结果不确定则记录，不伪报。
|
||
|
||
## 飞书收件
|
||
|
||
若存在 `project.bugIntake`，读 [feishu-bug-intake.md](references/feishu-bug-intake.md)。用户针对当前 `draftRevision` 明确审核通过并亲自把飞书状态改为 `已确认` 前：不创建或刷新任务、不启动 worker、不派发、不改应用代码。Coordinator 不得自行写入 `已确认`。未声明 workflow 的旧配置只按 `read-only-v1`，不得写回。来源消失或读取失败时不删除已有任务。
|
||
|
||
## 启动 worker
|
||
|
||
只使用 `scripts/launch_worker.py plan|launch`。不得直接 `orca terminal create --command`，不得拼接自由 command、argv、executable、env 或 cwd。读 [model-routing.md](references/model-routing.md)。先审阅 `plan.launchFingerprint`，再作为 `launch --expected-launch-fingerprint` 传入。派发文案用 [prompt-templates.md](references/prompt-templates.md)。派发后 terminal read 确认已开始；卡在审批、未回车或额度限制按环境失败处理。等待期间用 `scripts/worker_probe.py`，不盲等 `worker_done`。
|
||
|
||
## 交付配置维护
|
||
|
||
读 [delivery.md](references/delivery.md)。测试环境写成 `{via: deployer, env: <env>}`；`.pouch/deployer/<env>` 未就绪则停止并加载 deployer「初始化」，不在 ACK 里复制 compose。发版写在同一份 `delivery.yaml`，不保存 shell。本地 `npm run dev` / `go run` 不算测试环境。旧项目首次启用只补文件指针与 `deliveryRuns: []`，保持 `enabled: false`，用户确认后才启用。进行中的 run 使用开始时的 commit/config 快照。
|
||
|
||
## 运行测试环境
|
||
|
||
读 `delivery.yaml` 与 [delivery.md](references/delivery.md)，并加载 deployer。`enabled` 非 true 或 intent 为 null：停止，转入交付配置维护。intent 必须是 `{via: deployer, env: <env>}`；旧 profile ID 字符串要先迁移。不要用 ACK delivery profile 布环境，不猜测启动命令。不要求任务已 `verified`。对 `.pouch/deployer/<env>` 按 deployer：list → 按服务 sync+up → 健康检查。证据写入 `deliveryRuns`（`intent: testEnvironment`，`profile: deployer-<env>`）。未安装、缺目录、`check.py` 失败或健康检查失败：fail closed，报告 `userAction`，不记产品失败。
|
||
|
||
## 运行回归
|
||
|
||
读 [regression.md](references/regression.md)。缺目录则停止；用户授权后从模板生成空文件并只补指针与 `regressionRuns: []`。用 `select_regression.py` 读 active 用例（默认 `--suite smoke`）；无命中则停止。先执行「运行测试环境」，再派独立 Test worker。Coordinator 不亲自点浏览器或打 API；`browser` 不得改成只打 API。终检写入 `regressionRuns`。失败不自动派 Developer，不占三轮预算。任务 `verified` 后给出新增/更新/退役/无回归四选一，用户确认后写入；Test 只提名。
|
||
|
||
## 运行版本发布
|
||
|
||
1. 读同一份 `delivery.yaml` 与 [delivery.md](references/delivery.md)。
|
||
2. `enabled` 不为 true，或 `intents.release` 为 null：停止，先做交付配置维护。
|
||
3. 按该 profile 顺序执行。stable 发布和生产部署的 `approval` 不能用口头「发版」代替。
|
||
4. 证据写入 `deliveryRuns`，`intent: release`；绑定了任务时 `taskIds` 仍只能引用 `verified` 任务。
|