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

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

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

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

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

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

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

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

1. 环境准备（一次性）

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

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

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

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 推进。

脚本速查表

出错了怎么办

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

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

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

一、六阶段流水线

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

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

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

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

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

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

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

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

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

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

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

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

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

三、五大陷阱（摘要）

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

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

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

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

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

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 记的那一类静默假通过）。。逐项判绿的实际尺是判定行结构：该块的判定行必须恰有一枚且以放行标记开头；说明行只认质检脚本自己那两句打全了的话（豁免行与「正常接缝…无需处理」行，且整行须按该形状走到头），其余任何两空格缩进行一律算判定行——换一枚没见过的红符号穿不透，把结论写成「· 不合格…」这类说明句式也穿不透

脚本阈值口径与逐项修复动作见 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 → 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 处，多为原书图表页或无页边码页）。逐处强改代价高、收益低，建议在交付说明中如实列出，交由使用者据底本核对。

十、参考文件