doco: v2说话人分段模式 — ASR说话人分离+大block拆分+三维动画解说识别

- asr_adapter: 新增roleType=1说话人分离参数，新增parse_order_result_with_speaker()，write_asr_result自动输出asr_v2_timed_spk.txt

- fusion_align: 新增speaker-aware alignment v2流程（_annotate_b_lines_with_speakers区间匹配、_detect_speaker_blocks、SYSTEM_PROMPT_SPEAKER_ALIGN大block拆分prompt、_build_broadcast_segments支持block内多段拆分）

- cli: 兼容v1/v2 stats字典

- 新增convert_to_md.py（20期融合A稿docx转md+YAML frontmatter）

- backup_before_spk/: 修改前代码备份

doco/CLAUDE.md

@@ -16,8 +16,8 @@
 
 ## 🔖 状态栏 (STATUS — 每次结束 session 前必须更新这三行)
 
-- **最后更新**：Claude Code ｜ 2026-06-22（深夜，收摊）
-- **当前状态一句话**：**ep002（潜艇仿生）全流程 P1→C4 完工**，已出稿 + 通哥手动批改分段。**ep004 上游仍全空**（只有骨架），下一期待跑。C4 对齐层 MiMo 批次失败率偏高（47%），ep004 段切换密需留意。
+- **最后更新**：Claude Code ｜ 2026-06-24
+- **当前状态一句话**：**20 期全部出稿完成（16/16 批量跑零失败）。** doco 流水线验证通过。下一步：通哥逐期核验分段 → doco 收工 → 带 20 期成品回 TPS 主项目知识库。
 - **下一个动手的人从这里开始**：见下方「⏩ 交接备注」
 
 ---
@@ -63,28 +63,33 @@
   - `src/doco/asr_adapter.py` — C2 讯飞 ASR 适配层（已完工）：`get_hot_words(episode_id)` 读热词表、`transcribe()` 返回 `(句子, raw)`、`write_asr_result()` 落 `asr_v2_timed.txt` + `asr_result_raw.json`
   - `src/doco/video_split.py` — P1：含 `extract_audio()`（16kHz/单声道/16bit WAV），C2 直接复用，不另写 ffmpeg
   - `src/doco/fusion_review.py` — C3：B稿v2 ⊕ ASR 交叉复审 → 融合B稿(743行) + fusion_review.csv
-  - `src/doco/cli.py` — 命令入口（split / terms / asr / fuse）
-  - `doco/data/term_dict.json` — 累积词典（当前 110 条）
+  - `src/doco/cli.py` — 命令入口（split / terms / asr / fuse / compose / skeleton / **run**）
+  - `src/doco/templates/` — P1/P2 stage 脚本模板（`doco run` 自动复制到 episode 目录）
+  - `doco/data/term_dict.json` — 累积词典（当前 267+ 条）
   - `doco/programs/<episode_id>/` — 每期产物（热词表、各阶段输出）
 - **常用命令**：
   - C1（已实现）：`doco terms --episode-id <id> --a-script <path> [--no-ai]`
   - C2（已实现）：`doco asr --episode-id <id> --input-video <绝对路径mp4> --output-dir <绝对路径 doco/programs/<id>>`（`--skip-asr` 只分离不转写）。**务必传绝对 `--output-dir`，否则落到当前工作目录的 `programs/` 会与 doco 产物分家。**
   - C3（已实现）：`doco fuse --episode-id <id> [--no-ai] [--batch-size 35]`
-  - C4：待实现
+  - C4（已实现）：`doco compose --episode-id <id> [--batch-size 25]`
+  - 骨架：`doco skeleton --episode-id <id> --a-script <docx>`（需人工核验后再跑 compose）
+  - **一键全流程**：`doco run --episode-id <id> --a-script <docx> --input-video <mp4> [--batch-size 25] [--skip-p1]`
+  - **批量跑**：`python _batch_run.py`（16 期自动串跑，断点续跑，已有产物自动跳过）
 - **环境变量 / 密钥**：只放 `doco/.env`（已在 `.gitignore`）。需要的 key：`LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL`（已切换到小米 MiMo 2.5 Pro）、`XFYUN_APP_ID` / `XFYUN_SECRET_KEY`。**代码与对话里只引用变量名，绝不出现真值。**
 
 ---
 
 ## 3. 当前进度（核心交接区，以最新快照为准）
 
