ray-translate — 化学化工翻译技能（中英双向，含过程安全）

在化学/化工/过程安全领域的中英文文档之间翻译。领域三层定位（v3.0.0 扩展）：

• 化学基础（v3.0.0 新增）：元素/化合物命名、官能团、物性词汇 → data/termbase/chem.md
• 化学工程（v3.0.0 新增）：设备/单元操作/管道仪表/公用工程 → data/termbase/chem-eng.md
• 过程安全（既有资产全保留）：化工安全翻译全部既有能力（Excel 批量、安全培训英文化、警示语规范）+ 原 EN-GLOSSARY 129 条 → data/termbase/safety.md

三大方向：

• 方向一 英→中（Excel 批量）：Excel 工作簿（含 VBA 宏的 .xlsm）批量翻译。以 CHEF Calculation Aid 4.4 翻译项目（13 个 Sheet，~2,126 个单元格，5 轮翻译）积累的最佳实践构建。
• 方向二 中→英（PPT/讲义英文化）：安全培训 PPT / 讲义 / 讲稿的专业英文化。以 95 页化工厂入厂安全培训 PPT 英文化项目（2026-08-19）积累的方法论构建——面向外籍化工工程师时，目标是"读起来像是用英语写的"，不是逐字对应。
• 方向三 英→中（PDF/法规/长文 → 中文）（v3.2.0 新增）：英文 PDF（法律/法规/指南/事故报告/技术手册）→ 中文交付（默认同格式，v3.2.1）。以 2026-09-04 OSHA Act 514（马来西亚职业安全法全文）+ HIRARC 指南实战沉淀——结构化文档翻译 + 法律语气 + spec 驱动生成 + QA 抽读。版式敏感源的"版式保持型原位回贴"路线已拆分至 ray-file-inplace（v4.0.0，2026-09-21 用户裁决翻译与排版分家）；本 skill 在该路线上只负责按契约填译文池（frag_jobs/dN.json → frag_out/dN.json）。排版降级链（v4.0.1）：版式保持路线优先交棒 ray-file-inplace（提取/定组/装配/验收全由其主导）；若该 skill 未装载或明确缺席 → 降级退守原输出方式（spec→DOCX→Word COM 导出 PDF，同目录同类型），退守产物必须过基础验收（页数/U+FFFD/TOC 域刷新抽读），交付说明标注"深度排版审计未跑"——后续 ray-file-inplace 在场时可接管深度修复，不视为返工。

常驻术语库（v3.0.0 新增，data/termbase/ 四分域）

> 库文件 grep-only 永不整读——库合计 ~1100 条（四库+热词表+毕业库，硬顶 1800，v4.0.2 由 1500 扩容；建库阶段策略：大池子多任务筛选，稳定后再收缩），只许 grep 检索，禁止整文件读入上下文。库只对"译前程序化提取"这一步有价值——详见 CAT 三段式 ①。
> Schema 六列：| EN | 推荐 ZH | 拒用❌ | 语境/辨析 | 来源 | 日期 |（单行一条）。

grep 用法：

