verify-app

验证应用

这项技能要回答的问题是：这次改动涉及哪些功能，如何在隔离实例上测试这些功能，又有什么证据能证明它们正常工作？

这项技能包含两部分，遵循 Poteto 的验证技能：远程控制（node scripts/verify.mjs，不带参数时会列出所有命令）和功能映射（docs/verify/，每个领域一个文件，且都包含相同的 4 个二级标题：子功能、如何进入、使用 verify 驱动、注意事项）。CLI 用于驱动运行中的实例，不是测试运行器。请组合使用其命令：验证时绝不要编写驱动脚本。

CLI 中与产品相关的部分（种子状态、doctor 监控的服务端文件夹、额外的 up 标志、浏览器的语言区域和权限、报告中的措辞）位于 scripts/verify-app.mjs；其余部分在所有应用中都相同。

选择流程

每个检出版本都有自己的实例：端口、数据文件夹、浏览器和日志都根据检出路径生成，并存放在 .verify/<port>/ 中。Git 工作树（git rev-parse --git-dir）不会与主检出版本或其他 Agent 的工作树冲突。

• 全新的工作树或克隆： 如果尚未安装依赖项或 Chromium，运行 node scripts/verify.mjs setup 进行安装，然后构建页面并运行 up、doctor。
• 已完成设置： 运行 up，然后运行 doctor。
• 完成后： 运行 down；cleanup 会删除此实例的数据和日志（cleanup --all 还会删除报告、追踪记录和屏幕截图）。分支推送后，请从主检出版本中自行删除工作树。

doctor 必须输出 fresh。否则，它会指出问题：STALE BUNDLE（运行 npm run build）、STALE SERVER 或提交已更改（运行 down，然后运行 up）、WRONG INSTANCE（端口或浏览器属于其他实例）。

流程

1. node scripts/verify.mjs features：列出此变更影响的每个领域；只阅读这些文件（features <area>），跨领域的变更还要阅读 journeys。阅读 docs/INVARIANTS.md 中此变更涉及的规则。
2. node scripts/verify.mjs check：运行门禁，即项目的检查命令（project.md）：lint、契约（功能映射、规则、架构规则）、单元测试、形式化模型、类型检查 + 构建、捆绑包密钥、端到端旅程。必须先通过此项，其他结果才算数。迭代时使用 check --fast；单独运行 contract 无需安装。形式化模型需要 Java：没有 Java 时，它们会标记为 未运行，门禁会显示“未完成”，绝不会显示“已通过”（formal/README.md）。
3. setup 或 up + doctor → fresh。
4. report <area…> 会写入 .verify/report-<branch>.md，这是需要填写的模板。
5. 使用 seed <state> 将实例设置为所需状态，而不是逐个点击；要获得空白实例则使用 reset。对于运行中的状态（重新加载或运行中切换）：先执行 down，再执行 up --delay 4000。
6. 执行 mark "<what you test>"，然后像用户一样操作该功能：open、click、type、upload、press、wait-settle。
7. 收集证明：操作后以及重新加载后调用 api <route>（open "/" 会重新加载）；运行 network-summary --since-mark（操作发出的请求、状态、失败）；运行 console --errors --since-mark（无页面错误）；运行 snapshot，或为产品负责人运行 screenshot。当审核者需要重放操作时，运行 trace start … trace stop（npx playwright show-trace <zip>）；对于页面重量问题，运行 perf。
8. 在任何状态下检查前端规则：运行 a11y（无障碍名称缺失的控件、Tab 顺序：APP-F6），然后运行 viewport 375 812，再运行 overflow 和 screenshot（手机宽度：APP-F7），最后运行 viewport 1440 900。
9. 默认使用模拟模型：它们检查的是连接流程，而非措辞。若变更涉及 Agent 输出内容，请说明需要使用 up --real。仅在检查 Agent 行为时使用 up --real，并在 CODEX_AUTH_FILE 中提供 Codex 登录信息。
10. 如果变更新增或修改了用户可见内容，请在同一分支中更新 docs/verify/ 下对应的文件（跨领域时还要更新 test/e2e/ 中的旅程）。如果文件缺少四个 H2 标题，check 会拒绝通过。如果变更影响规则的证明方式，请更新 scripts/verify/VERIFY.json：缺少证据且没有记录延期的规则会被 check 拒绝通过。

证明标准

证明必须走生产路径，并展示持怀疑态度的审核者也会认可的结果。

• 通过页面及其常规服务端调用进行操作。eval 会在用户路径运行后读取状态；post 只会准备状态，作用类似 seed：两者都不算证明。api/post --bearer <token> 会使用该令牌的身份。
• 来自非 fresh 实例的证明不算证据。
• 覆盖所有可到达的入口点，以及变更可能影响的成功、失败、空状态、取消/重新运行和持久化路径（领域文件会列出这些路径；旅程中的 page.route 或已停止的服务端会导致请求失败）。
• 同时展示触发操作和稳定的最终状态（mark、操作、--since-mark 证据）。
• 关注副作用，而非像素：已存储的记录（api /api/<route>）、运行行（api /api/runs）、重新加载或 down/up 后的状态。
• 模拟模型之所以算数，只因它们位于生产边界之后（模型提供方处于相同的运行时、服务端和 Web 环境中）。任何绕过 Web 或服务端的方式都不能证明页面已覆盖。
• 说明哪些内容无法到达（原生文件选择器、操作系统拖放、真实提供方、仅限生产环境），并说明你实际覆盖的最接近路径。

证据：先采用成本最低且足够的方式

lint + contracts + unit tests → formal models → end-to-end journeys (fake models)
→ driven instance (verify) → real models on the instance (up --real)
→ the people's own use

通过较低层级的检查绝不能证明更高层级的主张：单元测试通过并不能说明页面正常；模拟模型旅程也不能说明措辞正确。

切勿

• 仓库、测试、夹具、报告或已提交的截图中不得出现任何真实用户数据：只能使用虚构数据。
• 不得将生产环境用作测试平台。verify up 实例归你使用；生产环境属于用户（docs/verify/deploy.md 是部署后的只读检查）。
• 不得仅凭合并、CI 通过或部署就声称“已验证”：实际运行了什么、在哪里运行，是发布技能要回答的问题；“未知”也是有效答案。

声称已验证前先提交报告

填写 .verify/report-<branch>.md（使用 report <area…>），并将其粘贴到拉取请求中（即 .github/pull_request_template.md 中的证据表）：

• 提交、doctor 行、check 结果（以及是否运行了形式化模型）、模型（虚拟 / 真实）；
• 按区域列出：执行过的路径、命令、观察到的副作用（关键输出）；
• 跳过或无法访问的路径：每条路径受阻的原因，以及覆盖到的最接近的真实路径；
• 此处未能证明的内容（例如：措辞需要真实模型）。