ADR-023-video-ocr-offline-vision-extract.md

ADR-023: 视频会话 OCR 下线 + AI 精修图片理解（vision-exp）

状态

已接受（v0.12.0 M5，2026-08-23 用户裁决；已实施交付——精修侧 + 帧侧均落地；v0.12.4 补齐残留：直播/导入两条 region OCR 分支已删，展示层按 kind 分派纯图屏，真机验证待执行）

日期

2026-08-23

背景

本地 PaddleOCR 对视频全帧画面要点提取质量差（动态模糊/复杂版面/小字/干扰物）——同一引擎在字幕/图文场景效果好（质量债）。且图片上传是最敏感的隐私动作，需独立授权闸门。

决策

• 本地 OCR 只做字幕（视频）+ 图文采集（photo 会话）——视频会话不再做全帧 OCR。
• 关键帧纯图（存图不识别）；存图触发从"OCR 文本非空"解耦为"grid diff 变化 + 时间间隔"。
• vision-exp 图片理解（可选增强，仅视频会话，并入 AI 精修）：不做独立提取命令——精修时若 vision_refine_enabled 开启，屏卡图随转写文本一并送 deepseek-v4-flash-vision-exp（content 数组多模态），精修输出直接含画面要点；屏卡缩略图走现有 attach_images。
• 图文会话 OCR 已足够，不启用 vision（用户决策：仅视频会话使用）。
• 图片精修可选性：vision_refine_enabled 开关（默认关）——图片上传最敏感，独立闸门；关闭则精修纯文本（现有行为零变化）。
• AI 强化链条总开关：复用现有 AiSettings.enabled（全局闸门，默认关）——关闭则采集期领域识别/AI 复核/精修/补充全部拒绝（已有 content_gate 门控）。

隐私红线（ADR-010 扩展）：图片上传默认关（vision_refine_enabled 默认 false + 全局 enabled 默认关）；关闭时精修走纯文本（零变化）；图片仅随精修切片请求上传，不作独立提取。

备选方案

方案 A：保留视频全帧本地 OCR，仅调参增强

• 优点：无架构改动。
• 缺点：本地 OCR 在动态模糊/复杂版面根本性不可靠——调参治标不治本，且维持全帧 OCR 的算力/成本。

方案 B：视频全帧 OCR 下线 + vision-exp 精修图片理解（选定）

• 优点：质量债根治（关键帧纯图，不识别）；画面要点经 vision-exp 高质量提取并并入精修；图片上传独立闸门 + 默认关，隐私可控。
• 缺点：画面要点提取依赖云端 vision（需授权 + 有条件）；离线降级 = 无画面要点（纯图存证）。
• 适用场景：视频会话以转写为主体，画面要点为增强。

选择理由

本地 OCR 质量差的根因是引擎对视频全帧的鲁棒性不足——降级为"只做字幕/图文采集"规避该根因。画面要点本属增强，交给 vision-exp 高质量提取并在精修时随切片上云，同时以独立闸门 + 默认关满足图片隐私红线。

影响

正面影响

• 视频会话不再产生低质全帧 OCR；画面要点提取质量提升（vision-exp）；图片上传可控。

负面影响 / 代价

• 关闭开关时视频会话精修无画面要点（纯文本）；图片随精修上云需用户授权（默认关）。

风险

• vision-exp 画面要点抽取质量依赖云端模型（未实测校准）；需真机验证采集端改动（video 会话不再 OCR 全帧）。

合规性验证

• 视频会话关键帧纯图（无 OCR 文字）；开启图片开关后精修请求含屏卡图、输出含画面要点；关闭开关精修纯文本零变化；图文会话不受影响；enabled=false 时精修命令拒绝。

相关决策

• ADR-010: AI gap-filling 隐私契约（本 ADR 扩展图片授权）
• ADR-011: grid diff OCR 触发

参考

• docs/versions/v0.12.0.md（视频画面要点降级 + vision 提取 M5）