feat(tts): IndexTTS-2.5 专业用法沉淀：上游能力接通、读法修复与循证文档

docs/.agents/issue.md

@@ -3530,3 +3530,11 @@ R7 后浏览器对照 Section 2.1 区域发现两类正交缺陷：
 - **根因**：`{id}.mp3` 单槽位 + 摘要不含引擎标识——换引擎=每句摘要都「合法地」变了，逐句 sidecar 察觉不到「整集正在被换音色」；且硬化不对称：`--plan` 路径已按同一危害论证改为硬失败（tts.py:605-612 注释写明），**合成路径漏了同样的处理**。
 - **处理方式**：带值克隆参数（--ref/--style/--lang/--emo-*/--duration-factor/--num-beams/--steady）在 edge 下 `parser.error` 硬失败（典型手型=「照抄文档打了 --ref/--style 却丢了 --engine」）；`.engine` 音色签名标记作第二层（覆盖「一个参数都没打」的场景），不一致须 `--allow-voice-switch`。测试 `test_engine_guard.py` 六个用例锁定行为。
 - **后续防范**：**破坏性默认值必须硬失败而非提示**——静默降级的输出会覆盖唯一产物槽位时尤甚；修一处同类风险要横向扫全部入口（plan/合成/编排三层当时只硬化了一层）。
+
+## ISSUE-164 逐字稿「数字与汉字间加空格」的排版约定击穿中文归一化的年份规则，8 句成片读成「两千零二十六年」（2026-08-20）
+
+- **表因**：已上线三集共 **8 句**年份读错——`2025 年` 被念成「两千零二十五年」而非「二零二五年」，`1966 年` 念成「一千九百六十六年」而非「一九六六年」。命中句：EP1 `p0-01`/`p0-11`、EP2 `p0-01`/`p0-12`/`p5-15`/`p5-22`、EP3 `p0-16`/`p2-06`。
+- **根因**：**「排版约定 × TN 规则」的隐式耦合**，而非任何一方单独的缺陷。逐字稿有「数字与汉字之间加空格」的排版习惯（`88 页`/`15 分钟`/`16.2 个百分点`），这一约定对绝大多数场景无害；但 macOS 上实际的中文归一化引擎是 **wetext**（`~/tools/index-tts/indextts/utils/front.py:116-142` 按 platform 分叉，Linux 才走 `tn.chinese.normalizer`），其 date/year 规则要求**数字与「年」字面相邻**，插入空格后该规则失配、回落到 cardinal（基数）读法。实测空格敏感性矩阵里**只有 4 位年份这一条被击穿**：`6 月`/`20 日`/`88 页`/`47.6%`/`第 3 章`/`1.2 节`/`0.5~1.0 秒`/`9:30` 加不加空格结果一致且全部正确。另注：中文**不走** NeMo（`infer_v2_5.py:703-707` 是 if/elif，只有 ja/es 走 `nemo_tn`），此前若按 NeMo 排查等于查一条死路径。
+- **处理方式**：① 三集 `narration.md`（唯一维护处）共 8 句去掉数字与「年」之间的空格，重跑 `build_narration.py`；② `check_script.py` 新增 `READING_TRAPS` 成门，把**实测确认会读错**的 7 类写法固化为 FAIL/WARN（4 位年份带空格、三段版本号 `2.5.1`→「二.五点一」、连字符区间 `3-5 倍`→「三减五倍」、`±3%`→「百分之正负三」、`10x`→「十x」、整句无汉字→路由到英文归一化、`1080P`→「一千零八十P」WARN）；③ 每条规则都在 `test_check_script.py` 里配正反例，**反例组同等重要**——本轮调研初稿把 `0.5~1.0 秒` 与 `9:30` 也列为错误，实测证明它们其实正确（`零点五到一点零秒`/`九点三十分`），凭直觉扩大清单会造成误伤。
+- **后续防范**：**给外部引擎的文本，任何排版约定都要过一遍该引擎的真实行为探针，不能凭直觉列禁写清单**。归一化是**幂等**的（预写成汉字读法后再过一遍结果不变），故此类修复可逐句增量做、无需一次性全量改写、也不需要关 `text_normalization` 开关（关掉反而会丢失 `%`/小数/量词这些**已经正确**的能力）。加规则前先跑探针拿到「错读证据」，再把证据写进规则消息里——`READING_TRAPS` 的每条 message 都带实测输出。
+- **同类问题影响与注意**：① 生产若迁 Linux，归一化引擎换成 `tn.chinese.normalizer`，**必须在 Linux 上重跑同一组空格矩阵**确认行为一致；② 修复会改写这 8 句音频（每处少 2–3 个音节、约 −0.4~0.7 s），**牵动 beat 时长与片尾渐黑窗口**（同族踩坑：渐黑窗口须用 beat 时长而非末句时长），故重合成须按集排期、`pipeline.py tts --plan` 确认只有这几句 miss、重渲后 `qa_frames.py --last-n 6 --check` 复检尾幕；③ 本轮同时发现上游有一整套发音标注能力（`<行|HANG2>`）可治多音字，已接通并成门，见 [INDEXTTS-2.5-ADVANCED.md](../../media/pipeline/INDEXTTS-2.5-ADVANCED.md) 与 [PRON-GLOSSARY.md](../../media/pipeline/PRON-GLOSSARY.md)。

