Skip to content

v0.7.3.md

Latest commit

 

History

History
66 lines (50 loc) · 9.02 KB

v0.7.3.md

File metadata and controls

66 lines (50 loc) · 9.02 KB
Raw

v0.7.3 — 画面要点屏卡体系（OCR 碎片化治理 + 屏级组织 + 结构识别接线）

状态: 开发中（2026-08-20 头脑风暴裁决完成；M1-M5 代码建设已提交——屏聚合纯函数/落库/在线屏分配/消费端/结构接线，1053 单测全绿；真机验收待执行） 目标: 画面要点从"块流"升级为"屏卡"——屏级时间区间（00:02–03:23）+ 屏内版面组织（标题/正文/图注标签）+ 采集治理（前台过滤/平台 UI 黑名单）+ 结构识别接线（表格/公式/代码） 关联: 头脑风暴 OCR 屏卡体系（[ ] 已归档） · ADR-015（架构决策）· 需求池（REQ-155~161） 触发: 用户反馈"画面要点（OCR）提取的内容零碎（时间整理和识别内容）"；会话29 实证（175 块 OCR / 12 时间戳重复 / 平台 UI+其他窗口污染 / 无 bbox 落库）

一、阶段目标

  1. 屏级聚合与去重（REQ-155）：screen_merge 纯函数（normalize/similarity/cluster/line_merge/classify_roles）+ 在线 ScreenTracker（版面指纹变化=新屏，layout_cache 复用）+ 旧数据聚类兜底——175 块 → ~7 屏
  2. bbox/screen_id 落库（REQ-156）：session_ocr_blocks 加列（ensure_column 幂等），实时/导入双入口双写
  3. 采集治理（REQ-157）：前台窗口过滤扩展全帧（foreground_foreign 复用，REQ-084 先例）+ ui_junk 直播互动元素扩充——根治平台 UI/IDE 污染
  4. 屏内组织（REQ-158）：line_merge 断行拼接（治 det 切半句）+ classify_roles 版面角色 + SessionScreen 契约
  5. 结构识别接线（REQ-159）：refine_screen_structures 复用 commands_refine_inner（REQ-049/050 内核不动）+ 停止后批量精修 + 屏卡 Markdown/LaTeX/代码渲染
  6. 消费端（REQ-160/161）：原料屏卡流 + 笔记屏段落配图 + 大纲/检索按屏 + 实时面板按屏摘要

二、范围（需求追溯）

REQ 内容 验收要点 规划状态
REQ-155 屏级聚合与去重：screen_merge 纯函数 + ScreenTracker 在线屏 + 旧数据聚类兜底 在线/离线共用同一套纯函数（单管线双出口）；翻回旧页间隔>3s=新屏；截断变体合并 已排期
REQ-156 bbox/screen_id 落库迁移：session_ocr_blocks 加列 + 实时/导入双入口双写 加列幂等；旧库只读兼容；bbox JSON {x,y,w,h} 帧坐标系（TD-046 反算复用） 已排期
REQ-157 采集治理：前台窗口过滤扩展全帧 + ui_junk 直播互动元素扩充 前台≠目标窗口期间画面要点不落库；1人正在看/发送/X/频道名/logo 乱码不进屏卡 已排期
REQ-158 屏内组织：line_merge 断行拼接 + classify_roles 版面角色 + SessionScreen 契约 会话29 断行合并成完整句；标题/正文/标签分类正确；region_kind 结构块不参与行合并 已排期
REQ-159 结构识别接线：refine_screen_structures + 停止后批量精修 + 屏卡渲染 表格→Markdown/公式→LaTeX/代码→等宽块；模型缺失降级徽标；内核零改动 已排期
REQ-160 消费端：SessionDetail.screens + 原料屏卡流 + 笔记屏段落配图 + 大纲/检索按屏 屏卡可展开块级明细复查（可逆）；笔记配图 asset:// 可开关；旧数据降级聚类屏 已排期
REQ-161 实时面板按屏显示：live:ocr 带 screen_id 最近画面要点一行=一屏摘要（区间+标题） 已排期

