pstack Feature Verification Map 实战指南：为 Agent 冷启动编写可执行的用户视角验证地图-北京尧图网络

pstack Feature Verification Map 实战指南为 Agent 冷启动编写可执行的用户视角验证地图【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins导读本文以 pstack 插件中create-verification-skill技能自带的 Feature Verification Map特性验证地图示例为骨架完整讲解如何为你的应用编写一份让 AI Agent 能够冷启动驱动的验证地图。你将掌握验证地图的目录组织方式、基线前置条件Baseline Preconditions、驱动约定Driving Conventions、证据与跳过报告标准Proof and Skip Reporting以及每个特性文件的四段式结构约定Feature Entry Contract并看到 Notes 应用完整的create-note.md与search.md实战示例。读完即可为自己的项目生成同规格的验证地图。1. 什么是 Feature Verification Map它解决什么问题在 pstack 的工程理念里可验证是交付的前提对应其核心原则之一prove-it-works对真实产物验证而不是对代理结果或能编译自欺欺人。但验证存在一个现实矛盾验证脚本往往写得像写给人类的测试文档充满了 CSS 选择器、坐标和隐式假设一旦换一个从未见过该应用的 Agent 来执行就会在中途迷路。Feature Verification Map 正是为此而生的产物。它由create-verification-skill技能在生成项目本地验证技能时同步创建其定位是This directory is the maintained source for verifying the user-facing behavior of Notes. Read the index before driving the app, then use the matching feature file as the recipe.也就是说验证地图目录是验证用户可见行为的权威维护源。先读索引README再按匹配的特性文件当作菜谱执行。它刻意把实现细节排除在外部Keep implementation details out of the map只保留用户路径、稳定句柄、所需状态、命令和可观察证据——因为它的读者不是人类 QA而是任务中途、对应用一无所知、需要冷读取的 Agent。参考示例位于 pstack/skills/create-verification-skill/references/feature-map-example/共三个文件README.md—— 地图索引与全局约定本文主题create-note.md—— 特性创建笔记的完整验证配方search.md—— 特性搜索笔记的完整验证配方。在create-verification-skill的 SKILL.md 中生成流程第 3 步Seed the feature map明确要求创建.cursor/skills/verify-app/features/README.md加每个用户可见特性一个文件起步建议 35 个并严格遵循本示例目录的形状。而maintain-verification-skill则把这份地图当作后续维护的唯一事实源——应用一变地图就会腐烂需要定期以特性为单位做源审查一次实机驱动的校正循环。2. 地图索引 README全局约定的四大部分feature-map-example/README.md把全局规则收敛为四个部分任何特性文件都必须在这份框架内书写。2.1 Baseline preconditions基线前置条件每次验证运行都必须从同一个可复现的起点出发否则证据不可比、并发会互相污染。示例给出的基线是在http://127.0.0.1:4173启动 Notes并使用一次性数据目录设置NOTES_DATA_DIR/tmp/notes-verify-$RUN_ID使并发运行之间不共享状态预置标题为Quarterly plan和Grocery list的种子笔记把control-notes与notesCLI 加入PATH运行control-notes doctor要求返回预期的 URL、数据目录和构建版本号绝不去驱动一个不是本次验证运行启动的实例。这里有几个值得注意的设计意图状态隔离是第一优先。$RUN_ID式的临时目录保证多次并行验证互不踩踏对应 pstack 原则里的 make-operations-idempotent无论先前部分运行如何都收敛到同一终态。doctor 是入场安检。在create-verification-skill生成的技能结构中Doctor 是唯一一个只读检查回答这个实例值不值得驱动——进程在不在、版本/构建对不对、端口是否归我们、鉴权是否有效。基线前置条件要求先跑 doctor正是把这条规则下沉为每次运行的强制第一步。只驱动自己启动的实例是硬性安全线。从源码结构看这与control-ui的 guardrails不要使用来自其他仓库的硬编码选择器/端口以及maintain-verification-skill中绝不在未健康检查的实例上驱动的不变量一脉相承。2.2 Driving conventions驱动约定约定是让所有特性文件保持风格统一、让 Agent 少踩坑的通用规矩除非某个配方的前置条件另有说明否则每个配方都从基线状态开始优先使用 ARIA role 与可访问名称而不是 CSS 选择器或 DOM 位置把每条命令当作字面量对待引号内的名字与 flag 保持不变浏览器操作一律通过control-notes browser执行终端操作一律通过control-notes cli -- command执行变更数据后要恢复种子数据清理时不得移除证明产物proof artifacts。优先 ARIA role 与可访问名称这一点与control-ui的 Setup Pattern 第 6 条完全一致Prefer accessibility roles, labels, and stabledata-*selectors over coordinates.。坐标点击只在紧接截图之后才被允许control-ui的 Guardrails 第 2 条而本地图直接将其排除在默认约定之外因为坐标与 DOM 位置在应用改版后最容易漂移ARIA 名称则相对稳定。2.3 Proof and skip reporting证据与跳过报告证据标准决定了验证过到底意味着什么。README 给出的五条标准值得逐条展开捕获用户动作与结果状态而不只是最终画面。例如点击保存后出现Note saved状态动作与状态缺一不可UI 证据包括一份 ARIA 快照一张能看到应用身份的截图CLI 证据包括命令、stdout、stderr 与退出码变更mutation证据要求用第二个只读视图复核存储后的值——防止看起来保存了其实是假象每个证明产物都要记录对应的特性 ID 与入口点。关于跳过skip报告README 立了两条非常严格的红线无法到达某条路径时要报告尝试过的命令未满足的前置条件而不是含糊地说这功能测不了不得把某个入口点通过另一条路径验证过就当作它被验证了。这两条红线与maintain-verification-skill的 Live pass 不变量呼应无法到达的特性只有在给出具体前置条件鉴权、权限、OS、外部状态与尝试过的路径时才能标记为verified-unreachable。证据文化也直接对应 pstack 的 show-me-your-work 思路——可审查的决策痕迹。2.4 Feature entry contract特性文件契约这是整个地图格式的核心约束。每个特性文件必须以H1 标题一段描述用户可见行为的段落开头之后恰好四个 H2 小节顺序固定H2 小节内容Sub-features列出简短 ID每个行为一行How to get to it (user POV)列出该特性的每一个用户入口点Driving it with harness以Preconditions:开头用带标签的 bullet 把每个用户动作与精确命令、可观察结果配对Gotchas列出会浪费或使一次验证运行失效的陷阱最后再次强调Keep implementation details out of the map. Name only user paths, stable handles, required state, commands, and observable proof.把实现细节排除在地图之外只点名用户路径、稳定句柄、所需状态、命令与可观察证据。这个四段式契约的价值在于H1H2 结构是机器可解析的。Agent 读取特性文件时能确定性地知道行为是什么 → 用户怎么到达 → 我怎么驱动 → 什么会坑我这正是让一个从未见过应用的 Agent 冷启动执行成为可能的结构基础。3. 特性文件实战剖析一Create a notecreate-note.md演示了一个同时覆盖浏览器与 CLI、含取消与持久化确认的完整特性配方。3.1 Sub-features 与用户入口点四个子特性 ID 精确描述了行为切片create-open—— 从每个浏览器入口点打开空白编辑器create-save—— 持久化标题与正文create-cancel—— 丢弃未完成的浏览器草稿create-cli—— 从终端创建同样形状的笔记。用户视角的入口点POV则列出三种到达方式点击浏览器工具栏的New note按钮焦点不在可编辑字段内时按n键终端运行notes create --title title --body body。注意焦点不在可编辑字段内这个限定——它直接预告了 Gotchas 中的第一条陷阱。3.2 Driving it with control-notes动作 × 命令 × 可观察结果配方以Preconditions:开头声明三条Notes 健康运行在http://127.0.0.1:4173不存在标题为Release checklist的笔记control-notes doctor报告预期的 URL 与一次性数据目录。随后每个带标签的 bullet 都是用户动作 → harness 命令 → 可观察结果三元组Open editorcontrol-notes browser click --role button --name New note→ 出现名为Note editor的表单焦点在Title文本框Enter contentcontrol-notes browser fill --role textbox --name Title --value Release checklist与--role textbox --name Body --value Tag and publish→Save note按钮变为可用Save notecontrol-notes browser click --role button --name Save note→ 出现Note saved状态标题读作Release checklistConfirm persistence依次control-notes browser click --role link --name All notes和--role link --name Release checklist重开笔记 → 编辑器显示两个已保存的值Cancel draft开新笔记、填入Discard me、点Cancel→ 笔记列表返回且没有Discard me链接CLI entrycontrol-notes cli -- notes create --title CLI note --body Created from terminal --format json→ 退出码0stdout 含新笔记 ID 与标题Proof重开两篇已保存笔记后control-notes browser snapshot --aria --path artifacts/create-note/list.aria.txt与control-notes browser screenshot --path artifacts/create-note/list.png产物中同时出现Release checklist与CLI note。这段配方是 README 全部约定的一次完整示范ARIA rolename 定位、动作与状态成对捕获、CLI 用--format json保证可稳定断言、证据落到artifacts/下的命名位置。3.3 Gotchas让验证运行免于浪费文本框聚焦时按n会输入字符而不是打开新编辑器保存时标题会被 trim断言应针对渲染后的标题而非草稿输入值仅凭保存状态不足以证明持久化必须从列表重开笔记复核夹具清理时要移除Release checklist与CLI note但保留它们的证明产物。第 3 条直接呼应 README 的 mutation proof 规则——变更证据要求第二个只读视图。这也与maintain-verification-skill中证据必须在清理后仍存在于指定位置的不变量一致。4. 特性文件实战剖析二Search notessearch.md展示了一个更复杂的交互型特性标题/正文匹配、空态与清除态、键盘入口、CLI 双路径验证。4.1 六个子特性与入口点search-open—— 从每个支持的浏览器入口点打开搜索search-match—— 返回标题与正文匹配且不改动笔记数据search-open-result—— 在笔记编辑器中打开搜索结果search-empty—— 对无匹配查询展示完整空态search-clear—— 移除查询并恢复最近笔记视图search-cli—— 终端返回同样的匹配结果。入口点工具栏Search按钮焦点不在可编辑字段时按/终端notes search query。4.2 驱动配方的可观察结果设计工具栏入口与键盘入口均断言对话框Search notes出现且焦点在搜索框键盘入口额外断言页面没有插入斜杠字符标题匹配填入quarterly→Search results含Quarterly plan且不含Grocery list双向断言匹配与排除同时验证正文匹配换成budget→Quarterly plan仍可见且带正文匹配摘录打开结果点击Quarterly plan→ 对话框关闭、编辑器标题读作Quarterly plan空态填入volcano→ 搜索完成后出现No matching notes状态注意搜索完成后即等待具体状态而非固定 sleep清除点Clear search→ 搜索框为空Recent notes区域替换结果列表CLI 命中与未命中notes search quarterly --format json返回含Quarterly plan的对象数组notes search volcano --format json退出码0且 stdout 为[]——未命中也要证明且用空数组表达Proof快照与截图落盘到artifacts/search/results.*两个产物都要能识别出 Notes、查询词与Quarterly plan。4.3 Gotchas交互特性的专属陷阱编辑器或搜索框聚焦时按/会插入文本而不是打开搜索结果有防抖延迟应等待结果列表或空态出现而不是固定 sleep与control-cli的prefer deterministic waits over sleeps完全同源归档笔记默认被排除除非用户启用Include archivedCLI 默认输出是给人看的格式稳定断言必须用--format json打开结果会改变浏览器状态证明下一个查询前要重新打开搜索——这是状态管理层面的关键提醒。5. 地图如何融入验证技能的生成与维护闭环Feature Verification Map 不是孤立文档而是create-verification-skill产出的项目本地验证技能.cursor/skills/verify-app/的第三个组成部分。生成流程共五步Interview the repo, not the user——从代码库回答 Surface / Run / Drive / Observe / Isolate 五个问题优先复用仓库已有的 Playwright/Cypress/expect 脚本等 harnessGenerate the skill——写出带 YAML frontmatter 的SKILL.md包含 Launch、Doctor、Drive、Evidence、Cleanup、Helpers 六个章节Seed the feature map——即本文主角创建features/README.md加每个特性一个文件遵循示例目录的形状Prove the generated skill before handing it over——端到端跑一遍自己的指令launch → doctor → 驱动一个已映射特性 → 捕获证据 → 清理并确认清理后证据仍在命名位置Offer the maintenance loop——把维护职责交给/maintain-verification-skill。而maintain-verification-skill则定义了这个地图的保质期管理索引卫生修正缺失/多余/重复/失效条目、按特性并行的只读源审查、配方合并与漂移抽查、一次必须执行的实机 Live pass每特性至少驱动一次全程守住不驱动未健康检查的实例 / 证据在清理后仍存在 / 驱动启动的东西不超出其用途寿命三条不变量最后以 clean / changed / blocked 三种结果之一收尾。核心取舍是地图描述的某个行为应用不再有了要么是文档漂移修地图要么是产品回归上报不在文档里掩盖——这正是验证地图作为维护的事实源应有的地位。6. 编写你自己的 Feature Verification Map可复用的检查清单综合上述内容为任何项目Web UI、CLI、Electron、纯服务编写验证地图时可按以下清单自检目录层README是否声明了可复现的基线端口/URL、一次性数据目录、种子数据、PATH 依赖、doctor 校验项是否用$RUN_ID式隔离保证并发运行不共享状态是否明确只驱动本次运行启动的实例是否写明驱动约定ARIA role/name 优先、命令字面量、浏览器与 CLI 的入口封装是否写明证据标准UIARIA 快照带身份截图、CLI命令/stdout/stderr/退出码、mutation第二个只读视图、每个产物带特性 ID 与入口点是否写明跳过报告规则不可达路径要报命令与未满足前置条件禁止用另一条路径冒充验证特性清单是否链接到同目录的各个特性文件特性文件层每个 featureH1 一段用户可见行为描述恰好四个 H2Sub-features/How to get to it (user POV)/Driving it with harness/Gotchas顺序固定Sub-features是否每行一个短 ID、一个行为入口点是否覆盖用户能触达的所有方式工具栏、快捷键、CLI驱动段是否以Preconditions:开头每个动作都是用户动作 → 精确命令 → 可观察结果是否同时验证出现什么和不出现什么双向断言是否包含持久化/副作用复核重开、第二个视图Gotchas是否覆盖焦点状态、格式差异如 trim、防抖等待、默认输出格式、状态污染是否把实现细节排除在地图之外7. 结语Feature Verification Map 把验证从一次性的临时脚本升级为可持续维护的工程资产。它的核心洞察是验证配方的读者是冷的——一个任务中途、从未见过应用的 Agent。因此地图必须以机器可解析的结构固定四段式契约、用户视角的命名ARIA role 与可访问名称、字面量级精确的命令、以及动作状态成对的证据标准来书写。结合 create-verification-skill 的生成流程与 maintain-verification-skill 的维护闭环这套方法适用于任何语言、框架和平台——从 Web UI 到 CLI/TUI 再到纯服务。本文给出的 Notes 双特性示例create-note.md、search.md可作为直接对照的模板对应的驱动 harness 约定可进一步参考 control-ui 与 control-cli。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

pstack Feature Verification Map 实战指南：为 Agent 冷启动编写可执行的用户视角验证地图

相关推荐

小爱音箱免费听歌完整指南：xiaomusic 十分钟部署，说出歌名就能播

SCCM 2012运维实战：从架构到补丁管理的排查与沉淀

neurolib全脑建模框架：轻量高保真神经动力学仿真

更多资讯

昇腾910B/C部署Qwen3-Coder-A3B实战指南

若依Plus框架XSS过滤器缺陷分析与修复方案

Matlab车牌识别：图像处理定位、字符分割与BP/ONNX分类

上下文无关文法CFG从入门到实践：手写解析器搞定表达式计算与JSON解析

Oracle自动维护任务原理与实战调优指南

STM32启动流程深度解析：从复位向量到main函数的完整链路

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？