章节层 start_seg 乱序排序归一化 + chapters_error 落盘（含未触碰层回填）

[zj1123581321]

背景

生产事故：BV1fcHD6cEw3（2026-10-10）章节层两次因「start_seg 序列非严格递增」语义校验失败整体判 FAILED，llm_chapters.json 未落盘，视图页无章节目录。主脑生产取证 + 双顾问咨询（claude-opus / codex，任务 vta-chapters-order-rootfix-20261015，报告归档于 agent-config consult 记录）后拍板根治方向。

改动

A. 排序归一化（llm/processors/chapters_processor.py）

• _validate_and_normalize_start_segs：去重后非严格递增从整体判 FAILED 改为按 start_seg 排序归一化；排序确实改变顺序时打 warning（含 moved 错位数 + LIS 长度，生产样本实测 moved 6/17、LIS 14/17）
• 规格变更声明：旧「乱序必须判 FAILED」语义有意废止（test_chapters_processor.py 原断言同步改写）。依据：数组排列顺序是 start_seg 取值集合的冗余表示；生产 dialogs 逐章核验确认乱序样本各章 gist 与排序后区间全部吻合（非主题回溯），原校验把可救数据判死
• 排序发生在 _derive_end_segs 之前（数组顺序隐含区间划分）；(title, gist, start_seg) 配对不变；已升序输入零行为变化
• 已否决并锁定（勿重开）：LIS 阈值/碎章否决（本事故样本即超阈值，且现有校验对顺序正常输出同样放行碎章）；prompt 强化（已在位且被模型违反）；/regenerate_chapters 端点（重提交同 URL 已可单层补跑）

B. chapters_error 落盘（cache_manager.py + llm_ops.py）

• save_llm_status 新增 chapters_error：None=不更新；chapters_status=="generated" 时强制 pop 旧 error（不变式锁单点，防 caller 误传）
• _save_llm_results 提取并按既有 final_* 回填模式传入：effective_chapters_status is not None 用本轮值，未触碰层（resummarize / generate_notes）回填 old_llm_status 旧值（write-ahead 撤销后磁盘已空，不回填会静默丢历史失败诊断）

验证

• 窄验证三文件 261 passed（主脑实测）；全量 make test 默认 TMP exit=0 零失败（主脑实测）
• 红验抽查：新增排序测试在 base 上 4/5 转红；chapters_error 契约测试红验 AssertionError 原文在执行器报告
• 独立 review（codex，H0 冻结 30466452..819b6f84）：结论继续，I1–I10 全过，failure-visibility: p2-only；唯一 P2（两个统计 helper 单调用方）判定接受不修（卡面 I4 强制 warning 统计，helper 是其最小实现，测试锁精确数值），verdict 见 docs/sessions/chapters-sort-261015/reviews/VideoTranscriptAPI-20261015-01-verdict.md
• OCR 前置扫描（主脑侧，deepseek 兜底腿）曾抓到 B 的回填缺口，已由修复轮 819b6f84 补齐并加契约测试

提交

• 9cfed705 章节层 start_seg 乱序改为排序归一化
• 4d0dbe70 chapters 失败原因落盘 llm_status.json
• d5445149 CHANGELOG 条目
• 819b6f84 chapters_error 层未触碰回填（review finding 修复）
• a449b6e7 独立 review verdict 归档

后续

• 部署 n305（docker pull_and_deploy）需用户授权，另行处理
• 深层模型观测（deepseek-v4-flash 空内容回退 gpt-4.1-mini 触发率）与本 PR 正交，另行立卡

已知取舍与跟进项（验收 consult 裁决）

• 取舍声明：乱序排序归一化用「失败可见」换「错了难见」——若模型乱序并非数组置换而是 start_seg 本身锚错，排序后会以 GENERATED 落盘、仅有一条 warning 日志。接受理由：章节是导航辅助不是数据本体，旧行为的代价是整份目录消失（本次生产事故即此形态）；生产样本逐章核验为置换型。后续 warning 统计（moved/LIS）就是为观察这类样本预留的仪表。
• 已知边角（跟进卡）：章节层被触碰但结果为 skipped_*/disabled 的轮次，旧 chapters_error 会按「None=不更新」语义与新状态共存（过期诊断）。该字段仅存在于 llm_status.json 供人工排障，API/页面零引用（已 grep 核实），不阻塞合并；跟进修复方向：cache_manager 对非 failed 的非 None 新状态统一 pop 旧 error。
• 独立 review 唯一 P2（两个统计 helper 单调用方）：接受不修，理由见 verdict 与 PR 正文。

Gate primary finding 处置对照表（run 38049989670）

工具标注	本仓判定	P1 两问（personal 档）
major / compatibility-positional-parameter-shift（chapters_error 中段插参，假想位置调用方错位绑定 notes_status/artifact_provenance）	事实成立但非现行缺陷：AST 全仓核查 60 个调用点 0 个位置传参到达该槽位（生产方 **status_updates 关键字解包）；按仓内「内部签名只许尾部追加」演进惯例（llm/core/config.py 同款纪律）仍属应守规约	Q1 触发：现存调用方式下不会触发；Q2 后果：假想未来调用方才有影响 → 非 P1，判 P2 形态类
处置	已修：chapters_error 移至签名尾部（append-only），零行为变更（全关键字传参），commit 见 PR head

[github-actions]

Required Gate v2 — 状态面板

当前状态：pass · 可合并

当前裁决：code_pass / primary_pass

PR 累计主审轮（影子）：2/5 · collecting

Gate 历史（v1；来源为持久化 gate_terminal 制品）

Run	Attempt	Head	状态	PR 累计主审轮（影子）	收件人动作
38049989670	1	a449b6e	fail	—	要修代码
38051657840	1	0e957bb	pass	2/5 · collecting	可合并

历史行按 run_id + run_attempt 去重并只增不删；删除本评论后可由 gate_terminal 制品重建。