From 61ef55c514930f73671311e8e0d316229e2ee385 Mon Sep 17 00:00:00 2001 From: laily Date: Tue, 7 Jul 2026 09:44:55 +0800 Subject: [PATCH] feat: modify ack --- kits/ack/README.md | 60 ++++++++++++++++++ kits/ack/VERSION | 2 +- kits/ack/core/kickoff.md | 85 ++++++++++++++++++++++++++ kits/ack/core/prompt-templates.md | 27 +++++++- kits/ack/core/roles-and-permissions.md | 51 ++++++++++++++++ kits/ack/examples/project.example.md | 3 +- kits/ack/templates/project.template.md | 1 + 7 files changed, 224 insertions(+), 5 deletions(-) create mode 100644 kits/ack/core/kickoff.md diff --git a/kits/ack/README.md b/kits/ack/README.md index 2391b60..068791c 100644 --- a/kits/ack/README.md +++ b/kits/ack/README.md @@ -23,6 +23,7 @@ ack/ README.md adoption-checklist.md core/ # 稳定核心：跨项目通用，随 kit 升级，尽量别改 + kickoff.md # 如何开始一个需求（启动手册 + 开场指令模板） roles-and-permissions.md # 角色/权限/状态机/完成定义（SSOT） model-routing.md # 三角色默认模型档位 + 升级规则（SSOT） closed-loop.md # 编排无关闭环 + 手动模式 + worktree 对齐 @@ -94,6 +95,65 @@ ln -s <此框架绝对路径> /docs/ack/kit --- +## 常用使用方法 + +### 开一个新需求（最常用） + +你（强模型会话）就是 Coordinator(PM)。完整手册见 `core/kickoff.md`，开场指令： + +```text +我要做一个新需求：<一句话需求>。你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 规范： +先读 project.md 与 core/*；写产品文档到 docs/ 并把需求拆成带可观测验收信号的任务写进 docs/ack/tasks.yaml； +先给我确认产品文档+任务拆分，再按闭环起 DEV/TEST worker（cursor-agent --model auto）循环派发/复测/终检； +每个任务最多三轮，三轮不过记 leftover。 +``` + +### 起 worker（模型固定为 auto） + +```bash +orca terminal create --worktree active --command "cursor-agent --model auto" --title "DEV" --json +orca terminal create --worktree active --command "cursor-agent --model auto" --title "TEST" --json +``` + +需要隔离/并行时先建 worktree：`orca worktree create --name --base-branch --json`（选择依据见 `core/closed-loop.md`）。 + +### 派发与等待（Orca） + +```bash +orca orchestration task-create --spec "<任务与验收>" --json +orca orchestration dispatch --task --to --json +orca orchestration check --terminal --wait \ + --types worker_done,retest_result,escalation,decision_gate --timeout-ms 900000 --json +``` + +不能 `--inject` 时手动投递 `core/prompt-templates.md` 的模板；命令细节见 `core/orca-adapter.md`。 + +### 校验任务板结构 + +```bash +python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml +``` + +### 只处理已有未通过项 + +用「默认口令」（见下）让 Coordinator 直接扫 `tasks.yaml` 里的 `open` / `failed_retest` 继续闭环。 + +### 速查：想做什么 → 看哪个文件 + +| 想做的事 | 文件 | +|----------|------| +| 开一个新需求怎么起步 | `core/kickoff.md` | +| 角色/权限/状态机/完成定义 | `core/roles-and-permissions.md` | +| 三角色各自该怎么做（规划/写测试/复测能力清单） | `core/roles-and-permissions.md` §三角色能力清单 | +| 用哪个模型、怎么固定、何时升级 | `core/model-routing.md` | +| 闭环步骤、手动模式、worktree 决策与对齐 | `core/closed-loop.md` | +| 验收信号写法、三轮失败策略 | `core/optimization-method.md` | +| 派发/复测/回报的 prompt 文案 | `core/prompt-templates.md` | +| Orca 具体命令 | `core/orca-adapter.md` | +| 新项目接入步骤 | `adoption-checklist.md` | + +--- + ## 默认口令 ```text diff --git a/kits/ack/VERSION b/kits/ack/VERSION index b616048..a3df0a6 100644 --- a/kits/ack/VERSION +++ b/kits/ack/VERSION @@ -1 +1 @@ -0.6.2 +0.8.0 diff --git a/kits/ack/core/kickoff.md b/kits/ack/core/kickoff.md new file mode 100644 index 0000000..c9373d0 --- /dev/null +++ b/kits/ack/core/kickoff.md @@ -0,0 +1,85 @@ +# 如何开始一个需求（Kickoff） + +从零开一个需求的启动手册。角色/权限见 `roles-and-permissions.md`，闭环见 `closed-loop.md`，模型见 `model-routing.md`。 + +--- + +## 前提：谁是 Coordinator + +**你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。** 你负责写文档、拆任务、编排、终检，**不亲自写代码、不亲自跑测试**。开发和测试是另起的 worker agent（`cursor-agent --model auto`）。 + +--- + +## 第 0 步：给 Coordinator 的开场指令（复制改需求） + +```text +我要做一个新需求：<一句话需求>。 +你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 的规范执行： + +1. 先读 docs/ack/project.md、docs/ack/kit/core/roles-and-permissions.md、closed-loop.md、optimization-method.md。 +2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。 +3. 把任务写进 docs/ack/tasks.yaml（只有你写），跑 validate 校验结构。 +4. 先把「产品文档 + 任务拆分 + 验收信号」给我确认，不要急着派发。 +5. 我确认后，按 ack 闭环循环：为任务起 Developer/Test worker（cursor-agent --model auto）， + dispatch 开发 → worker_done → dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml； + 每个任务最多三轮，三轮不过记 leftover 并升级我复盘。 +``` + +--- + +## 第 1 步：Coordinator 产出（确认前） + +1. 产品文档 → `docs/PRD-.md` 等（Coordinator R/W）。 +2. 任务板 → `docs/ack/tasks.yaml`，每条任务带 `expected` + `verification`，验收写成可观测信号（见 `optimization-method.md` §1）。 +3. 校验结构： + +```bash +python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml +``` + +4. **停下来给人确认**——这是强模型该花时间的地方，不要跳过。 + +--- + +## 第 2 步：决定 worktree + +见 `closed-loop.md` §「子任务放哪」： + +- 需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。 +- 小改动 / 串行修复 → 当前 worktree 起子 agent。 + +--- + +## 第 3 步：起 worker（模型固定 auto） + +```bash +orca terminal create --worktree active --command "cursor-agent --model auto" --title "DEV" --json +orca terminal create --worktree active --command "cursor-agent --model auto" --title "TEST" --json +``` + +新 worktree 时先 `orca worktree create --name --base-branch `，再在其中起终端。选型与升级见 `model-routing.md`。 + +--- + +## 第 4 步：跑闭环（每个任务） + +```text +task-create → dispatch 给 DEV → 等 worker_done + → 回写 fixed_by_dev → dispatch 给 TEST 复测 → 等 retest_result + → Coordinator 读证据终检 → 过则 verified，不过则 failed_retest 再派 DEV（最多累计 3 轮） + → 三轮失败：leftover，升级复盘，继续下一个 +``` + +具体命令见 `orca-adapter.md`（Orca）或 `closed-loop.md` §「手动模式」（无 Orca）；派发文案见 `prompt-templates.md`。 + +--- + +## 第 5 步：收尾 + +一轮结束时 Coordinator 必须能回答 `optimization-method.md` §「结束条件」的问题：哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。 + +--- + +## 一句话 + +产品文档 + 验收信号写在前（你，强模型）→ DEV/TEST 用 `--model auto` 起 worker → dispatch / 复测 / 终检循环 → 结论只落 `tasks.yaml`。 diff --git a/kits/ack/core/prompt-templates.md b/kits/ack/core/prompt-templates.md index afe6cdb..337277f 100644 --- a/kits/ack/core/prompt-templates.md +++ b/kits/ack/core/prompt-templates.md @@ -4,6 +4,20 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发 角色分工见 `roles-and-permissions.md`；闭环顺序见 `closed-loop.md`。 +派发时除了具体任务，Coordinator 应把对应角色的**能力要求**一并带上（`roles-and-permissions.md` §「三角色能力清单」的 Must Do / Must Not）。下面模板已内置关键条目，复制即可。 + +--- + +## 0. 可选 skills 路由（装了才用，不阻塞） + +如果 worker 所在环境已安装以下 skill，可在对应环节调用以获得更强 playbook；未安装则按 `roles-and-permissions.md` 的能力清单执行： + +- Coordinator 规划复杂需求：`/think` 或 `superpowers:brainstorming` / `writing-plans`。 +- Developer 排查缺陷：`/hunt` 或 `superpowers:systematic-debugging`；行为变更：`superpowers:test-driven-development`。 +- Test 复测 / 合并前检查：`/check` 或 `superpowers:verification-before-completion`。 + +派发时可加一行：「若已安装 ，本环节可用它；未安装按 ack 角色能力清单执行。」 + --- ## 1. 初始派发给 Developer @@ -27,12 +41,18 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发 2. 3. +能力要求（见 roles-and-permissions.md §三角色能力清单 · Developer）： +- 动手前先复现失败现象，或先写一个会失败的测试再修。 +- bug 修复配可复现的失败用例；行为变更配单元测试。 +- 完成前亲自走一遍验收路径，不只满足静态文案。 +- 若是网站 / 常驻服务，改完重启服务并确认生效，别让 Test 测到旧进程或旧构建。 + 约束： - 只修改 Developer 可写路径（见覆盖层文件的权限表）。 - 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。 - 不要写 tasks.yaml，不要标记 verified。 - 不要提交或推送，除非用户明确要求。 -- 最小 diff，避免无关重构。 +- 最小 diff，只改本任务根因，避免无关重构；若必须先重构请停下说明并请示。 完成前必须运行： - @@ -86,8 +106,9 @@ Developer 本轮声称（仅供参考，不作数）： - 改动文件： - 自测命令： -复测要求： -- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md）。 +复测要求（见 roles-and-permissions.md §三角色能力清单 · Test）： +- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md），避免测错实例或旧构建；网站类先确认服务已按新代码重启。 +- 网站类任务优先用浏览器复测真实交互，其次才是 API / 脚本。 - 逐条验证下列验收信号，不要只看静态文案，要验证交互后的真实状态： 1. 2. diff --git a/kits/ack/core/roles-and-permissions.md b/kits/ack/core/roles-and-permissions.md index 2ad8254..5ec088b 100644 --- a/kits/ack/core/roles-and-permissions.md +++ b/kits/ack/core/roles-and-permissions.md @@ -23,6 +23,57 @@ --- +## 三角色能力清单（SSOT） + +上面的表定义了**边界**（谁能碰什么），这一节定义**能力**（每个角色到底该怎么做好自己的事）。每个角色用同一骨架描述：`Outcome`（产出什么）/ `Must Do`（必须做）/ `Must Not`（不能做）/ `Evidence`（拿什么证明）/ `Output`（交付格式）。派发 prompt 会引用这里，见 `prompt-templates.md`。 + +这些是**通用工程习惯**，不含项目命令与路径；项目差异写在覆盖层文件（默认 `docs/ack/project.md`）。装了外部 skill 的环境可按每个角色末尾的「可选 skills」加速，未装则照本清单执行，不阻塞。 + +### Coordinator (PM) —— 拆解与终检 + +- **Outcome**：把一句话需求变成可执行、验收可观测的任务集，并跑完闭环得到明确结论（verified / leftover）。 +- **Must Do** + - 先澄清意图再动手：目标、成功标准、约束、明确「不做什么」。歧义有多解或多来源冲突时，先问清再拆。 + - 每个任务写**可观测验收信号**（可见文本 / API 结果 / 交互结果，见 `optimization-method.md` §1），而不是「功能正常」。 + - 拆任务时点明最脆弱的假设：「本任务假设 X，若 X 不成立则 Y」；列出被否掉的方案与原因。 + - 拆分/验收先给用户确认，再派发（`kickoff.md` 第 1 步的停顿点）。 + - 一次派发只针对一个明确问题（`optimization-method.md` §6）；每任务最多三轮。 + - 终检：读 Test 证据，逐条对齐原始意图后才落 `verified`，不亲自复测。 +- **Must Not**：改源码、亲自跑测试、凭 `worker_done` 直接标 `verified`、把多个无关失败塞进一次派发。 +- **Evidence**：产品文档、`tasks.yaml` 里的 `expected` + `verification`、Test 回传的复测证据。 +- **Output**：确认前给「产品文档 + 任务拆分 + 验收信号」；闭环结束给最终报告（`prompt-templates.md` §6）。 +- **可选 skills**：复杂需求可先用 `/think` 或 `superpowers:brainstorming` / `writing-plans` 收敛设计与计划。 + +### Developer —— 实现与白盒验证 + +- **Outcome**：在授权路径内做出满足验收信号的最小改动，并用白盒证据证明它可复现。 +- **Must Do** + - 动手前先读覆盖层文件、`tasks.yaml` 对应任务、相关规格；复现失败现象或先写会失败的测试。 + - 最小 diff，只改一个明确问题的根因，不顺手重构无关代码。 + - 行为变更配单元测试；bug 修复先有一个能复现的失败用例再修。 + - 完成前跑覆盖层里规定的命令（构建 / 单测 / 本地运行），亲自走一遍验收路径。 + - **网站 / 常驻服务**：改完重启服务（或触发热更并确认生效），保证运行实例跑的是新代码，避免 Test 测到旧进程 / 旧构建。 +- **Must Not**：改产品规格与集成测试、写 `tasks.yaml`、标 `verified`、绕过测试声称完成、把 bug 修复扩成大重构（需要就先停下说明并请示）。 +- **Evidence**：改了哪些文件、跑了哪些命令及结果、如何复现验收路径、残留风险。 +- **Output**：一次 `worker_done`，字段见 `prompt-templates.md` §4（只报证据，不下最终结论）。 +- **可选 skills**：排查用 `/hunt` 或 `superpowers:systematic-debugging`（先根因后修）；实现行为变更用 `superpowers:test-driven-development`。 + +### Test —— 独立黑盒复测 + +- **Outcome**：以独立视角复现验收路径，逐条给出通过/失败的可观测证据，供 Coordinator 终检。 +- **Must Do** + - 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 `closed-loop.md`），避免测错实例或旧构建；网站类先确认服务已按新代码重启。 + - 逐条验证验收信号，验证交互后的真实状态，而不是只看静态文案。 + - **网站类任务优先用浏览器复测**真实交互（点击 / 跳转 / 渲染），其次才是 API / 脚本；纯后端 / CLI 则以 API smoke 或脚本为主。 + - 把最容易反复误判的路径沉淀成可执行测试（`optimization-method.md` §8）。 + - 只回传证据 + 逐条结论，最终判定留给 Coordinator。 +- **Must Not**：改应用源码、改产品规格、写 `tasks.yaml`、凭 Developer 的 `worker_done` 直接下结论。 +- **Evidence**：运行环境快照、命令结果、每条信号 pass/fail + 证据（snapshot / DOM / API 结果）。 +- **Output**：一次复测报告，字段见 `prompt-templates.md` §5。 +- **可选 skills**：合并 / 发版前检查可用 `/check` 或 `superpowers:verification-before-completion`（证据先于结论）。 + +--- + ## 路径权限模板 目标项目在自己的**覆盖层文件**中填入实际路径（模板见 `templates/project.template.md`；覆盖层默认 `docs/ack/project.md`，路径记在 `tasks.yaml` 的 `project.overlayFile`）。 diff --git a/kits/ack/examples/project.example.md b/kits/ack/examples/project.example.md index 93c59ef..222b45f 100644 --- a/kits/ack/examples/project.example.md +++ b/kits/ack/examples/project.example.md @@ -1,6 +1,6 @@ # notes-web Agent 协作协议（示例，项目覆盖层） -> 本项目基于 ack v0.6.0。 +> 本项目基于 ack v0.8.0。 > 稳定规范引用 `docs/ack/kit/core/`，本文件只填项目差异。 > 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。 > 目录下只有一个软链接 `kit/` + `project.md` + `tasks.yaml`。 @@ -16,6 +16,7 @@ ## 稳定规范（引用，不重复） +- 开始一个需求（启动手册）：`docs/ack/kit/core/kickoff.md` - 角色 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md` - 模型档位与升级规则：`docs/ack/kit/core/model-routing.md` - 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md` diff --git a/kits/ack/templates/project.template.md b/kits/ack/templates/project.template.md index c2836a0..0144bb5 100644 --- a/kits/ack/templates/project.template.md +++ b/kits/ack/templates/project.template.md @@ -21,6 +21,7 @@ ## 稳定规范（不在此重复，直接引用） +- 开始一个需求（启动手册）：`docs/ack/kit/core/kickoff.md` - 角色模型 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md` - 模型档位与升级规则：`docs/ack/kit/core/model-routing.md` - 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`