verifykit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

verifykit

Drive a just-built frontend feature the way a user would, capture what happens (screenshots at each meaningful state plus one short animated GIF of the flow), and publish that proof so a pull request can embed it inline. verifykit is the step between reviewing the code and opening the PR: reviewing reads the source, this exercises the running feature and produces visual evidence it works.

It is a driver and recorder, nothing more. It does not write tests (that's a test-suite skill, testkit when it's installed), does not produce a human checklist (that's a manual-QA skill), and does not provision environments. It drives the UI it's given and records what it sees.

以用户操作的方式运行刚开发完成的前端功能，捕获运行过程（每个关键状态的截图，以及整个流程的短动画GIF），并发布这些验证证据，以便在拉取请求（PR）中内嵌展示。verifykit是代码评审与发起PR之间的环节：代码评审是查看源码，而本工具会实际运行功能并生成视觉证据证明其可用。

它只是一个驱动与录制工具，仅此而已。它不会编写测试（那是测试套件工具的功能，比如安装后的testkit），不会生成人工检查清单（那是人工QA工具的功能），也不会配置环境。它只会驱动给定的UI并录制所见内容。

When this fires

触发场景

After a frontend feature is built and you want proof it works before the PR: "verify this", "capture the feature working", "record the flow", "prove the UI change", "/verifykit", or a PR step that needs proof artifacts. It captures a running feature with a visual surface. If the change is backend/CLI-only with nothing to drive, say so and stop rather than inventing a flow.

Distinct from a manual-QA plan (which a human runs) and from a code review (which reads source). verifykit is the automated drive-and-record; if the user actually wants a hand-test checklist or a source review, point them at the right skill instead of capturing.

当前端功能开发完成，在发起PR前需要验证其可用时：比如执行「验证此功能」「捕获功能运行状态」「记录功能流程」「证明UI变更有效」「/verifykit」指令，或者PR流程需要附加验证工件时。本工具会捕获带可视化界面的运行中功能。如果变更仅涉及后端/CLI，无UI可驱动，则直接说明并终止操作，而非虚构流程。

本工具区别于人工QA计划（由人类执行）和代码评审（查看源码）。verifykit是自动化的驱动与录制工具；如果用户实际需要人工测试清单或源码评审，应引导其使用对应工具，而非执行捕获操作。

Procedure

操作流程

1. Scope the feature and find the entry point

1. 确定功能范围与入口点

Ground the run in what actually changed. Read

git diff

(and the linked issue/plan when there is one) to learn which screens, routes, components, or flows the change touches. Determine how to launch the app and reach the feature: the dev-server command and URL. If the project already documents how it runs, follow that; otherwise infer it and confirm the entry URL before driving.

Pick a slug for this run: the linked issue number when there is one, else a short lowercase kebab-case feature slug from the branch/diff (e.g.

login-throttle

). Form the bundle name as

verify-<slug>-YYYY-MM-DD

, using the run's ISO creation date at the end. Everything for the run is grouped under it.

基于实际变更内容确定运行范围。查看

git diff

（如有关联的需求/计划文档也一并查看），了解变更涉及的页面、路由、组件或流程。确定启动应用并进入功能的方式：开发服务器命令与URL。如果项目已有运行文档，遵循文档操作；否则推断运行方式并在开始驱动前确认入口URL。

为本次运行选择一个标识（slug）：如有关联需求编号则使用该编号，否则从分支/变更内容中提取简短的小写短横线命名的功能标识（例如

login-throttle

）。将包名格式化为

verify-<slug>-YYYY-MM-DD

，末尾添加运行的ISO格式创建日期。本次运行的所有内容都将归为此包名下。

2. Choose the flows to drive

2. 选择要驱动的流程

Derive candidate flows from the diff as distinct user entry points: a changed route/page, a form or dialog, a component tied to a user action. Then:

Explicit instruction wins. If the invocation names a flow ("verify the checkout flow"), drive that.
One flow touched → drive it, no question.
Multiple flows touched → list the candidates with short labels and ask the user which to verify (allow selecting several). Drive each chosen flow and label its captures as a separate section. Never silently guess a "primary" flow.

从变更内容中推导候选流程，作为不同的用户入口：变更的路由/页面、表单或弹窗、与用户操作关联的组件。然后：

明确指令优先。如果调用时指定了流程（如「验证结账流程」），则驱动该流程。
仅涉及一个流程 → 直接驱动该流程，无需确认。
涉及多个流程 → 列出候选流程及简短标签，询问用户要验证哪些流程（允许多选）。对每个选中的流程分别驱动，并为其捕获内容标注单独章节。绝不擅自猜测「主要」流程。

3. Pick the capture backend (by precedence)

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

Detect what's available and use the best, in order:

a browser-automation MCP (drives a real browser, takes screenshots), preferred;
computer use / desktop screen capture, the fallback;
neither → degrade: don't fake it. Print a short manual capture recipe (what to click, what to screenshot) and stop.

Record which backend was used in the run notes.

检测可用工具并按以下优先级选择最优方案：

浏览器自动化MCP（驱动真实浏览器，捕获截图），优先选用；
计算机操作/桌面屏幕捕获，作为备选；
均不可用 → 降级处理：不伪造证据。输出简短的人工捕获指南（点击位置、截图节点）并终止操作。

在运行笔记中记录使用的捕获后端。

4. Handle auth and required state

4. 处理认证与必要状态

verifykit reuses state; it never manufactures it. In order: reuse an already-authenticated session, a stored browser state file, or test credentials the project already exposes. If the flow is gated and none is available, ask once for the entry URL and credentials (or a seed command to run). If the user can't or won't provide them, degrade gracefully: capture up to the auth boundary and note where it stopped. Run a seed command you're handed, but never invent one, seed a database, or run migrations yourself.

verifykit会复用现有状态，绝不自行创建状态。优先级如下：复用已认证的会话、存储的浏览器状态文件，或项目已公开的测试凭据。如果流程需要认证且无可用状态，仅询问一次入口URL和凭据（或运行初始化命令）。如果用户无法或不愿提供，则优雅降级：捕获到认证边界为止，并记录终止位置。仅运行用户提供的初始化命令，绝不自行创建命令、填充数据库或执行迁移。

5. Drive and capture

5. 驱动与捕获

Walk each selected flow along its primary happy path as a user would. Capture a screenshot at every meaningful state (initial, mid-flow, error/empty states the change introduces, success), and a short animated GIF of the whole flow. Keep the GIF proof-grade, not cinema: a few frames per second, modest width, a short clip. When stitching frames into a GIF,

ffmpeg

works well if present:

ffmpeg -y -framerate 2 -i frame-%02d.png -vf "scale=800:-1" flow.gif

Cap the frame rate and width so the GIF stays small (a proof GIF is typically a few hundred KB; screenshots ~100 KB).

按照用户操作的主路径遍历每个选中的流程。在每个关键状态（初始状态、流程中状态、变更引入的错误/空状态、成功状态）捕获截图，并捕获整个流程的短动画GIF。确保GIF符合验证要求，而非高质量视频：每秒几帧、适中宽度、简短片段。如果需要将帧拼接为GIF，若环境中存在

ffmpeg

，可使用以下命令：

ffmpeg -y -framerate 2 -i frame-%02d.png -vf "scale=800:-1" flow.gif

限制帧率和宽度，确保GIF体积较小（验证用GIF通常为几百KB；截图约100KB）。

6. Write the bundle

6. 生成验证包

Save the captures to

docs/verify/verify-<slug>-YYYY-MM-DD/

(for example,

docs/verify/verify-login-throttle-2026-07-23/

): the screenshots, the GIF, and a fixed

notes.md

recording the flows driven, the capture backend used, per-step pass/fail, the environment, and any auth boundary the run stopped at. Keep the creation date stable when updating the same bundle. For a genuine same-day collision between distinct runs, make the slug more specific; only as a last resort insert a sequence immediately before the date (

verify-login-throttle-02-2026-07-23

). This directory is ephemeral, because the assets get published to a hidden git ref (below) rather than committed to the branch, so add

docs/verify/

.gitignore

将捕获内容保存至

docs/verify/verify-<slug>-YYYY-MM-DD/

（例如

docs/verify/verify-login-throttle-2026-07-23/

）：包含截图、GIF，以及固定的

notes.md

文件，记录驱动的流程、使用的捕获后端、每一步的成功/失败状态、环境信息，以及运行终止的认证边界（如有）。更新同一包时保持创建日期稳定。若同一天内不同运行出现标识冲突，可细化标识；仅在万不得已时在日期前添加序号（如

verify-login-throttle-02-2026-07-23

）。该目录为临时目录，因为资产会发布到隐藏的git引用（见下文）而非提交到分支，因此需将

docs/verify/

添加到

.gitignore

。

7. Publish so a PR can embed the proof

7. 发布以便PR内嵌证据

GitHub can't inline media from

gh

, and committing proof GIFs to the branch bloats the repo's history for every clone forever. Instead, publish to a hidden git ref (

refs/verify-assets/<slug>

). The assets live in the repo but a normal

