verifykit

verifykit

像用户一样操作刚构建的前端功能，并记录发生的情况。在 show 模式下，捕获结果是截图，会在会话中交给操作人员，成本足够低，可以用来回答“按钮移动了吗”这类问题。在 proof 模式下，捕获结果包括截图和一段简短的动画 GIF，并会发布，以便在拉取请求中内嵌展示。setup 会为这两种模式准备好机器和代码仓库。verifykit 是审查代码和创建 PR 之间的步骤：代码审查会读取源代码，而它会实际操作正在运行的功能。

它只是一个操作和录制工具，仅此而已。它不会编写测试（这是测试套件技能，若已安装，则是 testkit 的职责），不会生成人工检查清单（这是手动 QA 技能的职责），也不会配置自身驱动程序之外的环境。它会操作提供给它的 UI，并记录所看到的内容。

何时触发

前端功能构建完成后，如果你想查看效果或证明它能正常工作，就可以使用它。它会捕获具有可视界面的运行中功能。如果改动仅涉及后端或 CLI，没有可供操作的内容，请如实说明，不要编造操作流程，并转到 qakit 获取手动测试计划（/qakit）；如果没有 qakit，请列出人员应手动测试的命令和端点。

• show。“让我看看效果”“截个图”“现在页面是什么样”“按钮移动了吗”。截图保存到本地路径，不会发布。
• proof。“验证这个功能”“录下这个流程的运行情况”“证明 UI 改动有效”“为 PR 捕获证明材料”，或 PR 流程中需要证明材料的步骤。截图和 GIF 会打包并发布，供 PR 正文使用。
• setup。“设置 verifykit”“安装浏览器驱动”“准备好这台机器以便捕获”。安装缺少的内容，并报告已有内容。

动词含义不明确时，运行 show。 调用中提到了 PR、证明、录制或验证，即使用 proof。其他情况都使用 show，因为成本低且可撤销；升级到 proof 只需多说一句即可。

这与手动 QA 计划（由人工执行）和代码审查（读取源代码）不同。verifykit 会自动操作并录制；如果用户实际想要的是手动测试检查清单或源代码审查，请引导他们使用相应技能，而不是进行捕获。

通用流程

每种捕获模式（show 和 proof）都会先执行以下步骤。setup 会跳过这些步骤，并从自身文件开始。

1. 确定功能范围并找到入口

根据实际发生的变更来确定本次运行的范围。普通的 git diff 只显示未暂存的编辑，因此要确定完整的变更目标：已暂存和未暂存的编辑（git diff HEAD）、未跟踪的文件（git ls-files --others --exclude-standard，并读取每个文件），以及分支相对于基准的已提交变更（git diff <base>...HEAD）。如果安装了 gitkit，则从中获取基准；否则使用 git symbolic-ref --short refs/remotes/origin/HEAD 并去掉 origin/ 前缀；若无结果，则使用 main 或 master 中第一个能解析的分支。如果有相关 issue 或计划，请阅读。根据这些内容，了解本次变更涉及哪些屏幕、路由、组件或流程。

开始操作前，记录已测试的修订版本：应用提交（git rev-parse HEAD）和工作区是否干净（如果 git status --porcelain 有任何输出则记为 yes，否则记为 no）。proof 会将这两项写入证据包，方便之后查看的人确认捕获内容是否与分支匹配。确定如何启动应用并进入该功能：开发服务器命令和 URL。如果项目已有运行说明，请遵循说明；否则推断启动方式，并在操作前确认入口 URL。

为本次运行选择一个 slug：如果有关联的 issue 编号，则使用该编号；否则根据分支或 diff 选择简短的小写 kebab-case 功能 slug（例如 login-throttle）。每种模式都会根据 slug 和本次运行的 ISO 创建日期创建运行目录。

完成条件：每个已变更、已暂存、未跟踪和已提交的路径都已归类为视觉相关或无关，入口 URL 已确认，且提交和工作区状态已记录。

2. 选择要操作的流程

根据 diff，将候选流程归纳为不同的用户入口：发生变更的路由或页面、表单或对话框，以及与用户操作相关的组件。然后：

• 明确指示优先。 如果调用中指定了流程（例如“验证结账流程”“展示设置页面”），就操作该流程。
• 只涉及一个流程 → 直接操作，无需询问。
• 涉及多个流程 → 列出候选流程并附上简短标签，然后询问用户要捕获哪些流程（允许选择多个）。分别操作每个选定的流程，并将捕获内容标记为独立章节。绝不默默猜测哪个是“主要”流程。

完成条件：所有要操作的流程都已明确指定，可以来自调用、唯一候选流程或用户的选择。

3. 选择捕获后端（按优先级）

检测可用工具，并按以下顺序选择最佳工具：

