文档转 PDF bauerelizabeth07139/dsh-plugin-dxpdf

dsh-plugin-dxpdf

一个 DeepSeek Harness (DSH) 宿主插件，对外暴露一个工具 dxpdf_convert，它用第三方 dxpdf 引擎把 Microsoft Word .docx 文件转成 .pdf。这个引擎是 Rust + Skia 编译出来的 Python 扩展，不需要 Microsoft Office，不需要 LibreOffice，也不需要联网。它还会修复 WPS Office 写出的不符合 schema 的结构，并把 Word 在奇偶分节符处插入的空白页补回来。

引擎：github.com/nerdy-pro/dxpdf · PyPI：dxpdf ·许可证：MIT

环境要求

- Node.js ≥ 22 —— 承载插件的 Harness。
- PATH 里有 Python ≥ 3.8 —— 或者用 pythonPath 或 DXPDF_PYTHON 显式指定。任何解释器都行，只要能导入引擎。
- 把 dxpdf 引擎装进那个解释器：

python -m pip install dxpdf

- lxml，用于 Word 对齐分页那一趟：

python -m pip install lxml

py/paginate.py 会导入 lxml。没有它，分页那一趟就跳过：检查会以 ModuleNotFoundError: No module named 'lxml' 失败，转换照样完成，结果里带上 paginationSkipped 说明原因。分页那一趟是插件里唯一需要 lxml 的部分；转换、CLI shim 和 schema 修复都不需要。

安装

插件是一个 DSH bundle。把它装进你运行的配置档，打开这个 bundle，再把引擎装进插件要用的解释器。

桌面应用

Plugins → Add plugin → https://github.com/bauerelizabeth07139/dsh-plugin-dxpdf，然后在同一个列表里打开新 bundle。桌面应用启动的是保留的 desktop 配置档，所以 bundle 必须在那里启用。

命令行

dsh plugin --profile web add bauerelizabeth07139/dsh-plugin-dxpdf

机器上没有 git 时，这个简写解析不了：pnpm 会跑 git ls-remote，然后以 'git' is not recognized 失败。改用 GitHub tarball 安装：

dsh plugin --profile web add https://codeload.github.com/bauerelizabeth07139/dsh-plugin-dxpdf/tar.gz/main

把 main 换成 commit SHA 就能锁定到确切的修订版本。

安装引擎

插件会调用 dxpdf 引擎，那是一个 Python 包。把它连同 lxml 一起装进插件要用的解释器：

python -m pip install dxpdf lxml

卸载

dsh plugin --profile web remove dsh-plugin-dxpdf

为什么会有这个插件

PyPI 上的 dxpdf wheel 只带编译好的扩展模块（dxpdf/dxpdf.pyd）和 convert/convert_file 函数。它没有声明 console script，所以 pip install dxpdf 之后，文档里写的 dxpdf 命令根本用不了。这个插件从两个层面补上这个缺口：

- 包自带一份 CLI shim 的副本（py/dxpdf_cli.py），它插件能找到哪个 Python 就用哪个，所以转换前只需 python -m pip install dxpdf 这一步准备；
- 插件用显式 argv 驱动引擎，模型转换文档时不必担心引号问题——只有探测到的 dxpdf.cmd/.bat/.exe 路径会经过 cmd.exe，而该路径会给每个 token 加上双引号。

它还会修复 dxpdf 原本会拒绝的文档——见 WPS Office 兼容性。

WPS Office 兼容性

dxpdf 用严格的 serde schema 解析 OOXML。Word 接受四种 WPS Office 会写出的构造，dxpdf 却会拒绝，于是某章在编辑器里打开完全正常，转换却失败：

