跳转到内容
pstack 中文学习站
learn-pstack

maintain-verification-skill

你在看 pstack 0.15.6 时的版本，最新版在这里

维护验证 skill

Section titled “维护验证 skill”

应用一改，feature map（一份索引，加上每个功能一个说明文件）就开始过时。这个 skill 是 /create-verification-skill 所生成 skill 的维护循环（任何带 feature map 的项目本地验证 skill 也适用）。严谨要落到每个功能，而不是每一句话。每个功能文件都要对照源码过一遍，每个功能都要在实际运行的应用上操作一遍，但不用把每条要点都逐条验证到底。

结果

Section titled “结果”

选一个，并说明是哪一个：

  • clean：每个功能都从源码和实际运行两方面覆盖到了，没有值得交付的改动。不建分支，不开 PR。
  • changed：用一个 PR 交付验证过的修正，改的是文档、harness（用来操作应用的脚本和工具）或 map。
  • blocked：覆盖没能做完，或者某个验证过的修复没法安全交付。说清楚到底是什么挡住了。

改动范围

Section titled “改动范围”

只改这个验证 skill 自己的目录（它的 SKILL.md、features/，以及归它所有的 harness 脚本）。一轮维护进行中，绝不改产品代码。map 描述了某个行为，应用却不再这样做，只有两种可能：文档漂移（改 map），或者产品回归（报告出来，不要在文档里把它掩盖过去）。

Pass

Section titled “Pass”

  1. 找到目标。 找出要维护的验证 skill。它是项目本地的 skill，正文里有 Launch 和 Drive 两节，还有一份 feature map（通常在 .cursor/skills/verify-*/）。有多个候选，就问清是哪一个。一个都没有，就停下，指向 /create-verification-skill，不要自己编一个目标出来。

  2. 整理索引。 读 feature map 的 README，再用 glob 找出同目录下的其他文件。修正缺失、多余、重复或已失效的条目。这一步从简，不生成盘点清单。

  3. 并行读源码。 每个功能文件配一个只读子代理，同时启动。每个子代理根据源码解释「这个面向用户的功能是怎么工作的？」，标出可能的文档漂移并附上出处，再交回一条简短的实际运行验证步骤。子代理绝不操作应用，也绝不改文件。交回的格式：功能摘要 / 源码入口 / 可能的漂移或无 / 一条验证步骤。

  4. 汇总核对。 每个功能文件都要有交回的摘要。把重叠的验证步骤合并，在可行范围内让需要的应用状态尽量少。对子代理引用的漂移做抽查，不要重新证明那些说没问题的结论。把最近频繁改动的地方扫一遍，找 map 里漏掉的面向用户的界面。要认定某个界面漏了，必须先拿出具体的源码路径。

  5. 实际跑一遍。 源码看起来没问题也必须做。所有对应用的操作都由协调者负责。按验证 skill 自己的启动方式来：服务器和 UI 用一个长期运行的实例，依次串行操作；运行时间短的 CLI 每次操作都开一个新的隔离会话（用哪种由那个 skill 的 Launch 一节决定，不由这个 skill 决定）。每个功能至少操作一次。整一轮里，不管遇到哪种失败，都要守住三条不变量。（1）实例上一次出现意外之后，只要还没做过健康检查，就绝不能操作它。第一次操作前跑 doctor（验证 skill 里那项只读的健康检查）；以会话为单位时，每个新会话都跑 doctor；任何一次操作失败后，再跑一次 doctor。doctor 发现不了的失败（进程健康，UI 却卡在某个状态里），要重置到已知状态或重新启动，不要碰运气。（2）到目前为止采集的证据，每次清理之后都必须还在。要去 skill 为它指定的位置检查，不能想当然。（3）一次操作启动的任何东西，在这次操作用不着之后都不能留着。失败迭代留下的残留一律清掉，不管会话是卡住了、已经退出，还是共享的（共享实例只清残留，不清实例本身）。如果 doctor 失败是 skill 漂移造成的，那就是漂移。先在改动范围内修好，再重试一次，重试过才能把这一轮判为 blocked。重试时，这次修复让什么失效了就只重启什么，别的不动。到不了的功能，只有写明具体的前提（鉴权、使用资格、操作系统、外部状态）和尝试过的路径，才能记为 verified-unreachable。如果 map 没写这个前提，那就是漂移。分类处理时做的任何 harness 修复，交付前都要重新实际跑一遍。最终拆除放在这一轮最后一次操作之后，那些重新验证也算在内。这样，这一轮结束后什么都不会留下（证据按 skill 的规定保留）。

  6. 分类处理。 从用户视角写的描述有错或缺失 → 文档漂移，修掉。行为本身正常，harness 却操作不了 → harness 缺口，修掉。修 harness 要遵守和生成 skill 时同一条 Helpers 规则（脚本可执行，调用方法写在 skill 正文里）。应用行为确实坏了 → 产品缺口。记下来告诉用户，不放进这个 PR。

  7. 开 PR 或到此为止。 结果是 changed 时，用一个 PR 提交验证过的修正，提交前先把每个改过的文件重读一遍。结果是 clean 或 blocked 时，不开 PR，如实报告结果和覆盖情况。

在临时位置留一份简短的运行笔记（覆盖了哪些功能、到不了的功能缺什么前提、确认过的漂移、结果），不要提交。