docs(asr): v0.20 立项（ADR-030）+ ASR 实现口径修订

Author: Aparencia

AGENTS.md

@@ -25,7 +25,7 @@
 |----|------|------|
 | 桌面壳 | **Tauri 2 + React + TypeScript** | 替代原项目 Electron |
 | 后端/系统层 | **Rust** | Tauri 主进程 |
-| 本地 ASR | **sherpa-onnx crate** | 流式 Zipformer + Silero VAD + SenseVoice 两遍解码 + hotwords |
+| 本地 ASR | **sherpa-onnx crate** | 流式 Zipformer（zh 2025-06 fp16）+ 能量自适应 VAD + SenseVoice 重打分/导入全窗两遍 + hotwords（实现口径 2026-09-03 修订，ADR-030；Silero VAD 未接线） |
 | 本地 OCR | **paddle-ocr-rs（PaddleOCR PP-OCRv5/v6 ONNX）** | 关键帧文字检测+识别 |
 | 本地数据库 | **SQLite**（rusqlite / sqlx） | 音频/转写/笔记/卡片全本地 |
 | AI 笔记增强 | 云端多模态（Qwen-VL 系），**不用 Ollama** | 增量+课后精修，离线降级本地拼接 |

docs/adr/ADR-003-streaming-asr-architecture.md

@@ -4,6 +4,8 @@
 
 已接受（Accepted，2026-08-18）
 
+> 修订注记（2026-09-03，依据 ADR-030）：§决策 4 的 Silero VAD **未接线**——实际实现为能量自适应 VAD（`vad_adaptive.rs` + sherpa 端点规则，含 hangover/隔块喂入）；§决策 5 的"两遍解码"实现口径 = 实时会话端点句 SenseVoice 重打分（3s 有界、一致性校验）＋ 文件导入全窗两遍。原文保留作历史，实施口径以 ADR-030 为准。
+
 ## 日期
 
 2026-08-18

docs/adr/ADR-030-asr-quality-batch.md

