Skip to content
Back to search

pdf-translate

"Use when translating PDF documents between languages while strictly preserving original layout, formatting, typography, tables, and signatures. Powered by LLM direct comprehension, two-stage data-contract translation, chunked modular generation, in-browser JS overflow detection, and high-fidelity vector PDF reconstruction. Features zero-hallucination guardrails and automated 1:1 page-by-page audit script (audit_pdf.py)."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lxsssssss--pdf-translate/badge.svg)](/listings/lxsssssss--pdf-translate)

HTML

<a href="/listings/lxsssssss--pdf-translate"><img src="/api/listings/lxsssssss--pdf-translate/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. 安装依赖

git clone https://github.com/lxsssssss/pdf-translate.git
cd pdf-translate

pip install -r requirements.txt
playwright install chromium

> *注:Windows 环境下亦支持直接调用系统自带的 `msedge` 浏览器信道。*

---

2. 运行一键开箱即测 Demo

无需准备任何复杂环境,直接运行项目内置的端到端体验脚本:

python examples/quick_demo.py

终端将依次执行:渲染英文原件与中文译件 ➔ 递归溢出探针与页数校验 ➔ 以原件为基准逐页审计译件 ➔ 在 `examples/output/` 输出 JSON 报告与并排对比图!

运行测试:

pip install -r requirements-dev.txt
python -m pytest

---

3. 命令行工具使用指南

🔹 矢量 PDF 渲染 (`render_pdf.py`)

将排版好的 HTML 源码渲染为物理隔离的矢量 PDF:

# 基础渲染
python scripts/render_pdf.py input.html output.pdf

# 开启严格模式 (任何溢出或页数不符则不写出 PDF,退出码 2)
python scripts/render_pdf.py input.html output.pdf --strict-overflow

# 指定浏览器 (默认 auto:优先 Edge,失败回退 Playwright 自带 Chromium)
python scripts/render_pdf.py input.html output.pdf --browser chromium

🔹 自动化 1:1 对比审计 (`audit_pdf.py`)

比对原版 PDF 与翻译后 PDF 的页码、矢量层、条款编号与文本完整性:

# 基础对比审计
python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf

# 严格模式 (任何警告均触发非零返回码)
python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf --strict

# 输出结构化 JSON 审计报告 (便于 CI/CD 或 Agent 自动化解析)
python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf --json audit_report.json

# 生成原件|译件并排对比图 (可用 --pages 1,3,5-7 指定页)
python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf --compare-png compare_png/

