Skip to content

v0.7.5.md

Latest commit

 

History

History
86 lines (68 loc) · 12.5 KB

v0.7.5.md

File metadata and controls

86 lines (68 loc) · 12.5 KB
Raw

v0.7.5 — 会话转笔记规则净化优化 + 停止状态残留修复

状态: 已实施（REQ-162173 净化批次 + REQ-174176 停止残留修复全部落地；REQ-174176 于 0834b38 先行完成，净化批次于 2026-08-20 完成） 目标: 会话→笔记产出质量跃升——口语净化/口头禅删除/结巴折叠接入笔记管线，视频页 UI 垃圾/单字符碎片/OCR 错字净化画面要点，产物加时间锚点与规则版本元数据，黄金语料回归；同时根治"停止采集后仍显示采集中"的会话状态残留（会话31 实证：status=failed + ended_at 有值 = 线程未走完 finish_session，重启兜底翻案） 关联: 头脑风暴 会话转笔记规则优化（[ ] 已归档） · v0.7.3 版本文档（屏卡体系——本版消费其 bbox/screen_id 落库）· 需求池 REQ-162176 触发: 会话31（B站"项目从立项到交付全流程"讲座，14.5min/172 段 ASR/215 块 OCR）转笔记实证——口头禅/UI 垃圾/零跨度屏/重复图/无时间锚点/无规则版本；同日用户反馈"停止采集后会话长时间显示采集中"

一、阶段目标

  1. 转写净化接线（REQ-162~165）：verbal_normalize/symbol_normalize 从"仅实时路径"接入笔记管线；口头禅短段规则级删除（免 AI）；结巴/叠字折叠 + 术语替换；段落时间戳锚点 [MM:SS]
  2. OCR 画面净化（REQ-166~168）：视频页 UI 垃圾类别（VideoPageUi）+ 数字量词模式 + 边缘条带 bbox 黑名单；单字符碎片丢弃 + 低分阈值校准；OCR 错字纠错（glossary 复用 + 转写共现校验）
  3. 产物与体验（REQ-169~170）：屏零跨度修复 + 重复图去重；失败/异常会话转笔记警示（诚实降级）
  4. 规则工程（REQ-171~173）：笔记规则版本化元数据（rule_version + 净化统计）；会话→笔记黄金语料回归集；净化阈值配置化
  5. 停止状态残留根治（REQ-174~176）：audio.stop() join 超时保护（注释承诺兑现）；前端全局采集徽标拉取兜底；DB 残留 recording 会话兜底标记——会话31 的 status=failed 不再需要重启才能"翻案"

二、范围（需求追溯）

REQ 内容 验收要点 规划状态
REQ-162 口语净化接入笔记管线：filter_note 段循环接 verbal_normalize（保守档）+ symbol_normalize 会话31 重跑「对不对？/啊/呃/就是/大家知道吗」大幅减少；原料层不动（可逆） 已排期
REQ-163 口头禅短段规则级删除：≤8 字且全由口头禅词组成 → 直接删（免 AI） 段 1018「对不对？」不再进笔记；正常短句（"对"回应语义）不误杀 已排期
REQ-164 ASR 结巴/叠字折叠 + 术语替换：「甲甲甲」→「甲」、「项目班」→「项目班子」 白名单保护合法叠词（慢慢/常常/好好）；glossary 替换可逆 已排期
REQ-165 讲述内容段落时间戳锚点：[MM:SS] 前缀（段首 start_ms） 每段可回跳原视频位置；可开关 已排期
REQ-166 视频页 UI 垃圾过滤：VideoPageUi 类别（简介/评论/点赞/收藏/投币/观看数/标签/作者/推荐卡片/二维码/展开）+ 数字量词短串 + 边缘条带 bbox 会话31 的「清晖加油站/若凡娃娃/1.3万0/qh202522」不进画面要点；正文数字不误杀 已排期
REQ-167 单字符碎片块丢弃 + MIN_BLOCK_SCORE 校准：0.5→0.7（配回归验证） X/?/o/不/三 消失；低分真内容不误删 已排期
REQ-168 OCR 错字纠错：glossary 复用 + 转写共现校验 「項灣」→「项目」类可纠；无映射不猜（保守） 已排期
REQ-169 屏零跨度修复 + 重复图去重：first=last 并入相邻屏；相同图只留首个屏引用（frame_cluster 复用） 会话31 画面 1~5 零区间消失；569515.webp 三屏重复 → 一屏 已排期
REQ-170 失败/异常会话转笔记警示：status != finished → 笔记追加 > ⚠️ 会话异常（status），内容可能不完整 会话31 重转笔记带警示行；可手动删除 已排期
REQ-171 规则版本化元数据：notes 加 rule_version + purify_stats（JSON 净化统计）落库；旧笔记 NULL 诚实降级 笔记可回答"用哪版规则生成"；预览统计与落库一致 已排期
REQ-172 黄金语料回归集：会话31/29 原始素材 → 期望笔记夹具（note_filter_tests 扩展） 新增规则先写失败测试再实现（TDD）；全量回归一键跑 已排期
REQ-173 净化阈值配置化：120字/60s/0.5/0.6 集中常量 + JSON 校准（ui_junk.json 先例） 现场调参无需改码 已排期
REQ-174 停止链路超时保护：audio_loopback::stop() join 加 2s 超时（超时 detach 不阻塞） WASAPI GetBuffer 卡死时停止命令仍返回；会话线程不永久卡死 已排期
REQ-175 前端全局采集徽标拉取兜底：App.tsx 监听 session:fusing（融合开始=采集已停）+ 停止 invoke 成功后 live_session_status 确认 停止后徽标 ≤2s 清除，不依赖 live:status 事件到达 已排期
REQ-176 DB 残留 recording 会话兜底标记：list_sessions 发现 recording 但 manager 无活动线程 → 自动标 failed（复用 mark_interrupted_sessions 语义，无需重启） 会话31 类残留下次列表拉取即翻案；进行中会话不误标 已排期

