# 浏览器诊断

[English](diagnostics.md)

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

## 常开的异常告警

`error` 与 `warn` **总是打印**（无需开关、无需配置），即使从未配置的用户也能看到故障：

| 级别 | 含义 |
| --- | --- |
| `error` | 意外/破坏性故障（如设置卡片注册失败） |
| `warn` | 可恢复的异常护栏（如回退命令/回填抛出异常、等待的结果始终未落定、会话绑定缺失） |

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

## 作用域

诊断以 `[dsh-rewind:<scope>] ...` 形式打印。`scope` 标明异常所属子系统，因此可用单个控制台过滤器抓取报告：

| scope | 这里的异常含义 |
| --- | --- |
| `boot` | 启动身份行——`loaded v<version> (build <hash>)`，由详细输出开关控制（见下）。用于确认运行中的 bundle 是否匹配某个修复。 |
| `refill` | 回退后的输入框回填（命令/等待/回填抛出异常、命令被拒绝或未匹配、等待的结果始终未落定） |
| `preview` | 模式气泡背后的 `/rewind preview` 影响探测（命令被拒绝/未匹配/抛出异常、等待的结果始终未落定） |
| `portals` | 每条消息按钮的挂载问题（如无会话绑定） |
| `settings` | 快照清理设置卡片 |
| `hiding` | **保留区**——当前无活跃告警。若未来新增行隐藏诊断，应归属此区域。 |

## 详细输出开关

`info`/`debug` 级别受 `localStorage['dsh-rewind.debug']` 控制，每次调用读取并按命名空间过滤。在撤下那些复述现象的详细输出后，**恰好剩一条** verbose 行：`boot` 作用域的启动身份行。它**默认关闭**（普通用户控制台保持干净，且它不是异常），排查者需先开启该作用域才能看到：

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

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

设置后刷新（`F5`）。关闭：

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

`error`/`warn` 异常告警**不受**该开关控制——它们总是打印。其余详细输出（所用写入通道、空的隐藏集、每次回退的生命周期行）已撤下：它们重复用户已经看到的现象、无归因增量。

## 采集一段报告

1. 在出问题的页面上复现一次。
2. 在 DevTools 里把 Console 按 `[dsh-rewind]` 过滤，复制输出（连同插件版本、DSH/内核版本）。

`error`/`warn` 异常告警无需任何设置——它们总是打印。若要同时采集启动身份行（`boot`，用于排除「旧 bundle / 宿主未重启」），请先开启详细输出开关（见上），再刷新。

## 备注

- 该诊断表面是维护者与配合排查者使用的工具，**不是**稳定公开接口；其具体键与输出可能不经通知而改变。
- 它受单个浏览器 origin、单个浏览器限定；请在实际出问题的地方采集。