app-verification — 让任何 agent 都能把应用真正跑起来

编译通过、测试全绿、作者自述，都不等于改动在用户手里成立。验证常常是整件事里最慢的一步，因为它在等人去点一遍。把「启动应用、像用户一样操作、留下证据」写成项目本地的 skill，之后每个 agent 都能自己完成这一步：派工时的交付能写成可跑的检查，独立验证有了统一的驱动方式。

两种用法：

• 创建：项目还没有这样的 skill。按本文从「先问仓库」做到「交付前跑一遍」。
• 维护：已有 verify skill，应用变了、某次驱动因为文档过时而失败，或定期体检。读 references/maintain.md。

生成的 skill 写给下一个 agent：它在任务中途冷启动读到这份文件，从没见过这个应用。

先问仓库，不问用户

下面几件从代码里回答，只问用户看不到的：

• 表面：用户实际碰的是什么——Web UI、桌面应用、CLI/TUI、API、移动端、库。有多个就挑主要的，其余记下。
• 启动：本地怎么起，优先用仓库自己写明的开发命令；端口、环境变量、种子数据、鉴权。
• 驱动：agent 怎么程序化地操作它。先找现成的（Playwright/Cypress 用例、expect 脚本、PTY 助手、能 curl 的接口、调试端口），没有再选通用做法：Web 和 Electron 用浏览器自动化或 CDP，CLI/TUI 用 tmux 或 PTY，服务直接发 HTTP。
• 观察：能留下什么证据——截图、终端记录、响应体、日志、退出码、数据库状态。
• 隔离：两个实例能不能并排跑（端口、数据目录、profile）。不能就在生成的 skill 里写明：宁可拒绝驱动共享实例，也别弄坏用户正在用的会话。

仓库现状跑不起来，先修好或准确报告再生成：在坏基线上写出来的步骤会教错。和验证无关的缺失资源挡住启动时（API 不用的静态目录、示例配置），生成的 skill 可以补上，标明是验证脚手架，清理时删掉。

生成的 skill 长什么样

放在当前 agent 会自动加载的项目 skill 目录；项目里已有 skill 目录就放在一起。命名 verify-<app>，frontmatter 的 description 写明应用、表面和什么时候用——没有 frontmatter 就不会被识别。正文每一节都来自上面问到的实情，不留占位符：

• 启动：让应用进入可用状态的确切命令，以及怎么判断已就绪（某行日志、某个提示符）。要能从空数据目录起到可用，含迁移和种子数据；就绪指能用，不只是进程有应答——数据库健康检查可能在初始化脚本还没跑完时就通过。写上怎么关。短命的 CLI/TUI 没有常驻进程：启动指构建一次，每次驱动各开一个隔离的 PTY 或 tmux 会话。
• 体检：一条只读检查，回答「这个实例值不值得驱动」——进程在、版本对、端口归我们、鉴权有效。任何时候看着不对，先跑它。
• 驱动：用仓库里真实的选择器和命令，不是示例。优先稳定的句柄（ARIA 标签、data 属性、提示符、路由），不用坐标和 tab 顺序。驱动是给下一个 agent 验证它刚改的行为用的，所以要能单独走一个功能、换上它自己的输入，在隔离的状态里执行并留证。一键跑完全部旅程的回归脚本可以有，但代替不了单步驱动：它断言的是写脚本时的行为，新行为它看不见，照样报通过。
• 证据：要留什么、放在哪（不进版本控制：证据属于那一次运行，提交了就会过期），以及证据的标准：走真实的用户路径，不用内部 setter 或测试专用接口；记录动作和动作后的状态，不只是最后一屏；可见结果之外核对副作用（写出的文件、插入的行、发出的消息）；只在生产环境本来就隔离外部系统的边界上用 mock。安全路径是 dry-run 或测试模式时，靠观察（文件、网络、git refs）确认它到底跳过了什么，别信名字。
• 清理：拆掉这次起的实例和临时状态。只杀自己起的进程，不按进程名杀。证据不在清理范围内，留在 skill 写明的位置。
• 附带脚本：可执行，调用方式写在正文里。要读者逆向才能用的脚本不算助手。

功能地图

在 skill 目录下建 features/README.md 作索引，每个面向用户的功能一个文件，先覆盖最重要的 3–5 个（从路由、命令、菜单或文档里找）。每个文件从用户视角回答：这是什么功能，用户怎么走到它，用驱动方式一步步怎么操作（每步的具体命令），看到什么最终状态算它正常，有哪些坑。写法参照 references/feature-map-example.md。

种子数据缺了某个旅程的前提时，这个旅程报失败，原因写进该功能的「坑」——不要为了通过把旅程改弱。地图是仓库维护的验证依据：地图列了多个入口而只走了其中方便的一个，就不算验证完整。

交付前跑一遍

按生成的 skill 自己的说明完整跑一次：启动、体检、驱动地图里的一个功能（一个就够，其余留给之后的运行）、留证据、清理，然后确认证据在清理后还在写明的位置——清理把证据吃掉了，这一步就没过。哪里不通就修，每次失败的尝试之后也跑一遍清理，别留下进程和端口。没跑过的 skill 只是草稿。

如果是在替身环境里证明的（容器代替全新虚拟机、本地栈代替远端），列出替身做了而真实目标不会做的每一步；这些步骤在真实目标上跑过之前都算未验证。

交付之后

• 把 skill 提交进仓库，让每个人和每个 agent 都用同一种方式驱动应用。
• 派工时把「用 verify-<app> 走某某功能，留截图或记录作证」写进交付；独立验证照同一种方式跑。
• agent 反复手写一次性脚本去点同样的流程时，把它收成一个小的控制 CLI 让 skill 调用：少量可组合、每条都做实事的命令，破坏性操作带 --dry-run，错误信息说清该怎么做，输出可机读（如 JSON）。省 token，每次运行也可复现。
• 应用变了、地图开始和实际不符时，按 references/maintain.md 维护。