PPTX 侧栏阅读器 drscrewdriver/dsh-pptx-sidebar

dsh-pptx-sidebar

⛔ 本项目已停止维护（2026-10-01）。 DSH 宿主较新版本已内置 office 演示文稿的侧栏预览，本插件不再单独维护、不再发版，也不参与后续宿主版本线适配。已发布版本仍可安装使用；0.1.x 宿主请使用冻结分支 compat/0.1.7 / compat/0.1.5 的对应版本。

在 DSH 侧栏里读 .pptx / .pptm 演示文稿——幻灯片按演示顺序排列，带文本、项目符号层级、演讲者备注和内嵌图片。

这是阅读视图，不是幻灯片还原。 不做绝对定位，不做主题字体，不做占位符继承，不做动画。查看器在头部就说明了这一点，因为一个看起来像渲染 bug 的布局差异，比一条标注清楚的限制更糟。

它是 dsh-better-sidebar 的使用方：注册一个文件预览器，在 Side 卡片的预览区里渲染。没有那个插件，它会加载、警告一次，然后什么都不做。

安装

dsh plugin --profile <profile> add github:drscrewdriver/dsh-pptx-sidebar#<sha>
dsh plugin --profile <profile> add dsh-pptx-sidebar@0.1.0 # once published

然后重启 DSH 宿主——新增 loader 行时，刷新浏览器不够。不启动任何东西也能验证：

dsh --profile <profile> --dump-config | Select-String dsh-pptx-sidebar

手动安装是三步，不是一步——见 cordis.patch.yml。只做第 1 步和第 3 步，会得到一个配置档：包在、补丁行在，却什么都不加载，而且悄无声息。

做什么 / 不做什么

| 做 | 不做 |
| 按 p:sldIdLst 顺序列出幻灯片 | 视觉布局、绝对定位 |
| 文本段落、逐段项目符号层级 | 主题/母版字体解析 |
| 按占位符类型识别标题 | 占位符继承（见下） |
| 从 notesSlide 部件读取演讲者备注 | 把图表重新渲染成图表 |
| 内嵌图片转成 blob URL | 动画、切换、计时 |
| 真实表格（a:tbl） | 批注、修订标记 |
| 加粗 / 斜体 run | 编辑、写回 |
| 七道熔断上限 | 旧版 .ppt（BIFF/OLE2）、WPS 格式 |

占位符继承这条线（有意为之）

幻灯片经常显示它并不包含的文本：页码、页脚，以及标题文本，它们住在 slideLayout / slideMaster 里，通过 p:ph 占位符引用。要解析这些，就得重新实现 PowerPoint 的继承链——包括 lstStyle 层级覆盖，以及幻灯片实际用的是哪个版式。

v1 不做这件事。 只读幻灯片自己的部件。后果明说，不藏：文本全部靠继承的幻灯片，会渲染成没有文本。这是看得见的缺失，不是损坏——反过来取舍（继承错了）会显示幻灯片上根本没有的文本。

宽度自适应

侧栏面板可以调大小，所以阅读视图会跟着适应——在边界之内，因为「自适应」不是放任它一直变大或变小的许可证：

| 旋钮 | 取值 | 原因 |
| 基准宽度 | 360 px | 这里系数正好是 1，所以常规面板宽度渲染出的布局就是 0.1.0 发布时的样子 |
| 下限 | 0.9× | 面板再窄，字号依然可读 |
| 上限 | 1.15× | 面板再宽，字号只是舒适，不会大得离谱 |
| 量化 | 2 位小数 | 拖动时按 0.01 的步长重新布局，而不是每个像素都重排 |

系数由面板宽度推导得出，写入 --reader-scale 自定义属性；根字号变成 13px × scale，幻灯片内容用 em 表示，所以文字会按新尺寸重新排版，而不是做 transform 缩放（那会让字形发虚）。

只有文档内容缩放。 标题、项目符号、段落、备注、表格和图片说明跟随系数；顶部条、幻灯片条、分隔横幅以及加载/空状态保持固定尺寸。拖动分隔条时，外框跟着变尺寸，看起来像故障，而不像自适应。

两个相关决定：

- 宽度无法测量时回退到 1，而不是回退到某个边界值。首次测量之前宽度是 0，把它当成「尽可能窄」来渲染，会导致每次打开演示文稿都闪一下极小的字。
- 图片不缩放。 图片按形状 transform 指定的尺寸渲染，只受面板上限约束；为了跟上文字而把位图放大到超过其原始尺寸，只会让它更糊，而不是更还原。

流水线

