# Qiq Tech Paper Trans

> 英文技术论文翻译为中文（信达雅学术风格）。支持本地 PDF 文件与 URL 输入（arXiv 链接优先抓取 HTML 版本）。针对 AI/ML 论文深度优化，兼容通用技术论文。采用滑动 窗口翻译单元机制保证上下文连贯、术语一致；支持逐段、逐章节和 hybrid 章节翻译； 阻断级质检确保正文段落、图片、表格、公式、代码、引用均完整保留。默认从 References / Bibliography 开始截断，参考文献及其后内容（如 Appendix）不进入最终译文。 表格默认采用“截图入文”策略（pdfplumber + pymupdf），避免复杂表格被 Marker 抓成乱码、 并保证导出的 Markdown / Word 中表格清晰完整。PDF 预处理采用小文件整篇 Marker 超时回退、 大文件分块 Marker 单块回退的组合策略，支持分块并行 + status.json 断点修复；翻译调度输出 waves.json，同 wave 内单元可并发调用 LLM。finalize 阶段保留 `assets/` 作为最终 Markdown 的主图片路径，并镜像出 <stem>.assets/ 作为便携副本，同时生成图片链接校验报告。 整体流程采用平台中立的文件协议，可在 WorkBuddy、OpenClaw 或其他可读写文件并调用 LLM 的平台运行。 触发词：翻译论文、翻译技术论文、翻译学术论文、翻译 arxiv、arxiv 翻译、论文汉化、 paper translation、translate paper、英译中论文、paper to Chinese、学术翻译。