-- **已完成至**：ep001 + ep003 + **ep002** 三期全流程跑通。ep002 C4 已出稿，通哥手动批改分段完毕。
-- **正在做**：无。
-- **卡点 / 待解**：ep004（枪王对决）上游全空，需跑完整 P1→C4。C4 对齐层 MiMo 批次失败率 47%（ep002 实测），ep004 段切换更密，需关注（见关键决策）。
+- **已完成至**：ep001-004 四期全流程出稿。一键脚本 `doco run` + 批量脚本 `_batch_run.py` 已就绪。16 期骨架全部生成并通过核验。C3 prompt 已收紧（专名铁律）。C4 batch_size 已降至 25。
+- **正在做**：无（等通哥逐期核验分段标签）。
+- **卡点 / 待解**：20 期出稿已全部产出，通哥核验分段后 doco 收工，带成品回 TPS 主项目。
 
 ---
 
 ## 4. 已完成（只追加，最新在最上）
 
+- [2026-06-23 ｜Claude Code] **批量化基础设施完工 + ep004 全流程通过 + 16 期批量跑启动**。本 session 完成：① ep004（枪王对决，最难·小剧场密·58段）全流程 P1→C4 一次通过，C4 punct_ok 58/58 全过、confidence 全 ≥0.80（batch_size=25 效果显著，无批次回退）；② 新增 `doco run` 一键全流程命令（Cline 实现，Opus 审核），参数 `--episode-id / --a-script / --input-video / --batch-size / --skip-p1`，ep004 `--skip-p1` 验证通过；③ C3 SYSTEM_PROMPT 收紧专名铁律（防 ASR 同音字替换权威 B稿专名）；④ Ollama 并发提至 16 路（`OLLAMA_NUM_PARALLEL=16`，8 路实测 GPU 96%、显存充裕）；⑤ 16 期新目录建立 + 文件拷贝 + 骨架批量生成并集中核验（真名零泄露、隔断/ignore 正确）；⑥ `_batch_run.py` 批量脚本启动跑 ep005-ep020。**doco PRD 完成标准已与通哥确定**：20 期全出稿 → 带成品回 TPS 主项目知识库批量导入。
 - [2026-06-22 晚｜Claude Code] **ep002 C4 审核完毕，全流程收工**。Cline 跑完 C4 compose 出稿 `20260127潜艇的仿生之路_穆佩弦_融合A稿.docx`。Opus 审核核验：硬校验（汉字零改）全过、733 行全覆盖、标点回退 0 段。**但发现两个问题**：① Cline 自报空段名称错了两个（报"解说3/解说6"，实际是"三维动画解说3/解说8"）、隔断数也报错（报 3 个，实际 4 个）——再次印证不信 Cline 自检；② **9/19 批次（47%）LLM 对齐失败走回退**（全 confidence=0.30），本次因失败批次恰在大段中间未翻车，但属黄色预警。**分段偏差根因**：A 稿是拍摄前剧本，专家采访段与实际播出内容差异巨大（A 稿一句话提纲 vs 专家自由发挥两分钟），LLM 无法正确匹配——这是信息不对应，非算法问题。通哥手动批改分段（~10 处高亮标签），内容本身正确。**结论（通哥拍板）**：治本靠编导给贴近播出版的稿子，现阶段接受"程序保证文字零改 + 编导手调分段"的模式。
 - [2026-06-22 ｜Claude Code] **ep002 C3 融合通过**。融合B稿 733行（零偏移），review 10条（5 minor_edit 全是 OCR 错字修正，专名无同音替换）。C4 compose 交 Cline 跑中。
 - [2026-06-22 ｜Claude Code] **ep002（潜艇仿生）P1→P2→C1→C2 完成**。P1 全量抽帧 1620 帧（不做 dHash/IoU 去重，全部进 OCR）；P2 OCR 4路并发首秀通过（~50帧/分钟，约串行3倍），Stage B 文本去重出 B稿v2 733行；C1 术语提取 68 条热词（词典累积至 235 条）；C2 讯飞 ASR 411 句。下一步 C3 fuse。
