pstack 特性地图实战用 control-notes 驱动并验证 Notes 搜索功能【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins导读本文以 pstack 插件中create-verification-skill技能所附的 search.md 特性地图示例 为核心骨架完整讲解如何在验证技能verification skill中为「搜索」这类用户可见功能编写可复现的驱动配方从子特性拆分、用户入口枚举到用control-notes浏览器与 CLI 双通道逐条执行命令、采集证据再到规避防抖、焦点与归档状态等陷阱。读完本文你将掌握一种以用户视角驱动真实应用、以可观测状态作为唯一验收标准的 Agent 验证写作范式可直接套用到任何 Web UI CLI 双表面的项目。一、特性地图中的搜索一份给陌生 Agent 冷读的验证配方在 pstack 的 create-verification-skill 工作流里生成的验证技能会附带一个features/目录称为特性地图feature map。地图中每个特性一个文件其写作对象不是人而是从未见过这个应用的 Agent——它会在任务中途被冷启动读取然后照着文字驱动真实应用。search.md 正是这份地图中「搜索」特性的示例文件。按 feature-map-example/README.md 定义的特性条目契约Feature entry contract每个特性文件必须以一个 H1 标题加一段用户可见行为描述开头随后严格按顺序使用四个 H2 小节Sub-features——列出短 ID每行描述一个行为How to get to it (user POV)——列出用户的每一个入口点Driving it with harness——以Preconditions:开头用带标签的 bullet 把每个用户动作与一条精确命令、一个可观察结果配对Gotchas——列出会浪费或作废一次验证运行的陷阱。search.md 严格遵循了这一契约。地图本身则要求保持实现细节不出现在地图中只写用户路径、稳定句柄、前置状态、命令与可观察的证据——这正是它能在仓库变更后仍被维护的根基对应 maintain-verification-skill 的防漂移循环。二、功能定义与子特性拆分搜索到底要验证什么search.md 开篇用一句话定义特性边界Search lets a user find notes by title or body text, inspect a matching note, and distinguish no matches from an unavailable search.即用户能按标题或正文查找笔记、检视匹配项并且能区分没有匹配与搜索不可用——后者正是许多弱验证最容易漏掉的状态。围绕这一定义文档拆出六个子特性每个对应一个可单独断言的行为子特性 ID行为描述验收要点search-open从每个受支持的浏览器入口点打开搜索对话框出现且焦点落在搜索框search-match返回标题与正文匹配项且不改动笔记数据结果列表内容正确、数据无副作用search-open-result在笔记编辑器中打开某条结果对话框关闭、编辑器标题正确search-empty对无匹配查询展示完整的空状态出现No matching notes状态search-clear清除查询并恢复最近笔记视图搜索框清空、结果区被Recent notes取代search-cli从终端返回相同的匹配笔记退出码 0、stdout 为稳定 JSON子特性拆分的意义在于每一个 ID 都是一次可独立声明的验证单元。地图 README 的Proof and skip reporting约定要求每条证据都记录特性 ID 与入口点当某个入口点无法到达时如实上报尝试过的命令 未满足的前置条件而不是通过另一条路径冒充已验证。三、用户入口枚举user POV同一功能的三条触达路径search.md 明确列出搜索功能的所有用户入口验证时每条都必须覆盖——地图 README 特别强调只驱动一个便利入口点的证据是不完整的工具栏入口在浏览器工具栏点击Search按钮键盘入口在浏览器中、焦点不在可编辑字段内时按下/CLI 入口在终端运行notes search query。同时search-cli子特性还隐含了CLI 结果与浏览器结果一致的跨表面一致性要求即搜索是 Web 与终端共享同一数据行为的典型双表面功能。四、用 control-notes 驱动搜索前置条件与全命令清单Driving it with control-notes是整份文档的实操核心。它先声明 Preconditions前置条件再用带标签的 bullet 逐条给出用户动作 → 精确命令 → 可观察结果的完整配方。4.1 前置条件Preconditions任何驱动开始前必须满足Notes 服务健康位于http://127.0.0.1:4173一次性数据目录中包含标题为Quarterly plan、正文为Draft budget的种子笔记对应地图 README 的 Baseline preconditions用NOTES_DATA_DIR/tmp/notes-verify-$RUN_ID隔离并发运行状态control-notes doctor报告期望的 URL 与数据目录doctor 是这个实例值得驱动吗的只读健康检查来自 create-verification-skill/SKILL.md 的 Doctor 小节。4.2 完整驱动序列原文全量继承1. 工具栏入口search-open。用户点击Search按钮Agent 执行control-notes browser click --role button --name Search可观察结果出现名为Search notes的对话框焦点落在搜索框内。2. 键盘入口search-open。关闭对话框、聚焦页面后按/control-notes browser press --key /可观察结果同一对话框出现且页面没有插入斜杠字符证明快捷键被应用层捕获而非落到输入区。3. 标题匹配search-match。输入quarterlycontrol-notes browser fill --role searchbox --name Search notes --value quarterly可观察结果Search results列表包含Quarterly plan且不包含Grocery list——同时断言在与不在避免弱断言。4. 正文匹配search-match。将查询替换为budgetcontrol-notes browser fill --role searchbox --name Search notes --value budget可观察结果Quarterly plan保持可见并带有正文匹配的摘要片段excerpt证明搜索覆盖正文而非仅标题。5. 打开结果search-open-result。选择Quarterly plancontrol-notes browser click --role link --name Quarterly plan可观察结果对话框关闭编辑器标题显示Quarterly plan。6. 空状态search-empty。重新打开搜索并输入volcanocontrol-notes browser fill --role searchbox --name Search notes --value volcano可观察结果搜索完成后出现名为No matching notes的状态。注意措辞after search completes——这是对防抖时序的显式要求见下文 Gotchas。7. 清除查询search-clear。点击Clear searchcontrol-notes browser click --role button --name Clear search可观察结果搜索框清空Recent notes区域取代结果列表。8. CLI 命中search-cli。终端搜索control-notes cli -- notes search quarterly --format json可观察结果退出码0stdout 为含一个对象title 为Quarterly plan的 JSON。9. CLI 未命中search-cli。搜索不存在的值control-notes cli -- notes search volcano --format json可观察结果退出码0stdout 为[]——空数组本身就是无匹配这一状态在 CLI 侧的确定性表达。10. 证据采集Proof。捕获填充后的结果状态control-notes browser snapshot --aria --path artifacts/search/results.aria.txt control-notes browser screenshot --path artifacts/search/results.png两份产物ARIA 快照 截图都必须能同时识别出 Notes、查询词与Quarterly plan。这对应地图 README 的证据标准捕获用户动作与结果状态而不仅是最终画面UI 证据包含带应用身份可见的 ARIA 快照与截图。4.3 驱动细节的工程含义句柄优先于坐标所有定位都使用 ARIA role accessible name--role button --name Search这是 control-ui/SKILL.md 反复强调的用稳定的 ARIA 标签与可访问名而非 CSS 选择器或 DOM 位置。命令字面化地图 README 的 Driving conventions 要求把每条命令当字面量对待保持引号内的名称与标志不变——这是为了消除 Agent 在冷启动时对命令做聪明但错误的改写。浏览器动作与终端动作分通道浏览器动作一律走control-notes browser终端动作一律走control-notes cli -- command两套 harness 语义清晰不混用。CLI 断言用 JSON--format json提供稳定、可程序化断言的输出人类可读输出不适合作为验收依据。五、Gotchas五次验证中最常见的翻车点search.md 的 Gotchas 小节浓缩了真实驱动中积累的五条陷阱每一条都对应一种验证结果看似通过、实则作废或误报的情况焦点陷阱在编辑器或搜索框持有焦点时按/会插入文本而非打开搜索。这解释了为什么前置条件要强调焦点在可编辑字段之外。防抖时序结果在短暂防抖debounce后更新。必须等待结果列表出现或空状态出现这一确定性信号而不是固定 sleep——对应 control-cli/SKILL.md 的护栏优先确定性等待而非 sleep若必须 sleep 需说明原因。归档过滤除非用户勾选Include archived归档笔记一律不参与搜索。验证者必须知晓该过滤条件避免把归档笔记搜不到误判为缺陷。CLI 输出格式CLI 默认输出人类可读文本做稳定断言必须显式加--format json。浏览器状态污染打开一条结果会改变浏览器状态。证明下一条查询前必须重新打开搜索——这条与前置条件的从基线状态开始相呼应也是search-open-result之后必须重开对话框的原因。六、证据标准与行为而非实现的底层原则search.md 中的证明环节snapshot --ariascreenshot与地图 README 的 Proof and skip reporting 共同定义了这套验证体系的质量下限其思想与 pstack 的两条验证原则一脉相承prove-it-works验证必须针对真实工件——运行真实功能路径、读取真实值而非它编译过了或代理信号。地图中重新打开笔记从列表确认持久化快照必须同时识别应用、查询与结果都是这一原则的落地证据可被复查者重跑而不是一次性的眼观。test-behavior-not-implementation断言用户观察到的字面结果结果列表含/不含、退出码、[]而非内部调用。若一条断言在所有被调函数都返回 undefined时依然通过它就是无效断言——搜索配方中同时断言包含与不包含CLI 断言[]而非 没有输出都刻意避开了这种弱断言。此外地图 README 还约定变更型证据要有只读的第二次视图验证存储值清理阶段删除夹具数据但绝不移除证据产物——证据在卸载后仍存留于技能指定的位置这正是 create-verification-skill/SKILL.md 第 4 步清理会吃掉证明即失败的验收项。七、把搜索配方放回特性地图与维护闭环搜索特性文件不是孤立文档它与整个特性地图形成可维护的验证资产索引与条目feature-map-example/README.md 维护基线前置条件隔离数据目录、种子数据、control-notes doctor健康检查与全局驱动约定并把 创建笔记 与搜索两份文件编入索引。生成流程搜索配方由 create-verification-skill/SKILL.md 第 3 步Seed the feature map产出——为每个用户可见功能写一个文件起始聚焦前 35 个特性并按上述四 H2 契约成文。防漂移维护maintain-verification-skill 的维护循环以特性为严谨性单位并行源码通读 一次全量实机驱动产出 clean / changed / blocked 三种结论。当应用行为变化导致地图描述失效时要么修正地图文档漂移要么如实上报产品回归——绝不用文档粉饰产品缺陷。一句话总结这套方法的闭环生成create-verification-skill→ 用按 search.md 这类配方冷启动驱动→ 维护maintain-verification-skill 防漂移。搜索特性的每一步驱动、每一条断言、每一份证据都是这条闭环上可独立引用、可重跑、可复查的验证单元。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考