前言¶

在智能體裏處理 PDF 翻譯，常見做法是整份丟給大模型或外部服務，譯文往往和原文版式脫節：公式錯位、表格打散、頁眉頁腳與正文混在一起。若需要雙語對照、指定頁碼、領域術語表，還要自己拼腳本和前後處理。BabelDOC PDF Translate 把「解析—翻譯—排版—抽查」收成一套 agent skill，本地完成解析與排版，翻譯走你自行配置的接口，不捆綁雲端賬號、不上報遙測。下面介紹它是什麼、能做什麼，以及在 DeepSeek Harness（DSH）裏如何安裝與使用。

這是什麼¶

BabelDOC PDF Translate 是由維護者 reliable-ly0411 提供的通用 agent 技能包，面向 Codex 與 DeepSeek Harness，底層依賴另行安裝的 BabelDOC 運行時。倉庫自述爲：Portable agent skill for layout-preserving PDF translation with BabelDOC, bilingual output and custom terminology（版式保留 PDF 翻譯、雙語輸出與自定義術語）。

在 DSH 生態裏，該倉庫歸類爲工作流類插件：適配層只把技能註冊到宿主技能目錄，不替代 BabelDOC 引擎本身。社區目錄頁：skillhub.cn；源碼與文檔：GitHub。

核心功能¶

下列能力均來自倉庫 README 與包說明，安裝插件≠具備完整翻譯能力，運行時須按部署文檔單獨配置。

1. 版式保留翻譯：本地解析與排版；翻譯由用戶配置的 provider 完成。
2. 輸出形態：支持單語、雙語，以及雙語頁順序等選項；可按頁選擇範圍。
3. 術語與風格：自定義 glossary、上下文術語審視；支持術語表 CSV、風格提示等（見 references/ 與 assets/）。
4. 質量與流程：主流程包含 Luna 翻譯 → BabelDOC 排版 → 可配置的視覺審查 → 有界返工與輸出前審計等步驟（詳見 README「當前版本與適用範圍」）。
5. 無人值守橋接（自 1.3.0 起）：可複製 assets/job.dsh.example.json，經 chat-doctor 與 run --execute 走 DSH 原生客戶端橋接；細節見 references/unattended.md。

當前源碼標註版本爲 1.5.0-rc.29（package.json），主要增加 DSH 插件安裝入口；未發佈 npm 包。預發佈包 1.5.0-rc.28 爲 Windows / R1 限定預發佈，驗收邊界與已知限制見 README、VALIDATION.md 與技術報告——離線測試通過不等於真實 PDF 質量已驗收。

許可：倉庫原創技能與適配腳本爲 MIT；patches/babeldoc-0.6.4/ 衍生補丁爲 AGPL-3.0；BabelDOC、PyMuPDF 等運行時依賴各有上游許可，且不包含在本倉庫分發包內。

安裝與啓用¶

環境要求¶

• DSH：0.2.2-rc.1 及以上，且支持 skills.registerProvider（package.json 要求 dsh: >=0.2.2-rc.1 <0.3.0-0）。
• Node.js：24.9+（engines.node）。
• Python / BabelDOC：須按 運行時部署 另行安裝；插件不下載引擎、不讀取賬戶憑據、不自動啓動翻譯。

插件以當前 dsh 進程權限運行；安裝前建議閱讀倉庫源碼、DSH.md 與許可證條款。

DSH 插件安裝（推薦入口之一）¶

在獨立或已有的 web profile 中執行：

dsh plugin --profile web add github:reliable-ly0411/babeldoc-pdf-translate

重新啓動該 profile 後，agent 技能目錄會出現 babeldoc-pdf-translate。適配層僅註冊隨包技能，不修改其他技能、不調用模型。

詳細安裝、卸載與兼容邊界見倉庫 DSH.md。

文件系統 skill（備選）¶

DSH 亦支持在項目根目錄發現 .dsh/skills/<name>/SKILL.md。可將包內 skills/babeldoc-pdf-translate 複製到 .dsh/skills/，或配置的用戶技能目錄（與 Cordis 插件二選一；同名項目或用戶技能優先於插件 bundled 技能）。

也可從 Release 下載預打包 ZIP（如 v1.5.0-rc.28）校驗後解壓，再完成運行時部署；校驗示例：

sha256sum -c SHA256SUMS

其他安裝路徑¶

• Codex：codex plugin marketplace add reliable-ly0411/babeldoc-pdf-translate（獨立市場，非 OpenAI 官方目錄）。
• 無技能機制時，可直接讓 agent 閱讀包內 SKILL.md。

典型用法¶

經過上面的步驟完成技能註冊後，還需按部署說明配置 BabelDOC 運行時，再向 agent 說明 PDF 路徑、目標語言與偏好。README 中的示例請求如下。

按頁雙語 + 固定術語：

使用這個技能把論文第 2–4 個物理頁翻譯爲中文，輸出交替頁中英對照，只保留選中頁。phase margin 固定翻譯爲相位裕度，其餘術語結合控制領域上下文自動匹配。保留公式、圖片和單位。雲端接口稍後配置，先準備作業和術語表。

整份 PDF + 航空術語表：

翻譯整份 PDF，輸出中文單語及左右對照兩個版本。航空專有名詞采用英文（中文），使用我提供的 CSV；先試譯有公式和表格的兩頁。

快速使用三步概括：1）將技能放到平臺支持的技能目錄（或通過 DSH 插件註冊）；2）配置 BabelDOC 運行時；3）用自然語言描述 PDF、語言、版式與術語約束。服務未配置時也可先準備術語與作業草案。

包內結構便於對照：SKILL.md 爲 agent 入口；scripts/ 負責參數校驗與執行；references/、assets/ 含參數、術語與作業模板。

適用場景與注意¶

適合誰：需要在 agent 工作流裏做學術論文、技術 PDF 等版式敏感翻譯，且願意自建 BabelDOC 環境與翻譯後端的 DSH / Codex 開發者。

務必注意：

1. 本倉庫是技能與腳本分發包，不是開箱即用的完整翻譯軟件；doctor 只證明 CLI 可用，譯文與版式仍需人工或協議內審查（needs-review 等狀態見 README）。
2. 當前 rc 系列對平臺、R1、複雜 PDF 仍有 README 所列限制（如部分英文保留、圖內文字、特定查看器 dpi 差異等）；投產前請讀 VALIDATION.md 與穩定性說明。
3. 社區目錄收錄不代表 DeepSeek 官方認證，亦不等於應用內一鍵安裝市場；生態上 DSH 主張「一切皆插件」，目錄站點與 DeepSeek / 幻方無官方從屬關係。
4. 更新技能文件不會自動修改已部署引擎；部分修復需按文檔運行 scripts/repair_runtime.py --apply。

結尾¶

BabelDOC PDF Translate 把版式保留 PDF 翻譯收成可註冊的 agent skill，在 DSH 裏通過 dsh plugin --profile web add github:reliable-ly0411/babeldoc-pdf-translate 掛載後，與自建 BabelDOC 運行時和用戶自選翻譯接口配合，支持雙語輸出、選頁與術語表等工作流需求。進一步瞭解可看 社區目錄頁 與 GitHub 倉庫。