@@ -107,13 +112,15 @@
 - [x] **C3**：B稿v2 ⊕ ASR 交叉复审 → 融合B稿(743行时间戳零偏移) + fusion_review.csv(5条留痕)。
 - [x] **C4（全部收口）**：融合B稿按 A稿28段对齐归拢 → 融合A稿 docx（公文格式）。汉字零改 + LLM 按语义加标点，红线 28/28 段逐字一致。`doco compose --episode-id <id>`。**OCR 漏字决定不补**（讨论见关键决策）；seg8/seg27 两段标点接受一逗到底。
 - [x] **A稿解析器升级**：正则 → LLM分段骨架+人工确认+ignore合并；三期骨架已产并核验通过。`doco skeleton`。
-- [~] **批量化首批三期·跑完整流水线（下一步主线）**：ep001 + ep003 + ep002 三期已全流程完工。**ep004 上游仍全空**（只有骨架），需跑完整 P1→C4。stage 脚本从 ep003 复制。
+- [x] **批量化 ep001-004 全流程完工**：四期均已出稿。ep004（最难·小剧场密·58段）C4 全过，batch_size=25 效果显著。
 - [x] **【已完成】标点层 prompt 修复**：加第5条规则+示范，ep003 逗号占比 88%→76%，commit `fd2ef1a`。
-- [x] **【已完成】配 Ollama 并发**：`OLLAMA_NUM_PARALLEL=4`，ep002 OCR 4路实跑通过，~50帧/分钟。
-- [ ] **【backlog】C4 对齐层 batch_size 调优**：ep002 实测 batch_size=40 导致 47% 批次 MiMo 返回空/JSON 截断走回退。ep004 段切换更密，建议降到 25-30。Cline 在 `_run_compose.py` 里加 `--batch-size 25` 即可。
+- [x] **【已完成】配 Ollama 并发**：已从 4 路提至 16 路（`OLLAMA_NUM_PARALLEL=16`），8 路实测 GPU 96%、显存充裕。
+- [x] **【已完成】C4 对齐层 batch_size 调优**：已降至 25，ep004 实测 confidence 全 ≥0.80，无批次回退。批量脚本 `_batch_run.py` 固定用 25。
 - [ ] **【产品 backlog】原稿缺【专家N】/【三维动画N】标签**：ep003 复查发现编导原稿里就没有专家、后续三维动画的分段标注，骨架如实反映=融合A稿里也没有（通哥手工补了高亮）。不赖程序（原稿零信号，LLM 与人一样猜不准），**不让程序猜**。治本=提醒编导/责编原稿把【专家N】等段头标全；50 期前在导入须知里写清。