三、关键设计决策

  1. 屏 = 派生视图而非新表：屏 first/last_seen/成员块 = GROUP BY screen_id 聚合；旧数据（screen_id NULL）走 cluster_blocks_into_screens 聚类兜底——零冗余、可逆（ADR-006 派生视图传统，ADR-015 决策 2）。
  2. 在线/离线共用纯函数：screen_merge.rs（normalize/screen_similarity/cluster_blocks_into_screens/line_merge/classify_roles）——在线 ScreenTracker 与离线聚类同一套逻辑（单管线双出口，延续 REQ-081 原则）。
  3. 屏边界：版面指纹变化（layout_cache 现成）= 新屏；同屏内容相似 → 续屏（更新 last_seen 不新增行）；翻回旧页间隔>2 分钟 = 新屏。
    • 实现校准（2026-08-20）：CLUSTER_GAP_MS 初版 3s 与 OCR 帧间隔（强制兜底 15s + 事件驱动，会话29 实测 5-58s）冲突导致同屏续帧误分屏——按实测校准为 120s；TITLE_HEIGHT_RATIO 初版 4% 把正文/标签（30px/626px 屏高 ≈4.8%）误判为标题——校准为 6%（只命中 PPT 大标题）。
  4. 行合并保守阈值：bbox y 中心差 ≤ 行高×0.6 且 x 间隔 ≤ 字高×0.5 → 同行拼接；跨帧同位置块先经 dedupe_blocks 去重（防多帧重复识别被 line_merge 误拼）；屏卡可展开块级明细复查（原料不动）。
  5. 采集治理：前台≠目标窗口期间画面要点不落库（复用 REQ-084 foreground_foreign）；平台 UI 黑名单扩充（LiveUi 类别：正在看/人在看/人看过/发送/下载/预约/回放/分享/直播）+ 持久元素自学习（第二波）。
  6. 结构识别：只补消费端接线（refine_screen_structures 纯函数匹配 artifact_blocks 精修产物），识别内核（SLANet/FormulaNet/refine 链路）零改动；停止后自动精修（stop_live_session 检测 table/formula 区域块 → 后台 run_refine，模型未就绪内部降级跳过）；失败降级徽标保留。
  7. 降级四级链：新数据全能力屏卡 → 旧数据聚类屏（无行合并/角色/结构）→ refine 失败徽标 → 现行文本列表兜底（零回归）。
  8. 导入链路口径（REQ-156 实现注记）：bbox 反算回帧坐标系落库（裁剪图坐标 + 等比缩放 + 顶部偏移，TD-046 同思路）；screen_id 不分配（None）——视图层聚类兜底与在线 ScreenTracker 共用同一套纯函数，结果等价。

四、测试与验证

  • Rust 单测（M1-M5 已提交）：screen_merge（normalize/similarity 边界、cluster gap 分屏/相似合并/翻回旧页/累积重置、line_merge 断行拼接/不同行不误并/位置去重、classify_roles 标题/正文/标签、dedupe 跨帧去重）；ScreenTracker mock 块流（新版面=新屏/同屏续屏/gap 分屏/翻页分屏）；screens（分组/聚类/混合/结构块/图匹配/精修产物匹配）；迁移加列旧库可读新库可写；note_filter 屏段落输出/过滤口径回归——1053 单测全绿 + clippy 新代码零警告
  • 前端：npm run build 通过；屏卡流 UI 真机验证清单见下
  • 模型：structure 模型已本地就绪（pp-doclayout-l / pp-formulanet-s / slanet_plus_v2），无新增下载

真机手动验证清单（实施完成后执行）

  1. 会话29 重跑：原料视图 175 块 → ≤10 张屏卡，每卡带时间区间，无平台 UI/IDE 污染，断行已合并成完整句
  2. 旧会话（无 screen_id/bbox）：聚类屏正常展示（降级 2 级），列表不劣化（零回归）
  3. 直播平台新会话：1人正在看/发送/频道名不进屏卡；切窗到 IDE 期间画面要点不落库
  4. 表格/公式屏：停止后自动精修，屏卡内 Markdown/LaTeX 渲染；模型缺失时徽标降级
  5. 转笔记：画面要点 = 屏段落+配图，数量与 full 图对应；预览过滤统计按屏口径

五、文件清单（实施中，按提交逐步更新）

Rust：screen_merge.rs（新：纯函数聚合/去重/行合并/角色/dedupe）· screen_tracker.rs（新：在线屏状态机）· screens.rs（新：屏构建/可消费过滤/图匹配/精修产物匹配）· db.rs/db_sessions.rs/db_sessions_rows.rs（bbox/screen_id 列 + 双写 + 行映射）· types.rs（SessionScreen/ScreenStructure 契约）· live_keyframes.rs/import_frame.rs（落库双写 bbox + 屏号/导入反算）· live_frame_process.rs/live_session_frame.rs（ScreenTracker 挂载 + 前台过滤 + live:ocr 带屏号）· ui_junk.rs（LiveUi 直播元素扩充）· commands_session.rs（SessionDetail.screens + 笔记 attach 配图 + 大纲按屏）· note_filter.rs（屏段落渲染/refresh_screen_points）· outline.rs（detect_outline_smart 屏标题优先）· db_ocr_search.rs（命中带屏区间）· commands_live.rs（停止后自动精修触发）· screens.rs（refine_screen_structures）· 测试文件若干

前端：types.ts（SessionScreen/ScreenStructure/ocrScreens/screenId）· SessionDetailPanel.tsx（屏卡流+块级明细+配图）· NotePreviewView.tsx（屏段落配图渲染）· LiveActivityPanel.tsx（按屏摘要）

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

  • AI 精修屏内容（路线 C：OCR 文本走云端整理——留给 v0.8.0 REQ-141 管线对接，图像永不出本机）
  • 持久元素自学习（同 bbox 位置+长期不变小块自动标记 UI，第二波）
  • 章节检测升级（屏标题变化=精确章节边界，可选第二波）
  • 屏卡图注（C6 REQ-088 影子层接线，产物配图）