debug-broken-ui

应用出问题了，但代码看起来没问题

再读一遍源码也无法告诉你原因。证据就在运行中的应用里，而且大部分证据根本不会显示在屏幕上：失败的请求、没有变化的 store、从未绑定的处理程序、被不可见元素遮挡的元素。

Reticle 会从页面内部读取所有这些信息。尚未设置？请遵循 reticle 技能：它会安装 Reticle，在 init 更改应用文件前征求用户同意，并验证一个工作流。

别从猜测开始。从重现问题开始。

reticle_look({ action: "page", sessionId, mode: "interactive" })   // controls only, with refs
reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "element", query: { testid: "..." } } })

判定结果已经缩小了范围：no / contradicted 表示某个通道发现了与 UI 不一致的情况：这就是 bug。unknown 表示 Reticle 执行了操作，但无法判断；这与“操作失败”是不同的调查方向。

先阅读 act 结果，再调用其他内容。 它的 summary 块已经包含了这次点击的完整因果窗口：net {total, errors, headline}、consoleErrors、stateDiffs [{path, from, to}]、storageDiffs [{key, from, to}]、route、signals、layoutShift、longTasks：是真实的前后差异，不是计数。下面的控制台、网络、存储和状态调用，是为了进一步查看摘要已指向的问题。紧接着 act 就把这三项全都调用一遍，会多花三轮模型往返（在需要审批的客户端中，还要用户点击三次），只为查看你已经掌握的证据。

summary.stateUnwatched: true 表示状态通道未启用：没有注册可订阅的 store，因此空的 stateDiffs 意味着 未监控，而不是 未变化；在有人注册 store 之前，也无法得出任何基于状态的结论。这是这里唯一一个描述检测工具而非应用本身的字段。

当摘要确实指向某个通道时，请限定到刚才执行的操作来读取该通道：传入 act 结果中的 since，否则你读到的缓冲区可能早于这次点击：

reticle_observe({ action: "console", sessionId, since })
reticle_observe({ action: "network", sessionId, since })
reticle_look({ action: "state", sessionId, store })

诊断表

你看到的情况	问题所在	下一步
完全没有发出请求	处理程序未绑定，或者客户端缓存返回了过期值	对该元素运行 reticle_look { action: "element" }，查看其 file:line；如果使用 TanStack Query，请检查缓存
已发出请求，返回 4xx/5xx	UI 隐藏了真实的后端故障	响应正文位于网络条目中
返回 2xx，但没有变化	应用根本没有读取响应：判定结果为 outcome_unread	通常是成功路径中的真实 bug
请求正常，DOM 正常，store 未更新	UI 与状态不同步，截图无法发现	只有 reticle_look { action: "state" } 能发现；这是这里最有价值的查看项
点击无效，也没有错误	控件已失效、被遮挡或处于禁用状态	reticle_look { action: "element" } 会返回 occluded、box（0×0）、styles.cursor、opacity
提示元素“未找到”，但你能看到它	虚拟列表尚未挂载该元素	reticle_run({ tool: "reticle_scroll_to", args: { by: "text", value } })。find 找不到，并不能证明元素不存在
看起来已登录，行为却像未登录	令牌从未持久化	reticle_run({ tool: "reticle_storage", args: {} })
控制台错误早于你的点击	这是已有故障，不是你的 bug	继续操作前先指出这一点

找到文件，而不是停留在推测

reticle_look({ action: "element", sessionId, ref })

这会返回你正在查看的元素所属组件，以及 source: { file, line }，并说明元素是否被遮挡、是否有尺寸、是否禁用或是否偏离主题。这个位置就是你应该打开的文件。调查结束时应给出具体位置，而不是假设。

工作流较长时

不要在 act → snapshot → act → snapshot 之间来回切换，只为找到失败步骤。用 reticle_act { steps: [...] } 执行整个流程，然后断言一次；第一个后果不符合预期的步骤就是要检查的地方，而且找到它所需的调用少得多。

在说问题已修复之前

将复现操作作为判定重新运行（使用 reticle_act_and_wait，并在开头说明预期结果），而不是凭肉眼查看页面。通过观察页面确认修复，正是导致这张工单的失效模式。

绝不要为了让检查通过而放宽检查条件。

---

排查 Reticle 本身的问题（而非应用）：curl https://docs.reticle.sh/troubleshooting.md。其他所有问题：curl https://docs.reticle.sh/llms.txt。如果 Reticle 无法看到你需要的内容，请使用 reticle_session { action: "feedback" }，并设置 kind: "gap"。