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/解压预算代码各持一份；等到出现第三个使用者再考虑抽公共包（阈值驱动，而不是提前设计）。