| 构造 | WPS 写出什么 | dxpdf 报什么 |
| 重复的属性元素 | <w:rPr> 带两个 <w:sz> 子元素（先是 21 后是 20），第二个排在 <w:b/> 和 <w:color/> 之后 | failed to deserialize XML: duplicate field sz |
| 属性元素不在最前 | 目录项的 <w:pPr> 排在其三个域字符 run 之后 | duplicate field $value |
| run 嵌套在 run 里 | <w:r><w:r>…</w:r><w:r><m:oMath>…</m:oMath></w:r></w:r> 包住一段文本加公式 | unknown variant r, expected one of t, delText, … |
| 公式包在 run 里 | <w:p><w:r><m:oMath>…</m:oMath></w:r></w:p>，此时 OMML 数学属于段落 | unknown variant oMath, expected one of t, delText, … |

这四种都是系统性的——整套教材都可能带着它们，还会叠加出现。电路那一章在四种里占了三种，共需 206 处修复。

py/normalize.py 只重写出问题的元素，其余 ZIP 条目逐字节原样复制。重复的属性会被删除（默认保留第一次出现的那份）；包在 run 里的公式会被拆开，还原到段落；嵌套的 run 会被拼接进父级，并把它的 w:rPr 下放给缺少该属性的子 run；位置不对的 w:pPr 会被移到最前。修复后的副本在临时目录里转换，源文件绝不改动。

为什么 $value 不指向任何元素

quick-xml 的 serde 把元素的字符数据绑定到保留字段 $value。w:pPr 若夹在段落中间，就会打断这段数据，于是 dxpdf 两次看到段落被拍平后的内容，报出 duplicate field $value ——这个错误指向的是 serde 的伪字段，不是元素，因此无法按名字修复。它靠只调整顺序的重排规则解决，这条规则每轮都跑，正是因为没有任何名字可供定位。

无需许可的规则，与需要许可的规则

修复 2–4 都保持结构不变：拆开 run、拼接嵌套 run、把 schema 固定位置的属性移到最前，都不会改变文档的渲染结果，所以它们每轮都跑。只有修复 1 会删除东西，所以只有修复 1 要等引擎说出它拒绝的字段名。

重复项保留哪一个

对于实际文档中出现的重复项，Heading1 携带 32/32，Heading2 携带 26/26——值完全相同，说明这种重复是冗余的重复输出，而不是有意覆盖。第一次出现的位置也正好在规范 schema 位置上，与 w:szCs 配对。因此默认值是 first；两种取值测得的差异最多半磅，而 duplicatePolicy: last 会翻转结果。

绝不靠猜测删除任何东西

引擎会指出它卡在哪个字段上。插件把这个名字回传——duplicate field sz 变成 --only sz——只修复真正被拒绝的部分，每轮添加一个名字。每轮之后都会重新尝试处理文档，而被拒绝的文档在解析阶段就失败，早于任何布局或绘制，所以多跑几轮只花几毫秒。

这一点很重要：改为扫描一份内置的「应该只出现一次」元素列表，正是文档被悄悄损坏的原因。w:tblStylePr（每个条件表格区域一个）和 w:rsid（完整的修订 ID 历史）都是重复出现的元素，而天真的列表会把它们标记为重复项。定向路径从不触碰它们，批量回退方案也明确排除它们。

一遍处理并不总是够

规则之间会相互影响。展开嵌套的 run 会暴露出方程式，它们随后位于段落层级，需要自己展开；移动一个属性可能让下一个属性暴露出来，顺序错乱。每一遍都会重新解析上一遍产出的结果，并在某一遍没有发现任何问题时停止，所以结果是固定点，而不是某条规则乐观的猜测。

这些文档还携带重复的 w:pPr 块，它们不符合 schema，但 dxpdf 容忍它们，所以定向修复正确地不去碰它们。

与 Word 兼容的分页

Word 和 dxpdf 在一个地方存在分歧，表现为本该存在的页面却没有出现。如果某个分节符的 w:sectPr/w:type 是 oddPage 或 evenPage，它就承诺下一个分节获得该奇偶性的页面；当它前面的分节在错误的奇偶性上结束时，Word 会插入一个空白页。dxpdf 把两者都记录为按 nextPage 处理，所以它直接分页到下一页，空白页永远不会出现。电路那一章带有十一个这样的分节符。

