v1.0.7 to v2.0.0-rc.3

49 added, 65 removed. Audit A to A.

---

name: double6-pdf-translation

- version: 1.0.7

- description: Translate user-supplied text PDFs into Simplified Chinese and bilingual PDFs. Reads the PDF and only explicitly selected local LaTeX, sends extracted text to an explicitly approved OpenAI-compatible endpoint, runs local PDF/Python subprocesses, and writes outputs, diagnostics, and the default runtime cache under the chosen directory. Local proxy, arXiv download, Docker compilation, and external cache paths require explicit command-line opt-in.

+ description: 论文和PDF英译中执行。先读 configs/default-routes.json，按源证据直接调用已有命令。清晰单栏扫描先预检和源图确认；审过再准备用单配置；冻住了只重出PDF。电子PDF和已核过的LaTeX走原路线。全文、实际PDF、复制和冷重建必须保留。旧的整篇强翻译流水线不是当前入口。

metadata:

- openclaw:

- homepage: https://github.com/double6-ai/double6-skills/tree/main/skills/double6-pdf-translation

- emoji: "📑"

- requires:

- anyBins:

- - python3

- - python

- - py

+ version: "2.0.0-rc.3"

+ development_revision: "110-unpublished"

+ source_contract_revision: "111-20261017"

+ release_status: "local-prepublication-candidate"

+ default_routes: "configs/default-routes.json"

+ entry_point: "scripts/paper_translation_workflow.py"

---

- # Double6 PDF Translation

- 将英文 PDF 翻译为简体中文，尽量保持原始版式，并通过文本与视觉门禁检查成品。

- > ⚠️ **适用范围**：本 skill 只针对**非扫描版 PDF**。对于扫描版 / 图像版 PDF，可能翻译失败或效果较差，请谨慎使用。

- ## 运行

- 先配置用户选择的 OpenAI-compatible Chat Completions 服务；不得假设本地模型或使用内置

- 默认模型。模型必须显式指定，服务商 URL 推断规则见 `references/provider-base-urls.md`。

- 在 skill 根目录运行，并为本次调用显式传入 endpoint、模型和凭据：

- ```bash

- python scripts/preflight_runtime.py --strict \

- --provider deepseek --model <model-name> --api-key-file <key-file>

- # 用户确认目标 host 后才做带凭据的联网探测：追加 --allow-endpoint-check

- ```

+ # PDF 中文翻译

- 先修复 required 级失败，再开始翻译；可选诊断依赖缺失只减少自动检查。

+ ## 当前合同

- ```bash

- python scripts/run_pdf_translation.py <input-file.pdf> \

- --output-dir <output-dir> \

- --provider deepseek --model <model-name> --api-key-file <key-file>

- ```

+ 先读 [configs/default-routes.json](configs/default-routes.json)。按源证据判断输入和任务，直接调用 [scripts/paper_translation_workflow.py](scripts/paper_translation_workflow.py) 里已经存在的动作。从已安装的 skill 目录用独立 Python 环境执行；安装和模型配置见下文。直接使用已有动作。

- 也可用参数提供 provider、base URL、model 和 API key；缺任一必要配置时 preflight 必须阻断。

- 兼容代理、LaTeX 源码、离线模式和诊断参数见 `references/workflow.md`。

+ 路线名称仍是 `110-unpublished`，本页已同步源项目第 111 轮（2026-10-17）的开工合同。旧长说明、旧默认命令、并发 3/4 和历史模型参数不作为当前入口；历史原件保存在本地来源核对报告中，不加入公开运行包。

- ## 最小依赖

+ | 输入和任务 | 直接调用 |

+ | --- | --- |

+ | 清晰单栏扫描，还没审过 | `inspect-input`。具名看过源图之后，才进入既有 OCR、source-plan 和全文审校 |

+ | 扫描已经审过，确需按原配置再准备 | `run-reviewed-scan --config` |

+ | 同一份冻结合同，只是重出 PDF | `trial-render`。不重复准备，不探测模型 |

+ | 电子版 PDF | `collect`，固定参数 `--route digital_pdf`，再走既有源组审校和 candidate |

+ | 已经核过的 LaTeX | `candidate`，固定参数 `--route latex_verified` |