archive bytes (host /sidebar/file, custom loader)
→ archive-size gate refuse before any unpacking
→ central directory (declared-size gate) refuse a lying part before inflating
→ streaming inflate + total budget the zip-bomb gate
→ ppt/presentation.xml p:sldIdLst — slide ORDER → ppt/_rels/presentation.xml.rels rId → slides/slideN.xml → ppt/slides/slideN.xml p:spTree → p:sp / p:pic / p:graphicFrame │ p:txBody → a:p → a:pPr@lvl (level), a:r → a:rPr(b/i) + a:t │ p:pic → a:blip@r:embed → slide rels → ppt/media/* │ p:grpSp → recursed, never flattened away ├→ ppt/slides/_rels/slideN.xml.rels .../notesSlide → notesSlides/notesSlideN.xml └→ rules: a slide too long loses only its own tail; notes absent is silence

图片从 zip 中取出，转成 object URL。内嵌图片就住在归档文件内部，没有可指向的宿主路由——这不是「我们自己读文件」，而是使用宿主已经交过来的字节。

七道熔断上限

| 维度 | 默认值 | 超限时 |
| 归档大小 | 8 MB | BLOCKED — 解包之前就拒绝 |
| 总解压量 | 64 MB | BLOCKED — zip 炸弹闸门 |
| 单个部件 | 32 MB | BLOCKED — 单个超大的 XML 部件 |
| 幻灯片数 | 300 | TRUNCATED — 阅读器停止遍历演示文稿 |
| 幻灯片文本 | 20 000 字符 | 该幻灯片剩余文本省略 |
| 图片 | 200 | 后续图片跳过 |
| 单张图片 | 8 MB | 该图片跳过（甚至不膨胀） |

每个维度最多一条警告，这是结构上的保证——警告存放在 Map<reason, warning> 里，所以某个维度在每张幻灯片上都触发，也只产生一行，而不是六十行。

每张幻灯片的文本上限只省略出问题的那张幻灯片。按块设上限会把每张幻灯片都削掉同样多，丢掉演示文稿本来有预算保留的信息；我们接受的失败模式是「第 12 张幻灯片被截断」。

测试

npm install
npm run verify # build (bundle load gate) + tests
npm test # 19 checks

测试夹具是测试文件里构建的真实 pptx 结构 zip，带一张真正的微小 PNG。格式刁钻的地方，它也一样刁钻：

- p:sldIdLst 把 slide2 列在 slide1 前面，所以按文件名排序部件会通过其他所有断言，却依然是错的；
- 一个幻灯片关系用的是绝对目标，另一个是 External；
- ppt/slideLayouts/slideLayout1.xml 里带着 MASTER TEXT MUST NOT APPEAR，这段文本绝不能露出来——这就是这里「不做占位符继承」的含义。

目录结构

| 文件 | 作用 |
| pptx.ts | 读取器：部件、关系、形状树、备注、图片 |
| circuit-breaker.ts | 七项上限，以及每个维度只发一条警告的规则 |
| zip.ts / xml.ts | 容器读取；带深度计数的定向 XML 扫描 |
| PptxViewer.tsx | 幻灯片条、当前幻灯片渲染、object-URL 生命周期 |
| locales.ts | zh / en 词典，包含每一条警告模板 |
| seams.ts | 我们消费的客户端服务的结构镜像 |

zip 和 XML 代码是从同门的文档插件复制过来的，而不是共享。这份代码只有两个使用者，还不到抽成包的门槛——那会多出第三个要发布、要锁版本的东西。

兼容性

| 插件版本 | DSH 宿主范围 | 说明 |
| 0.3.0 | >=0.2.0-rc.1 <0.2.1-0 | 0.2.0 线（main，从 compat/0.2.0 提升而来）。仅元数据适配：消费面是纯 ctx.get(...) 调用，0.2.0-rc.1 保持 0.1.7 插件 API 不变 |
| 0.2.0 | >=0.1.5-rc.1 <0.2.0-0 | 由冻结分支 compat/0.1.7 / compat/0.1.5 提供 |

engines.dsh、package.json 里的 @deepseek-ai/dsh-client-locale peer，以及 dsh.plugin.json 的 engines.dsh，三者携带同一范围（保持同步）。

Languages / Sprachen / Langues / Языки / Idiomas / Lingue

本 README 用英文撰写。兼容性与安装速查（本行要求 DSH 0.2.0：>=0.2.0-rc.1 <0.2.1-0；安装：dsh plugin --profile <profile> add dsh-pptx-sidebar@dsh-0.2.0）：
- Deutsch — 需要 DSH 0.2.0（>=0.2.0-rc.1 <0.2.1-0）。安装：dsh plugin --profile <profile> add dsh-pptx-sidebar@dsh-0.2.0。0.1.x 宿主线由冻结分支 compat/0.1.7 / compat/0.1.5 维护（npm 标签 dsh-0.1.7 / dsh-0.1.5）。
- Français — 需要 DSH 0.2.0（>=0.2.0-rc.1 <0.2.1-0）。安装：dsh plugin --profile <profile> add dsh-pptx-sidebar@dsh-0.2.0。0.1.x 宿主线由冻结分支 compat/0.1.7 / compat/0.1.5 维护（npm 标签 dsh-0.1.7 / dsh-0.1.5）。
- Русский — 需要 DSH 0.2.0（>=0.2.0-rc.1 <0.2.1-0）。安装：dsh plugin --profile <profile> add dsh-pptx-sidebar@dsh-0.2.0。0.1.x 宿主线由冻结分支 compat/0.1.7 / compat/0.1.5 维护（npm 标签 dsh-0.1.7 / dsh-0.1.5）。
- Español — 需要 DSH 0.2.0（>=0.2.0-rc.1 <0.2.1-0）。安装：dsh plugin --profile <profile> add dsh-pptx-sidebar@dsh-0.2.0。0.1.x 宿主线由冻结分支 compat/0.1.7 / compat/0.1.5 维护（npm 标签 dsh-0.1.7 / dsh-0.1.5）。
- Italiano — 需要 DSH 0.2.0（>=0.2.0-rc.1 <0.2.1-0）。安装：dsh plugin --profile <profile> add dsh-pptx-sidebar@dsh-0.2.0。0.1.x 宿主线由冻结分支 compat/0.1.7 / compat/0.1.5 维护（npm 标签 dsh-0.1.7 / dsh-0.1.5）。

License

MIT