dxpdf 是编译好的 wheel，所以修复方法不是改变它的布局，而是交给它一份文档，其中的普通 nextPage 分节符已经落在所需的奇偶性上。两个实测事实让这件事变得精确，而不是靠搜索：

- 携带 w:pageBreakBefore 的空段落可靠地恰好占一页，所以每个有问题的边界放一个填充段就能复现 Word 的分页；
- 添加一个填充段会让后面每个分节都恰好偏移一页并翻转其奇偶性，所以一个边界永远不需要第二个填充段。

py/paginate.py 通过转换文档中停在某个边界处的前缀，来测量每个分节结束在哪一页，然后遍历边界一次，在下一个分节否则会以错误奇偶性开始的地方插入一个填充段奇偶校验。每次探测都在已确定的填充内容就位后进行，因此观察到的是位移，而不是建模推测。

| 构造 | dxpdf | 本次修复 |
| w:br w:type="page" | 已支持——在段落末尾和段落开头均已验证 | 未改动 |
| w:sectPr w:type="nextPage" | 已支持 | 未改动 |
| w:sectPr w:type="oddPage" | 按 nextPage 处理 | 需要时插入奇偶填充 |
| w:sectPr w:type="evenPage" | 按 nextPage 处理 | 需要时插入奇偶填充 |

如何接入

dxpdf_convert 自己运行这一遍处理，位置在 schema 修复与最终转换之间，并报告它做了什么：

Converted … (12.2 MiB, 269929 ms, image_dpi=220, 420 pages). Repaired 58 schema violation(s) in a copy first; the source file was not modified. Restored 6 blank page(s) so the 10 odd/even section break(s) land on the page parity Word promises.

它带有门控，所以常见文档几乎不付出代价。paginate.py --check 靠扫描 document.xml 的字节来回答是否存在 oddPage/evenPage；两者都没有的文档根本不会进入测量环节，工具会报告 paginated: false, boundaries: 0。在语料上实测：

| 文档 | 奇偶分节符 | 页数 | 代价 |
| 核探测仪器-数学篇.docx | 0 | 458 | 总计 25 s，无测量环节 |
| 核探测仪器-电路篇.docx | 10 | 414 → 420 | 总计 270 s，12 次探测 |

这一遍真正运行时，有两道防线约束代价，而且它们相互关联：超时必须超过每个奇偶分节符一次引擎运行的时间，否则分节数在上限之内的文档会因超时而失败，而不是收敛。maxPaginateSections（默认 48）会拒绝奇偶分节符超过该数的文档，而不是花掉无上限次数的引擎运行；此时工具报告 paginationSkipped 说明拒绝原因，而不是悄悄少分页。paginateTimeoutMs（默认 45 分钟）约束这一遍本身。每次探测约 20 s，48 个分节符约需 16 分钟，所以把上限提得更高就意味着超时也要一起提。matchWordPagination: false 会完全关掉它。

这些步骤也可以手动运行，测试就是这么做的：

python py\normalize.py in.docx --output stage1.docx --quiet
python py\paginate.py stage1.docx --output final.docx --report report.json
python py\paginate.py in.docx --check # boundaries only, no conversion

报告会列出每个边界、该节结束的页码、下一节开始的页码，以及是否插入了填充。--python 和 --cli 覆盖引擎的调用方式，与插件自身的 runner 设置一致。

工具

dxpdf_convert

| 参数 | 类型 | 必填 | 含义 |
| input | string | 是 | 源 .docx。绝对路径，或相对于会话工作目录。 |
| output | string | 否 | 目标 .pdf。默认为输入路径换成 .pdf 扩展名。已存在的文件会被覆盖。 |
| image_dpi | number | 否 | 内嵌位图会降采样到的分辨率，1–2400。默认 220，也就是 Word 用的值。要印刷质量就调高（比如 300），要文件更小就调低（比如 96）。图片永远不会上采样超过源分辨率。 |

工具返回解析后的绝对 input 和 output、用到的 imageDpi、生成的 bytes、elapsedMs、从 PDF 读回的 pages 数量（可选），以及 runner —— 它记录引擎是怎么找到的，方便排查某台机器的环境问题。