- 必须安装 PyPI 包 `pdf2zh_next`。它会提供本 skill 使用的 `pdf2zh` 命令；**不要**安装同名旧包 `pdf2zh`。

+ 扫描这条不能套到所有 PDF。隐藏文字层要单独决定走不走，不能悄悄换模型，也不能悄悄改页面尺寸。

- ```bash

- # 通过专用 venv 安装（也可使用 scripts/setup_venv.sh）

- pip install pdf2zh_next

- ```

+ ## 必须留下的结果

- PyMuPDF 会随 `pdf2zh_next` 带入，不必再单独安装。Poppler、reportlab、TeX Live、Docker、RapidOCR 只用于可选诊断或显式 LaTeX 路径，不是主翻译所需。后端解析顺序见 `references/runtime-dependencies.md`。

+ - 完整源组和角色都要有人确认过的依据。分组提案不能当成已经确认。

+ - 全文语义要审。漏译、误译、重复、语义变了，必须改，包括只出现一次的句子。改完对照源段，在实际 PDF 上重核内容和样式、链接。

+ - 要有实际中文页，以及左边原文、右边译文的双语页。

+ - 核对实际字形、字体、样式、链接和保护区域。刊头的颜色和字重能按源复原就复原；做不到就写明没复原。

+ - 用普通阅读器打开，整段中文要能真实复制出来。

+ - 材料冻住后，在新目录冷重建一次。

+ - 只有源、译文、实际成品和适用标准都没变，才沿用旧结论。

+ - 页面保持输入的原始尺寸，不把原页静默放大或换一套包装。

- ## 输出

+ ## 明确不自动做

- 普通交付只保留两份 PDF：

+ - 不自动判断是不是完整作品、有没有手写、隐藏识别层能不能用。

+ - 不自动确认分组、角色、几何、跨页或空白页。

+ - 不把重复填路径、重复准备省下的几秒，写成省下了人第一次读源的时间。人的操作时间要单独记，机器耗时不能代替。

+ - 本目录仍是未发布草稿。上游历史本地分发包为 `2.0.0-trial.2`，其发布接受不自动延续到本目录；严格验收和阅读接受都要另记。

+ - 多栏、复杂表格、公式、差扫描、手写页，没有这页范围里的实测，就不能写成已经支持。

- - `<原文件名>.zh.pdf`：最终中文单语 PDF。

- - `<原文件名>.bilingual.pdf`：默认英文原文在左、中文译文在右；左右方向以打开文件后的几何核验为准，可用 `--bilingual-layout zh-left-en-right` 切换为中文在左。

+ ## 细节放在哪

- 同时保留 `render_manifest.json`；内部 gate 明细仅在调试或失败时报告。

+ 命令参数见 [references/input-preflight-and-reviewed-run.md](references/input-preflight-and-reviewed-run.md)。结构、字号和源页锚点见 [references/adaptive-flow-contract.md](references/adaptive-flow-contract.md)。整页验收见 [references/quality-and-delivery-contract.md](references/quality-and-delivery-contract.md)。译法见 [references/academic-translation-policy.md](references/academic-translation-policy.md)。电子版和 LaTeX 的原步骤见 [references/release-quickstart.md](references/release-quickstart.md)。

- ## LaTeX 与降级

+ 资源按当前路线：一次只跑一个任务；进程树内存上限与单作业时限按平台默认（macOS 3GiB RSS／120 秒，Linux 4GiB PSS／300 秒，且默认不超过物理内存 25%），可用 `--task-memory-mib`、`--job-timeout-seconds`、`--memory-metric` 或对应环境变量 `PAPER_TRANSLATION_TASK_MEMORY_MIB`、`PAPER_TRANSLATION_JOB_TIMEOUT_SECONDS`、`PAPER_TRANSLATION_MEMORY_METRIC` 显式调整（显式值最多物理内存 50%）。扫描新输入默认最多 2 页。模型服务另计，上限 40GiB。先做一页，确认内存正常再扩大。

- 只使用 `--latex-source` 或 `--latex-source-root` 显式批准的本地 LaTeX 源码。arXiv 和 Docker 默认关闭，分别只在用户

- 同意并显式传入 `--allow-arxiv-source-autodownload`、`--latex-compile-runtime docker` 时启用。

