DWG 预览 · dsh-dwg-preview
中文 | English
DeepSeek Harness（DSH）桌面端的文档预览插件：在工作区里点开 .dwg / .dxf 图纸，
右侧预览标签直接显示矢量图形 —— 可拖拽平移、Ctrl/⌘ + 滚轮缩放、一键适应宽度。
DSH 自带的预览只认识文本与图片，DWG 图纸点开只会是「无法预览」。这个插件补上那一步：宿主侧用 LibreDWG（编译成 WebAssembly）把 DWG 解成 DXF，再用本仓库里零依赖的渲染器 lib/dxf2svg.mjs 画成一张自包含的 SVG；浏览器侧只负责显示这张图，不解码、不加载任何第三方查看器库。DXF 是纯文本，不需要 LibreDWG，直接进渲染器。
示例图纸
上图由 test/sample.dxf 生成（node tools/make-example.mjs），覆盖下面列出的图元类型。
它做什么
- 位置：工作区文件树里点开
.dwg 或 .dxf，右侧文档预览标签里的内容就是它 —— 槽位 sidebar.right.tab.document，body 键 @local/dsh-dwg-preview/dwg。
- 行 id：
dwg-preview（见 cordis.patch.yml）。插件不注册设置页，所以没有 order。
- 接管方式：向官方
sidebar-documentpreview 插件提供的注册表登记一个渲染器，声明后缀 dwg 与 dxf、priority: 'extension'（按后缀认领）、loading: 'bytes-complete'（要整份文件，不是流）。其它后缀不受影响。
- 工具栏：放大、缩小、适应宽度，以及当前图纸的图元总数；视图里可拖拽平移，Ctrl/⌘ + 滚轮缩放，普通滚轮仍然是滚动。
- 宿主侧两条路由（挂在 connection 的共享
/api 通道上）：
| 方法 | 路径 | 响应 |
|---|
| GET | /api/dwg-preview/ping | 200 {"ok":true,"plugin":"dsh-dwg-preview","cache":<已缓存张数>} |
| POST | /api/dwg-preview/svg | 200 {"ok":true,"kind":"dwg"|"dxf","svg":…,"stats":…} |
| POST | /api/dwg-preview/svg | 400 {"ok":false,"code":"EMPTY","message":"文件内容为空"} |
| POST | /api/dwg-preview/svg | 413 {"ok":false,"code":"TOO_LARGE","message":"文件超过 64 MB，预览已跳过"} |
| POST | /api/dwg-preview/svg | 500 {"ok":false,"code":"FAILED","message":…} |
- 依赖：浏览器半边只
require('react')；DWG 解码需要 @mlightcad/libredwg-web（见文末许可）。
怎么工作
- 文档预览把文件的原始字节交给这个渲染器（
content.kind === 'bytes'）。
- 浏览器半边把字节
POST 到 /api/dwg-preview/svg，附带 x-dwg-name（百分号编码的文件名，只作旁注 —— 宿主的格式判定不看它）。
- 宿主按内容判定格式：前 8 字节以
AC10xx 开头是 DWG；前 8 KB 里同时出现 SECTION 与 HEADER/ENTITIES 是 DXF；都不是就报 FAILED。
- DWG 交给 LibreDWG（WASM）转成 DXF；DXF 直接进
dxfToSvg()。
- 渲染结果是一张自包含 SVG（
viewBox + 背景 rect + 一个翻转 g），整份字符串返回给浏览器，浏览器用 Blob URL 显示。
为什么要绕这一圈：LibreDWG 的 wasm 约 9.5 MB，而 DWG 解码是 CPU 密集的同步调用。放进宿主进程，页面侧只处理一张图片；放进页面，每个预览标签都要为它付一份代价。DXF 路径是纯函数，所以能完全离线测试。
渲染器覆盖的图元：LINE、LWPOLYLINE（含 bulge 圆弧）、POLYLINE + VERTEX、CIRCLE、ARC、ELLIPSE、TEXT、MTEXT、ATTRIB、INSERT（嵌套块、行列阵列、旋转与缩放）、HATCH（多段线边界与边边界：直线、圆弧、椭圆弧、拟合点）、SOLID / 3DFACE、POINT、DIMENSION（走它的匿名块）。列表之外的实体被忽略，不报错也不画。
刻意的取舍
- 范围：优先用图纸自己的
$EXTMIN / $EXTMAX；缺失或退化时用模型空间坐标的原始跨度。块内几何不参与范围计算 —— 有些块带着远在图纸之外的垃圾几何，否则会把视图撑坏。最后加 2% 内边距。
- 垃圾几何过滤：块内实体（嵌套深度 > 0）的世界坐标足迹若超过图纸对角线的 3 倍，或超过 0.8 倍且中心落在「图纸 ± 0.6 倍跨度」的裁剪带之外，则整条丢弃；INSERT 阵列落在这条带外的肢体也不画。丢弃数量记在
stats.__stray（图元级）与 stats.__skippedOutside（总数，含被丢掉的阵列肢体），界面不显示。
- 图层颜色取绝对值：libredwg 写出的 DXF 把每个图层颜色都写成负数（DXF 里表示「图层关闭」），所以这里一律忽略符号、只看颜色号。代价是不实现「按颜色关闭图层」，只有
70 位 1（冻结）的图层会被跳过。
- 曲线：bulge 段转成 SVG 的
A 命令；ARC 用一段 A；HATCH 的圆弧边界按每 10° 一段折线近似（单条最多 64 段），椭圆弧按每 15° 一段。
- 文字：TEXT / ATTRIB / MTEXT 都放在翻转组里再用
scale(1 -1) 翻回来，所以字是正的。MTEXT 只做有限清洗（\P 换行、\A…; 一类格式码、{}、\~），格式与堆叠分数会丢；不嵌入字体，字形靠系统字体（SimSun, 'Microsoft YaHei', sans-serif），换机器字形会变；不做折行与分栏，也不做 SHX 大字体。
- 不画线型与线宽：全部是实线，靠
vector-effect="non-scaling-stroke" 在任何缩放下保持 1 像素。
- 只读：没有实体拾取、没有图层开关、没有标注编辑、没有打印导出。
顺带说清楚计数口径：预览页上的「N 个图元」是渲染器各类型计数之和；ATTRIB 在图元遍历与图元渲染两处各计一次，所以含属性块的图纸会多算一个。它只是显示口径，不影响绘制。
安装
本插件是一个标准 DSH bundle：package.json 里声明了 dsh.bundle.patch 与 dsh.client，装进任何 profile 都走同一条路。先装好 DSH 桌面端（deepseek.com/download），然后下面任选一种。
方式一 · 在 DSH 桌面端里装（推荐）
- 侧栏点 插件 → 添加插件（Add plugin）；
- 在输入框里填下面任意一种 spec：
- 本仓库地址：
https://github.com/linanbuan/dsh-dwg-preview
- 本仓库的压缩包链接（GitHub 页面的
Source code (zip)）
- 已经克隆到本机的目录绝对路径
- 包名（若将来发布到 npm）
- 点 安装：Harness 先读出这个 spec 指向什么（包名、简介、版本），确认后开始装；
- 装完点 立即启用。
整个安装由 Harness 自己的插件管理器完成：把这个包写进当前 profile 的 dsh.profile.bundles，并挂上宿主半边。桌面端装插件不需要命令行，也不需要手改 profile 文件。
方式二 · 让 Agent 自己装
把仓库地址或本机目录直接交给任意会话里的 Agent，它会调用 plugin_manager 工具（action: install_bundle）走同一条路。这是官方给第三方插件推荐的安装方式。
方式三 · 命令行
装了 dsh CLI 的机器上：
dsh plugin --profile <profile 名> add <spec>
<spec> 与方式一相同（包名、Git 地址、压缩包链接或本地路径）；参数以 dsh plugin --help 的实际输出为准。
方式四 · 手工装进某个 profile（排障用，不推荐）
profile 目录默认在 ~/.dsh/profiles/<profile 名>。把包放进去，并在 profile 自己的 package.json 里登记两处：
"dependencies": { "@local/dsh-dwg-preview": "link:<本目录绝对路径>" },
"dsh": { "profile": { "bundles": [ "…", "@local/dsh-dwg-preview" ] } }
手改 profile 文件要过权限审批，写坏会让 Harness 起不来，所以正常安装请走前面三种。手工安装时依赖不会自动装：宿主半边需要 @mlightcad/libredwg-web，你要自己把它装进 profile（方式一至方式三由 Harness 按 dependencies 装）。
装上之后
- 浏览器半边：注册
documentPreviews 渲染器与 sidebar.right.tab.document 的 body，随启动图加载；由 HMR 更新时不需要刷新页面。
- 宿主半边：注册两条
/api/dwg-preview/* 路由。安装时若提示需要重启，重启 DeepSeek Harness 应用（不是刷新页面）—— 桌面 profile 的 base 组合包以 root: [] 启用 HMR（只监听显式注册的配置），而 HMR 的忽略规则默认含 **/node_modules，装在 node_modules 下的插件代码不在监听范围内。
- 注册表要先在：渲染器登记到官方
@deepseek-ai/dsh-client-ui-sidebar-documentpreview 插件提供的注册表上（dsh.client.inject 声明了这份加载顺序）。注册表还没就绪时，浏览器半边会在 6 秒内每 150 毫秒重试一次（最多 40 次），不会静默丢掉渲染器。
- 第一次看 DWG 会慢一点：宿主懒加载 LibreDWG 的 wasm（约 9.5 MB）并只建一次实例，之后复用。
- 确认它在跑：侧栏 插件 → 找到这个包，看组件状态是否为「运行中」；也可以在会话里请求
GET /api/dwg-preview/ping。
停用 / 卸载
临时关掉（在 profile 自己的 cordis.patch.yml 里，或直接用插件页那一行的开关）：
- id: dwg-preview
disabled: true
彻底移除：插件页 → 这个包 → 卸载，它会把包从 profile 的依赖与 dsh.profile.bundles 里去掉。
注意事项
- 本插件不是官方插件：与 DeepSeek AI 无任何关联，不提供服务承诺。它跟随 Harness 的插件接缝工作，Harness 升级后可能失效；失效时预览以错误码或「预览失败」的形式退化，不会影响 Harness 本身启动。
- 安装后不会自动更新：官方插件管理器目前不支持自动更新，升级＝先卸载再装新版。手动替换已安装的包之后，宿主半边要重启应用才会加载新代码（Node 的 ESM 缓存按文件 URL 命中，停用再启用只会重跑旧模块的
apply()）；浏览器半边在开发时由 HMR 更新。
- 平台：只要 DSH 能跑（Windows / macOS / Linux）即可用。DXF 路径是纯 Node 代码；DWG 路径依赖
@mlightcad/libredwg-web 的 wasm，同样跨平台。本插件在 Windows 桌面端 + DSH 0.1.7-rc.2 上实测过。
- 用到的内部接缝不是稳定 API：
connection.fetch.register、slots.register、locale.register 与 documentPreviews 注册表都是 Harness 的内部形态，官方没有兼容承诺，版本升级后可能改名或改形。
- 权限：只读预览。除了在插件目录追加一行
.mount.log 挂载标记（已 gitignore，只为排障），它不写任何文件；不读你的会话、不读凭据、不联网、无遥测。
- 数据在哪：文件字节只在本机宿主进程里处理 —— 读进内存、解码、渲染，随请求结束释放；渲染结果按 sha1 缓存在内存里（最多 6 张，进程退出即消失）。浏览器半边拿到的只是 SVG 字符串。任何内容都不会上传，也不会写到磁盘。
- 一起分发要付 GPL-3.0 的代价：DWG 解码依赖
@mlightcad/libredwg-web（GPL-3.0），它由 Harness profile 按 dependencies 单独安装，本仓库不分发它。若你把本插件与它打进同一份 bundle 再分发，这份组合受 GPL-3.0 约束；本仓库自己的代码是 MIT。
- 失败是退化，不是崩溃：空文件
400 EMPTY、超过 64 MB 413 TOO_LARGE、格式认不出或解码失败 500 FAILED，界面显示「预览失败」与原因；路由把异常都收在响应里，不会把宿主进程带崩。
- 没有破坏性操作：它不删除、不覆盖、不改名任何文件，也不修改 profile 配置；唯一的写入是那一行挂载标记。卸载就是移除包本身。
- 64 MB 是请求体上限：超过就不解码，直接
TOO_LARGE。上限以内的大图纸仍会占用宿主进程的内存，并让它同步忙上一会儿（渲染是同步的）。
- 不支持编辑类功能：没有实体拾取、图层开关、标注编辑、打印导出。渲染器认不出的实体会被静默忽略，所以「画出来了但少东西」时先对照上面那份图元清单。
- 隐私：本仓库不含任何密钥、账号标识或本机路径；示例图纸
test/sample.dxf 是为这个仓库手写的，不含任何真实图纸数据。
自检
node test/selfcheck.mjs # 或 pnpm test
node tools/make-example.mjs # 重新生成 docs/example.svg（或 pnpm run example）
自检不需要网络、不需要 Harness、不需要 React、不需要安装任何依赖，纯 Node 跑完 31 项，全部通过时打印 31/31 checks passed 并以 0 退出，任何一项失败就以非 0 退出（可直接接 CI）。注意 pnpm test 会走 pnpm 自己的流程：它第一次会按 dependencies 真的装一遍依赖（于是写 node_modules/ 与 pnpm-lock.yaml，两者都在 .gitignore 里、不随仓库分发），装上 @mlightcad/libredwg-web 之后，DWG 那一项检查会自动跳过并打印原因 —— 它只能在装好依赖的 profile 里验证真实解码。它做的事：
- 用真实渲染器渲染
test/sample.dxf，逐类型钉住 stats（LINE 11、CIRCLE 5、ARC 1……）与 SVG 结构：viewBox 的具体数值、唯一的根 g、translate(0 80) scale(1 -1) 翻转、non-scaling-stroke、标签成对闭合；
- TEXT / MTEXT / ATTRIB 各一个
<text>（共 4 个）、都在翻转组里翻正、XML 特殊字符被转义；
- 用合成图纸验证垃圾几何过滤（
stats.__stray）、图层颜色取绝对值、冻结图层被跳过、空图纸抛错；
- 驱动
client.js：后缀（dwg/dxf）、priority: 'extension'、keyed body（sidebar.right.tab.document + @local/dsh-dwg-preview/dwg）、zh/en 字典键一致、样式只装一次，并断言 require 只被 'react' 调用过（一旦它去 require 任何官方客户端包，自检当场失败）；
- 用桩
fetch 真跑一遍视图：字节以 POST 发到 /api/dwg-preview/svg、x-dwg-name 是百分号编码、返回的 SVG 变成 Blob URL、图元总数显示为 31 个图元；放大 / 缩小 / 适应宽度、Ctrl + 滚轮、拖拽平移各自的结果都断言到百分比与滚动偏移；
- 用假
ctx 驱动 index.js 的 apply() 并真调用两条路由：ping、DXF 往返（同一份文件第二次走缓存）、空体 400 EMPTY、垃圾内容 500 FAILED、超过 64 MB 413 TOO_LARGE（用零填充的 SharedArrayBuffer 视图把请求体做到 64 MB + 1 字节，不复制、不占 64 MB 内存）、以 AC10xx 开头的体走 DWG 分支；
- 断言打包约束：
package.json 的 license / repository / keywords / files 覆盖树里每个文件、engines.node 且没有 engines.dsh；.gitignore 覆盖 node_modules/、*.log、.mount.log；两份 README 的章节、代码围栏与表格行数一致；全树扫描没有密钥、没有个人绝对路径、版权人姓名只出现在 LICENSE / package.json / 两份 README 里。
它不能证明什么，说清楚：
- DWG 解码本身：
@mlightcad/libredwg-web 是本仓库之外的运行时依赖（见许可），这里只验证「以 AC10xx 开头的内容会走 DWG 分支，且依赖缺失时如实报 FAILED」。真正的 DWG 解码只能在装好依赖的 profile 里试；自检检测到该依赖存在时会跳过那一项并打印原因。
- 真实浏览器：浏览器半边跑在桩
__ModuleLoader__ 与一个最小 hook 运行时上，不是 DOM，也没有官方注册表，因此字体、paint 与 Blob 的真实语义都没被覆盖。
- 官方接缝的行为：
documentPreviews、slots、locale、connection.fetch.register 在自检里都是替身；HMR 与重启规则也无法在这里验证。
- 字形与线型：SVG 依赖系统字体，自检只检查属性，不检查字形。
结构
package.json bundle 清单（dsh.bundle.patch + dsh.client）
cordis.patch.yml 一行 insert：装载宿主半边
index.js 宿主半边：两条 /api/dwg-preview/* 路由、内容判定、sha1 缓存
client.js 浏览器半边：documentPreviews 渲染器 + sidebar.right.tab.document 视图（手写 lazy CJS，只用 react）
lib/dxf2svg.mjs 零依赖的 DXF → SVG 渲染器（dxfToSvg(text, options)）
icon.svg 插件图标
docs/example.svg 由 test/sample.dxf 生成的演示图（本文顶上那张）
test/sample.dxf 样例图纸：覆盖上面列出的 14 类图元
test/selfcheck.mjs 自检（31 项）
tools/make-example.mjs 重新生成 docs/example.svg
致谢与第三方许可
@mlightcad/libredwg-web（GPL-3.0）：DWG 解码依赖，即 LibreDWG 的 WebAssembly 封装（上游 LibreDWG 同样是 GPL-3.0）。它是 Harness profile 按 dependencies 单独安装的 npm 包，本仓库不分发、不内置、也不把它打进任何产物。把本插件与它打包在一起分发，这份组合就受 GPL-3.0 约束；本仓库自己的代码仍是 MIT（见 LICENSE）。- 没有复制的第三方插件代码：
index.js、client.js、lib/dxf2svg.mjs 与 test/sample.dxf 都是为这个插件写的；ACI 颜色表的取值来自 DXF 规范本身。
- 用到的 Harness 接缝：
connection、slots、locale 服务，以及官方 sidebar-documentpreview 插件提供的 documentPreviews 注册表。浏览器半边自己不 require 任何官方客户端包，也不加载任何第三方查看器库（没有 three.js、没有 dxf-parser、页面里没有 wasm）；dsh.client.inject 只是声明加载顺序，不是代码引用。
License
MIT © 2026 linanbuan
