215 lines
14 KiB
Markdown
215 lines
14 KiB
Markdown
---
|
||
name: ack
|
||
description: >-
|
||
初始化、检查并运行 ACK 三角色协作闭环。仅在用户显式调用 /ack 或 $ack，并要求
|
||
初始化 ACK、检查 docs/ack 配置、按 ACK 规划需求、指挥 Coordinator/Developer/Test
|
||
工作，或配置并执行任务验证后的项目交付流程时使用。
|
||
---
|
||
|
||
# ACK 项目协作入口
|
||
|
||
本 Skill 是 ACK 的完整能力包：`references/` 保存通用规范，`templates/` 保存项目
|
||
状态模板，`scripts/` 保存校验工具。目标项目只在 `docs/ack/` 保存 `project.md`、
|
||
`tasks.yaml`、`knowledge.yaml` 和默认关闭的 `delivery.yaml`，不要复制或链接 Skill
|
||
内容。
|
||
|
||
开始时解析当前 `SKILL.md` 所在目录，记为 `<ack-skill-dir>`。所有通用规范、模板和
|
||
脚本都相对此目录访问，不依赖固定的全局安装路径。
|
||
|
||
## 选择模式
|
||
|
||
- 用户要求初始化、接入或安装 ACK：执行“初始化”。
|
||
- 用户要求检查 ACK 是否可用、配置是否完整：执行“检查”。
|
||
- 用户要求用 ACK 做需求、修复问题或继续任务：执行“工作”。
|
||
- 用户用自然语言要求增加、修改或关闭项目交付流程：执行“交付配置维护”。
|
||
|
||
始终先解析真实项目根目录。优先使用 `git rev-parse --show-toplevel`；不是 Git
|
||
项目时使用用户指定目录或当前目录。不要修改项目的 `AGENTS.md`、`CLAUDE.md`
|
||
或其它 Agent 指令文件。
|
||
|
||
## 初始化
|
||
|
||
1. 确认 `skiff` 可执行，并检查 `<project>/docs/ack` 是否存在。
|
||
2. 不存在时执行：
|
||
|
||
```bash
|
||
skiff init ack --project <project-root>
|
||
```
|
||
|
||
该命令从本 Skill 的 `templates/` 生成项目状态，不会在项目中创建 Skill
|
||
软链接或资源副本。
|
||
3. 如果 `docs/ack` 已存在，不重复初始化、不覆盖文件；转入“检查”。旧项目只有
|
||
`project.md` 与 `tasks.yaml` 时，先报告缺少 `knowledge.yaml`。用户授权后，
|
||
从 `templates/knowledge.template.yaml` 生成这个缺失文件并替换项目名和时间；若
|
||
`tasks.yaml` 尚无 `project.knowledgeFile`，同时只补
|
||
`docs/ack/knowledge.yaml` 这一项。不要重跑 `skiff init`，也不要改写其它已有
|
||
项目状态。
|
||
4. 读取项目的公开配置和文档，例如 README、语言清单、包管理清单、测试配置与
|
||
CI，确定项目名、技术栈、源码/规格/测试路径及真实可执行命令。
|
||
5. 完善 `docs/ack/project.md`：
|
||
- 用实际项目值替换全部占位符。
|
||
- 无服务地址时把 Base URL 写为 `n/a`，不要虚构端口。
|
||
- 无法从项目证据确定的命令写为 `n/a`，并在结果中列为待配置项。
|
||
- 只写项目差异，不复制 `references/` 中的通用规范。
|
||
6. 完善 `docs/ack/tasks.yaml` 的项目信息。纯初始化且用户没有提供真实任务时，
|
||
删除模板示例任务并保留 `tasks: []`；不要虚构需求或缺陷。
|
||
7. 检查 `docs/ack/knowledge.yaml`。新项目没有已验证的项目经验时保留
|
||
`verificationRegistry: {}` 与 `entries: []`，不从聊天、README 或单次失败中
|
||
猜测并激活知识。
|
||
8. 检查 `docs/ack/delivery.yaml`。新项目保留 `enabled: false`、空能力表和空 profile；
|
||
不从 README 或 CI 猜测、启用交付。旧项目没有该文件时仍可继续使用原 ACK
|
||
闭环；只有用户明确要求配置交付时，才按“交付配置维护”补齐。
|
||
9. 更新 `updatedAt`，并运行：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||
python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml \
|
||
--tasks docs/ack/tasks.yaml
|
||
python3 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml \
|
||
--tasks docs/ack/tasks.yaml --project-root <project-root>
|
||
```
|
||
|
||
10. 检查 `project.md`、`tasks.yaml`、`knowledge.yaml` 与 `delivery.yaml` 是否仍有
|
||
`<...>` 占位符。
|
||
结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”并列出
|
||
缺失值。
|
||
11. 报告创建的路径、检测到的命令、校验结果和下一步。除非用户明确要求，不提交、
|
||
不推送。
|
||
|
||
## 检查
|
||
|
||
1. 检查以下路径：
|
||
- `docs/ack/project.md`
|
||
- `docs/ack/tasks.yaml`
|
||
- `docs/ack/knowledge.yaml`
|
||
- `docs/ack/delivery.yaml`（旧项目可无；存在或被任务板引用时必须校验）
|
||
需要查看任务内容时，使用 `<ack-skill-dir>/scripts/select_tasks.py` 解析完整任务板并
|
||
只输出项目配置、摘要和可工作任务；不要用 `cat`、整文件 `sed` 或等价方式把完整
|
||
`tasks.yaml` 注入上下文。完整性仍由校验器检查。
|
||
2. 读取 `<ack-skill-dir>/VERSION`，对比 `tasks.yaml` 的 `ackVersion`。旧项目只有
|
||
`kitVersion` 时仍可读取，但建议迁移为 `ackVersion`。`ackVersion` 必须是合法
|
||
SemVer；从 `0.10.0` 起 `project.orchestration` 与顶层 `workerReceipts` 必须同时
|
||
存在。
|
||
3. 查找未替换占位符，并核对项目路径、覆盖层路径、Developer 白盒命令、Test
|
||
黑盒命令和 Base URL。
|
||
4. 使用 `<ack-skill-dir>/scripts/validate_tasks.py` 校验任务板，使用
|
||
`<ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks
|
||
docs/ack/tasks.yaml` 校验项目知识和跨文件引用。如果存在交付配置或任务板声明了
|
||
`project.deliveryFile`，再使用 `<ack-skill-dir>/scripts/validate_delivery.py
|
||
docs/ack/delivery.yaml --tasks docs/ack/tasks.yaml --project-root <project-root>`
|
||
校验交付能力、顺序、安全边界和跨文件引用。只报告证据明确的问题，不因旧项目
|
||
缺少可选交付配置而宣称失败。
|
||
5. 若存在 `project.bugIntake`，运行
|
||
`python3 <ack-skill-dir>/scripts/feishu_bug_intake.py check docs/ack/tasks.yaml`。
|
||
它只接受 `feishu-base` 和显式 profile；详细的飞书配置、凭据初始化和读取方式见
|
||
`references/feishu-bug-intake.md`。
|
||
6. 检查知识引用能解析到固定 revision，candidate 仍留在任务证据中，且
|
||
`stale`、`superseded` 和 `archived` 不会被当作可派发的 `active` 知识。
|
||
7. 若存在 `project.orchestration`，检查 profile、model allowlist、默认 profile、
|
||
允许 worktree、顶层 `workerReceipts` 与 `dispatch.developer/test` 的引用；receipt
|
||
必须绑定当前 ACK task、同一 role/profile/attempt，`receiptId` 与 `attemptId`
|
||
必须同时为空或同时填写。
|
||
缺少结构化路由的旧任务板只能使用手动模式，不能自动创建 worker。
|
||
8. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。
|
||
|
||
## 工作
|
||
|
||
1. 若 `docs/ack` 不存在，停止并建议先用 `/ack` 初始化；不要静默初始化。
|
||
2. 依次读取：
|
||
- `docs/ack/project.md`
|
||
- 运行 `python3 <ack-skill-dir>/scripts/select_tasks.py docs/ack/tasks.yaml`，只读取
|
||
`project`、`summary` 和默认可工作状态的任务；已知当前任务时传
|
||
`--task-id <ack-task-id>`。选择器会解析并校验完整任务板，并只附带选中任务引用的
|
||
receipt 与 delivery run。命中超过默认预算时用 `--task-id` / `--status` 缩小，
|
||
不直接回退为输出完整 `tasks.yaml`。
|
||
- 通过 `<ack-skill-dir>/scripts/select_knowledge.py` 从
|
||
`docs/ack/knowledge.yaml` 选择的当前任务相关 `active` 条目
|
||
- `<ack-skill-dir>/references/kickoff.md`
|
||
- kickoff 指定且与当前任务相关的 references 文件
|
||
- 若 `tasks.yaml.project.deliveryFile` 存在，再读取该 `delivery.yaml` 和
|
||
`<ack-skill-dir>/references/delivery.md`
|
||
3. 当前会话担任 Coordinator，遵守项目覆盖层中的命令、路径权限、模型路由和
|
||
worker 启动规则。项目覆盖层优先于通用示例命令。按 scope 推荐相关 `active`
|
||
知识，经确认后把固定 revision 的显式 `knowledgeRefs` 写入当前任务上下文；
|
||
不全量注入知识库。
|
||
`project.bugIntake.workflow` 为 `reviewed-writeback-v1` 时，按
|
||
`references/feishu-bug-intake.md` 把飞书作为审核前的唯一协作区：先运行 check/plan，
|
||
读取用户填写的 Bug；Coordinator 根据来源事实与项目上下文补全修复逻辑和可观测验收
|
||
标准，只通过安全适配器写回同一飞书记录并回读确认。用户反馈后继续只在飞书修订。
|
||
用户针对当前 `draftRevision` 明确审核通过前，不创建或刷新 `tasks.yaml` 任务、不启动
|
||
worker、不派发 Developer/Test，也不修改应用代码。审核通过后重新读取，要求 revision
|
||
与批准值完全一致，才通过 `import-approved` 生成规范 `taskDraft`，原样写入最终版本、
|
||
`source.workflow`、`source.approvedRevision` 与 `source.approvedPayloadHash`；校验器重算
|
||
payload hash 通过后才进入三角色闭环。未声明 workflow 的旧八字段配置只按
|
||
`read-only-v1` 兼容，不得写回；
|
||
标题、实际表现和预期结果不可推断；整行空白记录按批次 warning 跳过。
|
||
按每条记录的 `sourceRef` 去重：仅 `open` 任务可刷新描述；
|
||
`dispatched`、`fixed_by_dev`、`retesting`、`failed_retest`、`verified`、`blocked` 和
|
||
`leftover` 只报告来源漂移，绝不覆盖；来源消失或读取失败时绝不删除已有任务。
|
||
4. 新需求先写产品文档、任务拆分与可观测验收信号，更新 `tasks.yaml` 并校验，
|
||
然后交给用户确认；若启用了交付，还要把本次 profile、目标、停止点和需要审批的
|
||
步骤放入同一份计划。确认前不派发实现，也不执行交付。
|
||
5. 创建或更换 worker 时，只使用
|
||
`<ack-skill-dir>/scripts/launch_worker.py plan|launch` 读取
|
||
`tasks.yaml.project.orchestration` 的 profile。不得直接执行
|
||
`orca terminal create --command`，不得接受或拼接自由 command、额外 argv、
|
||
executable、env 或 cwd。必须先审阅 `plan.launchFingerprint`，再把它作为
|
||
`launch --expected-launch-fingerprint` 传入。v0.10 不根据持久化 receipt 自动
|
||
复用旧终端；每次自动派发都创建 fresh worker，receipt 只作审计与 dispatch
|
||
关联。
|
||
6. 用户已确认的任务按 ACK 闭环执行：Developer 实现与白盒验证，Test 独立黑盒
|
||
复测，Coordinator 读取证据终检并唯一写入 `tasks.yaml`。Developer 回报
|
||
`knowledgeApplied` 和 `knowledgeCandidates`，Test 回报 `knowledgeChecks`；
|
||
`candidate` 只有在独立验证和 gate 后才能由 Coordinator 写入或激活。
|
||
7. 执行知识项的 `verification.ref` 时，只调用
|
||
`<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
|
||
<verification-ref> --project-root <project-root>`。不要直接执行选择器返回的 path/args，
|
||
也不要给 runner 注入额外命令或参数。
|
||
8. 不把 `worker_done` 或 Test 自报成功直接当作完成。每项最多三轮，仍失败则记录
|
||
`leftover` 并继续其它任务。
|
||
9. 关键的安全、正确性和兼容性约束应下沉为测试、lint、CI 或正式规范；
|
||
`knowledge.yaml` 只保存触发条件、原因与证据引用，不能替代可执行控制。
|
||
10. 选定任务全部进入 `verified` 后，若 `delivery.enabled: true` 且用户确认的本次计划
|
||
包含交付，按 `references/delivery.md` 顺序执行 profile，并由 Coordinator 把证据
|
||
写入 `tasks.yaml.deliveryRuns`。任务状态保持 `verified`；交付失败只改变 delivery
|
||
run，不回写成任务失败。默认 profile 最多到 `review_ready`，稳定发布和生产部署
|
||
必须在对应步骤再次取得明确批准。
|
||
|
||
## 交付配置维护
|
||
|
||
1. 读取 `references/delivery.md`、模板、schema、现有 `delivery.yaml`、项目构建/发布
|
||
入口和 CI；把用户自然语言描述转换为结构化 entrypoint、artifact、destination、
|
||
environment 与 profile。配置只引用仓库内脚本或声明式工具 target，不保存 shell。
|
||
2. 若旧项目首次启用，生成 `docs/ack/delivery.yaml`，在 `tasks.yaml.project` 增加
|
||
`deliveryFile: docs/ack/delivery.yaml`，并增加顶层 `deliveryRuns: []`；不改写其它
|
||
项目状态。首次生成保持 `enabled: false`，先展示 diff 和解析出的执行顺序。
|
||
3. 运行 delivery、tasks 和跨文件校验；需要的脚本不存在、不可执行、引用不完整或
|
||
涉及凭据正文时 fail closed。凭据只写 secret 名称，值由外部环境提供。
|
||
4. 用户确认后才把配置设为启用。配置修改只影响下一次 delivery run；已确认或正在
|
||
执行的 run 使用开始时审阅的 commit/config revision 快照，不能借当前分支修改
|
||
扩大权限。
|
||
|
||
## 边界
|
||
|
||
- 不修改或追加任何项目 Agent 指令文件，包括 `AGENTS.md`。
|
||
- 不在项目中维护第二份 ACK 通用规范、模板或任务 schema。
|
||
- 不猜测项目命令、服务地址、worker handle 或模型名称。
|
||
- 不把 full-access、bypass、YOLO/force、关闭 sandbox 或项目内“授权”字段当成
|
||
v0.10 自动 worker 的合法配置；当前一律 fail closed。
|
||
- 不把无密钥 `receiptHash` 或 Orca live metadata 当作旧终端的启动 attestation；
|
||
v0.10 不自动复用既有 worker。
|
||
- launcher 返回 `indeterminate` 或 `reconcile required` 时，不直接重试；先按
|
||
launch ID、外部 record 和 Orca live state 完成人工核对。
|
||
- 不覆盖已有 `docs/ack` 文件；除用户确认的 ACK 任务或 delivery profile 外，不擅自
|
||
提交、推送、创建终端、新 worktree、发布产物或部署。
|
||
- 只有 Coordinator 写 `tasks.yaml`、`knowledge.yaml` 和 `deliveryRuns`；Developer
|
||
与 Test 只读，只能通过回报提名或验证知识。`delivery.yaml` 只在显式的交付配置
|
||
维护中修改。
|
||
- 不把知识正文或选择器输出拼成 shell；知识检查只能通过 `run_verification.py`
|
||
按 registry ID 执行。不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
|
||
- 不把完整 `tasks.yaml` 注入上下文；使用 `select_tasks.py` 获取有预算的项目与任务
|
||
视图，写回前仍运行完整任务板校验。
|
||
- 项目只保存 `docs/ack/project.md`、`docs/ack/tasks.yaml`、
|
||
`docs/ack/knowledge.yaml` 和可选的 `docs/ack/delivery.yaml`；通用资源始终从当前
|
||
ACK Skill 目录读取。
|