前言¶
DSH 的理念是「一切皆插件」。在智能体开发场景中，处理文档是常见需求。传统做法是把 PDF 内容复制出来，翻译后再重新排版，这会丢失原文的版式细节。
mariomly/dsh-pdf-translate 插件通过侧栏面板解决了这个问题：将英文 PDF 丢入后，自动产出保留版式的中文版 PDF 与 Markdown。它不是简单的 OCR 识别，而是通过解析 PDF 结构，先测量原文参数，再按参数重排。
核心功能¶
- 侧栏「翻译」面板：在左侧栏「日程」下方增加入口，支持拖拽或点击选择文件。
- 保留版式：输出文件保留原文的页边距、字号、行距、段距、强调色以及页眉页脚。
- 多格式输出：同时生成中文版 PDF 和 Markdown 文件。
- 模型工具集成：注册了
pdf_translate模型工具，可直接在对话中对 Agent 发起翻译请求。 - KaTeX 公式渲染：自动将 PDF 中的数学公式还原为 LaTeX，并使用 KaTeX 渲染。
- 对象流支持：支持解析对象流（
/ObjStm）、交叉引用流等复杂 PDF 结构。
安装与启用¶
安装该插件需要执行以下命令。插件会自动注册服务与面板入口，重启桌面应用或刷新页面后生效。
dsh plugin --profile web add <本目录>
安装完成后，左侧栏会出现「翻译」入口。默认输出目录为 D:\Translation，该路径在面板中可临时修改，或直接在 lib/index.js 的 defaultOutDir() 函数中修改默认值。
典型用法¶
- 打开 DSH 面板，找到左侧栏的「翻译」入口。
- 将一份英文电子版 PDF 拖入面板（或点击选择文件）。
- 等待解析、翻译与重排（耗时视文件大小与模型速度而定）。
- 结果会保存在
D:\Translation目录下，文件名格式为<原名>_中文版.pdf和<原名>_中文版.md。 - 在对话中，也可以直接对 Agent 使用模型工具
pdf_translate来翻译当前上下文中的 PDF。
技术实现与限制¶
插件通过五步流程实现版式保留：解析、量版式、翻译、重排、打印。
| 阶段 | 做的事 |
|---|---|
| ① 解析 | 使用零依赖 PDF 解析器提取文字层、位置、字号、颜色，支持对象流与复杂字体。 |
| ② 量版式 | 统计页边距、各级字号、行距、段距、强调色及页眉页脚，将内容切分为标题、正文、公式等块。 |
| ③ 翻译 | 将公式还原为 LaTeX（PDF 中常为碎片），分批交给模型翻译，并处理失败重试与漏块补问。 |
| ④ 重排 | 用测量参数生成 HTML，KaTeX 渲染公式（如 \tag{} 右对齐），尽量贴合原件页数。 |
| ⑤ 打印 | 通过 Edge 的 CDP Page.printToPDF 生成 PDF，遵循 @page 规则，纸张与原件一致。 |
重要限制：
* 仅支持电子版 PDF：只处理有文字层的电子版 PDF，不支持扫描件（无 OCR）。
* 仅支持英译中：目前只支持英文翻译为中文，不支持指定语言对。
* 皮肤兼容性：面板根节点必须设置 position: relative，且不要添加 z-index，否则在特定皮肤（如 maid-atelier）下会被立绘层遮挡。
* 令牌依赖：不依赖 --dsw-alias-* 令牌，本地测试时这些令牌不存在。
开发与自检¶
插件包含一套验证脚本 verify.mjs，覆盖了 88 项离线断言，确保宿主/客户端契约一致、客户端产物正确以及引擎行为符合预期。开发过程中可以通过以下命令进行自检：
pnpm install
pnpm run typecheck # tsc --noEmit
pnpm run build # tsdown 构建客户端 + 包成 ModuleLoader 工厂
node verify.mjs # 执行断言检查
验证脚本会自动检查公式是否被正确渲染、对象流 PDF 是否能读出页数、模型停滞是否被超时打断等。此外，tools/engine-render.mjs 可以完全脱离 DSH 跑通整个流程，用于单独验证版式。
KaTeX 库作为离线依赖内置在 lib/vendor/katex/ 目录中。该目录下的 package.json 声明了 commonjs，插件根目录的 "type": "module" 设置确保了 Node 在加载时不将 UMD 当作 ESM 处理，防止 this 为 undefined 导致公式渲染失败。
结语¶
该插件为 DSH 生态提供了一种处理文档翻译的高效方案，适合需要频繁处理英文文档并要求保留版式的开发者。源码与详情可访问 GitHub。