-- [ ] **【backlog】C3 prompt 收紧**：专有名词(厂名/型号/番号)遇 ASR 同音异写，必须以 B稿v2/A稿为准、不许采 ASR——ep003 已踩"斯泰尔→斯太尔"，50 期批量前在 prompt 里收紧防复发。
-- [ ] **串一键脚本**：把 C1→C2→C3→C4 串成"一条命令跑一期"(薄壳，各阶段已有断点缓存)，验 2-3 期稳定后再谈监控文件夹/绑定界面。
+- [x] **【已完成】C3 prompt 收紧**：`fusion_review.py` SYSTEM_PROMPT 新增专名铁律——厂名/型号/番号/国名/人名/机构名遇 B稿与 ASR 同音异写，一律以 B稿为准，零容忍采 ASR。
+- [x] **【已完成】串一键脚本**：`doco run` 命令（P1→P2→C1→C2→C3→C4 六阶段串联），ep004 验证通过。模板脚本放 `src/doco/templates/`。
+- [x] **批量跑 20 期（完成）**：ep001-004 + ep005-ep020 共 20 期全部出稿，16 期批量跑零失败（847 分钟），B稿行数 699-874，融合B稿行数全部零偏移。
+- [ ] **doco 收工后回 TPS 主项目**：20 期融合A稿批量导入知识库（走 Phase 3 已有的上传/embedding 链路），为 Phase 4a 语义搜索提供冷启动数据。
 - [x] **【已修复】`fusion_align.py` align_batch 崩溃 bug**：`_parse_align_json` 调用在 `try/except` 之外，LLM 返回空字符串时进程崩溃。Cline 已修，移入 try/except 内，错误时优雅回退。
 - [ ] **骨架小瑕疵 backlog（不拦路，后期顺手或跳过）**：ep002 演播室主持人 vs 主持人 是否统一；ep004 小剧场角色编号乱(斯9/斯通纳10、卡8跨场)直接改 JSON 即可，不必重调 LLM；ep003 行内`【固摇轨】`留在参照正文(无害，不进输出)。
 - [x] **C2** 讯飞 ASR 适配层（密钥外置 + asr_adapter 并入 + `doco asr` 命令 + 真转写310句）
@@ -125,6 +132,9 @@
 
 ## 6. 关键决策（为什么这么做 — 跨 session 最易丢，别推翻）
 
+- [2026-06-23] **doco PRD 完成标准：20 期全出稿 → 带成品回 TPS 主项目。** ep004 跑通 + 一键脚本就绪 = 流水线可用；剩余 16 期在 doco 子项目内批量跑完（一方面压力测试积累问题，一方面 20 期成品对 TPS 知识库冷启动有价值）。回归路径：融合A稿作为 manuscript 类文档 → 走主项目 Phase 3 知识库上传/embedding 链路 → Phase 4a 语义搜索。
+- [2026-06-23] **C4 batch_size=25 为量产默认值。** ep004 实测 58 段全过（confidence 全 ≥0.80，punct_ok 58/58），相比 ep002 的 batch_size=40（47% 批次回退）大幅改善。`_batch_run.py` 和 `doco run` 默认均为 25。
+- [2026-06-23] **Ollama OCR 并发提至 16 路。** 8 路实测 GPU 利用率 96%（4090D 24GB 显存充裕），16 路为批量跑默认值。环境变量 `OLLAMA_NUM_PARALLEL=16`（系统级）+ `OCR_NUM_WORKERS=16`（批量脚本内设）。
 - [2026-06-22] **C4 分段偏差的根因是 A 稿与播出版内容差异大，非算法问题，现阶段不追技术方案。** ep002 实证：专家采访段 A 稿只有一句话提纲，实际播出专家自由发挥两分钟，内容/角度/篇幅全变，LLM 拿提纲匹配实录当然对不上。解说段偏差轻，基本能对。**B 稿（唱词字幕 OCR）里没有隔断标题**（隔断是画面美术字不走字幕轨道），所以也没法用隔断做硬分界线。**通哥拍板**：治本靠编导给贴近播出版的稿子（尤其专家段录完后更新）；差异大的期接受"程序保证文字零改 + 编导花十几分钟手调分段标签"。
 - [2026-06-22] **MiMo 2.5 Pro C4 对齐层批次失败率偏高（ep002 实测 9/19=47%）。** 失败批次全 confidence=0.30，回退机制把该批所有行分配给 `min_normal_seg_id`。ep002 运气好——失败批次全在大段中间，回退恰好分对了。但 ep004 段切换密，边界批次失败会导致行归错段。**建议 ep004 前把 batch_size 从 40 降到 25-30**，或排查 MiMo 返回空/JSON 截断的具体原因。
 - [2026-06-18] **A稿段头识别改用「LLM 判结构 + 人工核骨架」，不用死正则。** 编导写法千变万化(方括号/冒号/前缀杂质`Xr`/`【固摇轨】`镜头标记/小剧场对话头)，正则分不清`【固】`(镜头)与`【主持人1】`(段头)——这是语义判断，交 LLM。**铁律：LLM 只输出结构(type/role_label/para 区间)，绝不复述正文；正文一律代码按下标从 docx 原样抽**(护住"汉字零改"红线)。配两道闸：① `validate_skeleton_coverage` 全覆盖硬校验(title 后每段恰好被覆盖一次，自动抓 LLM 数错下标/JSON 截断)；② 人类预览表给制片人肉眼核(重点抓真人姓名泄露/ignore 漏多/隔断认全)。`doco compose` 无骨架即报错(ep001 例外走正则)。
