--- name: create-verification-skill description: "生成一个项目本地验证技能,以用户实际使用的方式操作应用,适用于任何语言、框架或平台。用于 `/create-verification-skill`、“为这个仓库制作控制技能”,或项目没有脚本化方法来证明 UI/CLI/服务行为时。" disable-model-invocation: true --- # 创建验证技能 每个严肃的项目都需要脚本化方法来操作真实应用并证明行为:启动应用、以用户方式执行功能,并捕获证据。本技能将其生成一个针对仓库定制的项目本地技能(`.cursor/skills/verify-/`)。生成器的输出是写给下一个代理的,而不是给人类:一个从没见过应用的代理会在任务中途、毫无先前上下文地阅读它。 ## 1. 询问仓库,而不是用户 从代码库回答这些问题,只有无法观察到的内容才询问用户: - **界面:** 用户实际接触什么?Web UI、CLI/TUI、桌面应用、API、移动应用,还是库?仓库可能有多个;选主要的,并注明其余的。 - **运行:** 应用如何在本地启动?优先使用仓库自己记录的开发命令(package scripts、Makefile、README quickstart)。记录端口、环境变量、种子数据和认证。 - **驱动:** 代理如何以编程方式与它交互?先使用已有测试支架,例如 Playwright/Cypress 规范、expect 脚本、PTY 辅助工具、可用 curl 调用的端点、调试端口。之后才选择通用方案:Web 和 Electron 使用浏览器/CDP,CLI/TUI 使用 tmux/PTY 支架,服务使用普通 HTTP。 - **观察:** 可以捕获哪些证据?截图、终端记录、响应正文、日志、退出码、数据库状态。 - **隔离:** 两个实例能否并排运行(端口、数据目录、配置档案)?如果不能,在生成技能中说明:拒绝同时驱动共享实例,好过破坏用户会话。 如果检出内容按现状不能构建或启动,先修复(或精确报告),再生成;针对损坏基础编写的技能会教错步骤。如果无关的缺失资源阻碍启动(API 从不提供服务的静态目录、示例配置),生成的技能可以创建它,但要清楚标为验证支架,并在清理时移除。 ## 2. 生成技能 编写 `.cursor/skills/verify-/SKILL.md`,包含 YAML frontmatter(`name: verify-` 和点明应用、界面及使用时机的 `description`;没有 frontmatter,技能永远不会注册),并包含以下章节;每节都必须基于实际调查发现,不留下占位符: - **启动:** 用于验证的精确应用启动命令,以及如何判断就绪(一条日志、一条提示)。启动必须从空数据目录达到可用状态,包括所需迁移和种子数据。就绪意味着能使用,而不仅是有进程响应。数据库健康检查通过时,初始化脚本可能仍在运行。包括拆除步骤。短生命周期 CLI 或 TUI 没有需要保持存活的服务器:启动指构建二进制(或安装依赖)一次,然后在独立隔离的 PTY 或 tmux 会话中开始每次驱动。 - **诊断:** 一项只读检查,回答“这个实例值得驱动吗?”——进程已启动、版本/构建正确、端口归我们所有、认证有效。只要有任何异常,代理首先运行它。 - **驱动:** 使用仓库中真实选择器/命令的支架方案,不要示例。优先使用稳定句柄(ARIA 标签、data 属性、提示字符串、路由路径),而不是坐标和 Tab 顺序。 - **证据:** 为证明需要捕获什么,以及存放位置。说明证明标准:执行真实用户路径,而不是内部 setter 或仅供测试的端点;捕获动作和结果状态,而不只是最终屏幕;验证副作用(写入文件、插入数据行、发送消息)的同时,也检查可见内容;仅在生产边界已隔离外部系统时使用 mock。当安全路径是 dry-run 或测试模式时,通过观察(文件、网络、git refs)验证它实际跳过什么,不要相信名字:某些 dry-run 仍然访问网络或打开浏览器。 - **清理:** 如何拆除本次运行创建的实例。绝不按进程名杀进程;只终止自己启动的进程。清理移除实例和临时状态,但绝不移除证据:证明产物在拆除后仍须存在于技能指明的位置。 - **辅助工具:** 技能附带的任何脚本都必须可执行,且技能正文展示其调用方式。需要读者逆向研究的辅助工具算不上辅助工具。 ## 3. 初始化功能地图 创建 `.cursor/skills/verify-/features/README.md`,并为每个能识别的面向用户功能创建一个文件(开始时以最主要的 3–5 个为目标,从路由、命令、菜单或文档中识别)。遵循 [`references/feature-map-example/`](references/feature-map-example/) 的形态:一个 README 索引,每个功能一个文件。每个文件从用户视角回答:功能是什么、如何到达、如何用支架驱动,以及哪个可观察最终状态能证明它有效。四个二级标题为 `Sub-features`、`How to get to it (user POV)`、`Driving it with ` 和 `Gotchas`,分别表示子功能、如何从用户视角到达、使用指定支架驱动、易错点。如果种子数据缺少某条用户旅程所需前提,旅程应报告失败,并将原因写入该功能的 `Gotchas`。绝不弱化旅程使其通过。地图是仓库持续维护的验证来源;地图列有其他入口时,只驱动一个方便入口的证明是不完整的。 ## 4. 交付前证明生成的技能 将技能自己的指令端到端运行一次:启动、诊断、驱动一个已映射功能(一个足够;地图使后续运行可以覆盖其他功能)、捕获证据、清理。清理后,确认指定位置仍有证据;清理吞掉证明就无法通过这一步。修复失败处,每次失败迭代后也运行生成的清理流程,避免损坏尝试遗留进程和端口。生成但从未执行的技能是草稿,不是交付物。如果在真实目标的替代环境中证明(用容器代替全新 VM,用本地技术栈代替远程环境),列出替代环境执行但目标不会执行的每一步设置。直到在真实目标上运行并覆盖这些步骤之前,它们都仍未验证。 ## 5. 提供维护循环 指引用户使用 `/maintain-verification-skill`,让功能地图随着应用变化保持准确。只有用户询问时才建议周期。