docs/.agents/knowledge-map.md

@@ -73,4 +73,5 @@
 - [科普视频制作 Pipeline（公共基建）](../../media/pipeline/README.md) — 全仓可复用的论文→视频九阶段流水线：`pipeline.py` 单入口（status/doctor/build/check/tts/captions/render/qa/all）+ 每集 `pipeline.toml` 声明式配置 + `timing.json` 时序 SSOT（timing.ts 与 Python 共读，双语言镜像漂移结构性消灭）；技能规格 skills/01–09（01–05 内容层、06 生产层实现、07 TTS、08 草渲 QA、09 终渲交付），真 Skill 挂载于 [.agent/skills/science-video-pipeline](../../.agent/skills/science-video-pipeline/SKILL.md)（纯路由壳）；测试 `media/pipeline/tests/` 45 项（digest 黄金哈希守缓存零失效）；工具：check_script（分镜覆盖性/时长预算双口径）、check_series（系列顺序五规则执法 [series.json](../../media/series.json)）、captions（srt/vtt）、qa_frames --check（黑帧/字幕带侵入/冻帧/WCAG 对比度自动体检）、paper_extract（论文取证五子命令）、refs（样本指纹清单）。
 - [自进化系列科普视频 · 三集作品](../../media/series.md) — 发布顺序《上线之后，AI 才开始上学》（金/青/紫，EP1，v3 已交付：内容校准 + sunny-steady 重配，成片 14:01）→《AI 如何自己变强？》（蓝/橙，EP2）→《会写代码的 AI，开始给自己写代码》（绿/洋红，EP3）；系列纪律：口播永不携带他集标题与集数序号，顺序变更 TTS 代价恒为零；各集 research/paper-notes.md 为口播单一事实源、upgrade-*.md 为轮次审计记录。
 - [IndexTTS 声音克隆手册](../../media/pipeline/VOICE-CLONING.md) — 双引擎 TTS 的克隆侧单一参考：部署（~/tools/index-tts 服务）/参考样本（prospect+prepare+refs 指纹门）/风格预设（sunny 明快阳光推荐位、sunny-steady 成片档 beams=3）/试听关卡（tts_sample + 领航片段）/缓存摘要与幂等/许可合规。
