feat: modify ack
This commit is contained in:
@@ -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 <此框架绝对路径> <project>/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 <feature> --base-branch <base> --json`（选择依据见 `core/closed-loop.md`）。
|
||||
|
||||
### 派发与等待（Orca）
|
||||
|
||||
```bash
|
||||
orca orchestration task-create --spec "<任务与验收>" --json
|
||||
orca orchestration dispatch --task <task_id> --to <dev_handle> --json
|
||||
orca orchestration check --terminal <coordinator_handle> --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
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
0.6.2
|
||||
0.8.0
|
||||
|
||||
@@ -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-<feature>.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 <feature> --base-branch <base>`，再在其中起终端。选型与升级见 `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`。
|
||||
@@ -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`。
|
||||
|
||||
派发时可加一行：「若已安装 <skill>，本环节可用它；未安装按 ack 角色能力清单执行。」
|
||||
|
||||
---
|
||||
|
||||
## 1. 初始派发给 Developer
|
||||
@@ -27,12 +41,18 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
|
||||
2. <expected behavior 2>
|
||||
3. <expected behavior 3>
|
||||
|
||||
能力要求（见 roles-and-permissions.md §三角色能力清单 · Developer）：
|
||||
- 动手前先复现失败现象，或先写一个会失败的测试再修。
|
||||
- bug 修复配可复现的失败用例；行为变更配单元测试。
|
||||
- 完成前亲自走一遍验收路径，不只满足静态文案。
|
||||
- 若是网站 / 常驻服务，改完重启服务并确认生效，别让 Test 测到旧进程或旧构建。
|
||||
|
||||
约束：
|
||||
- 只修改 Developer 可写路径（见覆盖层文件的权限表）。
|
||||
- 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。
|
||||
- 不要写 tasks.yaml，不要标记 verified。
|
||||
- 不要提交或推送，除非用户明确要求。
|
||||
- 最小 diff，避免无关重构。
|
||||
- 最小 diff，只改本任务根因，避免无关重构；若必须先重构请停下说明并请示。
|
||||
|
||||
完成前必须运行：
|
||||
- <test command 1>
|
||||
@@ -86,8 +106,9 @@ Developer 本轮声称（仅供参考，不作数）：
|
||||
- 改动文件：<files>
|
||||
- 自测命令：<commands>
|
||||
|
||||
复测要求：
|
||||
- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md）。
|
||||
复测要求（见 roles-and-permissions.md §三角色能力清单 · Test）：
|
||||
- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
|
||||
- 网站类任务优先用浏览器复测真实交互，其次才是 API / 脚本。
|
||||
- 逐条验证下列验收信号，不要只看静态文案，要验证交互后的真实状态：
|
||||
1. <observable signal 1>
|
||||
2. <observable signal 2>
|
||||
|
||||
@@ -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`）。
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user