前言¶

在智能体里处理 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 仓库。