侧栏预览扩展 LeiYuXingZhou/dsh-preview-extra

dsh-preview-extra — DSH 右侧栏文档预览扩展

给 DSH（DeepSeek Harness 0.2.0-rc.2）右侧栏的文档预览增加这些格式： 3D 模型（STL/OBJ/PLY/glTF/GLB）、压缩包（zip/tar/gz）、音视频、字体、字幕、 TOML、Intel HEX、JCAMP-DX、VCD、KiCad 原理图/电路板、DFU。
纯客户端插件、零第三方依赖、无网络请求；所有预览都注册进内置的 @deepseek-ai/dsh-client-ui-sidebar-documentpreview 文档 tab，与内置的 Markdown / 代码 / 图片 / PDF / Office 预览共享同一套打开方式、路径头、刷新与「打开方式」菜单。

本仓库根目录就是可安装的 DSH 插件包（package.json + lib/ + cordis.patch.yml），因此可以直接在 DSH 的「添加插件」里用 GitHub 仓库地址安装。发布包在 v0.1.0。

状态

| 项目 | 结果 |
| 版本 | 0.1.0（GitHub Release） |
| 构建产物 | lib/client.js（约 362 KiB，24 个内部模块，单文件 classic script） |
| 契约静态校验 | skeleton/verify.mjs → 34/34 |
| 组装后冒烟（假 React + 假 Cordis ctx） | tools/smoke.mjs → 全部通过（每个预览正文都能挂上） |
| 解析器单测 | 3D 38/38、压缩包 28/28、新格式 13/13 |
| 真实 GUI E2E（无头 Chrome + CDP） | STL / GLB、ZIP 条目树与条目文本、WAV、SRT、7z 提示、TOML、Intel HEX、JCAMP-DX、VCD、KiCad 原理图与电路板、DFU —— 截图见 shots/ |

新增支持的格式

| 类别 | 后缀 | 预览内容 |
| 3D 模型 | stl（ASCII/二进制）、obj、ply（ASCII / binary_little_endian）、gltf、glb | Canvas2D 软件渲染：拖拽旋转、滚轮缩放、右键/Shift 平移、双击复位、线框开关、包围盒/三角形/顶点统计；glTF/GLB 读取内嵌 buffer 和节点变换；>30 万三角形自动抽样降级 |
| 压缩包 | zip、jar、war、apk、tar、gz、tgz、tar.gz | 条目树（名称/大小/时间/方法），点击条目查看文本（带行号，最多 200KB）、图片、或二进制说明；GBK 文件名兜底；防 zip bomb 限额 |
| 压缩包（仅识别） | 7z、rar、xz、bz2、zst | 显示格式与"请先解压为 zip/tar"的提示（浏览器端没有对应解压 API） |
| 音频 | mp3、wav、ogg、oga、m4a、aac、flac、opus | 原生 播放器；显示大小/MIME |
| 视频 | mp4、webm、m4v、mov、mkv | 原生 播放器；显示大小/MIME |
| 字体 | ttf、otf、woff、woff2 | FontFace 加载后的样张：中英文 pangram、大小写字母表、标点、字号阶梯 |
| 字幕 | srt、vtt、ass、ssa | 时间轴字幕列表（起止时间 + 文本）、条数/编码/总时长，可切换原始文本 |
| TOML | toml | 按表展开的键、类型和值；支持数组、内联表、[表] 和 [[表数组]] |
| Intel HEX | hex | 记录校验、线性/段地址合并、入口地址，以及按地址分段的十六进制转储 |
| JCAMP-DX | jdx、dx | 谱图折线（(X++(Y..Y))、峰表、PAC 压缩）和表头 |
| VCD | vcd | 数字波形：时间刻度、作用域、0/1/x/z 和总线值 |
| KiCad | kicad_sch、kicad_pcb | 原理图（导线、符号、针脚）或电路板（走线、过孔、焊盘、板框）；滚轮缩放、拖拽平移 |
| DFU | dfu | USB DFU 后缀（厂商/产品 ID、版本、CRC）和 DfuSe 多镜像的地址与大小 |

打开方式：右侧栏「文件」tab 里点任意文件；聊天里的文件卡片、交付物卡片也会走同一预览。

截图（真实 GUI，无头 Chrome + CDP 驱动）

| 3D 模型（STL） | 压缩包条目树 |
| STL 3D 预览 | ZIP 条目树 |

| ZIP 内条目文本 | 音频播放器 |
| ZIP 条目文本 | 音频播放器 |

| SRT 字幕 | 7z 不支持提示 |
| SRT 字幕 | 7z 提示 |