+ 输入预检与失败统一输出结构化 JSON：`status`、`error_code` 和 `findings`（每项含 `code`/`severity`/`message`/`details`）；被预检拦下时退出码为 2。错误码含 `encrypted_user_password_required`、`pdf_truncated_or_corrupt`、`page_limit_exceeded`、`non_digital_pages`、`source_language_matches_target` 等，`permissions_restricted` 为警告。当前只支持英译中：源文主要是中文时 `candidate` 直接拒绝，不会静默输出中文。成品另做渲染英文残留检查，大面积未翻译判为高风险失败（`quality_status: fail`），此时 `candidate` 仍写出译文，但以退出码 3 结束并在 JSON 中列出失败原因。错误码表见[运行说明](references/release-quickstart.md)。

- ## 安全与副作用

+ | 退出码 | 含义 |

+ |---|---|

+ | 0 | 成功；`candidate` 的质量结论为 `pass`/`warn`/`unverified` |

+ | 1 | 其它失败（如资源超限停止、后端失败），见 `status`/`stop_reason`/`exception` |

+ | 2 | 被输入预检或合同校验拦下（`status: blocked`，见 `error_code`/`findings`），不产生译文 |

+ | 3 | 仅 `candidate`：译文照常写出，但综合质量判 `fail`；结果 JSON 含 `quality_gate: fail`、`quality_fail_summary`、`quality_fail_reasons`（检查项、页码、残留比例与逐页等级）、`render_residue_pages` 和 `output_files` |

- - 权限为 `file_read`（用户 PDF／显式批准的可信源码）、`file_write`（默认仅 `--output-dir`）、

- `network`（获批模型 endpoint）和 `shell`（本地 Python／PDF 工具）；宿主必须按此最小授权。

- - 发送文档前须确认 endpoint；key 不得写入日志或产物，子进程只继承白名单环境变量。

- - 输入只读；输出、QA 中间件和本地质量记录只写 `--output-dir`。

- - arXiv 与 Docker 只接受上述显式 opt-in，不得自动代用户开启。

- - 本地兼容代理默认关闭；仅 `--translation-compat-proxy on` 会监听回环地址。`--engine-home` 可显式选择输出目录之外的缓存路径。

- - 本地代理忽略调用方的认证头，向上游只使用本次显式配置的 key，避免成为任意凭据中继。

+ ## 安装、配置与恢复

- ## 翻译规则

+ 使用 macOS/Linux、Python 3.12。从 skill 目录执行 `bash scripts/setup_venv.sh /absolute/new/venv`，随后用该环境的 Python 运行 `scripts/paper_translation_workflow.py`。详见 [运行依赖](references/runtime-dependencies.md)。

- 使用准确、可读的简体中文，保护公式、标识符、引用和专名；完整规则见

- `references/academic-translation-policy.md`。文本层为空时报告需要 OCR；版式不足、大段同文

- 回退或 delivery gate 为 partial/blocking 时交付诊断，不能接受退化 PDF。

+ 新翻译必须显式提供 `--base-url`、`--model` 及所需凭据；不自动选本机服务或替换模型。库存预检需显式给定 `--catalog-url`（不给则不探测库存，`inspect-input` 照常输出事实）。运行目录可通过 `PAPER_TRANSLATION_WORKSPACE` 指定；输入、输出及回执用绝对路径，输出选全新目录。联网获取源码、字体或模型须明确授权并记录来源。

- ## 参考

+ 主入口电子 PDF 与可信 LaTeX 的完整输入限 1–5 页。LaTeX 保护拒绝后的完整单元修订和断点恢复见 [恢复说明](references/latex-recovery.md)。`preflight` / `deliver` 仍使用严格门；有限交付只适用于具名接受的精确 PDF 及披露的限制。缺少语义、视觉、阅读器或重建证据时保留未验证。

- 工作流、依赖、平台陷阱、翻译政策、术语模板和服务商 URL 映射均在 `references/` 中按需读取。

+ 许可原文见 [LICENSE](LICENSE)，依赖及来源见 [运行依赖](references/runtime-dependencies.md)，维护差异见 [MODIFICATIONS.md](MODIFICATIONS.md)。