# 忽略合法差异 (如年份),或使用自定义敷衍词表
python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf --ignore "^(19|20)\d\d$" --keywords my_keywords.json

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: pdf-translate
  3. description: "Use when translating PDF documents between languages while strictly preserving original layout, formatting, typography, tables, and signatures. Powered by LLM direct comprehension, two-stage data-contract translation, chunked modular generation, in-browser JS overflow detection, and high-fidelity vector PDF reconstruction. Features zero-hallucination guardrails and automated 1:1 page-by-page audit script (audit_pdf.py)."
  4. version: 2.4.0
  5. author: Antigravity
  6. ---
  7. # PDF 保持原排版翻译 Skill (大模型直译 + 几何探针测量 + 矢量排版重构 + 生成后对比自愈)
  8. 当用户需要**翻译 PDF 文档**,且要求**必须完整保留原始版面格式、公文表头、目录、双语表格、签章栏、插图物理尺寸**并最终**输出为高保真矢量 PDF 文件**时,使用此 Skill。
  9. > [!IMPORTANT]
  10. > **四大核心铁律(杜绝机翻乱码、长文档幻觉、跨页溢出与图片排版变形)**:
  11. > 1. **严禁脑补,严格忠实直译 (Strict Faithful Translation & Zero Hallucination)**:
  12. > - **不得压缩或遗漏条款**:逐条忠实翻译每一个一级、二级、三级子条款(如法定资质证照清单 2.1.1~2.1.8、年限指标、年产能门槛 150,000 吨、分卷装订规则 Volume 2A/2B 等),坚决禁止主观总结或合并条款;
  13. > - **坚决禁止虚构常识**:严禁凭常识脑补原文不存在的交付程序、装订份数、银行授信金额或办事流程(例如原文未写具体金额则绝对禁止编造 1,000,000 KWD,无 5.3 节则绝对不可添加 5.3 节);
  14. > - **表格格式 1:1 忠实还原**:官方附表(如 Appendix-1 至 Appendix-6)的列名、行高、选项框、备注及签字盖章区必须严格对齐原件,严禁用自创的“申报核对清单 (Checklist)”或通用表格粗糙代替。
  15. > 2. **几何探针与视觉锚点测量铁律 (Geometry Probe & Visual Anchor Measurement)**:
  16. > - **绝对禁止经验主义猜度尺寸**:严禁在未测量原件几何信息的情况下,随意给插图或表格加上 `max-height: 220px` 等主观限制,导致原图严重缩水变形或比例失调;
  17. > - **原图物理坐标与尺寸 1:1 提取**:提取图片时必须调用 `page.get_image_rects(xref)` 获取原图在页面上的实际 `width`、`height` 以及 `x0, y0`,并在 HTML 中严格以真实物理尺寸呈现(如原件宽 218.9pt、高 322.4pt,HTML 中必须按照该物理尺寸渲染);
  18. > - **几何线条与装饰框高保真复刻**:通过 `page.get_drawings()` 提取所有几何元素(如顶会论文标题框的 4pt 粗黑顶线与 1pt 细底线、长度 143.5pt 的左对齐短横脚注线),严禁用通用单薄的 100% 宽度边框粗暴替代;
  19. > - **中文信息密度补偿与垂直基线对齐**:中文字符信息密度通常比西文高 20%~35%,必须记录关键文字块的垂直基准起点 `y0`(如摘要标题、正文、章节起始与脚注线位置),通过微调行高(`line-height: 1.35~1.45`)、段落间距(`margin`)以及灵活运用网格与绝对定位,确保中文版面的视觉重心与垂直基线与原件严密锚定,杜绝页面下半部分突兀大面积留白;
  20. > - **首页页眉页脚特殊规则**:大部分顶会论文(NIPS/ICML/CVPR 等)或官方公文首页(Page 1)不编排页码,底部通常为会议发表信息或官方备案行,严禁在第一页机械添加页码。
  21. > 3. **两阶段解耦与分块生成 (Schema-First & Chunked Pipeline)**:
  22. > - **数据与排版分离**:长文档翻译时,优先提取页面结构化数据(条款清单、参数字典、表格行列),再灌入标准化 HTML 模板,严禁一边长篇自由发挥一边写标签;
  23. > - **单批次生成严禁超过 10 页**:超过 10 页的文档强制按 10 页为单位拆分为独立模块(如 `part1_pages.py`, `part2_pages.py`),避免模型在中后段注意力衰减导致失控。
  24. > 4. **生成后对比质检与用户确认关卡 (Mandatory Audit & User Preview Before Commit)**:
  25. > - PDF 渲染生成后,**绝不允许直接交付给用户**,必须运行技能内置的 `scripts/audit_pdf.py` 执行页数、页面尺寸、矢量层、条款/数值/结构引用差集与敷衍词全面扫描,并用 `--compare-png` 生成并排对比图;
  26. > - 渲染生成 1:1 并排对比图(PNG),**必须在对话中直接展示关键页面对比效果供用户审阅确认**,在获得用户明确许可前严禁擅自 Git Commit 或推送!
  27. ---
  28. ## 触发场景 (Trigger Scenarios)
  29. - 用户提供或指定 PDF 文件,要求翻译为中文、英文或其他语言;
  30. - 用户明确要求“**保持原排版**”、“**格式不变**”、“**输出为 PDF**”;
  31. - 官方招标文件、商务合同、投标预审资格手册(如中东阿文/英文标书、水电部 MEWRE、管网工程);
  32. - 包含中英阿多语言混排、双语对照表格、签字盖章区、点线对齐目录的复杂 PDF 文档;
  33. - 行业技术规范、学术论文、企业白皮书。
  34. ---
  35. ## Agent 执行标准工作流 (Standard Operating Procedure)
  36. 当收到翻译 PDF 任务时,Agent 需严格遵循以下 5 步标准化闭环作业流程:
  37. ### 第一步:文档几何探测与结构分块 (Inspection & Geometry Probing)
  38. 使用 Python (`fitz` / PyMuPDF) 全面探测文档物理尺寸、插图尺寸、装饰线与关键文本块基线坐标:
  39. ```python
  40. import fitz
  41. doc = fitz.open("path/to/document.pdf")
  42. print("Total pages:", len(doc))
  43. for i, page in enumerate(doc):
  44. print(f"\n=== PAGE {i+1} rect: {page.rect} ===")
  45. # 1. 探测图片物理尺寸与位置
  46. for img in page.get_images():
  47. for r in page.get_image_rects(img[0]):
  48. print(f" Image xref {img[0]}: w={r.width:.1f}, h={r.height:.1f}, (x0={r.x0:.1f}, y0={r.y0:.1f})")
  49. # 2. 探测几何线条与装饰边框
  50. for d in page.get_drawings():
  51. r = d['rect']
  52. if r.width > 30:
  53. print(f" Line: w={r.width:.1f}, h={r.height:.1f}, (x0={r.x0:.1f}, y0={r.y0:.1f})")
  54. # 3. 探测核心文本块垂直基准起点 y0
  55. for b in page.get_text("blocks"):
  56. if b[4].strip():
  57. print(f" Block ({b[0]:.1f}, {b[1]:.1f}, {b[2]:.1f}, {b[3]:.1f}): {b[4].strip()[:40]}")
  58. # 若总页数 > 10 页,强制制定分块规划(如 Part 1: P1~10, Part 2: P11~20 ...)
  59. ```
  60. ### 第二步:两阶段专业直译(严格无脑补)(Two-Stage Strict Translation)
  61. - **阶段 1(提取与核定)**:先按页提取条款编号、所有数值区间与表格字段,建立精确的翻译数据契约;
  62. - **阶段 2(模板化填装)**:
  63. - 准确翻译专业术语与国际标准(如 Transformer 自注意力、编码器-解码器架构、BLEU 得分、残差连接;或标书中的 ISO 2531、BS EN 545、AWWA、科威特水电部 MEWRE 等);
  64. - 数字、单位与公式 100% 核实(如 200.00 ppm, 4°C, 150 微米, 2200 kg/cm², $d_{\text{model}} = 512$ 等)。
  65. ### 第三步:高保真矢量页面重构与物理限高 (Layout Reconstruction with Physical Anchors)
  66. 利用标准 HTML5 + CSS `@page` 打印样式进行 1:1 页面映射重构:
  67. - **物理尺寸动态适配与防溢出**:
  68. 根据第一步探测得到的真实页面尺寸定义 `@page`(如 US Letter `size: 8.5in 11in;` 或 A4 `size: 210mm 297mm;`):
  69. ```css
  70. @page {
  71. size: 8.5in 11in;
  72. margin: 0;
  73. }
  74. .page {
  75. width: 8.5in;
  76. height: 11in;
  77. max-height: 11in;
  78. padding: 72pt 108pt 72pt 108pt;
  79. page-break-after: always;
  80. position: relative;
  81. box-sizing: border-box;
  82. display: flex;
  83. flex-direction: column;
  84. overflow: hidden; /* 严禁内部元素撑爆高度触发打印机额外分页 */
  85. }
  86. .content-area {
  87. flex: 1;
  88. overflow: hidden; /* 渲染探针会递归检测所有裁切容器,被裁掉的内容同样报错 */
  89. }
  90. ```
  91. > 统一约定:`@page { margin: 0 }`,每个 `.page` 恰好等于一张物理纸张(宽高 = 原件 `page.rect`),页边距一律写在 `.page` 的 `padding` 中。不要同时使用 `@page margin` 与 `.page` 固定高度,否则极易多出空白页。
  92. - **插图 1:1 物理尺寸渲染**:严格按照第一步测量的 `w` 和 `h` 设定图片的 `width` 与 `height`(如 `width: 218.9pt; height: 322.4pt;`),绝对禁止用经验值限制!
  93. - **几何线条还原**:依据探测出的线条坐标绘制精确线宽与长度(如标题框 4pt 顶线 + 1pt 底线、143.5pt 短横脚注线);
  94. - **中文垂直基线对齐**:通过段落间距和舒适行高(1.35~1.45)合理分布垂直空间,使各区块垂直起点与原件基线严格对齐;
  95. - **字体标准**:默认使用标准专业矢量字体(英文 Times New Roman,中文 SimSun / Songti SC / Noto Serif CJK SC),确保学术严肃性与无乱码渲染。
  96. ### 第四步:内置引擎渲染与 JS 溢出探针 (Vector Rendering with Overflow Probe)
  97. 调用技能内置渲染脚本直接生成纯矢量 PDF(以下路径均相对于本 SKILL 所在目录):
  98. ```bash
  99. python scripts/render_pdf.py "path/to/full_doc.html" "path/to/output_full.pdf" --strict-overflow
  100. ```
  101. - 探针会递归检测每个 `.page` 及其内部所有 `overflow: hidden/clip/auto/scroll` 容器的纵向与横向溢出;
  102. - 渲染后校验 PDF 实际页数 = `.page` 容器数量,防止多出空白页;
  103. - `--strict-overflow` 下任何溢出均不写出 PDF 并以退出码 2 结束;浏览器默认先用 Edge,不可用时自动回退到 Playwright 自带 Chromium(可用 `--browser` 指定)。
  104. ### 第五步:自动化对比审计与视觉并排质检 (Automated Audit & Visual Review)
  105. 生成 PDF 后,**必须运行技能内置的 `audit_pdf.py` 自动化对比工具并生成对比图**:
  106. ```bash
  107. python scripts/audit_pdf.py --src "path/to/source.pdf" --tgt "path/to/output_full.pdf" \
  108. --json audit_report.json --compare-png compare_png/
  109. ```
  110. 该工具逐页执行以下检查(`--strict` 时所有 WARNING 也判为失败):
  111. | 检查项 | 级别 |
  112. | :--- | :--- |
  113. | 总页数 1:1 一致 | CRITICAL |
  114. | 逐页页面尺寸一致(默认容差 2pt,防止 Letter 被渲染成 A4) | CRITICAL |
  115. | 译文出现整页位图(扫描件伪装) | CRITICAL |
  116. | 译文出现 U+FFFD 乱码字符(字体缺字) | CRITICAL |
  117. | 敷衍/捏造词(如“因篇幅省略”“详见英文原版”“核对清单”)出现在译文但原文没有 | CRITICAL |
  118. | 条款编号缺失(2.1 / 2.1.1 …) | WARNING |
  119. | 跨语言结构引用缺失(Section/Appendix/Table/Figure ↔ 第N部分/附录/表/图) | WARNING |
  120. | 数值缺失或被改动(金额、年限、产能门槛,自动归一千分位) | WARNING |
  121. | 逐页图片数量 / 尺寸(>5%)不一致 | WARNING |
  122. | 原文有内容而译文页面近乎空白 | WARNING |
  123. | 译文存在未嵌入字体 | WARNING |
  124. - 敷衍词表位于 `scripts/keywords.json`,可用 `--keywords` 替换;
  125. - 对年份、标准号等合法差异,可用 `--ignore "<正则>"` 排除,例如 `--ignore "^(19|20)\d\d$"`;
  126. - `--compare-png DIR [--pages 1,3,5-7]` 输出原件|译件左右并排 PNG,供下方视觉门禁使用。
  127. **用户视觉确认门禁 (User Confirmation Gate)**:
  128. - 使用 `--compare-png` 生成的 1:1 并排对比图,在会话中直接展示重点页面(如封面、架构图页、复杂表格页);
  129. - 向用户汇报质检结果与对齐细节,**必须等待用户明确确认满意后,方可执行 Git 提交或任务交付**!
  130. ---
  131. ## 核心脚本工具箱 (Built-in Scripts)
  132. - **PDF 渲染引擎(含 JS 页面溢出自检)**:[`scripts/render_pdf.py`](scripts/render_pdf.py)
  133. - 底层基于 Microsoft Edge / Chromium 矢量打印,递归检测 `.page` 及嵌套裁切容器溢出,并校验 PDF 页数。
  134. - **PDF 1:1 自动化对比审计引擎**:[`scripts/audit_pdf.py`](scripts/audit_pdf.py)
  135. - 逐页 1:1 扫描源文件与目标文件:页数、页面尺寸、纯矢量层、图片、字体、条款 Diff、结构引用、数值一致性、敷衍词拦截,并可输出并排对比 PNG。
  136. - **敷衍/捏造词表**:[`scripts/keywords.json`](scripts/keywords.json)