| 3D 模型（GLB） | TOML |
| GLB 3D 预览 | TOML |

| Intel HEX | JCAMP-DX |
| Intel HEX | JCAMP-DX |

| VCD 波形 | KiCad 原理图 |
| VCD | KiCad 原理图 |

| KiCad 电路板 | DFU |
| KiCad 电路板 | DFU |

目录

dsh-preview-extra/
package.json ← 插件包清单：dsh.client 声明（platform=web、exports["./client"]、inject 提示） cordis.patch.yml ← bundle patch：安装后自动插入 Loader 行 lib/index.js ← 宿主半侧：no-op cordis 插件（全部逻辑在浏览器侧） lib/client.js ← 构建产物（scripts/build-client.mjs 生成，不要手改） src/client/main.js ← 浏览器入口：按 previewDefinitions 注册 preview + keyed body + locale + 样式 src/ui/views.js ← 原有预览组件 + 中英文案 + CSS + previewDefinitions src/ui/extra-views.js ← TOML / Intel HEX / JCAMP-DX / VCD / KiCad / DFU 正文 src/formats/ ← 上述格式和 glTF/GLB 的纯解析器 src/model/ ← STL/OBJ/PLY/glTF 网格 + Canvas2D 软件渲染器（纯 ESM，无 DOM 顶层依赖） src/archive/ ← zip/tar/gzip 解析 + 魔数识别 + 限额（纯 ESM，无 Node API） scripts/build-client.mjs ← 手写"打包器"：把 src/** 的 ESM 拼成 __ModuleLoader__.load 的 factory scripts/install.mjs ← 安装/卸载到任意 profile（复制包 + 追加 patch 行） tools/smoke.mjs ← 无浏览器冒烟：加载真实 bundle 并渲染每个预览正文 tools/cdp.mjs ← 无头 Chrome CDP 驱动（导航/求值/截图） tools/probe-bundle.mjs← 探测某个 DSH 实例是否已提供本插件 bundle tools/fixtures-gen.mjs← 生成 E2E 样例文件（STL/OBJ/PLY/ZIP/TAR/GZ/WAV/SRT…）
notes/ ← 逆向文档：module-contract.md（客户端插件契约）、preview-api.md（预览扩展契约） skeleton/ ← 手写客户端插件最小骨架 + verify.mjs 契约校验器（来自契约调研） shots/ ← E2E 截图

_fixtures/（样例文件）与 _dsh_test/（隔离测试用 DSH_HOME）属于本地测试产物，已在 .gitignore 中排除，需要时用 tools/fixtures-gen.mjs 重新生成。

通过 DSH 安装

DSH 的「设置 → 插件 → 添加插件」支持包名 / GitHub 仓库地址 / 本地目录路径三种来源。本仓库根目录就是包，因此：

1. 打开 DSH → 设置 → 插件 → 添加插件；
2. 粘贴 GitHub 仓库地址：

https://github.com/LeiYuXingZhou/dsh-preview-extra

3. 点「安装」。装完后 profile 的 cordis.patch.yml 会由本包的 cordis.patch.yml（dsh.bundle.patch）自动挂载 Loader 行，页面刷新即生效（不需要重启 DSH）。

本机注意事项：

- 当前网络直连 github.com:443 不通，需要给 git 配代理后再装：git config --global http.proxy http://127.0.0.1:7877
- 或者直接用本地目录路径安装（绝对路径，指向本仓库根目录）：

C:\Users\Administrator\Documents\daily\dsh-preview-extra

- 也可以手动安装（本仓库自带脚本，复制包 + 追加 patch 行，幂等）：

& 'C:\Program Files\nodejs\node.exe' .\scripts\install.mjs --profile-dir "$env:USERPROFILE\.dsh\profiles\desktop"

快速使用

1. 在 DSH 右侧栏点「文件」tab（或聊天里的文件/交付物卡片）；
2. 点开以下任意文件即可看到新预览：.stl、.obj、.ply、.gltf、.glb、.zip、.tar、.tar.gz、 .mp3/.wav/.mp4/.webm、.ttf/.otf/.woff2、.srt/.vtt/.ass、 .toml、.hex、.jdx、.dx、.vcd、.kicad_sch、.kicad_pcb、.dfu；
3. .7z/.rar/.xz/.bz2/.zst 会显示"暂不支持，请先解压为 zip/tar"的提示。

重新构建 / 手动安装 / 回滚

$node = 'C:\Program Files\nodejs\node.exe'
& $node .\scripts\build-client.mjs # 改过 src 后重新打包 & $node .\tools\smoke.mjs # 组装后冒烟 & $node .\skeleton\verify.mjs . # 契约静态校验（34/34） & $node .\scripts\install.mjs --profile-dir "$env:USERPROFILE\.dsh\profiles\desktop" # 安装 & $node .\scripts\install.mjs --profile-dir "$env:USERPROFILE\.dsh\profiles\desktop" --uninstall # 卸载

desktop 配置档的原始补丁备份：~/.dsh/profiles/desktop/cordis.patch.yml.bak-before-preview-extra。

开发

常用命令：

& 'C:\Program Files\nodejs\node.exe' .\scripts\build-client.mjs # 构建 lib/client.js & 'C:\Program Files\nodejs\node.exe' .\src\model\tests\run.js # 38 项 3D 测试 & 'C:\Program Files\nodejs\node.exe' .\src\formats\tests\run.mjs # TOML / HEX / glTF / JCAMP / VCD / KiCad / DFU & 'C:\Program Files\nodejs\node.exe' .\src\archive\tests\run-tests.mjs # 28 项压缩包测试 & 'C:\Program Files\nodejs\node.exe' .\src\ui\smoke.mjs # UI 冒烟（假 React） & 'C:\Program Files\nodejs\node.exe' .\tools\smoke.mjs # 组装后的 bundle 冒烟 & 'C:\Program Files\nodejs\node.exe' .\skeleton\verify.mjs . # 契约静态校验

实现要点

- 浏览器 bundle 是手写的 classic script：window.__ModuleLoader__.load({ id, factory })， id 必须等于包名；factory(require) 里只 require 平台冻结表（react / react-dom / @deepseek-ai/dsh-client-ui-primitives 等 9 个 key），不引入任何动态包。
- 硬依赖只有 slots 服务；documentPreviews 与 locale 用 ctx.inject([...]) 软等待——这样即使内置文档预览被禁用，本插件也只是休眠，不会把整页启动拖垮（DSH 页面 boot 是"全有或全无"）。
- 每个格式族的注册都是两处：ctx.documentPreviews.register({ id, extensions, binaryExtensions, priority, title, loading, wrap }) + ctx.slots.register("sidebar.right.tab.document", { key: id })，两处都用同一个 id，且都包在 ctx.effect 里以便 HMR 回收。
- 全部解析器都是纯 JS / Web 标准 API（DecompressionStream、TextDecoder、FontFace、Blob URL），没有 Node 内置模块，也没有第三方依赖。

测试用 DSH 实例（E2E）

$env:DSH_HOME = 'C:\Users\you\Documents\daily\_dsh_test'
& 'C:\Program Files\nodejs\node.exe' 'C:\Users\you\.dsh\acl-runner\node_modules\@deepseek-ai\dsh\lib\bin.js' --profile test --no-open --port 1891
终端会打印带 token 的 URL；无头 Chrome 已可用 CDP 驱动： & 'C:\Program Files\nodejs\node.exe' .\tools\cdp.mjs new "<带 token 的 URL>" & 'C:\Program Files\nodejs\node.exe' .\tools\cdp.mjs eval "document.body.innerText.slice(0,500)" & 'C:\Program Files\nodejs\node.exe' .\tools\cdp.mjs shot .\shots\screen.png

已知限制

- 完整字节加载受宿主 32 MiB 上限；超大文件走内置"无法预览/本地打开"。
- 压缩包：5000 条目 / 单条目 32 MB / 累计 128 MB 限额；文本条目最多 200 KB。
- 7z/rar/xz/bz2/zst 仅识别提示；分卷 ZIP、加密 ZIP 条目不可读（显示原因）。
- 音视频编解码依赖浏览器；MKV/MOV 视编码而定。
- 3D：Canvas2D 软件渲染，无 WebGL；>30 万三角形自动降级；PLY 仅 little-endian。glTF/GLB 只画三角形（点/线会跳过），外部 .bin、蒙皮和动画不会套用。不支持 3MF/FBX/STEP。
- Intel HEX 按记录合并地址空间，单段转储只显示开头一段。
- JCAMP-DX 不展开 NTUPLES 多页；压缩编码支持 SQZ/DIF/DUP。
- VCD 最多画 40 条信号，超长跳变会截断。
- KiCad 是几何预览：不跑 ERC/DRC，不展开封装焊盘网表，复杂板会限制图元数量。
- DFU 展示镜像布局和 CRC，不模拟烧录。
- 字幕：ASS/SSA 样式与定位忽略；1 MB / 3000 条上限。
- 字体：不解析字形表；TTC 可能加载失败。