解读 openbot pstack 验证技能的 feature map:以 search.md 为例精读一条"搜索"功能验证配方

原创2026-10-27 17:24:092,123 阅读
文章标签:桌面应用AI Agent人工智能多智能体代码智能体浏览器控制本地部署MCP 服务

解读 openbot pstack 验证技能的 feature map:以 search.md 为例精读一条"搜索"功能验证配方

本文以 openbot 仓库中 pstack 技能包自带的 create-verification-skill/references/feature-map-example/search.md 为主体,逐节拆解一个"功能验证配方"(feature map entry)应当长什么样:如何定义子功能 ID、如何列全用户入口、如何用 ARIA 角色和精确命令驱动 UI 与 CLI、以及哪些坑会让一次验证运行作废。读完后你将掌握验证技能(verification skill)功能地图文件的完整写法,并能把它作为模板套用到自己的项目上。

1. 这份文档在 pstack 中处于什么位置

先交代背景,避免把示例当成仓库里的真实应用。

pstack 是 openbot Marketplace 生产目录中的一个技能包(pack),安装后提供 52 个技能,通过 $pstack-<name> 形式调用(如 $pstack-create-verification-skill),见 catalog.json 中 "slug": "pstack" 的 packs 条目与 production-catalog README。其中 create-verification-skill/SKILL.md 是一个"生成器"技能:它让 Agent 对目标仓库做一次"访谈"(用户表面、启动方式、驱动手段、可捕获证据、隔离能力),然后生成一个项目本地的验证技能 .cursor/skills/verify-<app>/。

该生成器的第 3 步明确要求:为每个面向用户的用户级功能建一个 feature map 文件,并直接指向本例所在的目录——

"Create .cursor/skills/verify-<app>/features/README.md plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Follow the shape in references/feature-map-example/…" —— SKILL.md

也就是说,references/feature-map-example/ 下的三份文件(README.md、create-note.md、search.md)共同构成"功能地图文件应该长什么样"的权威范本。它们描述的是一个假想的 Notes 应用和 control-notes 测试驱动工具——在本仓库中对 control-notes 做全文检索,命中点只分布在这三份示例文件内,证明它是示例脚手架而非仓库提供的二进制。这正是范本的意义:给出形状(shape),而不是给出可运行的目标。

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." —— search.md

最后一句"区分无匹配与搜索不可用"很关键:验证配方必须能把"查不到"和"坏了"两种状态分开断言,否则测试通过与否都说不清原因。

2. 功能文件的结构契约:四个固定 H2

feature-map 目录下 README.md 的 "Feature entry contract" 一节规定了每个功能文件的硬性格式:

  1. H1 标题 + 一段描述用户可见行为的引言;
  2. 恰好四个 H2 小节,顺序固定:
    1. Sub-features —— 短 ID 列表,每个行为一行;
    2. How to get to it (user POV) —— 列全所有用户入口;
    3. Driving it with <harness> —— 以 Preconditions: 开头,用"标签化 bullet"把每个用户动作与一条精确命令和一个可观察结果配对;
    4. Gotchas —— 会浪费或使验证运行失效的陷阱。

并且要求"Keep implementation details out of the map. Name only user paths, stable handles, required state, commands, and observable proof."——地图里只写用户路径、稳定句柄、必要状态、命令和可观察证据,不写实现细节。search.md 逐条满足该契约,下文按这四个小节逐一精读。

3. Sub-features:用短 ID 把功能拆成可引用的行为单元

search.md 的 Sub-features 小节定义了 6 个短 ID:

短 ID 行为
search-open 从每个受支持的浏览器入口打开搜索
search-match 返回标题与正文匹配结果,且不修改笔记数据
search-open-result 在笔记编辑器中打开一条结果
search-empty 对无匹配的查询展示完整的空状态
search-clear 清空查询并恢复最近笔记视图
search-cli 在终端返回同样的匹配笔记

