Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions plugins/waypoint/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

## [Unreleased]

### Fixed

- `project-navigator`: a criterion you verified by hand is no longer reported as unverified. Once you confirm the result, the orchestrator records the verdict as "用户已确认" (confirmed by the user), which counts as a pass, so you are not asked to "accept as is" for something you just checked. Results you already saw before the review, as in interactive slices, are recorded the same way without asking you to repeat them.
- `project-navigator`: manual verification no longer assumes what you have. The account, character, items, and devices a manual check needs are asked when the plan is written, and the executor prepares steps and materials only from what you confirmed.
- `project-navigator`: slices nobody needs are kept out of the roadmap. Before adding a slice the orchestrator answers what breaks without it and whether there is a cheaper way, and recommends the cheapest option; reverse-engineering and measurement slices are scheduled only when their conclusions are needed and cannot be obtained otherwise.
- `project-navigator`: less repetition. The executor's own report is no longer relayed while the review is running, the same steps are written out in full only once, and repeated waiting notices get a one-line reply.
- `project-navigator`: when you interrupt or raise a question after choosing, the orchestrator answers first and does not change state or commit until you confirm again.

## [2.0.1] - 2026-11-13

### Fixed
Expand Down
2 changes: 1 addition & 1 deletion plugins/waypoint/agents/navigator-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ model: sonnet
- 只运行这几类命令: 只读 git 命令 (例如 `git diff`, `git log`, `git show`, `git status`), 委派提示词 "验证方式" 中的命令, 以及切片文件 "自测记录" 中的命令. 需要真实账号, 会产生费用或外部副作用的命令不运行. 不安装依赖, 不改动项目.
- 委派提示词写明不构建, 不运行程序时, 不构建, 不运行; 只读代码与记录, 靠运行才能确认的标准写 "未验证".
- 调用 MCP 取证工具时只做查询类的只读调用, 调用前先用 ToolSearch 加载; 不发请求, 不清空或修改工具中的记录.
- 结论只用委派提示词列出的三种, 不自造 "部分通过" 之类的说法. 找不到证据时写 "未验证", 并写明缺少什么; 不凭推测写 "通过".
- 结论只用委派提示词列出的三种, 不自造 "部分通过" 之类的说法. 找不到证据时写 "未验证", 并写明缺少什么; 不凭推测写 "通过". "用户已确认" 由编排会话在用户确认之后写入, 你不使用.
- 接线要自己追: 从程序的真实入口读代码, 一步一步走到新代码, 不照抄实现方写的路径.

## 交回
Expand Down
50 changes: 27 additions & 23 deletions plugins/waypoint/docs/project-navigator-maintaining.en.md

Large diffs are not rendered by default.

12 changes: 8 additions & 4 deletions plugins/waypoint/docs/project-navigator-maintaining.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,14 +71,16 @@

