qiq-tech-paper-trans

name qiq-tech-paper-trans version 0.2.6 description 英文技术论文翻译为中文（信达雅学术风格）。支持本地 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、学术翻译。 location user entrypoint scripts/run.py qiq-tech-paper-trans 英文技术论文翻译为中文（信达雅学术风格）的 skill。 何时使用此 skill 当用户提出以下类型请求时， 立即加载并使用此 skill ： 翻译一篇 PDF 论文 / arXiv 论文 / 技术论文 提供论文 URL（arxiv.org / openreview / ACL Anthology 等）并要求翻译 对论文做中文化 / 汉化处理 需要保留图表、公式、引用编号的严格学术翻译 类似需求："把这篇 paper 翻一下"、"帮我译成中文"、"这篇 arxiv 能不能汉化" 核心原则 信达雅 + 忠实 ：学术语气，禁止擅自摘要、省略、补全。 结构保真 ：正文标题层级、图片、表格、公式（LaTeX）、代码块、引用编号 [12] 均原样保留。 References 截断 ：从 References / Bibliography / 参考文献 标题开始，后续所有内容（包括 Appendix 、补充材料等）均不翻译、不进入最终译文。 滑动窗口翻译单元 ：支持 segment 、 section 、 hybrid 三种模式；翻译时输入 previous_zh_context + current_source + next_source ，仅译 current_source 。 术语一致 ：内置 AI/ML 术语表 + 支持用户自定义 glossary.json 覆盖。 阻断级质检 ：正文段落对齐、图片/表格/公式/代码/引用数量一致、锁定块完整、References 后内容未混入译文、长度比正常、无摘要性短语；任一不通过则终止并报告，除非用户明确 --force 跳过。 定向返修 ：QA 阻断时自动生成 fix_prompts/ ，帮助外部 LLM 执行器精准修复问题翻译单元。 平台中立 ：核心脚本只依赖 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 所在目录，不要求固定为某个平台的专属路径。 # 检测 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 。 因此，只要平台具备以下能力即可接入： 执行 python3 scripts/run.py --stage prepare ... 生成任务。 读取 INDEX.md 和 prompts_per_segment/*.prompt.md 。 对每个 prompt 调用任意 LLM，并把纯译文写入对应的 zh_per_segment/<unit_id>.zh.md 。 执行 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 ： { "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 作为上下文）。 外部执行器推荐的伪代码： 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。