PDF/CHM 手册书式转换与翻译管线
定位
- 本 Skill 编排完整管线；
pdf-book-translator提供提取与构建内核（extract_pdf.py、build_book.py） - 增量资产在 scripts/（合并、注入、MD 反向、图片治理、验证）与 references/（流程、图片规则、并行定时、案例）
- 先用则读：references/pipeline.md（端到端编排）；图片问题读 references/image-governance.md；并行加速读 references/parallel-cron.md；HTRI 实证读 references/htri-case.md；CHM 输入（非 PDF）读 references/chm-source.md
六阶段工作流
- 提取：
python <pdf-book-translator>/scripts/extract_pdf.py <in.pdf> <workdir>→ work/{toc.json, pages.jsonl, images/} - 骨架：
python <pdf-book-translator>/scripts/build_book.py <workdir> <outdir>→ 英文书式 HTML + MD（锚点=slugify，图片内嵌/外链） - 翻译：按页写
translations/batch_s<段>_<序号>.json（titles + pages 覆盖层；公式$$LaTeX\\tag{编号}$$；模板见 scripts/make_batch_template.py） - 聚合：
python scripts/merge_batches.py translations/→ merged.json →build_book.py ... --translations merged.json重建 - 图片治理：
python scripts/scan_images.py <images_dir> <scan_out>+python scripts/clean_images.py <in.html> <out.html> <images_dir> <scan_out>（黑块/细条/残迹剔除，大图例外保留） - 验证交付：
python scripts/verify_book.py <book.html> <images_dir> <scan_out>+ Chrome 渲染目检 → 备份旧版 → present_files 交付 HTML/MD
关键规则（违背会翻车）
- 双层文本层 PDF：必须剔除 SimSun 假层（rawdict 按字体过滤），否则正文乱码
- 锚点一致：翻译覆盖层 titles 的 key、注入操作、MD 锚点链接都必须与 build_book.py 的 slugify 一致
- 并行安全：N 路翻译任务只写自己的 batch_sN_*.json；merged.json 与 build_book.py 只由聚合任务执行
- 图片碎片必清：提取器会把黑色填充/边框碎片当图导出（HTRI 实测 61% 图文件是纯黑块）；交付前必须治理并拼版目检
- 黑底白线大图保留：面积 ≥ 50000 的黑底坐标系趋势图是有效图，不得按"近纯黑"误删
- 无图版本检测：交付前验证 img 计数；云上/远端产物可能无图，用
python scripts/inject_imgs.py <skeleton.html> <target.html> <out.html>修复 - MD 与 HTML 同步：图片治理后必须重新生成 MD（md_from_html.py），否则图引用失效
- 侧边栏结构（CHM/自研构建器）：
<nav id="toc">必须是aside#sidebar的直接子项，严禁嵌套在.sb-head内——实测会把头部撑到 574px、目录 flex/overflow 全部失效、左侧完全无法滚动 - 侧边栏滚动 CSS：即使结构正确，
#toc{flex:1;overflow:auto}在height:100vhflex 容器内仍不滚动（flex 子项默认min-height:auto阻止收缩）；必须#toc{flex:1 1 0;min-height:0;overflow-y:auto;overscroll-behavior:contain}+aside{overflow:hidden}+.sb-head{flex:none}（移动端断点同样加 overflow:hidden） - 弹出层静态化：CHM 源页常有
popuponclick交互层（正文与其重复），CSS 必须加main .popuponclick{display:none !important}；PDF 必须在修复后重新生成，否则 PDF 含重复文本 - 旧版先备份再覆盖：主目录交付物替换前 Move 旧文件（保留 _old 备份）
- build_book.py 默认 HTRI 硬编码：脚本默认输出文件名
HTRI_Design_Manual_2026.html/.md、<title>HTRI 设计手册 · HTRI Design Manual 2026...</title>，与实际书无关。每次build_book.py重建后必须：①Move 重命名为实际书名（如AspenPhysPropModelsV15.html/.md）；②正则替换<title>标签为实际书名。否则浏览器标签页显示 HTRI 误导用户。 - build_book.py 默认 CSS 缺侧边栏滚动补丁：脚本生成的
#toc{flex:1;overflow:auto}在height:100vhflex 容器内不滚动。每次重建后必须重打补丁：#toc{flex:1 1 0;min-height:0;overflow-y:auto;overscroll-behavior:contain}+aside#sidebar{...overflow:hidden}+.sb-head{...flex:none}。见下方"构建后自动补丁脚本"。 - 验证不得省：结构计数 + 浏览器 DOM img 计数 + 单节预览截图 + 全量拼版目检，逐项通过才算完成
并行定时加速（可选，页数 1000+ 时）
见 references/parallel-cron.md：按 toc 分片 → 每段建翻译定时任务（每次译 10–15 页）→ 聚合任务统一 merge+build+交付 → 全部覆盖后逐个 get_cron_job + update_cron_job {"enable": false} 停用。任务触发轮严禁 create_cron_job。
验证命令速查
python scripts/verify_book.py book.html images/ scan_out/ # 结构计数+黑名单残留+拼版
# Chrome DOM 计数（Windows）
& "C:\...\chrome.exe" --headless=new --disable-gpu --dump-dom "file:///book.html" | Select-String '<img ' | Measure-Object
- 单节预览（长文档锚点截图不可靠时）：提取
<hN id="<anchor>">到下一标题间的 HTML 包成独立页截图目检 - 交付前结构期望：img=有效图数、已翻译徽标随覆盖增长、中文字符量、
</html>完整
构建后自动补丁脚本
每次 build_book.py 重建后，运行此脚本自动修复 HTRI 标题和侧边栏 CSS：
# scripts/post_build_patch.py <book.html> <实际书名>
# 1. 替换 <title> 标签
# 2. #toc 加 min-height:0 / flex:1 1 0 / overflow-y:auto
# 3. aside#sidebar 加 overflow:hidden
# 4. .sb-head 加 flex:none
补丁前必做备份（Move 旧版为 *_old.html）。补丁后用 Chrome 无头截图目检左侧目录可滚动。
妙搭（Miaoda）自动发布
构建+补丁完成后，如需更新在线预览链接，运行：
# 1. 发布到已有妙搭应用（复发布，app_id 复用首次返回值）
lark-cli apps +deploy --file-path ./book.html --app-id app_xxxx
# 2. 轮询到 finished
lark-cli apps +release-get --app-id app_xxxx --release-id <release_id>
或一键脚本（自动 deploy + 轮询）：
python scripts/deploy_miaoda.py book/AspenPhysPropModelsV15.html app_17fnud38g2a
关键规则：
- app_id 必须复用：首次 +deploy 返回的 app_id 要记住并写入项目配置；复发布带 --app-id 更新同一应用，不带则会新建应用。
- 路径必须相对：lark-cli 只接受相对路径，先 cd 到 HTML 所在目录。
- 异步发布：deploy 返回 status=publishing，必须用 +release-get 轮询到 finished 才算上线。
- 聚合任务自动发布：聚合构建流程最后一步可串联 deploy_miaoda.py，实现翻译完成→构建→补丁→发布全链路自动化。
依赖
- Python ≥ 3.10，pymupdf、pillow
- pdf-book-translator Skill（extract_pdf.py / build_book.py）
- 可选：Chrome/Edge 无头渲染（dump-dom / screenshot / print-to-pdf）
- CHM 输入：Windows 自带
hh.exe -decompile <outdir> <file.chm>（无需 7z）