- **工作单位是切片, 一个切片一份文件, 分三段.** 计划由编排会话写, 执行结果由实现方写, 验收由编排会话按验收子代理交回的内容写. 1.x 是三份文件, 各有固定结构, 读不出来流程就停. 改掉的后果: 回到三件套.
- **段的归属靠计划段的摘要保证.** 守卫只能按路径判断, 管不到文件里的段. `slice start` 记下计划段的摘要, `slice review` 比对, 不一致时拒绝送验; 是编排会话按用户的回答改的, 运行 `slice replan`. 摘要先去掉行首尾空白, 合并空白, 统一表格分隔行: 格式化 hook 重排表格时摘要不变. 这只能发现, 不能阻止; 实测中如果经常发生, 退路是把计划与执行结果分成两个文件.
- **脚本只读它需要的内容.** 完成标准 (编号列表), 需要决定与补做是否为 "无", 执行状态, 标准核对表 (结论只能取三种, 每行要有证据). 其余只检查 "不为空, 没有占位". 写入时不校验结构. 改掉的后果: 结构规则越多, 被拦下的次数越多.
- **脚本只读它需要的内容.** 完成标准 (编号列表), 需要决定与补做是否为 "无", 执行状态, 标准核对表 (结论只能取规格中的四种, 每行要有证据). 其余只检查 "不为空, 没有占位". 写入时不校验结构. 改掉的后果: 结构规则越多, 被拦下的次数越多.
- **默认只在验收之后请用户决定一次.** 计划的 "需要决定" 不是 "无" 时, `slice start` 拒绝, 用户回答后带 `--decided`. 1.x 每张工单固定两次 (审阅与验收), 而多数审阅用户只是点同意. 发布前核对也去掉了: 编排会话本来就能读代码, 写计划前自己读. 改掉的后果: 每个切片多一次没有信息量的确认.
- **硬约束与工作假设分两层.** 硬约束是目标, 完成标准, 明确不做, 模块安排; 其余是工作假设, 与实际不符时实现方取得证据后按实际做, 记进 "修正" 表, 由验收核对. 1.4.0 及之前把计划当合同, 细节不符就是一轮往返. 改掉的后果: 探索性的任务每发现一个细节就多一轮.
- **骨架是硬规则.** 第一个里程的第一个切片由脚本标为骨架, 种类必须是 `build`; 骨架通过之前 `slice plan` 拒绝其它切片; 骨架不能放弃. 改掉的后果: 回到 "先把各层横着写完, 最后发现接不上".
- **接线是验收的固定项.** 实现方在 "接线证据" 写出从入口到新代码的调用路径, 验收子代理自己再追一遍. 追不到时相关标准判不通过, 而不通过的切片只能补做或放弃, 所以没有接线的切片进不了下一个. 这条靠验收提示词与 `slice accept` 的拒绝共同保证, 脚本本身不判断接线.
- **同一时间只做一个切片.** `current` 只有一个位置. 改掉的后果: 基准提交与验收范围不再确定.
- **补做在同一份文件里进行.** `slice redo` 把执行状态改成 "补做中", 把现有的验收段标题加上轮次, 在文末追加一段空的验收段; 解析时同名的段取最后一个. 改掉的后果: 每轮一个文件, 或丢掉上一轮的验收记录.
- **未验证的标准可以由用户明确接受** (`slice accept --accept-unverified`). 验证方式为 `manual` 或 `measured` 的项目, 靠运行才能确认的标准都会是未验证, 由用户亲手确认后接受. 不通过的标准不能接受.
- **用户亲手验过的标准记为 "用户已确认", 与通过同样对待.** 验收子代理看不到用户的屏幕, 靠运行才能确认的标准它只能判未验证. 2.0.1 及之前, 这类标准只能走 "接受现状" (`slice accept --accept-unverified`): 用户在游戏里看过效果并说了没问题, 回复里仍然写 "3 条未验证", 还要他再选一次. 现在编排会话在用户确认后把结论改成 "用户已确认" (规格 `verdicts.confirmed`), 证据写用户的原话, `slice accept` 不需要参数. 用户在送验之前已经看过的结果 (交互式切片常见), 验收子代理的证据以 "用户实测: " 开头 (规格 `userEvidencePrefix`), 编排会话直接改, 不让用户再做一遍. "接受现状" 只留给用户决定不验证的情况; 不通过的标准不能接受. 脚本不核对 "用户已确认" 是否属实, 这一条只靠规则. 改掉的后果: 用户做完验证还被告知 "未验证".
- **人工验证的前提在计划里问清楚.** 有完成标准要用户亲手验证时, 用到的账号, 角色, 物品, 设备写进计划的 "需要决定", 开工前问用户; 实现子代理只用确认过的前提准备步骤与材料. 实测中出现过: 实现子代理做好了要某件装扮才能测的补丁, 用户没有这件, 之后来回半小时找替代品. 改掉的后果: 步骤写得再清楚, 用户也做不了.
- **新增切片之前先问 "不做会怎样" 与 "有没有更省事的办法".** 规则在 `references/intake.md` 的 "新增切片之前", 里程复查与需求变更引用它; 提问时推荐最省事的办法. 实测中出现过: 用户随口提到一个现象, 编排会话排了一个逆向切片加一个接入切片, 把逆向标为推荐, 用户配合截了四张图之后才发现让使用者自己选就够了. 改掉的后果: 路线里混进没人需要的切片, 而且每个都要用户配合.
- **提交不是状态.** `slice accept` 之后编排会话按输出调用 commit-message, 状态文件随这次提交入库.

### 模块化约束
Expand All @@ -103,6 +105,8 @@
- **要用户决定时, 问题与选项紧跟在第一段之后, 选项放在代码块里.** 2.0.0 的规则只有 "第一行结论, 第二行进展, 末尾列选项", 实际会话中出现了: 问题埋在长篇背景之后; 相邻的 "A. B. C." 三行被 Markdown 合并成一段; 进展行与第一行粘在一起; 立项时把全部疑点一次列给用户. 代码块中的换行不会被合并, 所以选项固定用代码块. 改掉的后果: 用户读完整条回复才知道要回答什么.
- **有提问框工具时必须用它, 但不依赖它.** 桌面应用在回合结束时提供提问框 (`wrap_up`), 终端里没有. 规则写成 "有这类工具时每次都用, 内容用简体中文, 按钮与代码块的选项对应", 代码块始终保留, 两种环境下回复都完整. 改掉的后果: 只写代码块时桌面应用里没有按钮可点; 只靠提问框时终端里看不到选项.
- **进展写在回复末尾, 有变化时才写.** 放在第二行时, 它每条回复都占着最显眼的位置, 而内容多数时候没有变化.
- **同一段内容只完整写一次; 送验时不转述实现方的自述.** 实测中, 送验时先复述一遍实现方报告的结果, 验收回来再报一遍, 同一批操作步骤整段发了两次.
- **用户打断或在选择之后提出疑问时, 先回答, 重新确认之前不改状态, 不提交.** 实测中, 用户选了 "接受并提交" 后立刻打断并提出疑问, 编排会话一边回答一边照样提交了.

