dsh-docx-sidebar
在 DSH 右侧栏阅读 .docx（dsh-better-sidebar 消费者）：标题层级、段落、列表缩进、真表格、内联图片，带熔断保护。
这是阅读视图，不是版式还原。 界面顶部直接标着这句话 —— 不做分页、不还原字体、不处理浮动/分栏/修订痕迹。让用户误以为排版差异是 bug，比明说能力边界更糟。
一、做到什么 / 不做什么
| 做到 | 说明 |
|---|
| 标题层级 | 由 styles.xml 的样式名称决定（heading 1 → w:h1），不靠 id 尾数字猜；w:outlineLvl 兜底 |
| 段落与行内格式 | 粗体、斜体、下划线、w:tab/w:br、等宽（rStyle/rFonts 命中 monospace） |
| 列表 | w:numPr + w:ilvl → 缩进层级（不重建编号序列） |
| 表格 | w:tbl → w:tr → w:tc，单元格内多段落合并；不会再作为正文段落重复出现 |
| 图片 | 从归档里取出字节 → blob: URL（内联图在 zip 内，没有宿主路由可指）；EMF/WMF/TIFF 渲染不了 → 标注占位 |
| 页眉/页脚 | 作为带标签的 note 块置顶/置底 |
| 公式 | 不排；只显示文件里存的文本 |
不做：分页与页边距、字体与字号还原、浮动/锚定对象、分栏、修订痕迹（w:ins/w:del）、批注、编号序列重建、公式排版。
二、宽度自适应
侧栏面板可拖动，阅读视图因此随宽度缩放 —— 但有上下限，「自适应」不是无限放大或无限缩小的许可：
| 旋钮 | 取值 | 理由 |
|---|
| 基准宽度 | 360px | 此宽度下比例恰为 1，即常见的面板宽度渲染出的就是 0.1.0 那套版式 |
| 下限 | 0.9× | 面板再窄，字也要能读 |
| 上限 | 1.15× | 面板再宽也只是舒适，不是巨大 |
| 量化 | 两位小数 | 拖动只在 0.01 台阶上重排，不是每像素 |
比例由容器宽度推出，写进 CSS 变量 --reader-scale；根字号为 13px × 比例，正文全部用 em，所以文字是重新折行到新字号，而不是整体 transform 缩放（那会让字发虚）。
只有文档内容缩放。 标题、段落、列表、代码、备注、表格与图片说明跟随比例；信息条、页眉页脚标签以外的界面元素、熔断横幅、加载/空态保持固定字号 —— 拖分隔条时界面文字跟着变会像故障，而不是像自适应。
两个相关决定：
- 不可测量的宽度回退到 1，而不是取极值。 首帧宽度是 0，若按「尽可能窄」渲染，每次打开文档都会闪一下极小字号。
- 图片不参与缩放。 按文档声明的尺寸显示，仅以面板宽度封顶；把位图放大到超过原始尺寸去追字号只会更糊，谈不上更还原。
三、读取管线
归档字节（宿主 /sidebar/file 路由，二进制）
→ 中央目录（声明的解压体积前置核对）
→ 流式解压 + 字节预算（边解压边计数，越界即 cancel）
→ word/document.xml 正文块（顺序扫描，跳过表格内部的段落）
→ word/_rels/document.xml.rels rId → 图片 / 页眉页脚目标（External 忽略）
→ word/styles.xml 样式 id → 标题层级
→ word/media/* 图片字节（按需，超限直接跳过、不解压）
零运行时依赖：zip 解压用浏览器原生 DecompressionStream('deflate-raw')，XML 用针对性扫描（WordprocessingML 是机器生成的规整结构，且正则无法平衡同名嵌套，所以 findElements 用深度计数）。
四、熔断（七道）
| 维度 | 默认 | 越界后 |
|---|
| 归档大小 | 5 MB | BLOCKED（未解压任何东西） |
| 累计解压 | 64 MB | BLOCKED —— 抗 zip 炸弹 |
| 单个部件 | 32 MB | BLOCKED |
| 块数 | 5 000 | TRUNCATED，停止读取 |
| 单块文本 | 20 000 字符 | 该块省略 + 警告 |
| 图片张数 | 200 | 跳过后续 + 警告 |
| 单张图片 | 8 MB | 该图跳过（体积在目录里就超限则不解压）+ 警告 |
每个维度最多一条警告是结构性保证（breaker 内部按 reason 建 Map），不是约定：同一维度触发两次会在横幅上渲染两行几乎一样的字 —— 兄弟插件曾因此发过一个补丁版。
被熔断的结果是一等公民：BLOCKED 渲染成可读的错误卡，永不抛异常、永不无限转圈。
五、构建与验证
npm run build # esbuild 双入口 + tsc 类型声明；构建期用 node:vm 真加载一次 bundle 并断言 apply/inject
npm test # 14 项断言
npm run verify # build && test
测试夹具是现场构造的真实 docx zip（正确的 CRC32 与中央目录，引用一张真 1×1 PNG），覆盖：样式名判定标题（List1 不得误判）、行内格式、列表层级、表格且单元格不重复成段、EMU→px、不可渲染格式占位、页眉 note 与 External 关系忽略、计数自洽，以及五道闸门与 zh/en 占位符完整性。
六、安装
# 官方 CLI（推荐；会一并维护依赖与 dsh.profile.bundles）
dsh plugin --profile <profile> add <path | npm 包 | github:owner/repo#<sha>>
手动安装是三步，缺一不可（只做第 1、3 步 = 插件永不加载且不报错）：① 复制到 profile 的 node_modules/；② 把 dsh-docx-sidebar 加进该 profile package.json 的 dsh.profile.bundles；③ 把本包 cordis.patch.yml 的 insert 行追加到 profile 的 cordis.patch.yml。
装完先离线验证再重启：
dsh --profile <profile> --dump-config | Select-String dsh-docx-sidebar
依赖：dsh-better-sidebar >= 0.18.1（可选）。缺席时插件正常加载、控制台 warn、不贡献任何条目。
七、与 dsh-opensheet-sidebar 的关系
表格（csv/xlsx）与文档（docx）按能力域分成两个插件，各自自包含：插件之间不做 import —— 那会造出两个"软依赖"插件之间的硬耦合与安装顺序陷阱。共享的 zip/解压预算代码各持一份；等到出现第三个使用者再考虑抽公共包（阈值驱动，而不是提前设计）。