三、关键设计决策

  1. 净化可逆优先（延续 REQ-081/082 单一管线双出口）：所有净化/纠错/删除只作用于产物层（kept/filtered/merged 记录），原料 segments/ocr_blocks 表不动；被滤内容带原因/时间进 filtered 供预览对照复查。
  2. 净化顺序：UI 垃圾 → 碎片 → 低置信（既有五步链）→ 口语净化 + 结巴折叠 → Filler-only 删除 → 相邻重复合并（净化后文本才做精确去重）。净化发生在 AI 三态判定（REQ-085）之前——规则层先净，AI 只判边界。
  3. 接线优先于新建（头脑风暴决策 4）：A1 复用 verbal_normalize/symbol_normalize（已有代码）、B1 扩充 ui_junk 黑名单机制、B3 复用 glossary——新代码量集中在 D2/E1/E2/E3。
  4. OCR 净化保守原则：单字符丢弃需"非公式/表格上下文"豁免（region_kind 保护）；数字量词正则 ^[\d.]+万?$ 仅匹配独立短串（防误杀正文数字）；阈值 0.5→0.7 必须跑黄金语料回归验证不误杀。
  5. 停止残留修复三件套（会话31 实证驱动）：
    • R1：audio_loopback::stop() 从裸 handle.join() 改为 is_finished() 轮询 + 2s 超时 detach——兑现模块注释"join 超时保护"的承诺（原实现注释与代码不符）。
    • R2：前端全局徽标不再单一依赖 live:status 事件——session:fusing 到达即视为采集已停（融合开始 = 采集已停的天然信号），停止 invoke 成功后再拉 live_session_status 确认兜底。
    • R3：list_sessions 装配层检测"status=recording 但 manager 无活动会话"→ 调用 mark_interrupted_sessions 语义的单会话版（标 failed + ended_at），避免必须重启应用才翻案。
  6. 元数据兼容：notes 加列用 ensure_column 幂等迁移（ADR-014 先例）；旧笔记 rule_version/purify_stats 为 NULL 不猜不填（诚实降级）。
  7. 标题：沿用会话标题 +「（会话）」后缀（标题优化 E4 留后续，低价值）。

四、测试与验证

  • Rust 单测（TDD，先失败后实现）：
    • verbal_normalize 接入回归（filter_note 输出断言）；is_filler_only 边界（口头禅/正常短句/数字）；fold_stutter 白名单矩阵（慢慢/常常不折叠，甲甲甲→甲）；OCR 词表命中与正文不误杀；数字量词正则边界（"3.14"不误杀、"1.3万"命中）；单字符豁免（公式上下文）；边缘条带 bbox；屏零跨度合并/图去重；警示行生成；notes 迁移加列旧库兼容；REQ-174 join 超时（注入假 handle 模拟不退出线程）；REQ-176 单会话残留标记（recording 无活动 → failed；recording 有活动 → 不动）
    • 黄金语料回归（REQ-172）：会话31 样本段/块 → 期望净化输出断言；会话29 直播 UI 样本 → 期望过滤断言
  • 前端：npm run build 通过；全局徽标兜底（fusing 到达清徽标；停止后拉取确认）
  • 真机手动验证清单（实施完成后执行）：
    1. 会话31 重跑转笔记：口头禅/视频页垃圾/单字符块消失，段落带 [MM:SS]，无零跨度/重复图，元数据带 rule_version，预览过滤统计与落库一致
    2. 停止采集（正常场景）：UI ≤2s 恢复非采集态，会话列表状态正确
    3. 停止采集（异常场景模拟：音频设备异常时点停止）：停止按钮即时响应，会话最终被标记 failed 或 finished，不出现"采集中"长残留
    4. 旧笔记（无 rule_version）：正常展示不报错（NULL 降级）
    5. 回归底线：现有 1053+ 单测全绿 + clippy 新代码零警告 + 前端构建通过