### 安装

Expand Down Expand Up @@ -163,7 +167,7 @@
| 实现子代理结束了, `status` 仍说等待 | 它没有把 "执行状态" 改成 "完成", 或写到了别的小节 | `lib/slice-file.mjs`, `lib/guidance.mjs` | 看切片文件 "执行结果" 段; 用 SendMessage 请它补写 |
| `slice review` 说计划段被改动 | 开工后计划段的内容变了: 编排会话按用户的回答改了, 或实现子代理误改 | `lib/slice-file.mjs` 的 `digestPlan` | `git diff` 看切片文件; 前者运行 `slice replan` |
| 验收段已写, `status` 仍说等待验收 | 标准核对表还有占位, 或不是合法的表格 | `lib/slice-file.mjs` 的 `readVerdicts` | 表头下要有分隔行, 每行三格 |
| `slice accept` 被拒 | 验收段有小节没填; 结论不是三种之一; 行数少于完成标准; 有不通过; 有未验证而没带参数 | `commands/slice.mjs` | 错误信息逐条写明 |
| `slice accept` 被拒 | 验收段有小节没填; 结论不是四种之一; 行数少于完成标准; 有不通过; 有未验证而没带参数 | `commands/slice.mjs` | 错误信息逐条写明 |
| `slice plan` 被拒, 提到最小骨架 | 骨架切片还没有通过验收 | `lib/slice-flow.mjs` | `roadmap.md` 中带 "最小骨架" 的那一行 |
| `roadmap` 被拒, 提到缺少已经开始的切片 | 草稿没有带上已有切片的 `id` | `lib/roadmap.mjs` | 对照 `roadmap.md` 把已有条目带上 `id` |
| 筛选器检查漏报或误报 | 工程文件用了通配符, 宏, 或正则没有覆盖的写法 | `lib/filters.mjs` | 输出中的 "没有检查" 项数; 用最小的工程文件复现 |
Expand Down Expand Up @@ -288,7 +292,7 @@
5. 计划的 "工作假设" 故意写错一个细节: 实现子代理不交回, 按实际做完, "修正" 表有一行; 验收的 "修正核对" 写出这项修正.
6. 实现子代理尝试改计划段: `slice review` 拒绝送验.
7. 故意不把新代码接到入口上: 验收的接线核对指出来, 相关标准不通过; 补做后通过.
8. 验证方式为 `manual` 的项目: 验收子代理不构建, 不运行, 靠运行才能确认的标准判为未验证并写出步骤; 用户确认后接受现状.
8. 验证方式为 `manual` 的项目: 验收子代理不构建, 不运行, 靠运行才能确认的标准判为未验证并写出步骤; 用户确认后编排会话把结论改成 "用户已确认", 不带参数通过.
9. Visual Studio 项目中新增一个没有归入筛选器的源文件: 验收提示词的筛选器检查指出来.
10. 交互式切片: 不派实现子代理, 编排会话直接做, 结论写进 `.navigator/findings/`; 新开会话调用技能能接着做; 编排会话写业务文件仍被拒.
11. 验收子代理尝试写文件时被拒.
Expand Down
5 changes: 3 additions & 2 deletions plugins/waypoint/docs/project-navigator.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,11 +151,12 @@ project-navigator check --filters
5. **Corrections and pending criteria.** When a detail in the plan does not match reality, the executor subagent gathers evidence, works to what is actually there, and records each case in the "修正" (corrections) table, without stopping to ask you. When an individual completion criterion cannot be met as a matter of fact, it finishes the rest and lists the criterion under "待定标准" (pending criteria). You see both in one go at review time.
6. **Submit for review.** The script checks that the Plan part was not changed during implementation and that the Result part is filled in.
7. **Review.** The reviewer subagent checks item by item in a fresh context. There are only three verdicts: pass, fail, and unverified, and each comes with evidence. It traces the wiring from the entry point itself and does not copy the path the executor wrote.
8. **Your decision.**
8. **What you verify by hand.** A criterion that can only be confirmed by looking at the running program is judged unverified by the reviewer, with the steps written out. The account, character, items, and devices those steps need are asked when the plan is written. Once you have checked and said what you saw, the criterion is recorded as "用户已确认" (confirmed by the user) and treated like a pass, and you are not asked to choose again; the same goes for results you already saw before the review.
9. **Your decision.**