README.md · README · 251 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <b>简体中文</b> | <a href="README_EN.md">English</a>
  3. </p>
  4. # 📄 PDF-Translate Skill
  5. > **High-Fidelity Vector PDF Translation, Layout Reconstruction & Automated Audit Engine for AI Agents.**
  6. > 基于大语言模型直译、矢量排版重构、浏览器溢出探针与自动化双向对比自愈的高保真 PDF 翻译技能。
  7. [![CI](https://github.com/lxsssssss/pdf-translate/actions/workflows/ci.yml/badge.svg)](https://github.com/lxsssssss/pdf-translate/actions/workflows/ci.yml)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  9. [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
  10. [![Playwright](https://img.shields.io/badge/Playwright-Vector%20PDF-green.svg)](https://playwright.dev/)
  11. [![PyMuPDF](https://img.shields.io/badge/PyMuPDF-Audit%20Engine-orange.svg)](https://pymupdf.readthedocs.io/)
  12. [![Compatible with Antigravity](https://img.shields.io/badge/Google-Antigravity-4285F4?logo=google&logoColor=white)](https://antigravity.google)
  13. [![Compatible with Claude Code](https://img.shields.io/badge/Claude-Code-D97706?logo=anthropic&logoColor=white)](https://claude.ai)
  14. [![Compatible with Cursor](https://img.shields.io/badge/Cursor-Rules-000000?logo=cursor&logoColor=white)](https://cursor.com)
  15. [![Compatible with Windsurf](https://img.shields.io/badge/Windsurf-Cascade-0EA5E9?logo=windsurf&logoColor=white)](https://codeium.com/windsurf)
  16. [![Compatible with Codex](https://img.shields.io/badge/OpenAI-Codex-10A37F?logo=openai&logoColor=white)](https://openai.com)
  17. [![Compatible with WorkBuddy](https://img.shields.io/badge/WorkBuddy-Agent-6366F1)](https://github.com/lxsssssss/pdf-translate)
  18. [![Compatible with DeepSeek](https://img.shields.io/badge/DeepSeek-V3%20%2F%20R1-4F46E5)](https://deepseek.com)
  19. ---
  20. ## 📸 效果对比展示 (Before & After Showcase)
  21. > **实测案例**:现代深度学习与大模型开山之作《Attention Is All You Need》(arXiv:1706.03762),包含多作者机构矩阵、精准边栏学术水印、双栏摘要、数学脚注及严格版面限高。
  22. ### 1. 顶会学术论文封面与双栏排版 1:1 还原 (Paper Cover & Dual-Column Layout)
  23. ![Cover Comparison](assets/comparison_cover.png)
  24. ### 2. 复杂模型架构图与物理点位 1:1 精准锚定 (Figure 1 Architecture & Physical Anchors)
  25. ![Page 3 Architecture Comparison](assets/comparison_page_03.png)
  26. ---
  27. ## 🌟 核心痛点与解决方案 (Why PDF-Translate?)
  28. 传统的文档翻译工具(如通用机翻、常规 OCR 导出)在面对**工程标书、跨国商务合同、法定资质证书、学术白皮书**等严肃公文时,常常面临四大致命难题:
  29. 1. **版面坍塌**:表格错位、签章栏截断、页码漂移、目录点线混乱。
  30. 2. **位图失真**:将文字光栅化为低分辨率图片,导致无法检索复制、模糊不清。
  31. 3. **AI 幻觉脑补**:长文本模型擅自“归纳升华”、擅增/缩减子条款编号或脑补不存在的数字。
  32. 4. **跨页溢出**:翻译后的中英文文本长度差异撑爆页面物理高度,导致打印机额外产生空页或乱页。
  33. **`pdf-translate`** 专为解决上述痛点而生,结合大模型精准语义提取与前端 CSS 矢量打印控制,确保翻译结果达到**正式出版与官方公文交付级标准**。
  34. ---
  35. ## 🚀 核心特性 (Key Features)
  36. - 🎯 **1:1 原版排版还原 (1:1 Layout Preservation)**
  37. - 严格保持页面尺寸(标准 A4、Letter 等)、物理边距与布局比例。
  38. - 精准重建双语对照表格、官方公文双栏表头、目录点线对齐(Dotted Leaders)及签字盖章框。
  39. - 🚫 **零幻觉与两阶段解耦规范 (Zero Hallucination Pipeline)**
  40. - **阶段 1(结构化契约)**:按页先提取条款树、数值、参数与表格结构。
  41. - **阶段 2(模板化填装)**:严禁压缩、省略或凭常识脑补条款(如法定资质清单 2.1.1~2.1.8)。
  42. - 📐 **浏览器物理高度溢出探针 (JS Height Overflow Probe)**
  43. - 在无头渲染阶段注入 JavaScript 探针,实时检测每个 `.page` 容器的 `scrollHeight` 与 `clientHeight`。
  44. - 自动拦截并报警任何可能导致分页错乱的微小溢出。
  45. - 🖨️ **纯矢量无损 PDF 重构 (Publication-Grade Vector PDF)**
  46. - 基于 Chromium / Edge 内核,输出全矢量、可选中、可搜索、超高清的工业级 PDF。
  47. - 🔍 **自动化对比审计引擎 (`scripts/audit_pdf.py`)**
  48. - **页数与页面尺寸校验**:总页数严格 1:1,逐页尺寸一致(防止 Letter 被渲染成 A4)。
  49. - **纯矢量层、图片与字体校验**:杜绝整页截图伪装,逐页比对图片数量/尺寸,检测未嵌入字体与乱码字符。
  50. - **条款 / 结构引用 / 数值逐页 Diff**:比对子条款编号、跨语言的 Section/附录/表/图引用,以及金额、年限等关键数字。
  51. - **敷衍词扫描(参照原文)**:拦截“待补充”、“因篇幅省略”、“详见英文原版”等占位符,原文本身就有的词不误报。
  52. - **并排对比图**:`--compare-png` 一键生成原件|译件左右对照 PNG。
  53. ---
  54. ## 🏗️ 架构与工作流 (Architecture & Workflow)
  55. ```mermaid
  56. flowchart TD
  57. A["原始 PDF 文档"] --> B["步骤 1: PyMuPDF 结构探测与分块规划"]
  58. B --> C["步骤 2: 两阶段数据契约抽取与严谨直译"]
  59. C --> D["步骤 3: 现代化 HTML5 + CSS @page 矢量重构"]
  60. D --> E["步骤 4: Playwright 无头渲染 + JS 溢出探针 (render_pdf.py)"]
  61. E --> F["生成目标矢量 PDF"]
  62. F --> G["步骤 5: audit_pdf.py 自动化审计对比"]
  63. G -->|"未通过: 发现溢出 / 遗漏 / 编号不符"| D
  64. G -->|"通过: 1:1 完美匹配 且 0 报错"| H["正式交付发布"]
  65. ```
  66. ---
  67. ## 📂 项目结构 (Repository Structure)
  68. ```text
  69. pdf-translate/
  70. ├── .github/
  71. │ ├── workflows/ci.yml # 自动化 CI 测试工作流
  72. │ └── ISSUE_TEMPLATE/ # 社区 Bug 与 Feature 规范模板
  73. ├── SKILL.md # Antigravity / AI Agent 核心技能指令与约束规范 (中文版)
  74. ├── SKILL_EN.md # Core Skill Definition & Zero-Hallucination SOP (English Version)
  75. ├── requirements.txt # 核心 Python 依赖项
  76. ├── requirements-dev.txt # 开发/测试依赖 (pytest)
  77. ├── LICENSE # MIT 开源协议
  78. ├── README.md # 简体中文说明文档
  79. ├── README_EN.md # English Documentation
  80. ├── assets/ # 官方公文 1:1 真实案例对比图
  81. ├── examples/ # 开箱即测示例与一键体验脚本
  82. │ ├── sample_source.html # 英文原件示例(审计的 --src)
  83. │ ├── sample_doc.html # 对应的中文译件示例(审计的 --tgt,A4 统一页面约定)
  84. │ └── quick_demo.py # 一键端到端「渲染原件+译件 → 审计 → 并排对比图」脚本
  85. ├── scripts/
  86. │ ├── audit_pdf.py # 逐页审计:页数/尺寸/矢量层/图片/字体/条款/结构引用/数值/敷衍词 + 对比图
  87. │ ├── keywords.json # 可扩展的敷衍/捏造词表
  88. │ └── render_pdf.py # Playwright 矢量渲染(递归溢出探针 + PDF 页数校验 + 浏览器自动回退)
  89. └── tests/ # pytest:抽取器单测 + 故意制造缺陷的译文集成测试 + 渲染探针测试
  90. ```
  91. ---
  92. ## 🛠️ 安装与快速上手 (Installation & Quick Start)
  93. ### 1. 安装依赖
  94. ```bash
  95. git clone https://github.com/lxsssssss/pdf-translate.git
  96. cd pdf-translate
  97. pip install -r requirements.txt
  98. playwright install chromium
  99. ```
  100. > *注:Windows 环境下亦支持直接调用系统自带的 `msedge` 浏览器信道。*
  101. ---
  102. ### 2. 运行一键开箱即测 Demo
  103. 无需准备任何复杂环境,直接运行项目内置的端到端体验脚本:
  104. ```bash
  105. python examples/quick_demo.py
  106. ```
  107. 终端将依次执行:渲染英文原件与中文译件 ➔ 递归溢出探针与页数校验 ➔ 以原件为基准逐页审计译件 ➔ 在 `examples/output/` 输出 JSON 报告与并排对比图!
  108. 运行测试:
  109. ```bash
  110. pip install -r requirements-dev.txt
  111. python -m pytest
  112. ```
  113. ---
  114. ### 3. 命令行工具使用指南
  115. #### 🔹 矢量 PDF 渲染 (`render_pdf.py`)
  116. 将排版好的 HTML 源码渲染为物理隔离的矢量 PDF:
  117. ```bash
  118. # 基础渲染
  119. python scripts/render_pdf.py input.html output.pdf
  120. # 开启严格模式 (任何溢出或页数不符则不写出 PDF,退出码 2)
  121. python scripts/render_pdf.py input.html output.pdf --strict-overflow
  122. # 指定浏览器 (默认 auto:优先 Edge,失败回退 Playwright 自带 Chromium)
  123. python scripts/render_pdf.py input.html output.pdf --browser chromium
  124. ```
  125. #### 🔹 自动化 1:1 对比审计 (`audit_pdf.py`)
  126. 比对原版 PDF 与翻译后 PDF 的页码、矢量层、条款编号与文本完整性:
  127. ```bash
  128. # 基础对比审计
  129. python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf
  130. # 严格模式 (任何警告均触发非零返回码)
  131. python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf --strict
  132. # 输出结构化 JSON 审计报告 (便于 CI/CD 或 Agent 自动化解析)
  133. python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf --json audit_report.json
  134. # 生成原件|译件并排对比图 (可用 --pages 1,3,5-7 指定页)
  135. python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf --compare-png compare_png/
  136. # 忽略合法差异 (如年份),或使用自定义敷衍词表
  137. python scripts/audit_pdf.py --src original.pdf --tgt translated.pdf --ignore "^(19|20)\d\d$" --keywords my_keywords.json
  138. ```
  139. ---
  140. ## 🌐 多平台 AI 助手原生兼容 (Multi-Platform Ecosystem)
  141. 本项目设计为**跨平台、零依赖摩擦的通用 Agent 技能**,原生兼容目前主流 AI 编程助手与大模型智能体环境:
  142. | 平台 / 工具 | 部署路径 / 形式 | 核心支持说明 |
  143. | :--- | :--- | :--- |
  144. | **Google Antigravity** | `.agent/skills/pdf-translate/` | 原生 Skill 识别,自动探测与 5 步 SOP 闭环 |
  145. | **Claude Code** | `.claude/skills/pdf-translate/` 或全局规则 | 遵循 `SKILL_EN.md` 规则与两阶段零幻觉契约 |
  146. | **Cursor** | `.cursorrules` 或 `.cursor/rules/` | 代码生成严格遵循 `@page` 限高与纯矢量布局 |
  147. | **Windsurf (Cascade)** | `.windsurfrules` | 自动化调用 `render_pdf.py` 与 `audit_pdf.py` 自愈 |
  148. | **OpenAI Codex** | Custom Instructions / Action | 结构化数据提取 + 模板化填充双阶段工作流 |
  149. | **WorkBuddy** | 智能体工作流 / 技能中心插件 | 商务公文、外贸标书 1:1 翻译自动化作业 |
  150. | **DeepSeek (V3 / R1)** | 系统提示词 (System Prompt) | 深度推理提取条款树,严禁虚构与脑补条款 |
  151. ---
  152. ### 💻 各平台快速接入指南
  153. #### 1. Google Antigravity
  154. 直接将本项目拷贝至工作区的 `.agent/skills/pdf-translate` 目录下:
  155. ```text
  156. your-project/
  157. └── .agent/
  158. └── skills/
  159. └── pdf-translate/
  160. ├── SKILL.md
  161. ├── SKILL_EN.md
  162. └── scripts/
  163. ```
  164. 在会话中提示 **“帮我把这份文件翻译为中文,保持原排版并输出为 PDF”**,Agent 将自动激活该 Skill 并执行闭环工作流。
  165. #### 2. Claude Code
  166. 将本项目拷贝到项目级 `.claude/skills/pdf-translate/`(或用户级 `~/.claude/skills/pdf-translate/`),Claude Code 会自动识别其中的 `SKILL.md`:
  167. ```bash
  168. git clone https://github.com/lxsssssss/pdf-translate.git .claude/skills/pdf-translate
  169. ```
  170. #### 3. Cursor & Windsurf
  171. 本项目根目录已内置配置好的 [`.cursorrules`](.cursorrules) 与 [`.windsurfrules`](.windsurfrules),直接打开本项目所在目录即可自动生效;或将规则内容直接复制进你现有工程的全局规则中。
  172. #### 4. DeepSeek / OpenAI Codex / WorkBuddy
  173. 将 `SKILL.md`(或 `SKILL_EN.md`)核心铁律与 SOP 粘贴为 Agent 系统的 System Prompt,并开放 Python 终端权限以供调用 `scripts/render_pdf.py` 与 `scripts/audit_pdf.py`。
  174. ---
  175. ## 📈 Star History
  176. <a href="https://star-history.com/#lxsssssss/pdf-translate&Date">
  177. <picture>
  178. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=lxsssssss/pdf-translate&type=Date&theme=dark&_v=101" />
  179. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=lxsssssss/pdf-translate&type=Date&_v=101" />
  180. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=lxsssssss/pdf-translate&type=Date&_v=101" />
  181. </picture>
  182. </a>
  183. ---
  184. ## 📄 开源许可证 (License)
  185. 本项目采用 [MIT 许可证](LICENSE)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.