五、文件清单（实施完成，与实际一致）

Rust 新增：stutter_fold.rs（REQ-164 结巴折叠+术语替换）· purify_config.rs（REQ-173 阈值配置）· ocr_correction.rs（REQ-168 错字纠错+共现）· note_filter_ai.rs（REQ-085 AI 层拆分——line-limit 登记计划）· app_setup.rs（lib.rs >600 硬拆——登记计划）

Rust 修改：note_filter.rs（净化链接线/口头禅删除/锚点/警示/统计——REQ-162/163/165/170/171）· note_filter_golden_tests.rs（REQ-172 黄金语料回归：会话31/29 样本）· screens.rs（可消费块过滤扩展：单字符/边缘条带/视频页共现/错字纠错——REQ-166/167/168）· screen_merge.rs（净化与屏修复纯函数：零跨度合并/图去重/包含率——REQ-169）· ui_junk.rs（VideoPageUi 类别+数字量词+QR——REQ-166）· concat.rs（锚点段落+可配置阈值——REQ-165/173）· types.rs/db.rs（notes 加 rule_version/purify_stats 列——REQ-171）· commands_session.rs/commands_ai.rs（净化配置接线+警示行+元数据落库——REQ-170/171/173）· commands.rs/lib.rs（AppState 装配 purify/ocr_corrections）

前端：types.ts（FilterStats/Note/FilteredItem 新字段）· NotePreviewView.tsx（口头禅统计/警示行渲染/净化计数卡）· App.tsx（REQ-175 已在 0834b38）

六、后续批次（本版本不做）

  • 结构组织（用户裁决暂不实施，与 v0.8.0 AI 精修 REQ-141 衔接）：章节/TOC、摘要/结论、要点/行动项、术语表入笔记、讲述↔画面时间对齐内联、语义切段
  • E4 标题优化（低价值）
  • 持久元素自学习（v0.7.3 第二波，OCR 净化升级依赖）
  • AI 纠错（A3 云端部分）/ AI 精修（v0.8.0 REQ-141）

七、增补（2026-08-20 讨论落地）：过渡句/修辞问句净化

触发：用户反馈会话31 净化输出「讲我们具体的工具了。…过程是什么？」两处无价值——探讨后裁决：形式特征明显的废话本地规则化，语义级留给 AI。

  • 纯过渡短句规则删除：note_filter_discourse.rs 精确表（整句去标点后 ∈ {接下来/我们来看/首先/总之/好吧…} 且 ≤8 字才删）——零误杀低召回；「接下来我们看第三章」（含章节内容）、「讲我们具体的工具了」（带话题预告）不删（宁漏勿误，filtered 可复查）
  • 修辞问句规则删除：自问自答判定——问句（≤15 字、问号/疑问词结尾）的核心词（去疑问词后最长 CJK 段）在紧邻下一段复现 → 删问句（信息由答案段承载）；「过程是什么？」+「这个过程是制定项目章程」实证命中；开放问题（「大家思考一下为什么？」）、答案不紧邻、疑问过泛（「为什么？」无核心词）保留
  • 过滤链顺序微调：过渡检查先于碎片检查（表内 2 字短语以"过渡"原因删除，原因标签语义准确）；口头禅/碎片/过渡均基于原文判定，净化残留检查后置
  • 配置：purify_config.json 可校准 transitionDelete/transitionMaxChars/rhetoricalDelete/rhetoricalMaxChars
  • 统计：FilterStats.transition/rhetorical 落库 purify_stats；前端统计卡与对照标签新增「过渡/反问」
  • 边界（诚实注释）：带话题过渡句与真问题（核心问题）本地不删——语义判断留给 v0.8.0 AI 精修 REQ-141 与结构组织批次（问答折叠）