写法的要点有三:

  • ID 是验证报告的最小引用单位。 配套 README.md 的 "Proof and skip reporting" 要求"Record the feature ID and entry point used with every artifact"——每份证据产物都要记录所用功能 ID 与入口。ID 就是这条规则的可索引锚点。
  • 一个 ID 对应一个可独立断言的行为,粒度细到"区分无匹配与搜索不可用"(search-empty)、"不改数据"(search-match 的只读性)这类可观察属性。
  • 入口多样性被显式拆出来:同一功能按浏览器(search-open)、按结果(search-open-result)、按 CLI(search-cli)分别编号,这样"只验证了一个顺手入口"会被报告为覆盖不全。这与 SKILL.md 的告诫呼应:"a proof that drives one convenient entry point is incomplete when the map lists others"(当地图列了更多入口时,只驱动一个便利入口的证明是不完整的)。

4. How to get to it (user POV):入口必须列全

search.md 列出三个用户入口:

  • 点击浏览器工具栏的 Search 按钮;
  • 在焦点不在可编辑区域时,于浏览器中按 /;
  • 在终端运行 notes search <query>。

写法上有两条隐含标准:

  • 用"用户视角"而非"实现视角"描述:按钮名、快捷键、CLI 命令,全是用户能直接对应的东西,不出现组件名或路由代码。
  • 每个入口都必须在下一节的驱动步骤中被覆盖。本例 Driving 小节里的 "Toolbar entry" 与 "Keyboard entry" 分别对应按钮和 / 快捷键,"CLI match / CLI miss" 对应终端入口——入口清单与驱动步骤一一对应,缺哪一个就是覆盖缺口。

5. Driving it with control-notes:前置条件 + 动作-命令-结果三元组

这是功能配方的核心。search.md 先给出三条 Preconditions(前置条件),再以 9 条标签化 bullet 把整条搜索旅程写成可逐字执行的脚本。

5.1 前置条件

Preconditions:
- Notes is healthy at http://127.0.0.1:4173.
- The disposable data directory contains Quarterly plan with body text Draft budget.
- control-notes doctor reports the expected URL and data directory.

注意它与目录级基线的关系:README.md 的 "Baseline preconditions" 规定了所有配方的共同起点——以一次性数据目录启动 Notes(NOTES_DATA_DIR=/tmp/notes-verify-$RUN_ID,避免并发运行共享状态)、预置 Quarterly plan 与 Grocery list 两条种子笔记、control-notes 与 notes CLI 在 PATH 上、先跑 control-notes doctor,以及最重要的隔离铁律:"Never drive an instance that was not started by this verification run."(绝不允许驱动一个不是本次验证运行启动的实例)。search.md 的前置条件正是这条基线在单功能上的投影:第 2 条要求的种子数据 Quarterly plan(正文 Draft budget)恰好来自基线清单,第 3 条把 doctor 检查下沉到功能级。

5.2 九条驱动步骤(命令逐字可执行)

每条 bullet 都是"用户动作 → 精确命令 → 可观察结果"的三元组。以下按原文完整给出:

  1. Toolbar entry(工具栏入口)。 点击 Search 按钮:

    control-notes browser click --role button --name "Search"
    

    期望结果:出现名为 Search notes 的对话框,焦点落在其搜索框(searchbox)内。

  2. Keyboard entry(键盘入口)。 关闭对话框、让页面聚焦后按 /:

    control-notes browser press --key "/"
    

    期望结果:出现同一个对话框,且页面没有插入斜杠字符。这一步同时验证了快捷键的正向行为与"不误触文本"的负向行为。

  3. Title match(标题匹配)。 输入 quarterly:

    control-notes browser fill --role searchbox --name "Search notes" --value "quarterly"
    

    期望结果:Search results 列表包含 Quarterly plan,且不包含 Grocery list——负向断言保证匹配逻辑不是"永远显示全部"。

  4. Body match(正文匹配)。 把查询替换为 budget:

    control-notes browser fill --role searchbox --name "Search notes" --value "budget"
    

    期望结果:结果 Quarterly plan 依然可见,且带有正文匹配摘录(body-match excerpt)。这验证了标题与正文两条匹配通路。

  5. Open result(打开结果)。 选择 Quarterly plan:

    control-notes browser click --role link --name "Quarterly plan"
    

    期望结果:对话框关闭,编辑器标题显示 Quarterly plan。

  6. Empty state(空状态)。 重新打开搜索并输入 volcano:

    control-notes browser fill --role searchbox --name "Search notes" --value "volcano"
    

    期望结果:搜索完成后出现名为 No matching notes 的状态。注意措辞是"after search completes"——空状态必须在搜索完成之后断言,而不是立刻。

  7. Clear query(清空查询)。 选择 Clear search:

    control-notes browser click --role button --name "Clear search"
    

    期望结果:搜索框为空,Recent notes 区域取代结果列表。

  8. CLI match(终端命中)。 从终端搜索:

    control-notes cli -- notes search "quarterly" --format json
    

    期望结果:退出码 0,stdout 恰好包含一个对象,其 title 为 Quarterly plan。

  9. CLI miss(终端未命中)+ Proof(取证)。 搜索一个不存在的值:

    control-notes cli -- notes search "volcano" --format json
    

    期望结果:退出码 0,stdout 为 []——CLI 未命中返回空数组而非非零退出码,这与第 3 节引言"区分 no matches 与 unavailable"的语义直接对应:未命中是成功,只有搜索不可用才该失败。随后捕获有结果的状态:

    control-notes browser snapshot --aria --path artifacts/search/results.aria.txt
    control-notes browser screenshot --path artifacts/search/results.png
    

    期望结果:两份产物都能识别出 Notes 应用、当前查询与 Quarterly plan。