如果文档先被修复过，normalized 为 true，repairs 统计修好的 schema 违规数量。如果奇偶分节符需要空白页，paginated 为 true，并带 fillers 和 boundaries；如果这一趟被拒绝或失败，paginationSkipped 会说明原因。渲染出的摘要会同时说明这两点，所以哪一项都不会被悄悄略过。

失败就是普通的工具错误，不会结束回合：输入缺失、输入不是 DOCX、image_dpi 超出范围、引擎以非零码退出、超时，都会以消息形式抛出来，模型能读到并据此处理。转换过程会响应调用方的取消信号。

Runner 解析顺序

磁盘上第一个存在的候选者胜出。pythonPath、cliPath 和 executable 来自配置；其余来自环境。解释器可以按路径指定，也可以按裸命令指定（python3、py），后者在 PATH 上解析 —— 所以 DXPDF_PYTHON=python3 照写就能用。

| # | 候选者 | 如何启动 |
| 1 | 配置的 pythonPath + cliPath | spawn(python, [cli, …])，直接启动 —— 不走 shell |
| 2 | DXPDF_PYTHON + DXPDF_CLI | spawn(python, [cli, …])，直接启动 —— 不走 shell |
| 3 | 配置的 executable，否则 DXPDF_EXE，否则在 PATH 上找到的 dxpdf.cmd / dxpdf.bat / dxpdf.exe | cmd.exe /d /s /c 加 windowsVerbatimArguments；每个 token 都加双引号 |
| 4 | PATH 上任意 Python（或 pythonPath / DXPDF_PYTHON）+ 本包自带的 CLI shim（py/dxpdf_cli.py） | spawn(python, [py/dxpdf_cli.py, …])，直接启动 —— 不走 shell |
| 5 | PATH 上的 Python + PATH 上的 dxpdf_cli.py | spawn(python, [cli, …])，直接启动 —— 不走 shell |

候选 1 和 2 要求两个文件都存在；3 要求可执行文件存在；4 要求解释器可解析，并且有随包发布的捆绑 shim。第 4 行就是「只 pip install dxpdf 也够用」的原因：wheel 没有声明 console script，所以找不到 dxpdf 命令，插件补上了缺失的前端。第 1、2、4、5 行把 argv 数组直接交给 spawn，所以没有任何 shell 会去解析文件名；第 3 行是唯一涉及 cmd.exe 的。

什么都解析不出来时，工具会带着试过的候选列表报错：

dxpdf is not installed where this plugin can find it. Tried configured
pythonPath/cliPath: …; DXPDF_PYTHON/DXPDF_CLI machine variables: …; …
Install it with "python -m pip install dxpdf", or point the plugin at it with
pythonPath/cliPath 选项。

配置

每个字段都可选；cordis.patch.yml 里的那一行不需要 config 块。
要覆盖默认值，加一个即可：

- insert:
- id: dsh-plugin-dxpdf
name: 'dsh-plugin-dxpdf'
config:
timeoutMs: 300000
pythonPath: 'C:\Python312\python.exe'
cliPath: 'C:\Python312\Scripts\dxpdf_cli.py'
duplicatePolicy: first
announcePolicy: true

| 字段 | 默认值 | 含义 |
| timeoutMs | 120000 | 一次转换的墙钟时间预算。 |
| paginateTimeoutMs | 2700000 | 分页处理的预算，该处理对每个 parity 分节各跑一次引擎。必须超过约 20 秒 × 分节数。 |
| maxPaginateSections | 48 | 超过这么多 parity 断点就拒绝分页处理，改为报告 paginationSkipped。 |
| matchWordPagination | true | 把奇数/偶数分节断点收敛到 Word 的分页上。没有这类断点的文档靠字节扫描检测，不花任何开销。 |
| duplicatePolicy | first | 修复保留重复属性的哪一次出现：first 或 last。 |
| announcePolicy | true | 是否注册常驻的 DOCX 转 PDF 系统提示词分节。 |
| pythonPath | 未设置 | 显式指定解释器，优先尝试。 |
| cliPath | 未设置 | 显式指定 CLI 脚本，优先尝试（与 pythonPath 配对）。 |
| executable | 未设置 | 显式指定 dxpdf shim，在 cmd.exe 那一行里尝试。 |