# 译前查 EN→ZH
grep -i "reactor" data/termbase/*.md
# 查 ZH→EN
grep "储罐" data/termbase/*.md
# 译后拒用译法扫描（对译文，应零命中）
grep -in "反应堆\|坦克\|检查阀\|饲料" 译文文件

动态库机制（v3.1.0）

• 台账：每次任务收尾往 _hits.md 追加一行 日期 | 任务 | 命中词条——频次信号源，成本一行
• 调整节奏：攒 10 个任务或月度做一次迁移，不逐任务调（机制重了不会被执行）
• 总量控制：四库+毕业库硬顶 1800 行（v4.0.2 由 1500 上调，2026-09-21 用户定档：建库阶段池子宜大、靠任务筛选沉淀高价值词，稳定后可再收缩），逼近即加快毕业
• 热词表纪律：只收无歧义词；多义词（base/charge 类）永不入表；热词只免"译前查"，译后拒用扫描照做

术语裁决优先级（库内未命中时逐级下查）

> ⚠️ 《安全科学技术名词》独立卷查无实据，不引用；IUPAC Gold Book 仅英文定义，不作中文依据。
> 备查池：~/.workbuddy/local-refs/chemical-glossary/（15.1 万条英汉化工词汇数据集，仅作候选，永不直接采用，绝不进技能包）。

CAT 三段式工作流（v3.0.0 新增）

① 译前：术语提取与锁定
> 🚨 机制说明（v3.6.1）：四库是 grep-only，库只在本步生效——入库 ≠ 自动生效。因此本步的唯一执行器是脚本，禁止人工挑词（实证：PGS 2 手工挑 112 条 → 漏 39 条；且挑入的 congestion/impoundment 源文出现 0 次，纯属"领域知识带入"，源文实际用 obstructed region/bund）。

• 程序化提取（必做）：python scripts/extract_terms.py <源文本> --lang en --min-freq 2 --min-words 1
• 产出两份：*_locked.md（命中 → 直接作为 spec 术语节，勿手写）+ *_gaps.md（缺口核对清单）
• 判据：句内 n-gram + 页覆盖样板词过滤 + 程序词/单位过滤 + 单复数归一 + 倒排索引（1.5 M 字源 ~3.5 s）
• 缺口清单不可按排名截断（低频领域词会被挤掉）；缺口≠都要入库——见下条分流
• 命中 → 锁定：全文档强制采用库内"推荐 ZH"，不得自行另译
• 缺口 → 三分类处置：① 领域专有词（有争议/易错，如 rainout/congestion）→ 必须权威源核验（见 references/term-verification.md）后入库；② 通用词（流体力学/气象/数学，如 湍流/浮力/等熵）→ 译法无争议，可直接采用；③ 噪声（句子片段/程序词）→ 剔除
• 自检：extract_terms.py --selftest（非空断言 + 正向控制 + SABOTAGE 负控）

② 译中：只注入命中词条
- 翻译脚本/字典只含"命中锁定项 + 新增核验项"，禁止整库灌入（token 经济 + 避免低频误替换）

③ 译后：拒用零命中 + 逐条核对
- grep 全部拒用❌译法对译文扫描 → 必须 0 命中
- 逐条核对锁定术语在译文中的实际落位（防"锁定后又被润色改掉"）

收尾：术语审计入库 + 记台账
- 每次任务结束，把新增/修订条目按六列 schema 回写四库（来源列标校准依据，如 CSB 校准/术语在线/行业通用(待核)），库随任务增长
- ⚠️ EN 匹配用「词边界子串」，禁「EN 单元格全等」（v3.5.0）：审计脚本若写成 k in en_set（en_set 是整格全等集合），复合词条下的词会被误判「缺」——实测 deadband（库里实为 alarm deadband）、first-out、interlock、safety integrity level、alarm setpoint、alarm summary 六项假缺，报缺 45 项而真缺仅 36 项（高估 20%）。判据须为 (?<![a-z0-9])term(?![a-z0-9])。
- ⚠️ 英式/美式拼写并收（v3.5.0，最易漏）：英式源（EEMUA 191）用 rationalisation / prioritisation，美式源（ISA-18.2）用 rationalization / prioritization —— 同一概念两套拼法，检索时两种都要能命中。术语库对拼写变体分列收录（不得只留一种），否则英式源文档整片漏检。
- 审计输出必须带正控 + 负控（v3.5.0）：正控 = 一个已知已收录的词必须落「已覆盖」档；负控 = 伪造词必须落「真缺」档。两者不全真即 VERDICT=FAIL —— 这是「非空转三件套」中「被检查对象非空」的执行方式。
- 入库判据用守恒式（v3.5.0）：旧行逐行仍在（子集相等）+ 新行数 == 追加条数 + 节数 +1 —— 三项全从产物推出、不写魔数；配 SABOTAGE 删一条旧行做负控（应 exit 2）。实测 EEMUA 191 追加 36 条：375→411 行、45,615→53,653 B、0 行丢失。
- 往 _hits.md 追加一行命中台账（日期|任务|命中词条）——动态库升级/毕业的频次信号源

通用翻译铁律（双向，开工前先过此节）

> 源头：对比官网通用翻译 skill 的「格式化保留 + 内容规则 + 语义 QC」沉淀（2026-08-20，v2.3.0）。面向化工文档本地化。

① Don't-translate 保留清单（原文原样保留，绝不翻译）：
- 占位符/模板变量：{name}、{{var}}、%s、$1、__KEY__
- 代码/公式：代码块、HTML 标签、XML 键名、API 端点、CSS 类、文件扩展名、正则
- sdt 元素（Word 结构化文档标签，v2.5.0 补）：封面标题、规范性引用、文内交叉引用等 w:sdt 包裹的内容——翻译时内容译、sdt 结构标签保留；若工具自动跳过 sdt 内容，需手动补译封面/引用区（外部同类实测：sdt 处理不当会整段丢失）
- 标识符：URL、email、编号、ID、设备/仪表/管线位号、CAS 号、标准号、数字与日期（除非需做本地化换算）
- 专有名词：品牌名、机构缩写（CCPS/OSHA/API…）、人名
- 单位符号与数值：kPa、ppm、≥、≤、10⁻⁶ 等（见白名单 KEEP_ENGLISH）
- 化学专项（v3.0.0 扩充）：CAS 号、分子式、R/S 构型符号、位次标点等规则 → 见 references/chem-conventions.md

② 语义 QC（机械 QA 之外的补强，交付前过）：
- [ ] 先通读全文上下文再译，别逐词硬译
- [ ] 译文在目标语中读起来自然流畅（不是"可读的 Chinglish"）
- [ ] 验证所有格式/结构元素（表格、位号、单位、层级）翻译后仍可用
- [ ] 全文档术语、语气、时态一致（同义词唯一化）

开工简报（v2.4.0 新增，动笔前先定 5 要素）

任何翻译项目开工前，先明确并写下（用户未说明时编号提问确认，不猜）：

输出格式默认规则（v3.2.1，用户明确）：译文输出格式默认与输入原格式相同（PDF→PDF、DOCX→DOCX、PPTX→PPTX、Excel→Excel），除非用户明确指示新格式。示例：用户说"把这份英文 PDF 转成中文版"→ 默认输出中文 PDF（不是 DOCX）；"翻译这个 xlsm"→ 默认输出中文 xlsm。方向三五步流程中的 spec→create-docx 是中间加工手段，最终交付格式仍按源格式还原（PDF 源 → 中文 PDF）。用户要求不同格式时才改（如"转成中文 Word"明确指定）。
交付目录默认规则（v3.3.2，用户明确）：翻译生成的文件默认放在源文件同一文件夹下，除非用户另有明确指令。中间产物仍不进交付目录（v3.2.2 纪律照旧，留临时工作目录）。
交付目录纪律（v3.2.2，用户明确）：交付目录中只放与原格式相同的文件——源为 PDF 则交付目录只放中文 PDF，中间产物（DOCX/spec/提取文本）不随交付放进同目录，留在临时工作目录。中间 DOCX 仅用于 QA 验证与 Word 导出 PDF 的桥接，验证导出完成后即完成使命，除非用户明确要求"也要 DOCX"否则不放进交付目录。

触发条件

当用户描述以下场景时加载此 skill：

1. 化工 Excel 翻译: "翻译这个 xlsm 文件"、"把这个化学 Excel 翻译成中文"
2. 术语管理: "提取 Excel 中的术语"、"整理翻译字典"、"查一下这个化工术语怎么翻"、"更新术语库"
3. 质量验证: "检查还有哪些英文没翻译"、"验证翻译质量"、"扫一遍拒用译法"
4. 批量处理: "把 XX 文件全部翻译成中文"、"大文件分批翻译"
5. 专业英文化: "把这个中文 PPT/培训材料改成英文版"、"中译英（化工安全）"、"给外籍员工做英文培训课件"
6. CSB/事故报告英→中（v3.0.0）: "翻译这份 CSB 调查报告"、"这篇英文事故报告翻成中文"

7. PDF/法规/长文 → 中文（v3.2.0 新增）: "把这份英文 PDF 转成中文版放同目录"、"翻译这份 OSHA/法规/标准指南"、"英文法条翻成中文"

8. 扫描件/无文字层 PDF → 中文（v3.4.0）: "这份扫描的英文标准/报告转成中文"、"PDF 里没有文字层，先识别再翻译"

工作流程 — 方向一：英→中（Excel 批量翻译）

第一阶段：分析与准备

1. 读取源文件结构: 使用 openpyxl.load_workbook(path, keep_vba=True) 打开 .xlsm，列出所有 Sheet 名称和行列数
2. 提取唯一文本: 遍历所有 cell，提取非空、非公式、含英文字母（≥2 个）的字符串，按 Sheet 分类
3. 构建术语字典: 将提取的文本按优先级排列——先确保以下关键字段完整：
   - 工作表名（13 个）
   - 核心标题/版权/声明
   - 章节标题（每个 Sheet 的 STEP/标题行）
   - 专业术语（单元操作、安全工程、化学危害术语）
   - 表头/列名
   - 表单字段/LOPA 字段
   - 参考文献
   - 化学名/物质名
   - 中英混合长句片段（Introduction 类段落）
4. 规划翻译轮次: 根据术语量和文本复杂度决定轮次，典型分 3-5 轮
5. 术语评审闭环（v2.1 新增，重要交付必做）：术语字典建成后导出 术语评审表.xlsx（原文|译文|备注）给用户确认，修订版即绑定后续所有轮次。小任务可跳过，但交付说明须注明"术语未经用户评审"。

> v3.0.0：第 3 步构建术语字典前，先过 CAT 三段式——候选词逐条 grep 四库，命中的直接锁定，未命中的走裁决优先级。

第二阶段：核心翻译

核心翻译函数与残留诊断白名单（KEEP_ENGLISH）完整可复用代码 → 见 references/code-patterns.md（按需查）。

关键规则:
- 公式保护：所有以 = 开头的单元格跳过（openpyxl 读取的公式值以 = 开头）
- 整词匹配：使用 \b 边界符避免子字符串误替换（如 "TNT Model" 中的 "T"）
- 长词优先：术语按字符串长度降序排列，避免短词抢占长词
- VBA 保护：openpyxl.load_workbook(..., keep_vba=True) 和后续 wb.save() 保留宏

分批策略（防止内存溢出）:

BATCH_SIZE = 3  # 每批最多 3 个 Sheet
for i in range(0, len(SHEETS), BATCH_SIZE):
    batch = SHEETS[i:i + BATCH_SIZE]
    wb = openpyxl.load_workbook(out, keep_vba=True)
    for sname in batch:
        n = translate_sheet(ws, patterns)
    wb.save(out)
    time.sleep(0.5)  # 系统释放内存

文件夹结构:
- 首次运行：shutil.copy2(src, out) → 复制源文件（含 VBA）
- 逐批累加：每次 load_workbook 读入已翻译文件 → 翻译 → save 覆盖

第三阶段：多轮递进翻译

典型轮次分配：

每轮策略：
1. 先用 check_remaining.py 扫描残留英文
2. 根据残留调整术语字典，补充漏翻项
3. 运行下一轮脚本
4. 重复直到仅剩应保留的白名单项

第四阶段：残留验证与白名单

残留扫描 (check_remaining.py):

# 扫描 >=3 字母的英文单词，统计词频
eng_words = re.findall(r'\b[A-Za-z]{3,}(?:/[A-Za-z]{3,})*\b', val)
word_freq = Counter()
for r in remaining:
    for w in r['eng_words']:
        word_freq[w] += 1
# 输出 Top 40 剩余词 + 15 个示例单元格

精细诊断 (extract_real_remaining.py)：白名单 KEEP_ENGLISH 全量集合见 references/code-patterns.md——单位/缩写/变量名预置白名单，过滤后只剩真残留

第五阶段：一致性检查与编号提问（v2.1 新增，交付前必做）

对照源文件逐项核对（不是只查残留英文）：
- [ ] 遗漏：源文件中出现的英文文本，译文中都已覆盖（反向扫描：源提取文本 - 已翻字典 = 遗漏）
- [ ] 误译：抽样核对专业术语（尤其 LOPA/化学危害/单元操作术语）译文与字典一致
- [ ] 结构对齐：Sheet 数、行列数、公式引用未因翻译变化；工作表名与引用链接一致
- [ ] 化学名/单位：化学式、CAS 号、单位符号未被改动

编号提问：核对中发现的不确定项（术语歧义、化学名、上下文不明），编号列出提问，等用户回答后再定稿——不要自行猜测定稿。示例："Q1: 'relief load' 译为'泄放负荷'还是'泄放载荷'？"

工作流程 — 方向二：中→英（化工安全专业英文化）

> 2026-08-19 沉淀：95 页化工厂入厂安全培训 PPT 英文化项目。适用对象：安全培训课件 / 讲义 / 讲稿 / 技术文本，面向外籍化工工程师或国际项目。

核心原则：翻译的三个层次

目标不是逐字对应，而是让英语母语的化工安全工程师读起来，感觉这份文件本来就是用英语写的。

第一层：术语精确（安全语义无歧义）

1. 先建术语库，后翻译——从 data/termbase/safety.md（原 EN-GLOSSARY 10 大类 + 过程安全新增，EN→ZH 可反查）起步，覆盖项目特有术语后开工
2. 高频错译黑名单（termbase 拒用❌列已收录，此处强调）：

最高危错译 Top5（译错即安全语义歧义，交付前 grep -i 必查）：

完整错译黑名单（11 条：逃生面罩≠gas mask、高处安全带≠safety belt、受限空间≠limited space 等）→ 见 data/termbase/safety.md 各行"拒用❌"列。

3. 警示语语气规范（法定条款强制语义）：

4. 不确定的术语优先查 NFPA/API/OSHA 标准用法，不要自行发明

第二层：行业地道（去 Chinglish）

句式检查清单（翻译后逐条过）：
- [ ] 全角序号 ①②③ → ASCII 1. 2. 3.（英文版里全角序号是明显的中文残留）
- [ ] 中文"进行/加以"式动词短语 → 英语惯用动词（make a calculation → calculate）
- [ ] 中文短句 → 按逻辑合并为英文主从结构或名词化
- [ ] 口语误用：perk（→optional）、bottom line（慎用）、make XX well（→maintain）
- [ ] 单位/阈值/连锁逻辑：数字安全关键信息不得在润色中被改掉

英文比中文长 ~40%：PPT 场景必须下调字号（标题 26→22pt、条目 15→14pt、描述 11.5→10.5pt）+ 放大行高，否则必溢出。

第三层：流程与验收

1. 术语库先行：开工前建 GLOSSARY.md（分类表），对照翻译
2. 脚本化改造（PPT 内容在脚本/数据文件里时）：改数据脚本（如 part1/2/3_en.py）→ 重建 → 重灌备注 → QA，比直接改 PPTX 高效
3. 讲稿/备注同步：## Page N 格式按节解析重灌；改完必须验证 ## Page 数量 = 页数（编辑误删行尾换行会把下一节标题吞进上一段落，95 节变 94 节）
4. QA 双保险：
   - 机械 QA：页数/图数/备注数/越界/中文残留/乱码（\ufffd）
   - 术语 QA：QA 无中文残留 ≠ 术语正确——必须对照术语库人工/逐页审关键页（分级页、表格页、警示页）
5. 交付对比：交付前跑 grep -i 扫描黑名单术语，确认 0 命中

方法 B：内容内嵌 PPT 的就地翻译（python-pptx，2026-08-20 沉淀）

> 适用：内容直接嵌在 PPTX（非脚本生成）的培训课件，需保留版式/图片/分组结构时，用 python-pptx 就地替换，比重建高效。

四步法：
1. 导出精确键：脚本递归（group 感知）输出每段/每 cell 的 repr(text)（含 \n、\xa0、全角引号、箭头等不可见字符）→ 精确匹配键。
2. 建 T 全量字典：键=精确原文、值=英文；数字/位号/标准号/ACRONYM 不进字典。跑完扫残留，剩余项基本都是「键里差一个空格/换行的坑」——比对 repr 逐字修键而非猜。
3. 格式保留：改首 run 的 text、删多余 run（保留 rPr 字体字号加粗）；单元格按 \n 分行、缺行 deepcopy 末段补行。⚠️ 分组 shape_type==6 必须递归进入，否则漏 group 内文字。⚠️ 段落级写回铁律（v3.3.1，2026-09-08 事故回流）：替换写入禁止"整框文本压进首 run"——含多段（编号列表/多行）的框会被压成单段+字面换行、丢段落结构（en2en 返工实证，已全量重建修复）。正确做法 = 逐 paragraph 替换（每段独立判断，段内写首 run、清同段其余 run），段落结构天然保留；仅确认单段框可用首 run 直写。
4. autofit 防溢出：英文长 ~40%，按「估算每行字符宽 0.5×字号 → 折算行数 → 估算高度 > 框高则整体等比缩小字号(下限 0.55)」对文本框与表格 cell 统一收缩（用列宽/行高做框尺寸）。极端缩小就检查 map 键问题。

验收：中文残留=0 + \ufffd=0 + 页数不变 + 黑名单 0 命中；autofit report 里字号 40→26 这类属正常。

方法 B+：超大 PPT 的并行子代理翻译（v3.3.0，2026-09-08 沉淀）

> 适用：PPT >100 页 / >5 万中文字符时，单进程顺序翻译会超长且慢。用并行子代理分章翻译 + 主进程统一替换。2026-09-08 实测：148 页 / 10.7 万字符设备培训课件，2 子代理并行完成第 1 章（P5-22），产出 138 键字典，用户验收 OK。

流程（主进程编排）：
1. 全量导出：脚本导出全部文本单元 → units.json（每项 {slide, shape_id, prefix, text, font_sizes, frame_w, frame_h}），统计单元数与字符量
2. 识别章节边界：找目录页/章节标题页，把 148 页切成 N 章（每章 ~1 万字符最优），逐章切出 chXX_units.json
3. 建翻译规范（主进程做，质量基线）：写 translation_spec.md = 通用栏目模板表（系统简介→System Overview 等跨页统一词）+ 本任务设备/术语锁定表 + 压缩规则。栏目名/术语必须主进程定，子代理不得另译——这是全书术语统一的唯一保障
4. 并行派子代理：每章 1 子代理（或按字符量 1 代理 1-2 章），prompt 模板：①读 chXX_units.json ②读 translation_spec.md + 已完成章节 dict 作风格参照 ③产出 chXX_dict.json：{"中文原文精确字符串": "英文译文"}——键逐字复制自输入（含 \n），中度压缩 ④报告键数/未处理 slide。⚠️ prompt 内嵌长度预期（v3.3.1，2026-09-08 二次全量实战）：写明"EN/ZH 字符比 2.5~3.5x 属正常（CJK 双宽，视觉宽比约 1.3~1.8x），勿为压长度删技术/安全内容；溢出由 fix_overflow 兜底"——否则代理会误判"超长"并在报告里反复解释（ch02/05/07/09 多代理同症状）
5. 主进程合并：各章 dict 合并 → 统一替换（子代理只产出字典，不碰 PPTX——避免并发写同一文件）
6. 就地替换：apply_dict.py 模式——精确匹配 text_frame 全文→替换首 run 保留格式（多 run 清空其余）；表格 cell 同样处理；group 递归
7. 溢出缓解：fix_overflow.py——英文/中文长度比 >1.4 的框按比例缩字号（下限 6pt / 0.55 比例）；原 PPT 常无 autofit 设置，此步必做
8. QA 每批必跑：中文残留（应逐批递减至 0）/ 乱码 / 页数不变 / 字号下限

要点：
- 子代理 prompt 必须自包含（看不到主会话）：输入文件路径 + 规范路径 + 风格参照 dict + 输出路径 + 键精确性要求
- 同 slide 重复文本（如导航角标）自动合并为单键（dict 天然去重）
- 已应用键匹配不到中文自然跳过 → 替换脚本可重复跑（分批合入安全）
- 压缩度以验收样板为准——先做 1 章样板给用户确认风格，再批量（软目标先确认）

方法 C：英文版版面装配——用 PowerPoint 自己的排版引擎定字号（v3.6.2，2026-09-15 沉淀）

> 适用：内容内嵌 PPTX 的中→英，且用户要求"避免文字溢出（必要时意译压缩）"。90 页 / 2.2 万字生产制度培训课件实战。

① 判据必须是「目标软件自己的排版度量」，不是自写估算模型
自写 em 估算（CJK=1.0em / ASCII=0.52em / 行距 1.2）会严重失真：模型报"需缩放 0.51"，而渲染显示中文原文只占版面 76%——偏差约 1.5 倍，据此调参就是白跑。
正解 = COM 实测：shape.TextFrame2.TextRange.BoundHeight / BoundWidth（真实排版高度）+ PageSetup.SlideWidth/SlideHeight（画布）+ Slide.Export(png) 抽查渲染。
> 这是一条可迁移的判断原则：凡"装不装得下 / 合不合法 / 能不能加载"类判据，用目标系统自身的引擎实测，不要用自写模型代替。

② 可用空间 ≠ 文本框高度（本类 PPT 的普遍形态）
文本框常小于文字实际高度（中文本身就"越框"渲染，作者靠周边空白兜住）。真实边界取三者最小值：
外层卡片底边 − GAP / 下方最近文字块顶边 − GAP / 页面底边 − MARGIN。
两类绝不能当边界：装饰小图形（圆/箭头/图标）、≤2 字符的编号徽标（"01"/"a)"）——它们与正文同卡片内重叠，当成阻挡物会算出 avail = 6~19pt 的荒谬预算（实测连踩 6 页）。
另：卡片标题槽往往只有 28~32pt，英文标题必须压到 2~4 词（"Check Automatic Lubricators"），否则必然压住正文。

③ 生长方向必须改：spAutoFit（框随文字长高）+ anchor=ctr（居中）→ 英文变长后框向上长，直接压住上方标题（第 25 页实测标题与正文重叠）。
修法：文本高于框时把 anchor 改 top，判据用几何（boundH × 缩放 > 框高）——不要只测 autosize == 1：出事的那个框 COM 报 autosize = -2（mixed），只测 1 会恰好漏掉唯一出事的容器。

④ 压缩与字号的分工
- 压缩：只对 s_need < floor 的条目做意译压缩，目标长度由实测算出（avail / (floor × boundH)，取 0.97 安全系数）；数字/单位/时限/标准号/否定/责任人/安全动作一律不可删（本任务 85 条压缩后逐项对源核对：数字、否定、责任人零丢失）
- 字号：按页统一 S = clamp(min(s_need), floor=0.78, 1.0)（同页一致，避免同页两种字号）；单容器兜底下限 0.62（14pt→8.7pt）
- 写回字号用 COM：python-pptx 里 font.size is None 是继承值，按其缩放会算错基准（实测：模型回退取 18pt，真实渲染约 14pt）；COM 的 Font.Size 直接给生效值

⑤ ⚠️ 静默丢内容陷阱：段落内软换行（方向二新增，必查）
源 <a:t> 内可内嵌 
 / 
 表示"同一段落中的多个可视行"（本套 PPT 第 9 页把 8 条 5S 要求塞进一个段落）。若按"一段落 = 一条译文"写回，只写首行、其余静默消失（实测丢 7 条 ≈ 1100 字符英文），而"中文残留 = 0""数字对账""行数守恒""replaced units 全绿"一个都不报错。
正解：
- 译文按源各段的行数 L_i（该段文本含 \n 数 + 1）切分回填；
- 断言 len(译文行) ≤ sum(L_i)——少了 = 译者删了尾部空段（可 pad 成空段）；多了 = 会丢内容（必须中止整批）；
- 段内多行用与源文相同的编码写回（字面换行即可，python-pptx 会写成等价字符）——不要用 <a:br/>：段落为两端对齐（algn="just"）时，<a:br/> 会把每个断行拉伸出巨大字间距（实测第 9 页）。
- 配套：替换计数（replaced units / paragraphs）不能当内容完整性判据，必须配"逐单元数字/术语对源核对 + 交付件渲染抽查"。

⑥ COM 另存 PPTX 后的"假报警"
媒体部件数会下降（实测 89 → 56），因 PowerPoint 归一化/重编码重复图；判据改用图片形状数（<p:pic> 计数 159 = 159 守恒）与 rels 目标可解析性，不要拿 media 部件数或文件名对账（另存会重命名媒体、重写 rels）。

⑦ 验收清单（缺一不可）：中文残留 0 / 逐单元数字对源核对 / 图片形状数守恒 / 渲染抽查若干页（标题与正文不叠、文字不出页、卡片内文字不被压住）。

工作流程 — 方向三：英→中 PDF/法规/长文 → 中文（v3.2.0 新增）

> 2026-09-04 沉淀：马来西亚 OSHA Act 514 全文（81 页法条 + 5 附表 + 修订流水）+ HIRARC 指南 → 中文交付。适用：英文 PDF（法律/法规/标准指南/事故报告/技术手册）→ 中文（默认同格式 PDF，用户指定 Word 时出 DOCX），同目录交付培训/合规场景。本方向典型源格式为 PDF（含法规/长文），故 spec→create-docx→导出是标准链路；若源已是 DOCX 则跳过导出步直接交付。

前置工具：配合 ray-doc-toolbox 使用（PDF 提取 + create-docx 生成），本 skill 负责翻译决策与内容质量。

五步流程

1. 提取全文：用 ray-doc-toolbox read/pdf-text 提取 PDF 文本到 txt（先 inspect 判断文本层/OCR 分支；扫描件用 --pages 关键页）。输出含分页标记时保留，用于定位。
   - 提取后先验字符数（v3.4.0）：提取结果 ≈0 字符/页或整页空白 → 判定无文字层，转下方 OCR 分支（别硬译空文本，最后发现整本没内容）
   - OCR 分支（v3.4.0，无文字层源）：dtool ocr / tesseract 分页批处理（每批 10-20 页），禁止整本一次跑——页数多必超时，且失败无提示
   - 超时降级三招：① 450 dpi 重渲染（dpi 低时细字识别率差）② psm 4 与 psm 6 双跑取优（版面差异大时两者差异显著）③ 逐页分批 + 结果落盘累加（断点可续，防单次失败全废）
   - 英文源加 -l eng：默认语言包不以英文为主，漏加会显著降低识别率
   - OCR 产物必做结构校验：页码连续性 + 章节标题行可辨 + 条号 1→N 连续；异常页回炉重跑（OCR 静默吞行是常态）
2. 翻译并构建 spec：
   - 先过 CAT 三段式（grep 术语库锁定命中项）
   - 全文翻译，译文按文档结构组织成 *_zh_spec.json（title + sections：heading/level/paras/table），供 create-docx 消费
   - 结构完整是硬要求：法律全文的 PART/条/款/附表/修订清单必须全覆盖；删页决策（如广告页）须用户先确认
   - ⚠️ spec 必须程序化构建（铁律，v3.2.3，09-06 实测）：写 Python 脚本（dict + json.dump(ensure_ascii=False)）生成 spec，禁止手写 JSON 文件——手写必踩内容 ASCII 引号坑（如「所谓"技术服务请求"」的 " 提前截断 JSON 字符串报 Expecting ',' delimiter）；状态机自动修复会搞坏文件（曾 3 次失败）。中文内容引号一律用「」，Python 构建自动转义永不出错。构建脚本分批 append（每批落盘防上下文丢失），最后统一 json.dump 写盘
3. 中间生成 DOCX：ray-doc-toolbox create-docx --spec <spec.json> --out <同名_中文.docx>——DOCX 是 spec 渲染的中间载体，最终交付格式按输出默认规则还原（见开工简报下方规则）
4. QA 抽读验证（必做，静默失败最危险）：生成后必须用 python-docx 抽读验证，不能只看 ok:true：
   - 条号/章节连续性：正则提取标题行条号，校验 1→N 连续无重复无缺失（曾抓出 spec 残留 28 个旧草稿 section 导致条文乱序重复）
   - 表格存在性：抽查每个 section 的表格列数/行数（曾抓出表格字段名错致整表静默丢失）
   - 乱码扫描：\ufffd 必须 0
   - 首尾段落抽查
   - 源↔成品结构化对账（v3.4.0 必做）：本步只验成品内部自洽（整体缺章时「连续」仍成立），必须另做双向结构对账 → 见本方向「验收与复核纪律」
5. 交付格式还原（默认与原格式相同）：
   - 源为 PDF → 用 Word COM 导出中文 PDF（doc.ExportAsFixedFormat(out, 17)，见 ray-doc-toolbox P-014）放入交付目录（交付目录默认 = 源文件同一文件夹，v3.3.2 规则；用户指定目录时以用户为准）；中间 DOCX 留在临时工作目录，不放进交付目录（除非用户明确要 DOCX）
   - 源为 DOCX → 直接交付中文 DOCX
   - 用户明确指定格式（如"转成 Word"）→ 按指定格式交付

验收与复核纪律（方向三特有，v3.4.0，2026-09-12 沉淀）

法律/法规文书翻译纪律（方向三特有）

插图回插子流程（v3.3.3，2026-09-09 沉淀）

> 方向三延伸场景：译文以「图 X.Y（原图略）：图题」占位后，把原版插图插回交付 PDF。CHEF Manual 189 页 / 71 图全量实战（四步 + QA）。 图题口径（v3.5.0）：图题译中文；图内标注文字保留英文（改图内文字成本与失真都高，EEMUA 191 216 页 / 56 图实战确认）。

1. 探针定界：fitz 真题注块检测（短文本块以 Figure X.Y 开头；勿用首次提及——正文交叉引用会误判页码）。区域上界 = max(同页上一题注底, 上一正文块底)+4；下界 = 题注上沿-1；题注在页顶（y<110）→ 图在上一页底部（跨页情形）。
2. 提取：内容框 = 栅格+矢量+短文本块并集（含图内标签；排除宽>380 且长>100 的正文块）。单一栅格占内容框 ≥70% → extract_image 原生字节（无损）；否则 220dpi 区域渲染。
3. 插入：python-docx 定位占位段，insert_paragraph_before 插图（居中）+ 题注去「原图略」（改写保首 run 格式）。width 与 height 必须同时给——fitz 写的 PNG pHYs=0，只给 width 会让 python-docx 读 DPI 除零崩溃。
4. QA：插图计数 + U+FFFD=0 + 5 张多模态对位抽查 + 译者说明页同步改写（勿漏）。

特殊情形裁决（探查→方案→用户批准后动手）：原书重号图（两处各自插图+译者注）；正文复用同图（双插或「参见图 X.Y」）；无编号图（同源去重→「参见图 X.Y」）；源书仅文字提及无图（保留原状）；表格型图（渲染为图 or 人工转录真表格，用户定）。

两坑：①题注与横轴标签合并成一个文本块 → 下沿钉题注上沿会切标签（下沿=区域下沿即可）；②题注块压在栅格 bbox 上（含行距空白）→ 下沿外扩到栅格底+2 且不超过题注字形上沿。

版式保持型 PDF（原位回贴）子流程 → 已迁出至 ray-file-inplace（v4.0.0）

> 适用判据（版式敏感手册：编号公式/矢量图/数据表密集，要"逐页对应、公式图零损伤"，与重排型互斥）、提取判据、冻结纪律、回贴要点、QA 判据——全套几何方法论现居 ray-file-inplace SKILL.md。本 skill 在该路线只按契约填译文池：frag_jobs/dN.json（gid/page/kind/src）→ frag_out/dN.json（gid→译文），术语锁定表（frag_spec.md 术语节）仍由本 skill 的 CAT 三段式程序化产出。

🚨 语言侧五条硬约定（填译文池时必须写进 frag_spec 与译者任务书）

> PGS 3 紫皮书 237 页实战（2026-09-23）证明：这五条不属于几何侧——它们是"译成什么"，写进任务书才生效；漏写的每一条都会在交付件上变成可见缺陷。

1. 指数/上下标一律保持 ASCII 原样（10-8、m-3、s-1、y-1），严禁改写成 Unicode 上标。
   理由：源件用「缩小字号 span」实现上下标，文本层本就压平为 ASCII；而中文字体（华文中宋/微软雅黑/宋体/黑体）全部缺 ⁻(U+207B) 与 ⁰⁴⁵⁶⁷⁸⁹，直写即渲染成黑块。
   仰角排版由几何侧按源 span 区间复刻（ray-file-inplace RF-19）。
2. 目录行（kind=toc）：只译标题，点导引与页码逐字符保留——必须用脚本从 src 正则切出「标题｜空白｜点串+页码」并程序化复制点串与页码，禁止手抄（上百个句点必错）；多行 toc 单元用 \n 保留源逐行结构。
3. 表格单元格（kind=cell）：只译有实义的词——站名/风向代码/航道专名/数值/符号/单位原样保留；固定口径如 Day→昼间、Night→夜间、Total→合计。
4. 参考文献著录（kind=reference）：保留原文著录（作者/题名/出版项不译，仅译「References→参考文献」这类标题），靠回贴端「译文==原文则跳过」同文安全阀原地不动。⚠️ 提取器的文献区识别只认独立标题行，5. REFERENCES 这类带章号的标题会漏判 ⇒ 任务书里要显式交代。
5. 窄单元格的压缩授权：表格列宽不足时允许意译压缩（如 <>"geen"（不等于"无"）→<>"无"），但数字/单位/否定/物质名一律不可删。⚠️ 压缩是译者权限，几何侧不得代做。

交付后精修与体积纪律 → 已迁出至 ray-file-inplace（v4.0.0）

> 字体资源名隔离 / subset_fonts() 必做末步 / 行距重分布 / 碎片段归因四类 / 定组铁律 / 实战教训（LRN-20260914~15 系列）——全套现居 ray-file-inplace SKILL.md（并已并入 PGS 2 v9.2 新教训：吞了没补、行内符号随行重译、不动点合并、译文池基线链、通道冲突消解与 superseded 实删）。

与方向一/二的分工

• 输入 Excel 工作簿 → 方向一；输入 PPT/讲义中译英 → 方向二；输入 PDF/法规/长文（英译中） → 方向三
• 方向三与方向一同属英→中，但载体不同（Excel 单元格 vs 连续文本/条款结构），spec 驱动 + QA 抽读是方向三特有；输出默认还原源格式

常见故障与解决方案（速查表）

| 9 | 中文路径下脚本静默崩（v3.4.0 补，09-12 实测） | 中文路径经 shell 传参时编码转换异常 → 脚本 exit 0/1、零输出、无 traceback（最危险：看起来「跑完了没报错」） | 脚本先 cp 到 ASCII 临时目录（如 %TEMP%\wbdiag\）再跑；结果写 JSON 落盘，不靠 stdout；ffprobe/tesseract 同类；Python 内路径用 raw 字符串 r"..." 或正斜杠 |
| 10 | 中文 PDF 目录空白/页码不对（v3.4.0 补，09-12 实测） | Word COM ExportAsFixedFormat 导出时不刷新 TOC 域，沿用旧域结果 → 目录页码与实际不符或整块空白 | 导出前依次 doc.Fields.Update() → doc.TablesOfContents(i).Update() → doc.Repaginate()，再 ExportAsFixedFormat(输出路径, ExportFormat=17, CreateBookmarks=1)（必须「先更新域后重排」，顺序反了页码仍是旧的；EEMUA 191 实测域条目 297 / 重排后 216 页 / 书签 319）；导出后用 pdf-text 抽读目录页验收 |

提速与 Token 优化策略（五招速查）

交付物清单

英→中（Excel）：
- *_CN.xlsm — 翻译后文件（含完整 VBA 宏）
- check_remaining.py — 残留英文扫描脚本
- extract_real_remaining.py — 精细残留诊断脚本
- 残留统计报告（Sheet 分布、词频 Top 40）
- 翻译覆盖总结（总 cell 数、轮次、术语总数）

中→英（PPT/讲义）：
- *_EN.pptx / *_EN.md — 英文版交付
- 术语审计回写 data/termbase/（新增/修订条目按六列 schema 入库，v3.0.0）
- 备注/讲稿（## Page N 格式，95/95 校验）
- 机械 QA + 术语 QA 双报告

英→中（PDF/法规 → 中文，v3.2.0）：
- 源 PDF → *_中文.pdf（交付目录唯一文件，默认同格式；中间 DOCX 留临时目录，用户要才给）
- 源 DOCX → *_中文.docx（直接交付）
- *_zh_spec.json — spec 源文件（可复用/改版重生成）
- QA 验证记录（条号连续性/表格存在/乱码 0） + 源↔成品结构对账表（v3.4.0）

遗留注意事项

• 正常保留项：含英文的单元格多数属正常保留（单位符号、专业缩写、公式变量、场景保留词）——残留报告需人工判读，非数字越小越好
• 性能: 3-5 轮翻译受文件大小和分批数影响，大工作簿预期 10-15 分钟量级
• 兼容性: 翻译后文件直接在 Excel/WPS 中打开，中英文混排显示正常
• 边界: 纯数值、空白、公式单元格不变——三类合计通常占文件 60-70%
• 中→英方向: 面向外籍员工的培训材料，宁可"术语精确但句式简单"，不要"句式华丽但术语模糊"——安全文档语义优先
• PPT 英文版: 英文比中文长 ~40%，必须下调字号 + 放大行高；图片若无文字（灰度/写实风格）可零成本复用，语言中立

• 术语库纪律（v3.1.0）: 库文件 grep-only 永不整读；命中即锁定不得另译；收尾必做术语审计入库+命中台账；热词表只收无歧义词（上限 80）；毕业=移 _graduated.md 永不删除；备查池数据集仅作候选永不直接采用（旧译名慎用）

• 术语库回写纪律（v3.4.0）: 库回写一律走 fail-closed 脚本——每处断言 count(old)==1，任一不符整批不写并报出全部不匹配项；写后跑 SABOTAGE 负向自测证明检查器会咬人（只对自造样本验不算）。拒用❌列禁止自造——须有权威源（术语在线/国标/CNKI）或实战实证依据，无依据则留空，不得凭语感填。

维护记录

历史版本记录见 references/changelog.md（frontmatter 当前 v4.1.0，2026-09-23：新增方向三「语言侧五条硬约定」——PGS 3 紫皮书 237 页实战回流；v3.6.3 的变更至今无记录，见 changelog 顶部占位行）