verify-ui-change

在运行中的应用中验证更改

你编辑了用户可以看到的内容。在真实应用中实际运行，并且得到 DOM 以外的信息印证之前，一切都不能算已验证。

本文使用 Reticle：它会在用户正在运行的应用中嵌入仅供开发使用的 SDK，并将其作为 reticle_* MCP 工具提供。验证过程中无需截图、无需下载浏览器，也无需启动它自己的开发服务器。

1. 这些工具可用吗？

reticle_session({ action: "list" })

• 返回了会话 → 继续第 2 步。
• 工具不存在 → 尚未安装 Reticle。先征求用户同意：init 会更改 package.json、锁文件和构建配置。若用户同意，运行 RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init，然后在没有这些工具的情况下继续：修复它打印的每个 ⚠，如果当前没有服务正在提供应用，就在后台运行项目自己的开发脚本，然后使用 npx @reticlehq/server open <the url the dev server is serving> 打开应用。只有等应用运行并连接后，才请用户帮你做一件你无法自行完成的事：重启客户端，让它加载 MCP 服务。若止步于 init 命令，用户只会得到配置文件和一个未经插桩的页面。完整设置说明见 reticle 技能。
• 工具存在，但列表为空 → 如果有 next_step，先阅读它：其中会询问是否同意运行 init，并会在应用正在运行时指出零安装租约。否则阅读响应中的 why 字段。它会区分“没有应用在运行”“有应用在运行，但从未连接到此守护进程”和“之前打开过标签页，但已经关闭”，每种情况都有不同的修复方法。如果没有应用在运行，就自行在后台运行 package.json 中项目自己的开发脚本，并用一句话告诉用户它正在运行以及如何停止：绝不能启动第二个，绝不能猜测命令，绝不能终止任何进程；权限提示由你的宿主处理。如果确实有应用在运行，缺少的就不是应用，而是 SDK；不要让用户去启动已经启动的东西。

2. 操作之前，先明确预期结果

这就是整个方法。在看到结果后才写下预期，可以让人把任何结果都解释成符合预期；而事先写下的预期则不行。

reticle_look({ action: "page", sessionId, mode: "interactive" })   // controls only, with refs

reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf", predicates: [
  { kind: "net",     method: "POST", urlContains: "/api/...", status: 200 },
  { kind: "element", query: { testid: "..." } },
  { kind: "console", level: "error", absent: true },
]}})

需要多步操作的流程？用一次调用 reticle_act { steps: [...] } 完成操作，然后只断言一次结果。不要按“操作 → 快照 → 操作 → 快照”的顺序进行：那只会以几倍的成本证明同一件事。

只有 reticle_act_and_wait、reticle_assert，以及带有 expect 的 reticle_act { steps } 才会给出判定。 单独调用 reticle_act、look、navigate 和 observe 只会操作或读取应用，不能证明任何事情。一次操作若结束时没有判定，就没有结果，无论它调用了多少次。

3. 如实解读判定

verified	含义	操作
yes	你事先说明的结果确实发生了	报告结果，并附上证据
no	结果没有发生，或某个通道的信息与 UI 矛盾	这是实际发现：附上 because 一并报告
unknown	Reticle 操作了应用，但无法判断	这不算通过。 说明结果未知，并解释原因

对于 unknown / unsettled，应重新断言，而不是重新操作：使用操作结果中的 since，调用 reticle_assert({ predicate, since, timeout_ms: 8000 })。重新操作会重复已经发生的副作用。

绝不要为了让判定变成绿色而放宽检查。 不断修改断言直到通过，什么也证明不了。

4. 检查你没有触及的部分

reticle_run({ tool: "reticle_verify", sessionId, args: { action: "coverage" } })   // { total, exercised, untouched }

如果 untouched 仍包含受你更改影响的控件，这次操作就还没完成。只需一次调用，就能以最低成本避免只打开一半内容却报告通过。

5. 报告

说明你执行了什么、结果如何以及证据：请求和状态、发生变化的状态、应用自身的信号。如果发生故障，使用 reticle_look({ action: "element", sessionId, ref }) 检查故障元素可获取 file:line：将其写入报告。

然后调用 reticle_session({ action: "yield", mode: "waiting" })，这样人类的面板就不会再显示“live”。

---

更多详情可逐页获取：运行 curl https://docs.reticle.sh/llms.txt 获取索引，然后获取所需的单个页面（https://docs.reticle.sh/tools/act-and-wait.md、https://docs.reticle.sh/predicates.md、https://docs.reticle.sh/troubleshooting.md）。如果 Reticle 本身出现异常，使用 reticle_session { action: "feedback" } 提交反馈：调用一次，然后继续。