git clone

never fetches that namespace, so there's zero clone bloat, and they render inline in a PR body via SHA-pinned

raw.githubusercontent.com

URLs. This needs a public repo (GitHub's image proxy can't authenticate into a private one).

The fragile git plumbing lives in the bundled verify-assets.sh
next to this file. Resolve the installed skill directory and call the script there; the current working directory is the target project, not the skill directory. Don't hand-run the plumbing:

VERIFY_ASSETS="<path-to-this-skill>/verify-assets.sh"

if bash "$VERIFY_ASSETS" check; then
  # publish the bundle; prints the commit SHA to embed
  SHA=$(bash "$VERIFY_ASSETS" publish <slug> docs/verify/verify-<slug>-YYYY-MM-DD/*)

  # resolve the inline-rendering URL for each file
  bash "$VERIFY_ASSETS" url <slug> "$SHA" flow.gif
else
  # private repo: skip publishing and write proof.md with local paths
  echo "private repo: link the local bundle in proof.md for manual attachment"
fi

The script also offers

list

(show all

refs/verify-assets/*

) and

delete <slug>

(remove a ref after its PR merges).

Then write the ready-to-embed proof into the bundle's fixed proof.md
(

docs/verify/verify-<slug>-YYYY-MM-DD/proof.md

), a Markdown fragment embedding the GIF and screenshots by their SHA-pinned raw URLs, captioned per flow. This file is the hand-off contract: the PR step reads it and splices it straight into the pull request body, so it never re-runs the publish. On a private repo (publish skipped), write

proof.md

with the local file paths and a note that they need manual attachment, so the PR step can still surface them.

GitHub无法内嵌来自

gh

的媒体文件，且将验证GIF提交到分支会永久增加仓库克隆的历史体积。因此，需将资产发布到隐藏git引用（

refs/verify-assets/<slug>

）。资产存储在仓库中，但默认

git clone

不会获取该命名空间，因此不会增加克隆体积，且可通过SHA固定的

raw.githubusercontent.com

URL在PR正文中内嵌展示。此方式需要仓库为公开（GitHub图片代理无法访问私有仓库）。

相关的git底层操作已封装在本工具附带的**

verify-assets.sh

**脚本中。找到已安装工具的目录并调用该脚本；当前工作目录为目标项目目录，而非工具目录。请勿手动执行底层操作：

VERIFY_ASSETS="<path-to-this-skill>/verify-assets.sh"

if bash "$VERIFY_ASSETS" check; then
  # 发布验证包；输出用于内嵌的提交SHA
  SHA=$(bash "$VERIFY_ASSETS" publish <slug> docs/verify/verify-<slug>-YYYY-MM-DD/*)

  # 解析每个文件的内嵌展示URL
  bash "$VERIFY_ASSETS" url <slug> "$SHA" flow.gif
else
  # 私有仓库：跳过发布，在proof.md中写入本地路径
  echo "private repo: link the local bundle in proof.md for manual attachment"
fi

该脚本还支持

list

（显示所有

refs/verify-assets/*

）和

delete <slug>

（PR合并后删除引用）命令。

随后将可直接内嵌的验证内容写入验证包中固定的**

proof.md

**文件（

docs/verify/verify-<slug>-YYYY-MM-DD/proof.md

），这是一个Markdown片段，通过SHA固定的原始URL嵌入GIF和截图，并为每个流程添加说明。该文件是交付契约：PR流程会读取此文件并直接插入到PR正文中，无需重新执行发布操作。对于私有仓库（跳过发布），在

proof.md

中写入本地文件路径并标注需要手动附加，以便PR流程仍能展示这些内容。

8. Hand off

8. 交付

Write this section in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.

Report the bundle path, the flows verified (with pass/fail), the capture backend used, and, when published, the commit SHA and the ready-to-embed raw URLs. Offer the PR step next: the artifacts are ready for a pull request's Proof section. Don't open the PR from here.

本节采用操作式表述：每句一个指令，主动语态，现在时，无比喻。

报告验证包路径、已验证的流程（含成功/失败状态）、使用的捕获后端，以及发布后的提交SHA和可直接内嵌的原始URL。接下来可执行PR流程：验证工件已准备好用于拉取请求的验证部分。请勿在此步骤发起PR。

Notes

注意事项

allowed-tools
covers the built-ins only, and the capture backend needs one thing more. The declared four are what verifykit runs itself:
```
Bash
```
for git,
```
gh
```
,
```
ffmpeg
```
, and the bundled
```
verify-assets.sh
```
;
```
Read
```
for the diff and the linked issue;
```
Write
```
for the bundle;
```
AskUserQuestion
```
for the flow choice and the one auth ask. The browser-automation surface is not in that list and cannot be, because it arrives as MCP tools whose names the server chooses (commonly
```
mcp__<server>__*
```
), so no list written here can name them in advance. On a host that enforces
```
allowed-tools
```
strictly, grant the browser MCP alongside these four, or verifykit will find no capture backend and take its documented degradation: print the manual capture recipe and stop. That degradation is the honest failure, and it never fakes proof.
Driver + recorder, not a provisioner. It reuses or asks for auth and runs a seed command it's handed; it never creates fixtures, seeds databases, or runs migrations. This keeps it safe (it can't mutate real data) and portable across projects.
No mp4. A hosted mp4 does not embed inline in a PR body, because GitHub only renders video uploaded through its web composer, so the proof format is screenshots + GIF. Video is a deliberate later add.
Private repos. Inline rendering needs a public repo. On a private one,
```
verify-assets.sh check
```
fails, so skip publishing and hand off the local bundle path for manual attachment rather than embedding dead links.
Zero clone bloat is the point. Proof is never committed to the branch; it lives on
```
refs/verify-assets/*
```
, which default clones skip. Old refs accumulate on the remote but never in anyone's clone, so prune them with
```
verify-assets.sh delete <slug>
```
once a PR merges.
No shell, no browser, or nothing to drive? If there's no way to run the app or capture it (e.g. a browser-only agent with no automation surface), don't fake proof. Say what's missing and print the manual capture recipe for the user to run themselves.

allowed-tools
仅包含内置工具，捕获后端还需额外权限。声明的四个工具是verifykit自行运行的工具：用于git操作的
```
Bash
```
、
```
gh
```
、
```
ffmpeg
```
以及附带的
```
verify-assets.sh
```
；用于查看变更和关联需求的
```
Read
```
；用于生成验证包的
```
Write
```
；用于询问流程选择和认证信息的
```
AskUserQuestion
```
。浏览器自动化工具不在此列表中，也无法提前列入，因为它们是以MCP工具形式存在，名称由服务器指定（通常为
```
mcp__<server>__*
```
），因此此处无法提前列出。在严格限制
```
allowed-tools
```
的环境中，需为浏览器MCP授予与上述四个工具相同的权限，否则verifykit将无法找到捕获后端并按文档降级处理：输出人工捕获指南并终止操作。这种降级是合理的失败处理，绝不伪造证据。
仅做驱动与录制，不做环境配置。它会复用或请求认证信息，仅运行用户提供的初始化命令；绝不创建测试数据、填充数据库或执行迁移。这确保了工具的安全性（不会修改真实数据）和跨项目的可移植性。
不支持mp4。托管的mp4无法在PR正文中内嵌展示，因为GitHub仅渲染通过网页编辑器上传的视频，因此验证格式为截图+GIF。视频支持会在后续版本中添加。
私有仓库。内嵌展示需要公开仓库。对于私有仓库，
```
verify-assets.sh check
```
会失败，因此需跳过发布，交付本地验证包路径以便手动附加，而非嵌入无效链接。
零克隆体积是核心目标。验证内容绝不会提交到分支；它存储在
```
refs/verify-assets/*
```
中，默认克隆会跳过该路径。远程仓库会累积旧引用，但不会进入任何人的克隆，因此PR合并后可使用
```
verify-assets.sh delete <slug>
```
清理这些引用。
**无Shell、无浏览器或无可驱动内容？**如果无法运行应用或捕获内容（例如仅支持浏览器但无自动化能力的代理），绝不伪造证据。说明缺失的条件并输出人工捕获指南，供用户自行执行。