长文档全文翻译流水线

外文长文（德/英/法/日，授权可访问）产出四类交付：主稿 .md、自包含阅读版 .html、逐段备查、新术语总表；存疑交人工不强译。 Do NOT use for: publishing copyrighted text as-is, practice-grade legal output.

长篇外文学术著作中译流水线

把一部几百页的外文专著译成「可交付、可核查、术语统一」的中文全稿。核心不是翻译本身，而是让 100+ 个翻译单元在体例与用词上保持一致，并在合并后不出现重复、断裂、未译残留。

源自实战：Dilthey《施莱尔马赫的生平·第2卷》（德文，OCR 底本，800+ 页）→ 141 片段 → 中文全稿 + 带目录导航 HTML，术语对照英文版 Oxford Handbook 与网络检索核校。

---

零、先判断：这份技能适合你吗？

本技能是为大规模流水线设计的。用错规模会比不用更累，先对号入座：

你的情况	建议
300 页以上学术专著 / 古籍 / 档案，术语需全书统一	✅ 完整流水线（本技能主场景）
100–300 页，或需多人 / 多子代理并行	✅ 完整流水线（批次可精简）
几十页，术语要求不严，单人完成	⚠️ 轻量模式（--scale light）
只译几段文字（< 10 页）	❌ 不要用——直接译即可，流水线的配置开销大于收益
要做排版级双语对照出版	❌ 超出范围（本技能产出单语主稿 + 阅读版 HTML）

轻量模式 vs 完整模式的差别（init_project.py --scale light 会生成对应清单）：

环节	完整流水线	轻量模式
切片 + 重叠检测（overlap_check）	必须	跳过（片段少，无滑动窗口重叠风险）
并行子代理翻译	必须	跳过（单人直接译）
边界去重（dedup_boundary）	必须	跳过
术语表	必须	选做（建议保留，成本很低）
体例三节（原注/译注/新术语）	必须	保留（这样日后升级完整流水线，脚本可直接复用）
质检（qa_check）	必须	建议跑一次，只看【3】未译残留与【7】空文件

轻量模式下仍保留体例三节，是刻意的：将来篇幅扩大时，不用返工补格式。

---

快速开始（首次使用，照抄即可）

1. 环境准备（一次性）

bash

python --version                # 需 3.8 以上
pip install markdown pypinyin

• markdown：合并时生成 HTML 用，缺了主稿 .md 仍可生成、HTML 会失败。
• pypinyin：术语表按拼音排序用，不装也能跑，只是术语改按 Unicode 排序（中文会乱序）。 脚本缺依赖时会明确提醒并说明降级后果，不会静默出错。

2. 一键建项目（推荐，省去手工造目录与模板）

bash

python scripts/init_project.py <项目目录>                  # 完整流水线
python scripts/init_project.py <项目目录> --scale light    # 轻量模式
python scripts/init_project.py <项目目录> --src en         # 指定源语言（默认 de）

产出：目录骨架（source/ work/chunks/ output/chunks/ glossary/）、 译者简报模板、术语表模板，以及一份 RUNBOOK.md—— 里面写好了本项目该按什么顺序跑哪些命令，照着打勾即可，不必通读本文档。

3. 填空 → 开译

1. 打开 TRANSLATOR_BRIEF.md 填空（开工前必填，它是所有译者的体例契约）；
2. 原文（解析后的文本）放 source/；
3. 按 RUNBOOK.md 推进。

脚本速查表

什么时候	跑哪个
项目初始化	init_project.py
翻译开工前（防整段重复，代价最高的一步）	overlap_check.py
合并前质检	qa_check.py
发现边界句级重复	dedup_boundary.py
出主稿 .md + 基础 HTML	merge_build.py
出增强阅读版 HTML	build_reader.py
复验本包自测面（只判包内夹具，不碰你的稿子）	check_translation.py --selftest

出错了怎么办

所有脚本对常见操作失误都会给出可执行的下一步，而不是抛 traceback：

• 目录不存在 → 提示检查路径拼写、提醒先跑 init_project.py；
• 选项缺值（如只写 --expect）→ 提示正确写法；
• 依赖缺失 → 提醒安装命令，并说明不装的降级后果。

一条重要保证（范围要说清，别读成万能保证）：目录路径写错时，脚本会报错退出， 而不会打印「0 个片段」再给一排全绿 ✅——这一类静默假通过已统一封在 scripts/_common.py 里。 但"全绿"只覆盖这一类失效：另有几类"判定根本没发生"的静默跳过（分组命名不匹配、短句低于 MINLEN 不参判、只有一片时无相邻可比），见硬规则 8 与 references/pitfalls.md §1c——所以报告全绿不等于逐项都成立，报告明细里的每一行跳过提示都要用户过一眼再放行。