@@ -158,27 +168,25 @@
 
 ## 7. ⏩ 交接备注（写给下一个接手的 session）
 
-> 下次开工读完这段应能 0 摩擦续上。接手后可清空重写。**（2026-06-22 深夜重写）**
+> 下次开工读完这段应能 0 摩擦续上。接手后可清空重写。**（2026-06-23 重写）**
 
-- **大局**：ep001 + ep003 + ep002 三期已全流程跑通出稿。**ep004（枪王对决）上游全空**，是下一期主线。
-- **ep002 收尾状态**：全流程完工。出稿 `融合A稿.docx` 硬校验全过（汉字零改），通哥已手动批改分段（`融合A稿_批改.docx`）。分段偏差根因是 A 稿与播出版内容差异大（见关键决策），非程序 bug，现阶段接受编导手调。
-- **ep004 现状**：`ep004_20260526_qiangwang_duijue`（枪王对决，最难·小剧场密）。只有 A稿 docx + mp4 + skeleton。需跑完整 P1→P2→C1→C2→C3→C4。stage 脚本从 ep003 复制。
-- **第一句话该干的**：与通哥确认是否开跑 ep004。ep004 小剧场多、段切换密，C4 对齐层可能更吃力（ep002 已有 47% 批次回退），**建议降 batch_size 到 25-30**。
-- **LLM 已切换**：代码和 Cline 都已从 DeepSeek 切到**小米 MiMo 2.5 Pro**。环境变量名 `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL`（旧 `DEEPSEEK_*` 已废弃）。
-- **Ollama 并发已配**：`OLLAMA_NUM_PARALLEL=4`，ep002 实测 ~50帧/分钟（串行的3倍）。4090D 显存余量大（GPU 利用率仅 2%），ep004 可考虑提到 8 路。
-- **P1 抽帧硬约束**：**不做 dHash/IoU 去重**，全部帧进 OCR，去重交 Stage B 按文本做（P2 完工快照铁律）。`doco split` 的去重逻辑是过时的，不要用。
+- **大局**：doco 子项目进入收尾阶段。ep001-004 四期全流程已出稿验证通过。16 期新节目（ep005-ep020）正在 `_batch_run.py` 批量跑中。20 期全部出稿后，doco 收工，融合A稿作为知识库资源带回 TPS 主项目。
+- **批量跑状态**：`python _batch_run.py` 在独立终端跑中。脚本有断点续跑能力（B稿v2 存在则跳过 P1+P2，ASR 已有则跳过转写，融合B稿已有则跳过 C3，融合A稿已有则跳过 C4）。中断后直接重跑即可。
+- **第一句话该干的**：看 `_batch_run.py` 跑完没有。跑完看汇总表，有失败的排查原因重跑。全部成功后，逐期打开融合A稿 docx 核验分段标签，分段偏差的地方手调。
+- **LLM**：小米 MiMo 2.5 Pro，环境变量 `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL`。
+- **Ollama**：16 路并发（`OLLAMA_NUM_PARALLEL=16`），4090D 24GB 充裕。
+- **关键参数**：C4 batch_size=25（`_batch_run.py` 硬编码），C3 batch_size=35。
 - **量产坑（务必记住）**：