5.3 命令写法体现的驱动规范

这批命令并非随意而写,它们整体执行了 README.md "Driving conventions" 的约定:

  • 优先 ARIA 角色与可访问名称,而不是 CSS 选择器或 DOM 位置(--role button --name "Search"、--role searchbox、--role link);
  • 命令是字面量,引号内的名称和参数保持不变("Treat every command as literal"),Agent 冷启动读文件时可以直接复制执行;
  • 浏览器动作一律经 control-notes browser,终端动作一律经 control-notes cli -- <command>,两个表面统一走同一个 harness,不混用。

SKILL.md 对 Drive 一节的要求与此一致:"Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order."(优先稳定句柄——ARIA 标签、data 属性、提示串、路由路径——而不是坐标和 Tab 顺序。)search.md 中没有任何坐标、nth-child 或 Tab 序列,是这一原则的完整示范。

5.4 证据标准:动作与状态都要留下

"Proof" 步骤(ARIA 快照 + 截图)对应 README 的取证标准:UI 证明须包含 ARIA 快照与一张能看出应用身份的截图(README.md);并且"Capture the user action and the resulting state, not only the final screen"(捕获动作与结果状态,而不只是最终屏幕)。search.md 特意在"有结果填充"的状态下取证(而不是任意时刻截图),两份产物被要求同时识别出应用、查询和 Quarterly plan——这使产物本身可被独立复核,不依赖运行当时的上下文。

6. Gotchas:五条让验证运行作废的陷阱

search.md 的 Gotchas 小节收录了 5 条陷阱,每一条都直接决定某次运行的结论是否有效:

  1. 焦点状态改变快捷键语义。 编辑器或搜索框持有焦点时按 / 会插入文本而不是打开搜索。写自动化时若不在按 / 前把焦点移出可编辑区,会把"正常输入"误判为"快捷键失效"。
  2. 结果有防抖延迟,等状态而不是固定 sleep。 "Results update after a short debounce. Wait for the results list or empty status, not a fixed sleep." 这解释了为什么第 6 步要写"after search completes":断言必须绑定在可观察状态上,而不是时间上。
  3. 归档笔记默认被排除。 除非用户开启 Include archived,否则归档笔记不参与匹配。种子数据里若混入归档笔记,匹配断言会莫名其妙地失败——前置条件中"数据目录内容必须精确"(只含 Quarterly plan)正是为了消掉这类噪声。
  4. CLI 默认人类可读输出。 断言必须加 --format json("Use --format json for stable assertions"),否则 stdout 的散文格式一变,解析就会碎。
  5. 打开结果会改变浏览器状态。 "Opening a result changes browser state. Reopen search before proving another query." 每打开一次结果,搜索对话框就被关闭,后续查询断言之前必须重新打开搜索。这类"状态污染"是多步验证中最常见的假失败来源。

