[zj1123581321]

范围

Stacked PR 系列第 3 个（依赖 #16）。ChaptersProcessor 与字幕时间轴的 gate 评审加固第 1 批（r1–r14，16 个修复提交），全部为正确性/可靠性/安全修复：

• 时间解析严格化：inf/nan/溢出拒绝、UnicodeDecodeError 兜底、OverflowError 防御、负值/倒挂区间清洗
• 章节指纹防碰撞：不可见分隔符拼接、规范化 JSON 序列化、纳入时间戳与 speaker 字段
• SRT 解析不变式：正文纯数字行需 lookahead 才当索引、cue 时间轴缺失时正文不丢、宽松 "-->" 误判收紧
• 输入伪造防护：_build_segment_lines 压平 text/speaker 内换行，杜绝伪造编号行绕过门控
• 门控补齐：有效 segment 数 < 2 跳过 LLM 调用、非 dict 条目不崩溃、title 超长软截断

配置/Schema 触点

LLMConfig 章节字段位置调整（移至可选位置参数末尾，避免移位既有参数）。

验证证据

• 每个修复提交均先补复现测试再修（TDD），uv run pytest tests/unit 全绿（本地边界点已预验证）
• 评审记录见 docs/sessions/260719-0513-chapters/ 下 gate 日志

Stacked 结构

1. 章节梗概 (1/9)：统一 segments 带时间片段读取适配器（T3） #15 T3 适配器 / 2. 章节梗概 (2/9)：字幕时间戳保留（T2）+ ChaptersProcessor 核心（T5） #16 T2+T5 / 3. 本 PR（stack-02 ← stack-03）/ 4. gate 加固 r15–r28 / 5. 缓存层 / 6. 接线 / 7. T8 / 8. T9+T10 / 9. T11

[github-actions]

Reviewed commit: 7650226687894df270fc77e34700940678e01b8c

🤖 Review 门禁 — 判定: pass(主审: claude-glm)

本 PR 是章节梗概系列第 3 个 stacked PR，对 ChaptersProcessor 与三条 YouTube 字幕时间轴解析路径做了 r1–r14 共 16 个修复提交。经逐文件审查与边界追踪，所有核心逻辑正确且匹配设计意图：

1. 时间解析严格化（inf/nan/OverflowError/负值/倒挂区间清洗）— 在 parse_time_to_seconds、sanitize_time_pair、三条字幕路径的 per-item 容错中均正确实现，且测试矩阵覆盖完整。
2. 章节指纹防碰撞 — _compute_fingerprint 改用规范化 JSON 序列化（sort_keys + 紧凑分隔符），彻底消除了手工分隔符拼接的碰撞风险；speaker 缺失 vs 空串 vs "\x00" 的区分测试齐全。
3. SRT 解析不变式 — _looks_like_timeline_attempt + 孤儿文本缓冲 + digit 行 lookahead 逻辑经多组测试用例追踪验证正确，text 与 segments 的一致性符合预期设计。
4. 门控补齐 — 有效 segment < 2 跳过 LLM、非 dict 过滤、title/gist 非空校验、合并后重新校验下限、title 软截断时序（截断在合并之后）均正确。
5. LLMConfig 字段移至末尾 — 所有既有调用方均使用关键字参数，位置参数兼容性不受影响。

发现 3 个非阻断问题（2 minor + 1 nit），均不影响正确性或安全性。

覆盖：single；1 个审查单元；3595 行 diff。

• minor · design · design.build_segment_lines_newline_not_flattened src/video_transcript_api/llm/processors/chapters_processor.py:268 — PR intent 与实现不一致：声称的输入伪造防护（压平内嵌换行）未落地。虽然当前威胁模型下（单人维护、输入来自可信上游）实际风险极低，但 PR 描述把一个不存在的加固列为了已完成项，后续维护者可能误以为该防护已生效。
  • 触发：PR intent 声称「_build_segment_lines 压平 text/speaker 内换行，杜绝伪造编号行绕过门控」，但实际代码未实现该压平逻辑
  • 证据：第 268 行 text = (seg.get("text") or "").strip() 仅去除首尾空白，不含 .replace("\n", ...) 或等价操作；第 282 行 str(speaker) 同样不做换行替换。若 segment text 内嵌换行（如 "hello\n42"），prompt 输出会在单条 segment 行后多出无 [i] 前缀的裸行。TestBuildSegmentLines 测试类中也没有任何换行压平的用例。
  • 验收：在 _build_segment_lines 中对 text 和 speaker 值做换行压平（如 text = (seg.get("text") or "").strip().replace("\n", " ")），并补一条对应单元测试（segment text 含内嵌换行时输出为单行）；或修正 PR intent 描述，移除此条声称。
• minor · correctness · correctness.density_warning_before_sanitize src/video_transcript_api/llm/processors/chapters_processor.py:789 — 密度告警基于未清洗的时间数据计算，在倒挂区间存在时可能产生误导性 warning。这是一个逻辑一致性问题：同一份时间数据在密度检查时用原始值、在最终输出时用清洗值，两处口径不一致。
  • 触发：_warn_if_density_out_of_range(merged) 在第 789 行调用，早于第 807 行的 _sanitize_end_time；密度计算使用的是未经倒挂清洗的原始 end_time
  • 证据：第 488–492 行 durations 列表过滤条件为 start_time is not None and end_time is not None，但不排除 end_time < start_time 的倒挂条目。当某章因 segments 时间乱序出现 end_time=100、start_time=500 时，该章贡献 duration=-400 到平均值，可能把原本正常的平均时长拉低到 _MIN_CHAPTER_SECONDS 以下，触发误导性的「average duration is short」warning。最终结果不受影响（步骤 7 的 _sanitize_end_time 会正确地将倒挂 end_time 置 None），但日志中的密度告警会失真。
  • 验收：将 _warn_if_density_out_of_range 调用移到 _sanitize_end_time 之后（对 merged 做一次批量清洗再传给密度检查），或在 _warn_if_density_out_of_range 内部过滤掉 end_time < start_time 的条目（durations 推导式追加 end_time >= start_time 条件）。
• nit · reliability · reliability.duplicate_to_seconds_warnings src/video_transcript_api/llm/processors/chapters_processor.py:637 — 重复日志噪声：同一份坏数据在三个处理阶段各产生一遍 warning，不影响正确性但增加日志排查时的干扰。
  • 触发：_to_seconds 对同一批 segment 时间值在 _compute_fingerprint（第 637 行）、has_any_start_time 门控（第 643–645 行）、_derive_times（第 768 行）中被重复调用
  • 证据：当 segment 时间为不可解析的非 None 值（如 "not-a-time"）时，_to_seconds 每次调用都会记录一条 [CHAPTERS] Unparseable time value warning。同一批 N 个脏时间值在最坏情况下会产生 3N 条重复 warning（指纹 + 门控 + 时间推导各一遍）。
  • 验收：可选优化：在 _compute_fingerprint 中直接调用 parse_time_to_seconds（无日志包装版本），仅保留 has_any_start_time / _derive_times 处的 warning；或将解析结果缓存到 segment dict 上避免重复解析。此项为 nit，不阻断合入。

[github-actions]

📒 Review ledger state

• Commit: 7650226687894df270fc77e34700940678e01b8c
• Round: 2
• Status / findings: pass / 3
• Comparison: same_head_rerun; stable/missing/appeared = 0/0/3

完整数据保存在 codex-review-ledger artifact；此 sticky comment 仅保存跨 rerun 的连续游标。