---

一、六阶段流水线

阶段	做什么	关键产出
1. 解析	PDF/图片 → 文本（优先 omni-reader 等 OCR 解析；有对照外文版则一并解析）	source/DE_原文.md、source/EN_参考.md
2. 清洗切片	修 OCR 错字、删页眉页脚、按原书结构（非等长）切片，写 manifest	work/chunks/*.txt + manifest.json
3. 建体例与术语	先于翻译：写译者简报 + 多语术语表	TRANSLATOR_BRIEF.md、glossary/DE-EN-ZH.md
4. 并行翻译	主线程译一批 + 子代理并行译其他批（每段仅一个写者）	output/chunks/*.md
5. 质检修复	完整性 / 体例 / 未译残留 / 重复段 / 页边码连续性	scripts/qa_check.py 报告
6. 合并交付	去重合并 → 单一主稿 .md + 增强阅读版 HTML（build_reader.py，搜索/脚注跳转/护眼夜间大字）	译名.md + 译名.html

顺序不可颠倒：阶段 3 必须在阶段 4 之前。边译边定体例 = 全书体例漂移，后期返工量巨大。

---

二、硬规则（写进译者简报，所有译者 / 子代理共守）

编号后可在文档中交叉引用（如「硬规则 4」）。派子代理时直接引用编号即可，不必复述全文。

译者简报 TRANSLATOR_BRIEF.md（必需） 至少规定：

1. 页边码：原书页码单独成行 〔S. XXX〕，保留以便核校与引用。（源文本页码常被打散成 S. 5 3 3，需还原）

2. 强调字体：原文舒展字体（Sperrdruck / 斜体 / 逐字空格）还原为完整文句 + **粗体**，绝不逐字直译。

3. 脚注：保留原编号，正文用上标 ⁷，注文统一移到段末 #### 原注 小节。

4. 残句：片段开头残句用 > 〔承前页〕……，结尾残句照译并以 …… 收尾，不编造补齐。

5. 存疑必标：任何不确定处加 #### 译注，格式 `N. 疑点。原文作「…」；对照版表述「…」；因…暂译作「…」，存疑。宁可多标，不可臆断。

6. 文末三节（每个片段文件都附，便于合并时汇总）：

   text

   #### 原注   （脚注译文）
   #### 译注   （存疑说明）
   #### 新术语 （本篇新定译名：原文 → 中文）
   

7. 术语表铁律（glossary/DE-EN-ZH.md，必需）：三语对照（原文 ⇄ 参照语言 ⇄ 中文）。同一原文词条全书唯一对应同一中文词；确需变通才在译注说明。建表依据：原书缩写 / 索引表 + 参照外文版 + 学界通行译法。

8. 脚本告警不等于全绿：overlap_check.py / dedup_boundary.py 存在「判定未发生」的情形（命名不匹配分组模式、MINLEN 阈值下的短句）。看到命名模式提醒、「仅 1 片，无相邻片可比较」或 exit 3 时，先按提示处理再放行——报告最后一行的 ✅ 不等于真的检查过。详见 references/pitfalls.md §1c。

---

三、五大陷阱（摘要）

完整版（含发现 / 修复 / 预防，以及脚本阈值的静默失效模式）见 references/pitfalls.md。

#	陷阱	一句话
1	切片窗口重叠	相邻片段边界重叠 → 合并后整段重复；翻译开工前必跑 overlap_check.py（硬规则 8）
2	OCR 错字批量替换误伤译注	只替换正文区，注释区的纠错说明必须保留
3	合并后跨片段标题重复	按同级标题去重，排除 #### 原注/译注/新术语
4	字符数 vs 字节数	对比体量统一口径（实测 1 字符 ≈ 2.4 字节，不是 3）
5	子代理产出未校验	查空文件、抽查头 25 行、读子代理自述

四、并行翻译策略（摘要）

完整版见 references/parallel-translation.md。

1. 分片：按原书结构（篇章 / 页码区间）划分，每片段有且仅有一个写者，批次严禁重叠。
2. 主线程 + 子代理：主线程译样板批，再派子代理。提示词必含——必读简报 + 术语表 + 1 篇紧邻已译样本；残句接续说明；「只写分配给你的文件」。
3. 429 限流：限制期内主线程手动逐片译，恢复后先小批量验证再放大。

五、质检清单（合并前必跑）

bash

python scripts/qa_check.py output/chunks
python scripts/check_translation.py --selftest    # 包内自带自测面（零网络、纯 stdlib）

check_translation.py --selftest 验的是本包自己：三档——好样链（scripts/fixtures/good/ 三片走完 overlap→qa→dedup(dry-run)→merge 并逐项断言上面七项与交付形制）、坏样必红（scripts/fixtures/bad/ 每片一处病灶，断言判定真的发生并点名到文件与行号）、反证与封死（对好样做七枚单点破坏，每枚必须让对应一项转红；一枚正向不误拦——注文里的 OCR 残痕必须仍 ✅（同样按判定行结构判：该块只许一枚判定行，且必须是放行行）；缺目录与空目录时五支脚本一律退 1、给「→」下一步、零 Traceback）。 一档里「七项全 ✅」按判定行结构判：qa_check 把判定打在两空格缩进、明细打在更深缩进，同缩进还有两类说明行（「（豁免 …）」「· 正常接缝…」）不算结论——一项为绿，当且仅当该块的判定行恰好一枚且以放行标记开头。所以往块里追加任何一枚别的判定行都当场翻红，不论它写 ❌、⚠、⛔、[X] 还是 "FAIL:"，也不必先见过那个符号；只留红行同样红。退码兜不住这一类（qa_check 报红仍退 0），判面自己兜。夹具命名必须合 部_篇_编号（如 01_phil_001.md）：不合式时相邻比较一次都不会发生却照样打印全绿（硬规则 8 记的那一类静默假通过）。。逐项判绿的实际尺是判定行结构：该块的判定行必须恰有一枚且以放行标记开头；说明行只认质检脚本自己那两句打全了的话（豁免行与「正常接缝…无需处理」行，且整行须按该形状走到头），其余任何两空格缩进行一律算判定行——换一枚没见过的红符号穿不透，把结论写成「· 不合格…」这类说明句式也穿不透

#	检查项	合格标准
1	片段完整性	译文片段数 == 切片数（或差异有 _redundant 解释）
2	体例三节	每个片段含 #### 原注 / #### 译注 / #### 新术语
3	未译残留	正文无「>60 字符且无中文」的整行外文（书目/广告页除外，应保留原文）
4	OCR 残痕	正文区错字数 == 0（注释区豁免）——错字表是项目级配置（OCR_TYPOS 现值，当前装的是本包样例那部德文书的实测残留），换一部书若没重填，这一项会近乎空判：它是配置域，不是包内固定闸
5	页边码连续	全稿页码无断档（罗马/阿拉伯分段各自连续）
6	重复段	正文关键句出现次数 == 1（术语表/附录内重复属正常）
7	目录干净	HTML TOC 仅含 2–3 级标题，无 原注/译注 杂项

脚本阈值口径与逐项修复动作见 references/qa-checklist.md；本文与那份清单里的数字都是镜像，判定=各脚本 CONFIG 区现值，一条命令原地打出来（自带安装后路径，任意目录整行粘贴可跑；装在别处把 ~/.workbuddy/skills/ 换成你的技能安装目录；命令用 grep（POSIX 工具），Windows 请在 Git Bash 或 WSL 内跑，路径写作 C:\Users<用户名>.workbuddy\skills\long-doc-translation\scripts\qa_check.py）： grep -n "CONFIG\|^[A-Z_]\{2,\} *=" ~/.workbuddy/skills/long-doc-translation/scripts/qa_check.py ~/.workbuddy/skills/long-doc-translation/scripts/overlap_check.py ~/.workbuddy/skills/long-doc-translation/scripts/dedup_boundary.py 闸分两性质：包内固定闸（缺目录即报错、片段数对账、TOC 层级、页码连续算法）不随项目变；配置域（页边码正则、OCR 错字表、体例三节命名、跳过哪些文件/章节、分组模式与各阈值默认值）按项目重填才成立——所举数字一律不作穷尽断言。

---

六、脚本模板（scripts/）

脚本	用途
init_project.py	一键建项目骨架（首次使用先跑它）：建目录 + 生成译者简报/术语表模板 + 按规模（完整/轻量）生成 RUNBOOK.md 操作清单；可加 --scale light / --src en / --no-copy
overlap_check.py	页码级切片重叠检测（翻译开工前先跑）— 按「部」分组比较各片页边码首尾；逆序片（索引）自动跳过
qa_check.py	上述 7 项质检（含句级重复行检测），输出可读报告
dedup_boundary.py	句级边界重复清理— 默认 dry-run，--apply 才写盘；重复行带页边码时只删句子、保留码
merge_build.py	同级标题去重合并 → 主稿 MD + 带 TOC 导航的 HTML；并对外暴露 SECTIONS/page_val/sort_terms/collect_doubts/collect_new_terms 等供 build_reader.py 复用（需 pip install markdown pypinyin）
build_reader.py	在 merge_build 之上生成增强阅读版 HTML：脚注正文↔注文双向跳转、全文搜索、原书页码跳转、目录高亮、护眼/夜间/大字主题、单文件自包含可直接发送
_common.py	各脚本共用的友好错误提示与目录/参数校验（非独立工具，被上面各脚本 import）。它保证了「目录写错就报错退出」而非静默假通过
check_translation.py	包内自带自测面（--selftest，零网络、纯 stdlib）：三档＝好样链／坏样必红／反证与缺目录封死，判的是本包夹具 scripts/fixtures/good/、scripts/fixtures/bad/，不动用户稿；末行自报「selftest: ALL GREEN（…断言 N 条，不符 0 条）」

推荐顺序：init_project.py → overlap_check.py → 翻译 → qa_check.py → dedup_boundary.py → merge_build.py → build_reader.py。

脚本顶部均有 CONFIG 区（页边码正则、错字映射表、标题层级、目录深度、是否跳过索引/书目），按新项目改配置即可复用——上面这些是配置域，不是包内已验证能力：改了配置，报告里对应那一项的判别力跟着变，别把默认值当承诺。

---

六·增强阅读版（build_reader.py，推荐交付形态）

完整工程决策与用法见 references/reader-build.md。

merge_build.py 产出「能看」的基础 HTML；build_reader.py 在其之上产出读者真正用得顺手的增强版，二者共用同一份 merge_build 逻辑，不在 reader 里另写一份（避免两份实现漂移）。

增强版能力：脚注双向跳转 · 全文搜索（/ n p Esc）· 原书页码跳转 · 目录高亮 · 阅读设置（字号 / 行宽 / 大字模式 / 日间 ▸ 护眼 ▸ 夜间，localStorage 记忆）。

四条不可省的工程决策：① 单文件自包含（CSS/JS 内联，不引 CDN）→ 一个 .html 可直接发送；② 术语表按拼音排序（不按 Unicode 码点）；③ 页边码正则要宽（覆盖阿拉伯 + 罗马数字与 OCR 变体）；④ 脚注 id 唯一（未被引用的编号不生成返回链接，避免死链）。

七、交付

• 主稿 *.md（单一文件，便于再加工/转 docx）；
• 阅读版 *.html（左侧固定目录，点击跳转，适合通读与检索）；
• 保留 output/chunks/*.md 逐片译文备查；
• 术语附录：合并时把各片 #### 新术语 汇总为文末「全书新术语总表」。

八、经验参数（本次实测）

• 800+ 页德文专著 → 141 片段（按结构切，非等长）→ 中译全稿 95.8 万字符 / 228 万字节。 ⚠ 别按「中文 3 字节」折算：正文夹大量德文引文、数字与标点，实测 1 字符 ≈ 2.4 字节。体量对比必须统一口径（见陷阱 4）。
• 有效提速组合：主线程译样板批 → 3 个子代理并行各译 10–17 片 → 质检修复 → 合并。
• 合并后实际修掉的问题（可作为同类项目的预期基线）：
  • 整段重复 2 处（022/023、023/024，子集窗口，约 20 页冗余）；
  • 句级边界重复 8 处（每处 1–2 句，源切片边界重叠）；
  • 体例三节缺失 11 个文件（多为缺「新术语」节，补「（无）」即可）；
  • 正文 OCR 残痕 5 处（ζ.B.→z.B.）。

九、交付后仍应保留的「已知轻微接缝」

切片边界不可避免会有 1–3 页的页码接缝（本次 32 处），以及 >3 页的疑似断档（12 处，多为原书图表页或无页边码页）。逐处强改代价高、收益低，建议在交付说明中如实列出，交由使用者据底本核对。

---

十、参考文件

文件	何时读
references/pitfalls.md	切片 / 翻译 / 合并各阶段排查重复与 OCR 问题；含脚本静默失效模式（§1c）
references/qa-checklist.md	合并前跑质检时——七项标准 + 脚本阈值 + 修复动作 + 交付基线
references/reader-build.md	出增强阅读版 HTML 时（工程决策与依赖降级）
references/parallel-translation.md	派子代理并行翻译前（分片原则、提示词三要素、验收）