Gotchas 小节的价值还在于它的写入时机:SKILL.md 规定,当种子数据缺少某个旅程所需的前置条件时,"the journey reports a failure and the reason goes in that feature's Gotchas. Never weaken the journey to make it pass."——失败原因写进 Gotchas,绝不为了通过而削弱旅程。这与维护技能 maintain-verification-skill/SKILL.md 的 triage 三分类一脉相承:用户视角描述错了是 doc drift(修文档)、行为正常但 harness 驱动不了是 harness gap(修 harness)、应用真的坏了是 product gap(报告而非掩盖)。Gotchas 正是这三类问题在功能文件里的落点。

7. 与同目录范本互相印证

把 search.md 放回范本目录中,能看清整份 feature map 的组织方式:

  • README.md:目录级"索引 + 基线前置条件 + 驱动约定 + 取证与跳过报告规则 + 入口契约",并在 Features 一节登记两个功能入口——Create a note 覆盖浏览器/CLI 创建、取消、持久化与清理,Search notes 覆盖工具栏、键盘与 CLI 搜索及匹配/空/清空状态。
  • create-note.md:姊妹示例,同样四节结构,Sub-features 给出 create-open / create-save / create-cancel / create-cli 四个 ID;其 CLI 入口 control-notes cli -- notes create --title "CLI note" --body "Created from terminal" --format json(create-note.md)与 search.md 的 CLI 步骤使用同一套 harness 语法,交叉印证了 control-notes cli -- 前缀的约定写法。
  • 两个功能共享同一批种子数据(Quarterly plan、Grocery list),因此可以在同一次运行里串行驱动而不互相污染数据;search.md 第 3 步对 Grocery list 的负向断言,正依赖于 create-note 侧不会在搜索验证前污染列表。

这套"README 管基线、每个功能一个文件、文件内四节固定"的结构,就是 Agent 冷启动时可以直接消费的形状:先读索引,再取对应功能文件当配方执行。

8. 如何把这个范本用到真实项目

把 search.md 当模板套用时的映射关系如下(依据 SKILL.md 第 2、3 节的要求):

范本要素(search.md) 真实项目中的对应物
前置条件中的 URL / 数据目录 / doctor 目标仓库的启动命令、端口、隔离数据目录与就绪检查(Launch 与 Doctor 一节)
control-notes browser click --role … --name … 目标仓库 harness 的等价命令,句柄换成该仓库真实的 ARIA 标签 / data 属性 / 路由
notes search <query> CLI 目标仓库真实的 CLI 子命令与稳定输出格式(如 --format json)
artifacts/search/… 证据路径 验证技能中命名好的证据目录,清理不得删除证据
Gotchas 首次端到端证明运行中踩到的真实陷阱与未满足的前置条件

两条来自 SKILL.md 的硬规则要一并记住:

  • 先证明,再交付。 "Run its own instructions end to end once… A generated skill that was never executed is a draft, not a deliverable." 生成的技能必须自己端到端跑通一次(启动 → doctor → 驱动一个映射功能 → 取证 → 清理),且清理后证据仍须存在于命名位置;每次失败迭代之后也要跑清理,避免残留进程和端口。
  • 隔离优先于顺手。 无法并行起两个实例时,就在技能里写明"拒绝驱动共享实例",而不是赌不会污染用户会话;清理只杀自己启动的东西,永不按进程名误杀("Never kill by process name; kill what you started")。

9. 小结:一份功能验证配方到底在做什么

search.md 用 45 行文字完整演示了 feature map 的全部纪律:用 6 个短 ID 把"搜索"拆成可引用、可逐项打勾的行为;用 3 个用户入口约束覆盖范围;用"前置条件 + 9 条动作-命令-结果三元组"把整条旅程写成逐字可执行的脚本,命令统一走 ARIA 角色句柄与 control-notes harness;用取证步骤把 ARIA 快照与截图固定到命名产物路径;最后用 5 条 Gotchas 把"哪些情况会让运行结论失效"显式登记在案。它不是测试用例集合,而是写给下一个(可能从未见过这个应用的)Agent 的冷启动配方——这正是 SKILL.md 开头那句话的分量:"You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app."

登录后查看全文
openbot