# 浏览器诊断

[English](diagnostics.md)

本插件在浏览器端输出的所有诊断信息都经由同一条分级通道（`src/client/log.ts`），因此异常可在单个控制台过滤器下浮现。该通道**刻意收窄**：`error` / `warn` 只记录插件自身检测到的、偏离预期契约的真实内部异常——**不记录**用户早已在屏幕上看到、且无归因价值的普通路径事实。

每行的形态固定为 `[dsh-rewind:<scope>] <消息> <数据>`。`scope` 标明异常所属子系统，因此可用一个 Console 过滤器抓取整份报告。

## 常开的异常告警

`error` 与 `warn` **无条件打印**——无开关、无配置，即使从未配置的用户也能看到故障：

| 级别 | 含义 | 源码中的典型来源 |
| --- | --- | --- |
| `error` | 意外、破坏性故障 | 设置表单 / 卡片 / 设置页注册失败；Chat 可见性安装探测失败 |
| `warn` | 可恢复的异常护栏 | 回退命令、输入框回填或图片还原抛出异常；等待的回退结果在超时内始终未落定；预览 / 历史 / 撤销的 RPC 调用失败或返回非法结果；回退按钮被点击但没有会话绑定；插话撤回竞争失败 |

这些情形少见、廉价、且偏离契约。普通路径的细节——回填走了哪个分支、写入是否匹配、回退切断哪些行——**刻意不记录**：它们重复用户已经看到的现象，对归因没有增量。

## 作用域

| scope | 这里的异常含义 |
| --- | --- |
| `boot` | 仅启动身份行（见下），由详细输出开关控制 |
| `refill` | 回退后的输入框回填：命令 / 等待 / 回填抛出异常、命令被拒绝或未匹配、结果在超时内始终未落定、图片引用不完整或类型不受支持、输入框拒绝还原的图片或在写入 / 聚焦时抛错 |
| `preview` | 确认弹窗与 `/rewind` 候选背后的预览 / 候选 RPC 查询：RPC 失败、结果非法、超时或抛错 |
| `history` | 回退历史与撤销端点：历史读取、`history.clear`、`caps`、`undo` 失败或返回非法结果 |
| `portals` | 每条消息按钮的挂载问题：无会话绑定、inbox 投影订阅失败 |
| `retract` | 插话撤回路径：remove 竞争失败（`info`）或抛错（`warn`） |
| `settings` | 配置卡片与「回退历史」设置页 |
| `visibility` | Chat 快照可见性包装器的安装与维护：安装探测失败、chat 视图订阅失败、chat 重建失败 |

## 启动身份行

`apply` 在每次页面加载时输出且仅输出一行 `boot`：

```text
[dsh-rewind:boot] loaded v<version> (build <hash>)
```

`<version>` 是构建时从 `package.json` 注入的插件版本，`<hash>` 是客户端源码的短内容哈希。两者由 `scripts/build.mjs` 的 esbuild `define` 块替换；在构建之外导入该模块（测试运行器）时都回退为 `dev`。这一行回答报告里最便宜也最常见的问题——*正在运行的 bundle 是不是修复过的那个*——从而排除旧缓存或宿主未重启。

该行级别为 `info`，**默认关闭**：普通用户的控制台保持干净。

## 详细输出开关

`info` 与 `debug` 受本插件独占、按 origin 隔离的 `localStorage['dsh-rewind.debug']` 开关控制，**每次调用都会读取**（从不缓存），并按命名空间过滤。因此翻开开关再刷新，对任何已发布版本立即生效，无需重建插件。未设置 / 空值即关闭；读取失败（localStorage 不可用或在销毁阶段抛错）也按关闭处理——日志绝不能让插件出错。

```js
// 仅启动身份行。
localStorage['dsh-rewind.debug'] = 'dsh-rewind:boot'

// 多个子系统，逗号分隔。
localStorage['dsh-rewind.debug'] = 'dsh-rewind:refill,dsh-rewind:portals'

// 全部开启（省去精确 scope）。
localStorage['dsh-rewind.debug'] = 'dsh-rewind*'
```

匹配遵循常见的 debug 包约定：逗号分隔的条目，每条要么是精确的 `dsh-rewind:<scope>`，要么是以 `*` 结尾的前缀；`*` 与 `dsh-rewind*` 选择所有命名空间。设置后刷新（`F5`）。关闭：

```js
delete localStorage['dsh-rewind.debug']
```

受控行走 `console.info` 而不是 `console.debug`：Chrome 默认过滤掉 "Verbose" 级别，若走后者，排查者即使打开了开关也仍然看不到。`error` / `warn` 告警**不受**该开关控制——它们总是打印。

## 采集一段报告

1. 在出问题的页面上复现一次。
2. 在 DevTools 的 Console 中按 `dsh-rewind` 过滤并复制输出。
3. 附上插件版本、DSH / 内核版本；若能取到 `boot` 行也一并附上（先开 `dsh-rewind:boot` 再刷新）。
4. 说明出问题的界面（消息行、确认弹窗、设置页），以及故障发生在对话那一半还是文件还原那一半。

`error` / `warn` 告警无需任何设置。只有需要 `boot` 行、`visibility` 安装行或 `retract` 竞争失败行时才需要开启详细输出。

## 备注

- 该诊断表面是维护者与配合排查者使用的工具，**不是**稳定公开接口；其作用域、键与输出可能不经通知而改变。
- 它受单个浏览器 origin、单个浏览器限定。请在实际出问题的地方采集：另一个窗口或全新配置文件有各自的存储与控制台。
- 宿主侧（服务端）故障不属于本通道：它们表现为命令结果文本，文件存储相关则表现为本地化的还原报告。