refactor(skills): slim ack/builder/deployer for layered loading

Move mode-specific steps into references so SKILL.md only keeps routing and fail-closed rules.
This commit is contained in:
2026-08-26 11:26:58 +08:00
parent 2be0964d73
commit ef22c6829e
6 changed files with 308 additions and 784 deletions
+18 -29
View File
@@ -1,6 +1,8 @@
# 如何开始一个需求(Kickoff)
从零开一个需求的启动手册。角色/权限见 `roles-and-permissions.md`,闭环见 `closed-loop.md`,模型见 `model-routing.md`
从零开一个需求的启动手册。本文件只覆盖确认前的产品文档、任务拆分与验收信号
用户确认后的三角色闭环、飞书收件、启动 worker、交付和回归由 `SKILL.md` 按条件加载,
不要在本文件开头预读其它规范。
---
@@ -18,15 +20,15 @@
```text
我要做一个新需求:<一句话需求>。
你作为 ack 的 Coordinator(PM),按 ACK Skill 的 references 规范执行:
你作为 ack 的 Coordinator(PM),按 ACK Skill 执行:
1. 先读 .pouch/ack/project.md,并用 `scripts/select_tasks.py .pouch/ack/tasks.yaml`
读取有预算的 project、summary 和可工作任务;已知任务时传 `--task-id`,不要把
完整 tasks.yaml 注入上下文。校验 .pouch/ack/knowledge.yaml 并用
`scripts/select_knowledge.py` 只读取当前任务相关的 active 条目,再读
references/roles-and-permissions.md、closed-loop.md、optimization-method.md。
如果 tasks.yaml 声明 project.deliveryFile,再读取 delivery.yaml 与
references/delivery.md,但不要把配置本身当作执行授权。
`scripts/select_knowledge.py` 只读取当前任务相关的 active 条目
本 kickoff 只做确认前的产品文档与任务拆分;用户确认后的闭环、飞书、启动
worker、交付和回归按 ACK Skill 的模式路由按条件加载,不要在本步预读其它
references配置本身不是执行授权。
2. 写产品文档到 docs/(PRD / 交互 / 验收),把需求拆成任务,每个任务的验收写成可观测信号(可见文本 / API 结果 / 交互结果)。
3. 按任务 scope 从 knowledge.yaml 推荐 active 知识,确认后把固定 revision 的
knowledgeRefs 写入任务;不要派发 candidate 或全量知识库。
@@ -41,7 +43,7 @@
dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml
每个任务最多三轮有效产品复验,三轮不过记 leftover 并升级我复盘;环境失败单独
记录、恢复并告诉我下一步,不占产品复验轮次。
7. 所选任务都 verified 后,按 regression.md 给出新增/更新/退役/无回归,确认后写入
7. 所选任务都 verified 后,按 SKILL.md「运行回归」给出新增/更新/退役/无回归,确认后写入
.pouch/ack/regression.yaml。只有本次计划包含交付时才按 profile 顺序执行并写
deliveryRuns;启用 delivery 时不能省略 defaultProfile,默认停在 validation_ready
或 review_readystable/production 步骤再次向我确认。
@@ -52,7 +54,7 @@
## 第 1 步:Coordinator 产出(确认前)
1. 产品文档 → `docs/PRD-<feature>.md` 等(Coordinator R/W)。
2. 任务板 → `.pouch/ack/tasks.yaml`,每条任务带 `expected` + `verification`,验收写成可观测信号(`optimization-method.md` §1)。
2. 任务板 → `.pouch/ack/tasks.yaml`,每条任务带 `expected` + `verification`,验收写成可观测信号(可见文本 / API 结果 / 交互结果)。
3. 项目知识 → 从 `.pouch/ack/knowledge.yaml` 按 component、path、dependency、version
和 tag 推荐 `active` 条目,Coordinator 确认后写入固定 revision 的显式
`knowledgeRefs`。candidate 不参与选择。
@@ -86,10 +88,9 @@ python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml \
## 第 2 步:决定 worktree
`closed-loop.md` §「子任务放哪」:
- 需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。
- 小改动 / 串行修复 → 当前 worktree 起子 agent。
用户确认后的闭环步骤由 SKILL.md「工作」加载,不要在本步预读其它规范。
---
@@ -99,7 +100,7 @@ python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml \
terminal 不能单独授权复用。复用候选必须属于同一轮 ACK、处于空闲状态,且角色、
profile、worktree 与启动身份仍完全匹配;还必须通过受信后端清理历史消息并取得可核对
的新会话身份。当前 Orca 接口缺少该清理证明,所以 Orca 派发仍创建 fresh worker。
原因和边界见 `model-routing.md` §「Receipt、审计与复用边界」
复用边界以 SKILL.md「启动 worker」为准,不要在本步预读其它规范
先查看目标 profile hash,确认本次结构化配置。这个 hash 只用于审计和漂移比较,
不能用于匹配或复用旧 receipt / 既有终端:
@@ -146,7 +147,7 @@ worktree 走同一套 `plan` -> 带 expected fingerprint 的 `launch`。在调
`allowedWorktrees`)。profile
只允许 `read-only``workspace-write`v0.10 的 full-access 授权通道尚未实现,
任何 bypass、YOLO/force 或关闭 sandbox 的请求都必须失败,不能手写命令兜底。
选型与升级`model-routing.md`
选型与升级以 SKILL.md「启动 worker」为准
---
@@ -163,7 +164,7 @@ task-create → dispatch 给 DEV → 先确认 DEV 已开始执行(read/probe
→ 三轮有效产品失败:leftover,升级复盘,继续下一个
```
具体命令见 `orca-adapter.md`Orca)或 `closed-loop.md` §「手动模式」(无 Orca);派发文案见 `prompt-templates.md`
Orca / 手动命令与派发文案由 SKILL.md「启动 worker」按条件加载
Coordinator 只内联本轮 `knowledgeRefs` 指向的少量知识,不要求 worker 全量读取
知识库。知识正文不得作为自由 shell 执行;需要命令时只能引用项目已审查的检查
@@ -175,27 +176,15 @@ Coordinator 只内联本轮 `knowledgeRefs` 指向的少量知识,不要求 wo
## 第 5 步:可选交付
用户说「重新布测试环境」时加载 deployer skill 执行
`intents.testEnvironment` 绑定;「发布一个版本」时按 `delivery.md` §3.1 的
release profile 执行。intent 为 null 时先做交付配置维护。
用户说「重新布测试环境」或「发布一个版本」时,转入 SKILL.md 对应模式,不要在本步预读交付规范。intent 为 null 时先做交付配置维护。
所选任务 `verified` 后,`regression.md` 把本轮黑盒路径收获进
`.pouch/ack/regression.yaml`(新增/更新/退役/无回归四选一,用户确认后写入)。
用户说「回归」时先布测试环境,再派 Test 按目录执行。
所选任务 `verified` 后,转入 SKILL.md「运行回归」给出新增/更新/退役/无回归四选一,用户确认后写入 `.pouch/ack/regression.yaml`。用户说「回归」时先布测试环境,再派 Test 按目录执行。
所选任务都由 Coordinator 标记为 `verified` 后,若用户确认的计划包含交付,
`delivery.md` 执行所选 profile。启用交付时必须在计划中默认列出 `defaultProfile`
用户可明确取消,Coordinator 不能静默省略。先重新校验 `delivery.yaml`,固定当前 commit 和
config revision,然后按有序步骤调用项目入口与已安装的低层 skill。每一步证据写入
`tasks.yaml.deliveryRuns`;默认 profile 到 `validation_ready``review_ready` 即停止。
前者必须把测试环境地址和用户下一步交付出来;stable 发布和 production 部署必须在
approval 步骤再次确认。失败时保留任务的 `verified`,把
delivery run 标为 `blocked``failed`
所选任务都由 Coordinator 标记为 `verified` 后,若用户确认的计划包含交付,转入 SKILL.md 对应交付模式。启用交付时必须在计划中默认列出 `defaultProfile`,用户可明确取消,Coordinator 不能静默省略。先重新校验 `delivery.yaml`,固定当前 commit 和 config revision,然后按有序步骤调用项目入口与已安装的低层 skill。每一步证据写入 `tasks.yaml.deliveryRuns`;默认 profile 到 `validation_ready``review_ready` 即停止。前者必须把测试环境地址和用户下一步交付出来;stable 发布和 production 部署必须在 approval 步骤再次确认。失败时保留任务的 `verified`,把 delivery run 标为 `blocked``failed`
## 第 6 步:收尾
一轮结束时 Coordinator 必须能回答 `optimization-method.md` §「结束条件」的问题:
哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。
一轮结束时 Coordinator 必须能回答:哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。复验轮次争议以 SKILL.md「边界」为准。
Coordinator 最后标记整轮任务完成后,用 `scripts/reclaim_workers.py` 先 dry-run
审阅决策、再 `--apply` 关闭所有只关联 `verified` 任务的 Developer/Test 终端并核对
回执;receipt 和落盘证据继续保留。仍关联 `blocked``failed_retest``leftover`