laily
f3cd56b78e
Use ~/.pouch, the pouch CLI, and .pouch.yaml as the SSOT container. Keep the inner skills/ packages, and store ACK project state in .pouch/ack instead of docs/ack.
209 lines
11 KiB
Markdown
209 lines
11 KiB
Markdown
# 如何开始一个需求（Kickoff）
|
||
|
||
从零开一个需求的启动手册。角色/权限见 `roles-and-permissions.md`，闭环见 `closed-loop.md`，模型见 `model-routing.md`。
|
||
|
||
---
|
||
|
||
## 前提：谁是 Coordinator
|
||
|
||
**你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。** 你负责写文档、拆任务、
|
||
编排、终检，**不亲自写代码、不亲自跑测试**。开发和测试是另起的 worker agent；
|
||
具体 CLI、模型、reasoning effort 和执行模式的机器事实源是
|
||
`.pouch/ack/tasks.yaml` 的 `project.orchestration`。`.pouch/ack/project.md` 只解释项目
|
||
差异，不能提供另一套启动命令。
|
||
|
||
---
|
||
|
||
## 第 0 步：给 Coordinator 的开场指令（复制改需求）
|
||
|
||
```text
|
||
我要做一个新需求：<一句话需求>。
|
||
你作为 ack 的 Coordinator(PM)，按 ACK Skill 的 references 规范执行：
|
||
|
||
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，但不要把配置本身当作执行授权。
|
||
2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
|
||
3. 按任务 scope 从 knowledge.yaml 推荐 active 知识，确认后把固定 revision 的
|
||
knowledgeRefs 写入任务；不要派发 candidate 或全量知识库。
|
||
4. 把任务写进 .pouch/ack/tasks.yaml（只有你写），校验 tasks.yaml 和 knowledge.yaml。
|
||
5. 先把「产品文档 + 任务拆分 + 验收信号 + 适用知识引用」给我确认；若启用了交付，
|
||
同时列明本次 profile、目标、停止点与审批步骤。不要急着派发或交付。
|
||
6. 我确认后，按 ack 闭环循环：先用 `scripts/launch_worker.py` 校验结构化
|
||
Developer/Test profile；优先选择同一轮内角色/profile/worktree 匹配的空闲 worker，
|
||
只有历史消息已可信清理并取得新会话身份才复用，否则审阅 plan 后用 expected
|
||
fingerprint 创建 fresh worker；
|
||
dispatch 开发 → worker_done → 若 intents.testEnvironment 已启用则先拉起测试环境 →
|
||
dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml；
|
||
每个任务最多三轮有效产品复验，三轮不过记 leftover 并升级我复盘；环境失败单独
|
||
记录、恢复并告诉我下一步，不占产品复验轮次。
|
||
7. 所选任务都 verified 后，只有本次计划包含交付时才按 profile 顺序执行并写
|
||
deliveryRuns；启用 delivery 时不能省略 defaultProfile，默认停在 validation_ready
|
||
或 review_ready，stable/production 步骤再次向我确认。
|
||
```
|
||
|
||
---
|
||
|
||
## 第 1 步：Coordinator 产出（确认前）
|
||
|
||
1. 产品文档 → `docs/PRD-<feature>.md` 等（Coordinator R/W）。
|
||
2. 任务板 → `.pouch/ack/tasks.yaml`，每条任务带 `expected` + `verification`，验收写成可观测信号（见 `optimization-method.md` §1）。
|
||
3. 项目知识 → 从 `.pouch/ack/knowledge.yaml` 按 component、path、dependency、version
|
||
和 tag 推荐 `active` 条目，Coordinator 确认后写入固定 revision 的显式
|
||
`knowledgeRefs`。candidate 不参与选择。
|
||
4. 校验结构与引用：
|
||
|
||
```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
|
||
```
|
||
|
||
`project.orchestration` 是 worker profile 的机器 SSOT；未知字段、非 allowlist 模型、
|
||
不匹配的角色/档位和非安全权限必须在派发前 fail closed。
|
||
|
||
读取任务上下文使用：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml
|
||
python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml \
|
||
--task-id <ack-task-id>
|
||
```
|
||
|
||
选择器解析并校验完整任务板，但只输出命中任务及其 receipt/delivery run；超过预算时
|
||
显式失败，不得改用 `cat` 或整文件 `sed`。
|
||
|
||
5. **停下来给人确认**：这是强模型该花时间的地方，不要跳过。
|
||
|
||
如果 `delivery.enabled: true`，确认内容还必须列出：profile、关联 task IDs、构建产物、
|
||
发布 channel、部署环境、PR 是否创建/标 ready、停止点，以及哪些步骤会再次审批。
|
||
|
||
---
|
||
|
||
## 第 2 步：决定 worktree
|
||
|
||
见 `closed-loop.md` §「子任务放哪」：
|
||
|
||
- 需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。
|
||
- 小改动 / 串行修复 → 当前 worktree 起子 agent。
|
||
|
||
---
|
||
|
||
## 第 3 步：审阅并启动 worker
|
||
|
||
先读 `tasks.yaml.project.orchestration` 的结构化 profiles。历史 receipt 或既有 Orca
|
||
terminal 不能单独授权复用。复用候选必须属于同一轮 ACK、处于空闲状态，且角色、
|
||
profile、worktree 与启动身份仍完全匹配；还必须通过受信后端清理历史消息并取得可核对
|
||
的新会话身份。当前 Orca 接口缺少该清理证明，所以 Orca 派发仍创建 fresh worker。
|
||
原因和边界见 `model-routing.md` §「Receipt、审计与复用边界」。
|
||
|
||
先查看目标 profile hash，确认本次结构化配置。这个 hash 只用于审计和漂移比较，
|
||
不能用于匹配或复用旧 receipt / 既有终端：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/launch_worker.py profile-hash \
|
||
--project-root <project-root> --profile-id <profile-id>
|
||
```
|
||
|
||
生成只读计划：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
|
||
--project-root <project-root> --task-id <task-id> \
|
||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99>
|
||
```
|
||
|
||
审阅计划后执行唯一创建入口：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||
--project-root <project-root> --task-id <task-id> \
|
||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99> \
|
||
--expected-launch-fingerprint <plan 中的 sha256:...>
|
||
```
|
||
|
||
`launch` 的 fingerprint 必须来自刚才审阅的 plan；若中间任何关键事实漂移，重新
|
||
plan，不得覆盖检查。标准输出是单一 JSON。Coordinator 校验其中的 receipt 后，把
|
||
receipt 原样追加到 `tasks.yaml.workerReceipts`，把 `receipt.id` 写入该任务
|
||
`dispatch.<role>.receiptId`、把 `profileId` 写入 `dispatch.<role>.profileId`，并把
|
||
本轮稳定 ID 写入 `dispatch.<role>.attemptId`。三者必须与 receipt 的当前
|
||
task/role/profile/attempt 完全绑定；不得把旧任务或旧轮次的 receipt 改挂到当前
|
||
dispatch。后续
|
||
紧随其后的本次 Orca dispatch 只使用这次 fresh receipt binding 中的 handle；持久化
|
||
receipt 仅用于审计，不能在后续轮次单独授权复用。不要自行拼装 Agent CLI 或 Orca 的
|
||
底层创建命令。
|
||
|
||
新 worktree 时可先运行
|
||
`orca worktree create --name <feature> --base-branch <base> --json`，再对返回的绝对
|
||
worktree 走同一套 `plan` -> 带 expected fingerprint 的 `launch`。在调用 launcher
|
||
前，确认新 worktree 与权威项目根同一 Git 仓库即可（v0.19 起不再需要登记
|
||
`allowedWorktrees`）。profile
|
||
只允许 `read-only` 或 `workspace-write`；v0.10 的 full-access 授权通道尚未实现，
|
||
任何 bypass、YOLO/force 或关闭 sandbox 的请求都必须失败，不能手写命令兜底。
|
||
选型与升级见 `model-routing.md`。
|
||
|
||
---
|
||
|
||
## 第 4 步：跑闭环（每个任务）
|
||
|
||
```text
|
||
task-create → dispatch 给 DEV → 先确认 DEV 已开始执行（read/probe；未开始按环境失败处理）→ 滚动 wait 等 worker_done
|
||
→ 每个角色先检查可安全重置的空闲 worker；不符合即通过 plan + expected fingerprint launch fresh worker
|
||
→ 每轮使用 Coordinator 分配的稳定 <task-id>-A<round>
|
||
→ 回写 fixed_by_dev → 若 intents.testEnvironment 已启用则先拉起测试环境 → dispatch 给 TEST 复测 → 等 retest_result
|
||
→ Developer 回 knowledgeApplied / knowledgeCandidates，Test 回 knowledgeChecks
|
||
→ 环境无法完成：记录 environmentIncidents，报告影响与用户下一步，恢复后重新复验（不计轮次）
|
||
→ Coordinator 读证据终检 → 过则 verified，产品失败则 failed_retest 再派 DEV（最多累计 3 轮）
|
||
→ 三轮有效产品失败：leftover，升级复盘，继续下一个
|
||
```
|
||
|
||
具体命令见 `orca-adapter.md`（Orca）或 `closed-loop.md` §「手动模式」（无 Orca）；派发文案见 `prompt-templates.md`。
|
||
|
||
Coordinator 只内联本轮 `knowledgeRefs` 指向的少量知识，不要求 worker 全量读取
|
||
知识库。知识正文不得作为自由 shell 执行；需要命令时只能引用项目已审查的检查
|
||
入口，并把它的 registry ID 交给 `<ack-skill-dir>/scripts/run_verification.py`，
|
||
不自行拼接 path/args。Test 独立验证且 gate 通过后，Coordinator 才能把 candidate
|
||
写成 active 知识；关键约束应继续下沉为测试、lint、CI 或正式规范。
|
||
|
||
---
|
||
|
||
## 第 5 步：可选交付
|
||
|
||
用户说「重新布测试环境」或「发布一个版本」时，按 `delivery.md` §3.1 的
|
||
`intents` 执行对应 profile，不另找文档。intent 为 null 时先做交付配置维护。
|
||
|
||
所选任务都由 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`。
|
||
|
||
## 第 6 步：收尾
|
||
|
||
一轮结束时 Coordinator 必须能回答 `optimization-method.md` §「结束条件」的问题：
|
||
哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。
|
||
Coordinator 最后标记整轮任务完成后，用 `scripts/reclaim_workers.py` 先 dry-run
|
||
审阅决策、再 `--apply` 关闭所有只关联 `verified` 任务的 Developer/Test 终端并核对
|
||
回执；receipt 和落盘证据继续保留。仍关联 `blocked`、`failed_retest`、`leftover`
|
||
或其它未完成任务/未解决环境事件的终端保留，不设置 TTL。一个终端只要仍被任一这类
|
||
任务引用，就不能因为同时关联了 verified 任务而关闭。
|
||
|
||
---
|
||
|
||
## 一句话
|
||
|
||
产品文档 + 验收信号写在前（你，强模型）→ 确认显式 `knowledgeRefs` → 从
|
||
`tasks.yaml.project.orchestration` 解析安全 profile → 审阅 plan 并用 expected
|
||
fingerprint 启动 fresh DEV/TEST → dispatch / 复测 / 终检循环 → 任务结论落
|
||
`tasks.yaml` → 可选 delivery profile 到审核点，验证后的
|
||
跨任务知识由 Coordinator 落 `knowledge.yaml` → 整轮完成后回收仅属于 verified
|
||
任务的 worker，保留 blocked/failed/leftover worker。
|