@@ -0,0 +1,46 @@
+# ADR-030：ASR 质量增强批——自验证路线 + 参数治理 + 全量精修 + 混淆画像闭环
+
+> 状态：**已接受**（2026-09-03，用户裁决 C：P0~P2 全批立项，v0.20 系列）
+> 关联：[asr-optimization-plan（决策稿）](../Foresight/asr-optimization-plan.md) · [ADR-003](./ADR-003-streaming-asr-architecture.md)（本 ADR 修订其 §决策 4/5 口径）· [ADR-012](./ADR-012-streaming-asr-quality-fixes.md) · REQ-263~270（已登记）· [v0.20 版本文档](../versions/v0.20.md) · [v0.19 检索与发现层设计](../superpowers/specs/2026-09-03-v0.19-rag-retrieval-discovery-design.md)（转写文本质量互依）
+
+## 背景
+
+repowiki（.qoder/repowiki/zh/content，2026-09-03 生成）+ 代码互证盘点发现：① 纯 ASR 保真度 90% 为未实测经验值，多批"真机验收待执行"；② VAD/端点/重打分/融合/去重阈值全员经验化、多处文档自注"需实测校准"；③ 实时会话只有端点句 SenseVoice 重打分（3s 有界），导入才是全窗两遍——缺"会话级全量精修"档；④ 术语/专名错（同音）是笔记资产污染主因，ASR 侧无 OCR 那样的混淆画像闭环；⑤ 文档/实现落差三例（Silero VAD 零代码引用、GPU 决策仅属 OCR、DTW 漂移校正未接线）。用户裁决：人工真机验证几乎不可能 → 验证必须**代码自验证**；按 C 范围立项 P0~P2。
+
+## 决策
+
+1. **自验证路线（验证主纲）**：新增 `bin/asr_eval` harness——批量样本（音频/视频+参考）→ 转写（流式/离线、参数矩阵、预处理开关）→ dtw_align 对齐 → cer.rs 计 CER → 同音错对画像 → A/B 对比表 → 回归退出码；有参考样本沉淀 fixtures + CI 回归。
+2. **参考信道策略**：外挂/内嵌字幕轨（~100%）> 字幕 OCR 多帧投票（~99%）> 会话内字幕段；**无参考素材不进 CER 评测**（只做稳定性/画像/回归）。结论只作相对对比与回归，不宣称绝对指标。
+3. **DTW 漂移校正接线**：`dtw_align.rs` 纯函数+测试已备但无生产调用点 → 接入字幕融合入口 + 漂移估计分布统计（无人工观测依赖）。
+4. **参数治理**：阈值族（VAD 预热/窗口/倍率、端点 rule1/2/3、重打分门限、融合 gap/SIM/权重、去重阈值）集中**配置化/档案化**（JSON 校准与 audio_preproc_config 先例）；经 asr_eval 自动 A/B 标定后定默认并持久化；预处理链（默认关）默认定案以数据支撑（REQ-101 口径延续）。
+5. **会话全量离线精修档**：会话结束用 S4 落盘音频全量 SenseVoice 第二遍 → 段级 diff → 预览**采纳/回退**；原料层不可变（可逆契约延续），替换段标记来源与置信。
+6. **混淆画像闭环**：ASR 同音错对画像（以参考文本对齐统计）→ 候选纠错表（**共现才替换**、确认制——OCR ocr_confusion 机制迁移）→ 反哺 hotwords；全部 JSON 可校准、golden 防误删。
+7. **可选 LLM 文本校对**：建议制逐句（非直改），content_gate 双闸门**默认关** + 成本审计；**仅文本上云，语音不出本机红线维持**；失败/离线降级规则路径。
+8. **换芯门控**：同 crate 换模型（sherpa-onnx 生态内）经 asr_eval 同评测集裁决（CER×延迟×体积×热词支持）；跨运行时（FunASR/FireRed/Qwen3 系）与语音上云需**另行 ADR + 用户授权决策**，默认不做。
+9. **规范口径修订（规范先行）**：ADR-003 §决策 4/5 与 AGENTS.md 技术栈行更新为实现口径——VAD 为**能量自适应**（vad_adaptive.rs，Silero 未接线）、"两遍解码"实现语义 = 实时端点句重打分/导入全窗；GPU 设备决策仅属 OCR（wiki 混写案例不入规范）。
+
+## 备选（否决）
+
+- **人工语料/真机验证基线**：用户裁决不可行（无人工转写与真机走查条件）——验证主纲改自验证。
+- **直接跨运行时换芯**（FunASR 服务/FireRedASR/Qwen3-ASR）：无自测证据 + 服务形态/GPU 与本地单机架构冲突；精度收益（公开口径 2.9~3.8% 级）需产品场景裁决——门控为决策 8。
+- **无治理的参数乱调**：阈值全量进代码常量→无法 A/B 与回退——配置化/档案化先行。
+- **LLM 校对直改产物文本**：破坏"人类裁决+可逆契约"——建议制（决策 7）。
+- **语音上云高精度档**：隐私红线（学习数据不出本机）——默认不做，需独立授权+ADR。
+
+## 影响
+
+- 正向：验证尺子落地（后续所有 ASR 改动可自动回归）；参数族首次有数据支撑的默认值；实时会话获得导入同级的离线质量档；术语/专名错误有自动发现与修正闭环；文档口径收敛。
+- 代价：asr_eval 与 fixtures 为新增开发面；全量精修命令与采纳/回退 UX；配置化迁移涉及既有常量与 env 入口（向后兼容：默认值不变则零行为漂移）；AGENTS/ADR-003 修订记录。
+- 风险：字幕参考误差稀释 CER 精度（只作相对结论）；画像纠错误改（共现+确认制防御）；全量精修 CPU 峰值（后台任务+可取消）。
+
+## 合规性验证
+
+- asr_eval 回归退出码挂 CI；fixtures goldens 全绿（cargo test）；每批产出 A/B 结论页（预处理默认/VAD/端点/融合/去重）；精修采纳流单测（原料不可变断言）；画像闭环单测（共现才替换、确认制）；content_gate 默认关路径测试；全量回归（cargo test/clippy/vitest/tsc）。
+
+## 相关决策
+
+- ADR-003（本 ADR 修订其 §4/5 实现口径）· ADR-012（流式质量修复——重打分/端点规则基调）· ADR-010（AI 增强层·文本上云契约）· REQ-041/068/101（预处理/音频落盘/CER 微基准）
+
+## 参考
+
+- [asr-optimization-plan（决策稿，含证据分级与待核查清单）](../Foresight/asr-optimization-plan.md) · v0.20 版本文档 · repowiki 相关页面（溯源见方案附 A/B）

docs/adr/README.md