1. PATH 中的 CLI 浏览器驱动程序，可接收 URL 并将屏幕截图写入磁盘，例如 playwright-cli。通过 command -v 探测每个列出的二进制文件。优先选择此项，因为它从 Bash 运行，且无需将可访问性树载入上下文；
2. 浏览器自动化 MCP（操作真实浏览器并截取屏幕截图）；
3. 计算机使用 / 桌面屏幕捕获；
4. 以上均不可用 → 降级处理：不要伪造。打印简短的手动捕获步骤（说明点击哪些内容、截取哪些屏幕），指出下一步应使用 verifykit setup 安装驱动程序，然后停止。绝不要在捕获过程中运行 setup。

在交接信息中记录所用的后端。完成条件：已选择一个后端，或已打印手动操作步骤并停止运行。

4. 处理身份验证和所需状态

verifykit 会复用状态；绝不会自行创建状态。按优先顺序：复用已通过身份验证的会话、已存储的浏览器状态文件，或项目已提供的测试凭据。如果流程受到限制，且以上都不可用，只询问一次入口 URL 和凭据（或要运行的种子命令）。如果用户无法或不愿提供，妥善降级：最多捕获到身份验证边界，并注明停止位置。运行用户交给你的种子命令，但绝不自行编造命令、填充数据库或运行迁移。

驱动之前，先限定会更改状态的流程。 驱动 UI 可能会写入数据：创建、删除、提交、付款、邀请或发送电子邮件等操作，都会像用户操作一样通过应用写入数据。若所选流程包含此类操作：

• 根据入口 URL 和应用配置，说明环境是本地环境、开发或预览部署，还是共享或生产主机。
• 列出流程将执行的每项状态更改操作，以及涉及的记录或账户。
• 仅在本地或一次性环境中使用测试数据时，才可不询问而驱动这些操作。对于任何其他主机，先询问一次并列出操作；只执行用户允许的操作。
• 如果用户拒绝，则最多捕获到该操作之前，不执行该操作，并注明边界。

完成此步骤的条件是：身份验证状态已复用、由用户提供或记录为边界，并且每项状态更改操作都已获准或记录为边界。

模式

每种模式的正文都位于 modes/ 下各自的文件中。根据 触发条件 进行路由，读取对应文件并遵循其中说明。此行以上的所有内容均适用于每种模式，不会在模式文件中重复说明。

• 模式 show → 读取 modes/show.md，然后遵循其中说明。
• 模式 proof → 读取 modes/proof.md，然后遵循其中说明。
• 模式 setup → 读取 modes/setup.md，然后遵循其中说明。

备注

• allowed-tools 覆盖主要路径。 Bash 用于运行 CLI 浏览器驱动程序、git、gh、ffmpeg、npm 和捆绑的 verify-assets.sh；Read 用于读取 diff 和关联的问题；Write 用于写入 proof 包；AskUserQuestion 用于询问流程选择、唯一一次身份验证问题，以及 setup 的安装确认。浏览器 MCP 回退方案不在此列表中，也无法加入，因为它以 MCP 工具的形式提供，名称由服务器选择（通常为 mcp__<server>__*）。如果主机严格强制执行 allowed-tools，且未安装 CLI 驱动程序，请同时授予浏览器 MCP 以及这四项工具；否则 verifykit 会按文档所述降级：打印手动捕获步骤并停止。这种降级是诚实的失败，绝不会伪造证据。
• 驱动程序 + 记录器，而非配置器。 它会复用或询问身份验证状态，并运行用户交给它的种子命令；绝不会创建测试数据、填充数据库或运行迁移。setup 只安装驱动程序，不对项目做任何操作。这样它就能在不同项目间通用。但这并不意味着它是只读的：通过驱动程序执行创建、删除或提交操作，会通过应用写入数据，因此 处理身份验证和所需状态 会在驱动之前限定这些操作。
• show 绝不会发布。 没有 GIF，没有包，没有 .gitignore 编辑，也没有隐藏引用。图片只发给操作者，不会发到其他地方。
• 不使用 mp4。 托管的 mp4 不会在 PR 正文中内嵌播放，因为 GitHub 只会渲染通过其网页编辑器上传的视频，所以证据格式为截图 + GIF。视频是有意留待日后添加的功能。
• 私有仓库。 内嵌渲染需要公开仓库。在私有仓库中，verify-assets.sh check 会失败，因此 proof 会跳过发布，并提供本地包路径供手动附加，而不是嵌入失效链接。
• 没有 Shell、没有浏览器，或没有可驱动的内容？ 如果无法运行应用或捕获内容（例如只有浏览器、没有自动化接口的 Agent），不要伪造证据。说明缺少什么，并打印手动捕获步骤供用户自行执行。