两个布尔值只有设为 false 才会关闭；duplicatePolicy 除非恰好是 last，否则都是 first；超时或上限只要不是正数、不是数字，就回落到默认值。announcePolicy: false 会抑制常驻的 DOCX→PDF 系统提示词分节 —— dxpdf:docx-to-pdf-policy，order 1250 —— 正是它让这个插件成为部署里的转换器。

优先级：部署里的 DOCX 转 PDF 转换器

Harness 对工具没有数值优先级。决定模型伸手去用哪个转换器的，是模型读到的东西，所以这个插件在真正要紧的两个地方把活揽了下来。

1. 常驻的系统提示词分节。 工具描述只跟其他工具竞争；它没法在跟技能的较量中定下选择。内置的 office-docx 技能告诉模型用内置 LibreOffice 渲染 PDF 交付物（<cli> convert --input report.docx --output report.pdf），否则技能的指令会赢。所以插件注册一个始终存在的提示词分节，dxpdf:docx-to-pdf-policy，order 1250 —— 夹在 write 工具的分节（1200）和 edit 工具的分节（1300）之间：

DOCX to PDF

Convert every DOCX-to-PDF request with the dxpdf_convert tool. …
Do not use bundled LibreOffice, soffice, or a Python rendering library to
turn a .docx into a .pdf. …

它的作用范围是刻意划定的。office-docx 技能仍然管创建、编辑和结构检查 Word 文档；XLSX 和 PPTX 仍然转换经由 LibreOffice 转换；策略本身也留了后门——引擎处理不了的文档（图表、SmartArt、修订记录）会回退到技能自带的 LibreOffice 路径，并让模型明确说明这一点。

2. 指令式工具描述。 dxpdf_convert 的描述结尾写明：它是本部署的转换器，任何 .docx → .pdf 都应优先于 LibreOffice 或 Python 渲染库使用。

该段落用 ctx.systemPrompt.section(...) 注册，会返回自己的 Cordis effect disposer，因此随插件一起消失，不会在多次重载后累积。announcePolicy: false 可以关掉它。

测试

这些测试套件是纯 Node 脚本，没有测试框架，也没有自己的依赖。它们用真实引擎转换真实的 DOCX 测试文件，所以必须先安装引擎才能通过：

npm test # every suite below, in order

Conversion core — 12 checks: runner discovery from DXPDF_* variables and from PATH, the .cmd shim strategy, both spawn strategies, page counting, image_dpi validation, error paths, overwrite behaviour.
npm run test:core

Tool contract — 13 checks: loads lib/index.js through a resolve hook that substitutes a stub for @deepseek-ai/dsh-tools, captures the registered definition and the system-prompt policy, and runs its execute/render/presentCall.
npm run test:tool

Document repair — 9 checks: the raw engine rejects wps-defects.docx, the plugin converts it anyway, the source is left untouched, both policies work, and a repaired copy needs no second repair.
npm run test:repair

Word-parity pagination — 6 checks: the cheap check finds no break in an ordinary document, finds the odd-page break in parity-sections.docx, and the conversion restores exactly the blank page Word inserts (2 -> 3 pages).
npm run test:paginate

Bundle composition — 10 checks over the installed profile wiring. Needs a profile that has this bundle installed and a copy of js-yaml.
npm run test:bundle

测试套件使用的引擎位置取自测试覆盖变量 DXPDF_TEST_PYTHON、DXPDF_TEST_CLI 和 DXPDF_TEST_SHIM；每个都会回退到插件自己读取的机器变量（DXPDF_PYTHON、DXPDF_CLI、DXPDF_EXE），再回退到本包自带的 shim。没有配置 shim 时，test/convert.test.mjs 会把 .cmd shim 检查报告为 skipped。