@@ -33,6 +33,7 @@
 | ADR-027 | [学习目标层建模——意图层对象（N:M / 判据配方 / 四态状态机 / 库即记忆）](./ADR-027-goal-layer-modeling.md) | 已接受（v0.18.0 M1） | 2026-09-02 |
 | ADR-028 | [AI 目标规划师——建议制规划 + 体系深度联动](./ADR-028-ai-goal-planner.md) | 已接受（v0.18.2） | 2026-09-02 |
 | ADR-029 | [检索与发现层（RAG 接层）——派生索引 + 双读路径 + 人工裁决闸门](./ADR-029-rag-retrieval-discovery-layer.md) | 已接受（v0.19 系列） | 2026-09-03 |
+| ADR-030 | [ASR 质量增强批——自验证路线 + 参数治理 + 全量精修 + 混淆画像闭环](./ADR-030-asr-quality-batch.md) | 已接受（v0.20 系列） | 2026-09-03 |
 
 ## 编号规则
 

docs/versions/v0.20.md

@@ -0,0 +1,33 @@
+# v0.20：ASR 质量增强系列（自验证路线 · P0~P2）
+
+> 状态：**系列文档（2026-09-03 用户裁决 C 立项，待实施）**
+> 依据：repowiki（.qoder/repowiki）盘点 + 代码互证 + 最新技术对标（[asr-optimization-plan 决策稿](../Foresight/asr-optimization-plan.md)）；用户裁决：① 人工验证不可行 → **验证一律代码自验证** ② 立项范围 C（P0~P2）
+> 关联：[ADR-030](../adr/ADR-030-asr-quality-batch.md)（已接受）· ADR-003/012 · REQ-263~270 · v0.19 检索层（同受转写质量影响）
+
+## 一句话
+
+给 ASR 链路装上"能自测的尺子 + 有数据的默认值 + 导入同级的离线质量档 + 自动发现术语错闭环"：新增 `bin/asr_eval` 自验证 harness（字幕信道做内置参考 → CER/混淆画像/A-B 矩阵/CI 回归门），随后用同一把尺子完成参数族定案（预处理默认/VAD/端点/融合/去重）、DTW 漂移校正接线、热词加固与注入扩展、实时会话全量离线精修（采纳/回退）、ASR 同音混淆画像→纠错/热词闭环，以及可选的 LLM 文本校对（建议制·默认关·语音不出本机）。
+
+## 自验证路线（本系列主纲，ADR-030 决策 1/2）
+
+- **参考信道**：外挂/内嵌字幕轨（~100%）> 字幕 OCR 多帧投票（~99%）> 会话内字幕段；无参考素材不进 CER（只做稳定性/画像/回归）。
+- **harness** `bin/asr_eval`：批量样本 → 转写（流式/离线、参数矩阵、预处理开关）→ dtw_align 对齐 → cer.rs CER → 同音错对画像 → A/B 对比表 → 回归退出码（CI）。
+- fixtures 固化首批有参考样本；**结论只作相对对比与回归**，不宣称绝对指标。
+
+## 批次与 REQ 映射
+
+| 版本 | 批 | 内容 | REQ |
+|---|---|---|---|
+| v0.20.0 | P0 | asr_eval harness + 参考信道策略 + fixtures/CI 回归 + 首轮自测报告（含漂移分布）；规范口径修订（AGENTS/ADR-003，Silero 未接线留痕） | REQ-263 |
+| v0.20.1 | P1 | DTW 漂移校正生产接线；参数定案族（预处理默认定案 + VAD/端点/重打分/融合/去重阈值 A/B 标定 + 配置化/档案化）；热词加固与注入源扩展；重打分积压验证与 drain | REQ-264~267 |
+| v0.20.2 | P2 | 会话全量离线精修（S4 全量第二遍 + 段级 diff + 采纳/回退）；ASR 混淆画像→纠错/热词闭环（共现才替换·确认制）；可选 LLM 文本校对（建议制·默认关·仅文本上云） | REQ-268~270 |
+
+## 验收门槛（全部代码自验证）
+
+- harness 回归退出码挂 CI；fixtures goldens 全绿（cargo test）；每批产出 A/B 结论页；
+- 精修采纳流单测（原料不可变断言）；画像闭环单测（共现才替换/确认制）；content_gate 默认关路径测试；
+- 全量回归：cargo test / clippy / vitest / tsc。
+
+## 边界（红线延续）
+
+原料层（session_segments 原文）永不可变；模型文件不入库/下载走既有镜像与本地归档；**语音不出本机**（文本级 AI 走 content_gate 双闸门默认关 + 审计）；跨运行时换芯（FunASR/FireRed/Qwen3 系）与语音上云需另行 ADR + 用户授权（ADR-030 决策 8）。