前言¶
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。