| Situation | You can choose |
| -------------------------- | -------------------------------------------------------------- |
| All pass | Pass and commit; pass, commit, and push |
| All pass or confirmed | Pass and commit; pass, commit, and push |
| Some unverified, none fail | Accept as is and commit; rework |
| Some fail | Rework; abandon this slice (the skeleton can only be reworked) |

Expand Down
5 changes: 3 additions & 2 deletions plugins/waypoint/docs/project-navigator.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,11 +151,12 @@ project-navigator check --filters
5. **修正与待定.** 计划中的细节与实际不符时, 实现子代理取得证据后按实际做, 逐条记进 "修正" 表, 不停下来问你. 个别完成标准按事实做不到时, 做完其余部分, 列为 "待定标准". 两者都在验收时由你一次看完.
6. **送验.** 脚本核对计划段在实现期间没有被改动, 执行结果已填好.
7. **验收.** 验收子代理在全新上下文中逐条核对, 结论只有通过, 不通过, 未验证三种, 每条都附证据. 它自己从入口追一遍接线, 不照抄实现方写的路径.
8. **你的决定.**
8. **你亲手验证的部分.** 要你进程序看效果才能确认的标准, 验收子代理只能判未验证, 并写出步骤. 步骤要用到的账号, 角色, 物品, 设备, 在写计划时就会先问你. 你验完并说了结果, 这条就记为 "用户已确认", 与通过同样对待, 不需要你再选一次; 你在送验之前已经看过的结果也一样.
9. **你的决定.**

| 情况 | 你可以选 |
| -------------------- | --------------------------------- |
| 全部通过 | 通过并提交; 通过, 提交并推送 |
| 全部通过或你已确认 | 通过并提交; 通过, 提交并推送 |
| 有未验证, 没有不通过 | 接受现状并提交; 补做 |
| 有不通过 | 补做; 放弃这个切片 (骨架只能补做) |

Expand Down
6 changes: 5 additions & 1 deletion plugins/waypoint/skills/project-navigator/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ allowed-tools: Bash(node *) PowerShell(node *) Bash(project-navigator *) PowerSh

| 种类 | 何时用 | 版式 |
| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 等待 | 子代理在后台, 用户不用做事 | 一两句话: 在等什么, 结果回来后做什么. 不复述计划, 也不复述子代理的报告 |
| 等待 | 子代理在后台, 用户不用做事 | 一两句话: 在等什么, 结果回来后做什么. 不复述计划与子代理的报告; 情况没变时再次等待只回一句 |
| 报告 | 做完了一件事, 不需要用户决定 | 第一段一句结论; 然后是不超过 5 条的要点. 细节留在文件里, 给出文件路径 |
| 要用户决定或操作 | 需要用户选择, 回答或亲手做一件事 | 第一段一句话: 结果, 以及要用户做什么; 紧接着是选项代码块或编号的操作步骤; 之后才是理由与背景, 能少则少 |

Expand All @@ -56,13 +56,17 @@ C. 一开始就支持多人

- 一次只问一件事. 其它待定的事不提前列给用户, 轮到时再问.
- 每个选项一行, 以字母开头; 有推荐时把它排在 A 并标 "(推荐)". 选择之后会发生什么, 用半句话写在同一行.
- 推荐能达到目的的办法中最省事的一个. 要多排切片, 逆向或实测的办法, 只在没有更省事的办法时才推荐.
- 用户看完第一段与代码块就应当能作答. 放在代码块之前的内容只有第一段.
- 会话中有回合结束时的提问框工具时 (例如桌面应用的 `wrap_up`), 每次要用户决定或操作都调用它: 内容用简体中文, 按钮与代码块中的选项对应; 按钮数不够时放推荐项与最可能被选的另一项. 提问框已经显示问题句时, 正文不再重复问一遍, 代码块照常保留. 没有这类工具时只用代码块.

其它规则:

- 进展有变化时, 在回复末尾单独一段写 "当前进展: ...", 照抄 `status` 的 "当前进展". 没有变化时不写.
- 标题, 表格与加粗只在内容确实有这种结构时用; 一条回复只有一个需要用户回应的地方.
- 同一段内容 (操作步骤, 结果, 清单) 只完整写一次, 之后只写有变化的部分.
- 要用户亲手做的事, 先确认他做得到再给步骤: 不清楚他有没有某件东西时先问, 不先准备好再发现用不上.
- 用户打断, 或作出选择之后又提出疑问时, 先回答疑问; 重新得到确认之前, 不运行改变状态的命令, 不提交.
- 工具调用之间的过渡句也用简体中文, 不超过一句.
- 不贴代码. 用简体中文与英文 (ASCII) 标点, 每个标点后加一个空格. 写朴素的话, 不自造简称.

Expand Down
Loading
Loading