+- [IndexTTS-2.5 进阶用法（上游能力面 · 机制循证 · 提升路线图）](../../media/pipeline/INDEXTTS-2.5-ADVANCED.md) — 与操作手册正交的循证篇，锚定上游 HEAD `4f8792f` 逐条给出 file:line：能力矩阵（含 `do_sample` 在上游失效、`max_text_tokens_per_segment` 对本仓惰性等否定结论）/文本前端（中文走 wetext 而非 NeMo；实测读法矩阵——4 位年份带空格是**唯一**被击穿的规则，已成门，见 [ISSUE-164](./issue.md)）/发音标注 `<行\|HANG2>`（DTW 对照证实拼音通道生效 2.4× 分离度，CMU 通道不可判定）/情感机制（`emo_bias` 8 维不等权、`normalize_emo_vec` 在 infer 内从不被调用 ⇒ `Σvec×alpha≤0.8` 是本仓自创口径，跨来源参数迁移偏差 16–33%；73 个「情感×说话人」原型解释「换选段则标定失效」）/采样参数族（`length_penalty=0.0` 非中性、`repetition_penalty=10` 与音色耦合、`max_mel_tokens`≈30s 且溢出表现为文本尾部未念出、无种子致 A/B 不可信）/参考音频（15s 硬截断保前丢后、恒重采样 22.05kHz、CMVN 使相似度对增益免疫、逐句成本来自 CFM 前缀）/性能（本机是 U-DiT 非论文 Zipformer ⇒ 论文 RTF 不可引用；分段 profile 实测 **s2mel 占 45–73%** 而非 T2S，束宽在 MPS 上近乎免费）/16 项 ROI 排序路线图与迁移地雷。配套工具：[发音标注台账](../../media/pipeline/PRON-GLOSSARY.md)、[pron_marks.py](../../media/pipeline/scripts/pron_marks.py)（标注解析/校验，拦「孤立 < 吞正文」等三类静默失效）、[tts_bench.py](../../media/pipeline/scripts/tts_bench.py)（耗时基准与**测量环境体检**：漂移已定因为热节流，加 75s 冷却后 A/A 极差比 1.016–1.047× 合格；含成对 A/B 模式与 whisper 回转写判据）、[prospect_ref.py --accept](../../media/pipeline/scripts/prospect_ref.py)（参考样本保真度验收：削波/底噪/动态/带宽/超 15s）。
 - [自进化 Agents Team 方案（Phase 3 记忆检索面已落地）](../concepts/design/self-evolving-agents.md) — 四层自进化架构：本次落地 `engine/evolution/` 子系统（GEPA proposer + 状态机 + decision 护栏）并在记忆检索权重面接通 propose→shadow→canary→promote/rollback 全闭环（迁移 0081 + evolution_inspector），默认全关灰度；agent/skill/knowledge 面、Phase 1 tool_invocations 遥测、eval 四表留后续

media/experience-era-agents-video/script/narration.json

@@ -2,7 +2,7 @@
   {
     "id": "p0-01",
     "scene": "P0",
-    "text": "2025 年，强化学习领域两位泰斗，放出一篇宣言。"
+    "text": "2025年，强化学习领域两位泰斗，放出一篇宣言。"
   },
   {
     "id": "p0-02",
@@ -57,7 +57,7 @@
   {
     "id": "p0-11",
     "scene": "P0",
-    "text": "2026 年 6 月，清华联合一家 AI 公司，发了一篇 88 页的综述。"
+    "text": "2026年 6 月，清华联合一家 AI 公司，发了一篇 88 页的综述。"
   },
   {
     "id": "p0-12",

media/experience-era-agents-video/script/narration.md

@@ -10,7 +10,7 @@
 
 > 画面：黑场，衬线金句卡打字机逐字打出；英文原文渐显在下方。
 
-- [p0-01] 2025 年，强化学习领域两位泰斗，放出一篇宣言。
+- [p0-01] 2025年，强化学习领域两位泰斗，放出一篇宣言。
 - [p0-02] DeepMind 的大卫·希尔弗，和强化学习教父萨顿，联名放话：
 - [p0-02b] AI 的下一个时代，叫经验时代。
 - [p0-03] 未来 AI 的进步，不再主要来自人类喂的静态数据，
@@ -32,7 +32,7 @@
 
 > 画面：论文封面卡：标题 + 机构行（清华大学 × Frontis.AI）+「88 页综述」。
 
-- [p0-11] 2026 年 6 月，清华联合一家 AI 公司，发了一篇 88 页的综述。
+- [p0-11] 2026年 6 月，清华联合一家 AI 公司，发了一篇 88 页的综述。
 - [p0-12] 系统回答了这个问题：经验，到底怎么变成实力。
 - [p0-13] 这期视频，我们把它讲透。