-  1. 每期热词/术语不同，**C1 每期重跑**；A稿分段编号各有各的重复/空格脏，**按出现顺序走、别假设单调唯一**。
-  2. **C3 fuse 后必扫 `fusion_review.csv`**：专名（厂名/型号/番号）若被 ASR 同音字改了要打回（ep003 踩过"斯泰尔→斯太尔"，见关键决策）。
-  3. **C4 出现空段先别当 bug**：多半是播出剪了那段戏，去融合B稿 grep 该段专属词确认（见关键决策）。
-  4. **C4 分段偏差是常态（A 稿≠播出版）**：内容正确但分段标签可能偏，编导手调十几分钟搞定。不追技术方案（见关键决策）。
-  5. **OCR 漏字本期不补**（通哥拍板）——根在抽帧/OCR 漏两三字单屏，LLM 补词=破红线。
-  6. **ASR 花讯飞额度**；长转写/OCR 放独立终端别让 Cline 盯。
-  7. Cline 会偷换模型/术语源、误判字数、口头猜错根因——**自报结果一律对源数据核验**（ep002 C4 报告空段名称错两个、隔断数也报错）。
-  8. **thinking 分任务用**：语义对齐/骨架开、标点/抽取/融合关（见关键决策）。
-  9. **MiMo C4 对齐批次失败率高**（ep002 47%），ep004 前考虑降 batch_size（见关键决策）。
-- **出稿命名**：`{原始A稿stem}_融合A稿.docx`（不覆盖原始定稿）。
-- **字体坑（C4 出稿）**：大标题方正小标宋_GBK（商业字体），出稿前确认已装，否则脚本回退。
+  1. **C3 fuse 后必扫 `fusion_review.csv`**：专名被 ASR 同音字替换要打回。C3 prompt 已收紧专名铁律，但仍需人工复核。
+  2. **C4 空段 = 播出剪了那段**，不是 bug。
+  3. **C4 分段偏差是常态**（A 稿≠播出版），编导手调分段标签即可。
+  4. **OCR 漏字不补**（通哥拍板），LLM 补词=破红线。
+  5. Cline 自报结果一律对源数据核验，不轻信。
+  6. thinking 分任务用：骨架/对齐开，标点/抽取/融合关。
+- **出稿命名**：`{原始A稿stem}_融合A稿.docx`。
+- **字体坑**：大标题方正小标宋_GBK（商业字体），出稿前确认已装。
+- **doco 收工后的路**：20 期成品 → TPS 主项目知识库批量导入（走 Phase 3 上传/embedding 链路）→ Phase 4a 语义搜索提供冷启动数据。主项目待办三选一中的"200+ Obsidian md 批量录入"正好是接收口。
+- **工具脚本清单**（一次性，跑完可删）：`_setup_episodes.py`（建目录+拷文件）、`_batch_skeleton.py`（批量生成骨架）、`_batch_run.py`（批量全流程）。
 
 ---
 
@@ -187,5 +195,6 @@
 - ~~**B稿_v2.txt 就位**~~：已完成（通哥已拷进 episode 目录并随 9340edc 入库）。
 - ~~**讯飞旧 key 轮换**~~：已完成（新值已在 `doco/.env`，旧 appid `84eff996` 代码内无残留）。
 - **方正小标宋字体可用性**：C4 出稿前确认两台机器是否已装。
-- ~~**OCR 并发提速**~~：已完成，4路并发实测通过（ep002），后续可提到 8 路。
-- **讯飞单源依赖**（远期）：是否接阿里云 ASR 做备份/交叉验证。
+- ~~**OCR 并发提速**~~：已完成，16 路并发（4090D 24GB 充裕）。
+- **讯飞单源依赖**（远期）：是否接阿里云 ASR 做备份/交叉验证。
+- **ep016 骨架的宣传词被标为 break**：其他期（ep006/13）宣传词标为 normal，需通哥确认 ep016 是否应改。