- Skill: `winstontang86/qiq-tech-paper-trans` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add winstontang86/qiq-tech-paper-trans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/winstontang86/qiq-tech-paper-trans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: winstontang86 (https://skillmd.com/u/winstontang86)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/winstontang86/qiq-tech-paper-trans

---

# qiq-tech-paper-trans

英文技术论文翻译为中文（信达雅学术风格）的 skill。

## 何时使用此 skill

当用户提出以下类型请求时，**立即加载并使用此 skill**：

- 翻译一篇 PDF 论文 / arXiv 论文 / 技术论文
- 提供论文 URL（arxiv.org / openreview / ACL Anthology 等）并要求翻译
- 对论文做中文化 / 汉化处理
- 需要保留图表、公式、引用编号的严格学术翻译
- 类似需求："把这篇 paper 翻一下"、"帮我译成中文"、"这篇 arxiv 能不能汉化"

## 核心原则

1. **信达雅 + 忠实**：学术语气，禁止擅自摘要、省略、补全。
2. **结构保真**：正文标题层级、图片、表格、公式（LaTeX）、代码块、引用编号 `[12]` 均原样保留。
3. **References 截断**：从 `References` / `Bibliography` / `参考文献` 标题开始，后续所有内容（包括 `Appendix`、补充材料等）均不翻译、不进入最终译文。
4. **滑动窗口翻译单元**：支持 `segment`、`section`、`hybrid` 三种模式；翻译时输入 `previous_zh_context + current_source + next_source`，仅译 `current_source`。
5. **术语一致**：内置 AI/ML 术语表 + 支持用户自定义 `glossary.json` 覆盖。
6. **阻断级质检**：正文段落对齐、图片/表格/公式/代码/引用数量一致、锁定块完整、References 后内容未混入译文、长度比正常、无摘要性短语；任一不通过则终止并报告，除非用户明确 `--force` 跳过。
7. **定向返修**：QA 阻断时自动生成 `fix_prompts/`，帮助外部 LLM 执行器精准修复问题翻译单元。
8. **平台中立**：核心脚本只依赖 Python 与文件系统；LLM 调用通过 `prompt -> zh.md` 文件协议完成，不绑定 WorkBuddy、OpenClaw 或特定 API。

## 输入

- **本地 PDF**：`/path/to/paper.pdf`
- **URL**：
  - arXiv（`arxiv.org/abs/xxxx` 或 `arxiv.org/pdf/xxxx`）→ 自动改走 HTML 版（ar5iv / arxiv.org/html）质量更高
  - 其他 PDF 直链 → 下载后走 PDF 流程
  - OpenReview / ACL Anthology HTML 页 → 直接 HTML 解析

## 输出

- `<paper_stem>.zh.md` —— 中文译文（图片引用默认指向同级 `assets/`，兼容多数 Markdown 预览器）
- `assets/` —— 最终 Markdown 的主图片目录
- `<paper_stem>.assets/` —— finalize 阶段从 `assets/` 镜像出的便携副本，便于打包搬运
- `<paper_stem>.zh.images.json` —— 本地图片链接存在性校验报告
- `<paper_stem>.qa.md` —— 质检报告
- 可选 `<paper_stem>.bilingual.md` —— 双语对照（`--bilingual` 启用）
- 可选 `<paper_stem>.zh.docx` —— Word 文档（`--export-docx` 启用，需 pandoc）

## 执行流程

```
输入 (PDF / URL)
  → fetch.py       下载（URL 情况）
  → preprocess.py  PDF/HTML → 结构化 Markdown (小 PDF 整篇 Marker；大 PDF 分块 Marker；超时/失败回退 pymupdf)
  → segment.py     分段 + 锚点化（锁定公式/代码/图片；表格可锁定或翻译；References 后内容标记排除）
  → translate.py   翻译单元生成 + previous_zh_context + 术语表 + 断点续译
  → postprocess.py 回贴锚点 + 中英排版规范化
  → qa_report.py   阻断级质检 + fix_prompts 返修提示
  → 输出
```

## 使用方式

任意宿主平台（例如 WorkBuddy、OpenClaw、本地脚本编排器）在满足触发条件后，都按如下方式调用。示例中的 `SKILL_DIR` 表示本 skill 所在目录，不要求固定为某个平台的专属路径。

```bash
# 检测 Python
which python3

# 进入 skill 目录，或直接使用脚本绝对路径
export SKILL_DIR=/path/to/qiq-tech-paper-trans
cd "$SKILL_DIR"

# 本地 PDF
python3 "$SKILL_DIR/scripts/run.py" \
  --input /path/to/paper.pdf \
  --outdir /path/to/output

# URL 输入
python3 "$SKILL_DIR/scripts/run.py" \
  --input https://arxiv.org/abs/2403.xxxxx \
  --outdir /path/to/output

# 可选参数
--bilingual          同时输出双语对照 Markdown
--export-docx        finalize 阶段额外导出 .docx（需本机安装 pandoc）
--glossary FILE      用户自定义术语表（覆盖内置）
--unit-mode MODE     翻译单元：segment / section / hybrid（默认 hybrid）
--hybrid-max-chars N hybrid 模式下单个翻译单元最大字符数（默认 12000）
--table-mode MODE    表格策略：lock / translate（默认 lock）
--pdf-engine MODE    PDF 解析：auto / marker / pymupdf / marker-chunked（默认 auto）
--marker-timeout N   整篇 Marker 超时时间秒数（默认 900；按实测 65-75s/页，正文 ≤8 页走整篇模式时 900s 留 1.6x 余量）
--large-pdf-pages N  auto 模式下，去掉 References 后的正文页数超过 N 页则改用分块 Marker（默认 8）
--pdf-chunk-pages N  分块 Marker 每块页数（默认 4；按 70s/页，单块约 280s，远低于 chunk-timeout，降低宿主中断风险）
--chunk-timeout N    分块 Marker 单块基础超时时间秒数（默认 600；OCR 日志仍活跃时自动宽限到最多 3 倍）
--chunk-fallback M   单块失败策略：pymupdf / skip / fail（默认 pymupdf）
--chunk-concurrency N 分块 Marker 并行 worker 数（默认 1；每个 worker 加载 ~1-2GB 模型，建议 2、4）
--progress-interval N Marker 与分块 PDF 预处理的心跳输出间隔秒数（默认 30；用于大 PDF 长时间运行时确认仍在执行）
--retry-fallback     --resume 时，重跑之前 fallback 到 pymupdf/skip/failed 的分块
--table-strategy MODE 表格处理策略：image / markdown（默认 image）
                        image：用 pdfplumber 检测 PDF 中的表格区域并用 pymupdf 截图为 PNG，
                        在 Markdown 中用图片引用替换掉乱的表格文本，译文原样保留图片，
                        翻译 / Word 导出都不会破表。
                        markdown：保留 Marker 抽出的 Markdown 表格，再由 --table-mode 决定锁定或翻译。
--force              跳过阻断级质检（仅在用户明确要求时使用）
--resume             断点续译；复用已有 source.md、segments.json 和已完成 PDF 分块
```

## LLM 翻译调用约定（重要）

本 skill 的 `translate.py` 本身不直接调用 LLM API，也不假设运行在某个特定 Agent 产品中。它会把每个翻译单元的 prompt 写入 `prompts_per_segment/*.prompt.md`，由宿主平台或外部 LLM 执行器读取、调用模型，并将译文写回 `zh_per_segment/*.zh.md`。

因此，只要平台具备以下能力即可接入：

1. 执行 `python3 scripts/run.py --stage prepare ...` 生成任务。
2. 读取 `INDEX.md` 和 `prompts_per_segment/*.prompt.md`。
3. 对每个 prompt 调用任意 LLM，并把纯译文写入对应的 `zh_per_segment/<unit_id>.zh.md`。
4. 执行 `python3 scripts/run.py --stage finalize --outdir ...` 组装、回贴锁定块并质检。

如果宿主平台支持 system/user 角色，请把 prompt 文件中的 `# SYSTEM` 用作 system prompt、`# USER` 用作 user message；如果不支持 system 角色，可把 `# SYSTEM` 内容放到 user message 开头。

### wave 并行调度（提速推荐）

`--stage prepare` 阶段除了生成 `prompts_per_segment/` 和 `INDEX.md` 外，还会输出 `waves.json`：

```json
{
  "total_units": 42,
  "num_waves": 8,
  "max_parallel": 9,
  "waves": {
    "0": ["sec_0001", "sec_0002", ...],
    "1": ["sec_0001_part_002", "sec_0002_part_002", ...],
    ...
  }
}
```

- 同一 wave 内的单元彼此**没有 previous_zh 依赖**，可并发调用 LLM。
- 不同 wave 之间必须串行（后面的 wave 需要前一 wave 的 `zh.md` 作为上下文）。
- 外部执行器推荐的伪代码：
  ```python
  waves = json.load(open("waves.json"))["waves"]
  for wave_id in sorted(waves, key=int):
      parallel_run(waves[wave_id], concurrency=N)  # wave 内并行
  ```
- 如宿主不支持并发，按 INDEX.md 的 unit_id 顺序串行调用同样正确。

### PDF 预处理并行

对于大 PDF（页数 > `--large-pdf-pages`，默认 20）自动进入分块 Marker 模式。设置 `--chunk-concurrency 2` 可在内存充足的机器上将预处理时间减少约 40%~50%；每个 worker 会独立加载 Marker 模型（16GB RAM 机器推荐 2，32GB 可试 3~4）。

每个分块在 `preprocess_chunks/<chunk_id>/status.json` 记录使用的引擎（marker / pymupdf / skip / failed）；配合 `--resume --retry-fallback` 可仅重跑之前 fallback 到 pymupdf 的分块，已用 Marker 成功的分块不会被触发。

## 依赖

- Python 3.10+（推荐系统已有的 3.12）
- 首次运行时按需 `pip install -r requirements.txt`
- Marker 会在首次 PDF 解析时下载 ~1–2GB 模型权重
- **可选**：`--export-docx` 依赖系统 pandoc（macOS：`brew install pandoc`；Ubuntu：`apt install pandoc`）

## 版本

v0.2.6（2026-04-26）—— 新增“表格即图片”策略（`--table-strategy image`，默认开启）：使用 pdfplumber 检测 PDF 中的表格区域，通过 pymupdf 2x 清晰度裁剪为 PNG 并插入译文，同时移除 Marker 输出的（常乱排的） Markdown 表格块，彻底解决复杂表格在 md/docx 中破表的问题；原有 `--table-mode lock/translate` 仅在 `--table-strategy markdown` 时生效；docx 导出直接渲染表格图片，不再依赖 pandoc 对复杂表格的有限支持。

v0.2.5（2026-04-26）—— 修复图片破图问题：修正整篇 Marker 模式下图片链接缺少 `assets/` 前缀导致的渲染失败；finalize 阶段自动将 `assets/` 镜像为 `<stem>.assets/` 并重写译文中的图片路径，确保单独搬运 `<stem>.zh.md` 或导出为 Word 时图片仍可渲染；新增 `--export-docx` 选项，通过 pandoc 导出带图片的 .docx。

v0.2.4（2026-04-26）—— 性能优化：PDF 分块 Marker 支持 `--chunk-concurrency` 并行，单块内 status.json 记录引擎；`--retry-fallback` 可配合 `--resume` 仅重跑 fallback 分块；默认 `--large-pdf-pages=20 --pdf-chunk-pages=12`；翻译阶段新增 `waves.json`，同 wave 内单元无 previous_zh 依赖可安全并发调用 LLM。

v0.2.3（2026-04-26）—— PDF 预处理采用组合策略：小 PDF 整篇 Marker 超时回退，大 PDF 分块 Marker 单块回退，并增强 `--resume` 复用已有预处理/分段产物。

v0.2.2（2026-04-26）—— 将 skill 运行协议平台中立化，移除 WorkBuddy 专属假设，补充 WorkBuddy / OpenClaw / 通用 LLM 执行器接入说明。

v0.2.1（2026-04-26）—— 从 References / Bibliography 开始截断，参考文献及其后内容（如 Appendix）不进入最终译文。

v0.2.0（2026-04-26）—— 支持 hybrid/section 翻译单元、上一单元中文上下文、表格策略、B9/B10 质检与自动修复 prompt。

v0.1.0（2026-04-25）—— 初始版本，v1。