pstack 验证技能维护实战:用 Source Wave 与单次实机通过让 Feature Map 永不失真
pstack 验证技能维护实战:用 Source Wave 与单次实机通过让 Feature Map 永不失真
导读
应用代码一变,验证技能的 feature map(功能地图)就会开始腐烂。本文讲解 pstack 插件中的 /maintain-verification-skill 技能:一套以"功能"为严谨度单位的周期性维护循环——先对每个功能文件并发派出只读源码审读子代理,再以单个长生命周期会话实机驱动全部功能,最终至多产出一个包含被证明修正的 PR。读完本文,你将掌握如何在应用演进中持续保持验证技能与功能地图诚实可信,理解 doc drift / harness gap / product gap 三类问题的处置边界,以及 Live pass 阶段必须坚守的三条不变量。
为什么功能地图必然会腐烂
pstack 的作者在 create-verification-skill 中定义了一套验证技能生成流程:它访谈仓库而非访谈用户,产出 .cursor/skills/verify-<app>/ 下的项目本地技能,包含 Launch / Doctor / Drive / Evidence / Cleanup / Helpers 六个固定章节,并在 features/ 下播种一张以用户视角描述功能的功能地图。
但生成只是起点。maintain-verification-skill 的 SKILL.md 开篇即点明核心矛盾:
"A feature map rots the moment the app changes."(功能地图在应用改变的瞬间就开始腐烂。)
这张地图是"仓库维护中的验证权威来源"(maintained verification source),它依赖人工或代理持续校正。本技能就是这张地图的养护循环,其服务对象是 /create-verification-skill 生成的技能,或任何带有功能地图的项目本地验证技能。
两个需要先明确的元规则:
- 严谨度的单位是"功能",不是"每个句子":维护循环要求从源码覆盖每一个功能文件、实机演练每一个功能,但不需要把地图里的每一条 bullet 都做成一次实机验证(without terminalising every bullet)。这是为了在"覆盖充分"与"维护成本可控"之间取得平衡。
- 这是周期性维护,而非一次性修复:技能 frontmatter 中
disable-model-invocation: true,即只能通过/maintain-verification-skill或"audit the verify skill"之类的显式指令触发,不会在模型日常任务中被自动唤起。
三个终点结果:先选一个,并明确说出
每次维护运行必须选定且声明一个终点结果(Outcomes):
| 结果 | 含义 | 交付物 |
|---|---|---|
| clean | 每个功能都获得了源码覆盖与实机覆盖;没有值得交付的修正 | 不开分支、不开 PR |
| changed | 一个 PR 交付被证明的文档、harness 或地图修正 | 恰好一个 PR |
| blocked | 覆盖无法完成,或一个已被证明的修正无法安全交付 | 无 PR,必须精确说明是什么阻塞了 |
选择哪个结果不是自由发挥,而是对整个运行"覆盖是否完整、修正是否被证明"的诚实裁决。blocked 的结果比伪造的 clean 更有价值——它保留了后续修复所需的事实基础。
编辑范围:验证技能的目录是唯一的可写区域
维护循环的边界纪律极其严格:
只编辑验证技能自己的目录(它的 SKILL.md、
features/,以及它拥有的任何 harness 脚本)。运行期间绝不编辑产品代码。
这意味着:如果地图描述的行为应用已经不再具备,只有两种可能性:
- 文档漂移(doc drift)——修地图;
- 产品回归(product regression)——报告它,而不是在文档里用粉饰掩盖它。
这一条与 pstack 的 prove-it-works 原则("验证真实工件,而非代理、自报或'它能编译'")一脉相承:维护验证技能本身也必须被验证,而验证的边界就是技能目录。
七步维护循环详解
整个 Pass 流程共七步(编号 0–6),从定位目标到交付或停止,每一步都有明确的输入输出。
步骤 0:定位目标
找到要维护的验证技能:项目本地、正文包含 launch/drive 章节和功能地图的技能,通常位于 .cursor/skills/verify-*/。
- 多个候选者 → 询问用户选择哪一个;
- 没有候选者 → 停下,指向
/create-verification-skill先生成一个,而不是凭空发明一个维护目标。
这一步保证了维护循环永远作用于真实存在的技能,避免为不存在的目标白跑一遍流程。
步骤 1:索引卫生(Index hygiene)
读取功能地图的 README,并 glob 其同级文件,修正地图索引中的四类问题:缺失、多余、重复、死条目(missing, extra, duplicate, dead entries)。
这是全程最轻量的一步:不做生成式清点(no generated inventory),只做肉眼可确认的索引一致性检查。参考仓库中的地图示例 feature-map-example/README.md,地图索引就是"Features"列表下指向各功能文件的链接清单——列表与实际文件不匹配,就是典型的索引卫生问题。
步骤 2:源码波次(Source wave)
每个功能文件派出一个只读子代理,全部并发启动。每个子代理只回答一个问题:
"这个面向用户的功能是怎么工作的?"
子代理的输出要求:
- 从源码解释功能的用户视角工作原理;
- 标注疑似文档漂移,并给出引用(citations);
- 返回一条简洁的实机验证配方(live-verification recipe)。
子代理的硬性约束是:永远不驱动应用,永远不编辑文件。返回形状固定为四元组:功能摘要 / 源码入口点 / 疑似漂移(或 none)/ 一条配方。
这与 pstack 的 guard-the-context-window 原则(把批量工作路由给子代理、主线程只保留摘要)一致:N 个只读审读器并行,主协调者只汇总四个字段,而不是吞下全部源码。
步骤 3:对账(Reconcile)
- 确认每个功能文件都有返回的摘要;
- 把重叠的配方合并为尽量少的应用状态(as few app states as practical);
- 抽查被引用的漂移,但不重新证明看起来干净的主张(spot-check cited drift; don't re-prove clean claims);
- 扫描近期变更(recent churn)中遗漏的地图功能面——但判定"某功能缺失"必须给出具体的源码路径,不能凭印象。
对账阶段体现了成本纪律:维护循环不为"看起来没问题"的部分重复做功,把实机预算留给真正有疑点的区域。
步骤 4:实机通过(Live pass)——全程最关键的一步
即使源码看起来完全干净,实机通过也强制执行(Required even when source looks clean)。这是本技能与纯静态审查的本质区别:地图记录的是用户可观察行为,只有真的驱动应用一次才能证明。
协调者(coordinator)拥有全部驱动权(The coordinator owns all driving),并遵循验证技能自身的 Launch 模型——由被维护技能的 Launch 章节决定,而非本技能越俎代庖:
- 服务器与 UI:使用一个长生命周期实例,串行驱动(one long-lived instance driven serially);
- 短生命周期 CLI:每次驱动使用全新的隔离会话(a fresh isolated session per drive)。
生成阶段(create-verification-skill 的 Launch/Doctor 章节)已经为这两种模型写好了启动命令、就绪判定与拆除方式,维护循环直接复用即可。
全过程中必须坚守三条不变量(无论失败与否):
- 绝不在"自上次意外行为后未做健康检查"的实例上驱动——
doctor纪律:- 首次驱动前必须 doctor;
- 以会话为单位的场景中,每个新会话都要 doctor;
- 任何一次驱动失败后要再次 doctor;
- 当 doctor 无法看到失败(进程健康但 UI 状态卡死,a wedged UI state on a healthy process)时,重置到已知状态或重新启动,而不是心存侥幸继续驱动。
- 已捕获的证据必须经受住每一次清理——证据要在其命名位置被检查,而不是默认它还在。这正是生成阶段"Cleanup 后确认证据仍存在"规则(
create-verification-skill步骤 4)的延续:清理吃掉证明 = 本次运行失败。 - 驱动启动的任何东西都不应活过该驱动不再有用的时刻——失败迭代的残留物必须清理,无论会话是卡死、退出还是共享;对于共享实例,清理的是残留物,而不是实例本身。
异常路径的处理规则:
- doctor 失败源于技能漂移 → 这就是漂移本身,在编辑范围内修复,然后只重启被该修复失效的东西,仅此一次(retry once),之后仍失败才可判定
blocked。 - 功能无法到达 → 只有在给出具体前置条件(auth、entitlement、OS、外部状态)与尝试过的路径后,才可标记为
verified-unreachable;如果地图漏写了该前置条件,那本身就是漂移。 - triage 中的任何 harness 修复 → 在交付前必须被重新实机驱动(Any harness fix from triage gets re-driven live before it ships)。
- 最终拆除 → 在本次运行最后一次驱动(包括上述重证明)之后进行,确保没有东西活过本次运行——证据除外,证据按技能规定保留。
步骤 5:分类(Triage)
实机通过后,对发现的每个问题按三分法归类:
| 现象 | 归类 | 处置 |
|---|---|---|
| 错误的或缺失的用户视角描述 | doc drift(文档漂移) | 修复地图 |
| 行为正常但 harness 驱动不了 | harness gap(工具缺口) | 修复 harness;harness 修复遵循与生成阶段相同的 helpers 规则——脚本可执行、调用方式写在技能正文里 |
| 应用行为确实坏了 | product gap(产品缺口) | 为用户记录,但排除在本 PR 之外 |
第三类的处置再次呼应编辑范围纪律:产品回归报告给用户,绝不在维护 PR 里用文档修正掩盖它。
步骤 6:交付或停止(Ship or stop)
- changed:交付一个 PR,包含全部被证明的修正;交付前重读每一个被改动的文件。
- clean / blocked:不开 PR,如实报告结果与覆盖情况。
运行笔记(覆盖了哪些功能、不可达的前置条件、确认的漂移、最终结果)保存在 scratch 位置,不提交到仓库。这与 show-me-your-work 的"工作产物默认不提交"一致——运行笔记是过程痕迹,不是交付物。
维护循环在 pstack 验证生态中的位置
/maintain-verification-skill 不是孤立技能,而是验证闭环的第二半:
/create-verification-skill ──► 生成验证技能 + 功能地图
│
▼
/maintain-verification-skill ◄── 应用演进、地图漂移时的养护循环
create-verification-skill 的生成流程本身就为维护循环埋好了伏笔:它的第 5 步明确"把维护循环指向用户"(Offer the maintenance loop)。而在 pstack 官方指南的验证与交付章节(docs/guide/06-verify-and-ship.md)中,维护循环被定位为"让验证技能保持诚实"(Keep the verification skill honest)的日常手段:一个功能一个并行只读源码审读器,随后一次实机通过驱动每一个已映射功能,最后在 clean / changed / blocked 三者中精确收尾,绝不触碰产品代码;若实机发现产品回归,报告回归而非在文档中粉饰。
在 pstack 的技能索引(pstack/README.md 的 skills 表格)中,它与生成技能成对出现:"你的验证技能的功能地图已经从应用漂移了。源码波次 + 一次实机通过,至多一个包含被证明修正的 PR。"——这正是对本技能能力的官方概括。
如何把地图维护做得更好:从示例地图学到的要点
仓库自带的 feature-map-example/ 给出了可参照的"被维护状态"模板,维护循环的许多判断标准都源于此:
- README 定义基线前置条件与驱动约定:如"启动于
http://127.0.0.1:4173并使用一次性数据目录""NOTES_DATA_DIR=/tmp/notes-verify-$RUN_ID使并发运行不共享状态""绝不驱动不是本次验证运行启动的实例"——这些正是 Live pass 不变量 1 的地图侧表达。 - 证明与跳过报告规则:捕获"用户动作 + 结果状态"而非仅最终画面;UI 证明含 ARIA 快照与截图;CLI 证明含命令、stdout、stderr 与退出码;变更证明需"只读的第二视图"确认存储值;不得把某个入口点标记为已验证当它实际走了另一条路径。
- 每个功能文件使用恰好四个固定 H2:
Sub-features/How to get to it (user POV)/Driving it with <harness>(以Preconditions:开头,标签化 bullet 配对"用户动作 + 精确命令 + 可观察结果")/Gotchas。地图中不保留实现细节,只写用户路径、稳定句柄、所需状态、命令与可观察证明(create-note.md、search.md是两个可复制的范本)。 - Gotchas 章节是漂移的高发区:它记录的陷阱(如"文本框聚焦时按
n会输入字符而不是新建笔记""保存时标题被 trim,应断言渲染后的标题而非草稿输入值")一旦应用行为改变,往往是文档漂移的第一现场,正是源码波次与对账阶段要优先抽查的对象。
何时运行、以什么节奏运行
本技能不规定固定节奏——create-verification-skill 明确"只在用户询问时才建议节奏"(Suggest a cadence only if they ask)。合理的触发时机包括:
- 应用发生了用户可见的功能变更(新增功能、改动入口、删除行为);
- 地图中记录的路径无法复现(疑似漂移或回归);
- 大规模重构或迁移之后,作为验收的一环;
- 周期性的诚实审计("audit the verify skill")。
适用前提值得说明:本技能面向已有验证技能与功能地图的项目。如果你的项目还没有脚本化的验证途径,请先运行 /create-verification-skill 生成一个——维护循环不负责从零发明目标。
参考路径速查
- 本技能全文:
pstack/skills/maintain-verification-skill/SKILL.md - 生成配套技能:
pstack/skills/create-verification-skill/SKILL.md - 功能地图示例:
pstack/skills/create-verification-skill/references/feature-map-example/README.md(含create-note.md与search.md两个功能文件范本) - 官方指南中的"保持验证技能诚实"章节:
pstack/docs/guide/06-verify-and-ship.md - 支撑原则——验证真实工件:
pstack/skills/principle-prove-it-works/SKILL.md - pstack 技能索引与安装方式(
/add-plugin pstack):pstack/README.md