test/bundle.test.mjs 检查已安装的配置档，所以需要把 DSH_PROFILE 指向一个配置档（默认是 ~/.dsh/profiles/desktop，或 DSH_PROFILE_NAME），还需要一份 js-yaml，它随 Harness 提供，而不是随本插件提供（DSH_JS_YAML）：

$env:DSH_PROFILE = '<profile directory>'
$env:DSH_JS_YAML = '<profile>\node_modules\js-yaml\dist\js-yaml.mjs'
npm run test:bundle

两者任一缺失时，它会打印 SKIP 并以 0 退出，所以 npm test 在全新克隆的仓库上也能跑。

test/fixtures/wps-defects.docx 由 test/fixtures/make-wps-defects.py 会往 single-page.docx 里注入每一种缺陷各一处；test/fixtures/make-parity-sections.py 负责生成 parity-sections.docx。两个生成器都用 lxml。改动基础文档后，要重新生成对应的 fixture。CI 在 Ubuntu 和 Windows 上跑 npm test，Node 22 加 Python 3.12。

故障排查

dxpdf is not installed where this plugin can find it

Runner 解析顺序里的每个候选都试过了，磁盘上一个都不存在。把引擎装进插件解析到的那个解释器，或者直接给插件指定解释器和命令行：

config:
pythonPath: 'C:\Python312\python.exe'
cliPath: 'C:\Python312\Scripts\dxpdf_cli.py'

转换成功时，runner 字段会写明用的是哪个候选。

ModuleNotFoundError: No module named 'dxpdf'

引擎装了，但没装进插件调用的那个解释器。python -m pip install dxpdf 装进的是 python 解析到的解释器，而插件解析到的可能是另一个（pythonPath、DXPDF_PYTHON、python3.exe、某个虚拟环境）。先打印出将要使用的解释器 —— python -c "import sys; print(sys.executable)" —— 再装进那一个。

分页被静默跳过

转换结果里出现 paginationSkipped: "the pagination check failed: …"，通常说明缺 lxml：Word 对齐分页会跑 py/paginate.py，而它要导入 lxml。把 lxml 装进引擎所在的同一个解释器（python -m pip install lxml）。普通转换不需要它。

WPS 文档失败

WPS Office 会写出不符合 schema 的结构，插件会自动修复；见 WPS Office 兼容性。如果引擎拒绝文档的原因不是 schema 校验失败，或者找不到同名的重复项，工具报错里会带上引擎自己的消息。

Windows 上 python 与 py -3 的区别

插件在 PATH 里找 python.exe、python3.exe 和 python；它不用 py 启动器。如果只有启动器可用，把 pythonPath（或 DXPDF_PYTHON）设成它指向的解释器 —— py -3 -c "import sys; print(sys.executable)"。就算 PATH 里没有任何解释器，转换仍能通过已安装的 dxpdf shim 跑起来，但 schema 修复和分页这两步是 Python 辅助脚本，这种情况下会被跳过。

开发

本地开发时，配置档可以通过 pnpm 的 link: 协议依赖这个包，所以源码目录就是权威：改完源码，已安装的插件立刻就是最新的，不用重装。

"dsh-plugin-dxpdf": "link:../dsh-plugin-dxpdf"

这是有意为之。pnpm 的 file: 协议会按 files 字段装一份过滤后的副本，而只改了包内容时，pnpm install 会报「Already up to date」，并不会刷新那份副本 —— 于是悄悄产生偏差源码与安装之间。link: 能消除这种失败模式。

激活改动

Harness 在启动时组合配置档的插件行。当有序的 dsh.profile.bundles 列表变化时，HMR 会重新加载，但如果某个 bundle 的包在那一刻还没落到磁盘上，导入就会失败。安装或编辑 bundle 之后，重启 DeepSeek Harness，或者在 Web 侧边栏的 Plugins 页面切换该 bundle 的开关，这会重写 bundles 列表并强制重新组合。

License

MIT — 见 LICENSE。