|
| 1 | +# v0.7.3 — 画面要点屏卡体系（OCR 碎片化治理 + 屏级组织 + 结构识别接线） |
| 2 | + |
| 3 | +> **状态**: 已排期（2026-08-20 头脑风暴裁决完成：路线 A+B+D，笔记形态=屏段落+配图；实施待启动） |
| 4 | +> **目标**: 画面要点从"块流"升级为"屏卡"——屏级时间区间（00:02–03:23）+ 屏内版面组织（标题/正文/图注标签）+ 采集治理（前台过滤/平台 UI 黑名单）+ 结构识别接线（表格/公式/代码） |
| 5 | +> **关联**: [头脑风暴 OCR 屏卡体系](../archive/2026-08-20/brainstorming-ocr-screen-cards.md) · [ADR-015](../adr/ADR-015-screen-cards-ocr.md)（架构决策）· [需求池](../product/requirements-pool.md)（REQ-155~161） |
| 6 | +> **触发**: 用户反馈"画面要点（OCR）提取的内容零碎（时间整理和识别内容）"；会话29 实证（175 块 OCR / 12 时间戳重复 / 平台 UI+其他窗口污染 / 无 bbox 落库） |
| 7 | +
|
| 8 | +## 一、阶段目标 |
| 9 | + |
| 10 | +1. **屏级聚合与去重（REQ-155）**：`screen_merge` 纯函数（normalize/similarity/cluster/line_merge/classify_roles）+ 在线 `ScreenTracker`（版面指纹变化=新屏，layout_cache 复用）+ 旧数据聚类兜底——175 块 → ~7 屏 |
| 11 | +2. **bbox/screen_id 落库（REQ-156）**：`session_ocr_blocks` 加列（ensure_column 幂等），实时/导入双入口双写 |
| 12 | +3. **采集治理（REQ-157）**：前台窗口过滤扩展全帧（foreground_foreign 复用，REQ-084 先例）+ ui_junk 直播互动元素扩充——根治平台 UI/IDE 污染 |
| 13 | +4. **屏内组织（REQ-158）**：line_merge 断行拼接（治 det 切半句）+ classify_roles 版面角色 + `SessionScreen` 契约 |
| 14 | +5. **结构识别接线（REQ-159）**：refine_screen_structures 复用 commands_refine_inner（REQ-049/050 内核不动）+ 停止后批量精修 + 屏卡 Markdown/LaTeX/代码渲染 |
| 15 | +6. **消费端（REQ-160/161）**：原料屏卡流 + 笔记屏段落配图 + 大纲/检索按屏 + 实时面板按屏摘要 |
| 16 | + |
| 17 | +## 二、范围（需求追溯） |
| 18 | + |
| 19 | +| REQ | 内容 | 验收要点 | 规划状态 | |
| 20 | +|-----|------|---------|---------| |
| 21 | +| REQ-155 | 屏级聚合与去重：screen_merge 纯函数 + ScreenTracker 在线屏 + 旧数据聚类兜底 | 在线/离线共用同一套纯函数（单管线双出口）；翻回旧页间隔>3s=新屏；截断变体合并 | **已排期** | |
| 22 | +| REQ-156 | bbox/screen_id 落库迁移：session_ocr_blocks 加列 + 实时/导入双入口双写 | 加列幂等；旧库只读兼容；bbox JSON {x,y,w,h} 帧坐标系（TD-046 反算复用） | **已排期** | |
| 23 | +| REQ-157 | 采集治理：前台窗口过滤扩展全帧 + ui_junk 直播互动元素扩充 | 前台≠目标窗口期间画面要点不落库；`1人正在看`/`发送`/`X`/频道名/logo 乱码不进屏卡 | **已排期** | |
| 24 | +| REQ-158 | 屏内组织：line_merge 断行拼接 + classify_roles 版面角色 + SessionScreen 契约 | 会话29 断行合并成完整句；标题/正文/标签分类正确；region_kind 结构块不参与行合并 | **已排期** | |
| 25 | +| REQ-159 | 结构识别接线：refine_screen_structures + 停止后批量精修 + 屏卡渲染 | 表格→Markdown/公式→LaTeX/代码→等宽块；模型缺失降级徽标；内核零改动 | **已排期** | |
| 26 | +| REQ-160 | 消费端：SessionDetail.screens + 原料屏卡流 + 笔记屏段落配图 + 大纲/检索按屏 | 屏卡可展开块级明细复查（可逆）；笔记配图 asset:// 可开关；旧数据降级聚类屏 | **已排期** | |
| 27 | +| REQ-161 | 实时面板按屏显示：live:ocr 带 screen_id | 最近画面要点一行=一屏摘要（区间+标题） | **已排期** | |
| 28 | + |
| 29 | +## 三、关键设计决策 |
| 30 | + |
| 31 | +1. **屏 = 派生视图而非新表**：屏 first/last_seen/成员块 = `GROUP BY screen_id` 聚合；旧数据（screen_id NULL）走 `cluster_blocks_into_screens` 聚类兜底——零冗余、可逆（ADR-006 派生视图传统，ADR-015 决策 2）。 |
| 32 | +2. **在线/离线共用纯函数**：`screen_merge.rs`（normalize/screen_similarity/cluster_blocks_into_screens/line_merge/classify_roles）——在线 ScreenTracker 与离线聚类同一套逻辑（单管线双出口，延续 REQ-081 原则）。 |
| 33 | +3. **屏边界**：版面指纹变化（layout_cache 现成）= 新屏；同屏内容相似 → 续屏（更新 last_seen 不新增行）；翻回旧页间隔>3s = 新屏。 |
| 34 | +4. **行合并保守阈值**：bbox y 中心差 ≤ 行高×0.6 且 x 间隔 ≤ 半字宽 → 同行拼接；屏卡可展开块级明细复查（原料不动）。 |
| 35 | +5. **采集治理**：前台≠目标窗口期间画面要点不落库（复用 REQ-084 foreground_foreign）；平台 UI 黑名单扩充 + 持久元素自学习（第二波）。 |
| 36 | +6. **结构识别**：只补消费端接线（抽 refine_screen_structures 纯函数），识别内核（SLANet/FormulaNet/refine 链路）零改动；停止后批量精修；失败降级徽标保留。 |
| 37 | +7. **降级四级链**：新数据全能力屏卡 → 旧数据聚类屏（无行合并/角色/结构）→ refine 失败徽标 → 现行文本列表兜底（零回归）。 |
| 38 | + |
| 39 | +## 四、测试与验证 |
| 40 | + |
| 41 | +- **Rust 单测**：`screen_merge`（normalize/similarity 边界、cluster gap 分屏/相似合并/翻回旧页、line_merge 断行拼接/不同行不误并、classify_roles 标题/正文/标签）；`ScreenTracker` mock 块流（新版面=新屏/同屏续屏/UI 变化不扰屏）；迁移加列旧库可读新库可写；note_filter 屏段落输出/配图格式/旧数据降级 |
| 42 | +- **前端**：`npm run build` 通过；屏卡流 UI 真机验证清单见下 |
| 43 | +- **模型**：structure 模型已本地就绪（pp-doclayout-l / pp-formulanet-s / slanet_plus_v2），无新增下载 |
| 44 | + |
| 45 | +### 真机手动验证清单（实施完成后执行） |
| 46 | + |
| 47 | +1. 会话29 重跑：原料视图 175 块 → ≤10 张屏卡，每卡带时间区间，无平台 UI/IDE 污染，断行已合并成完整句 |
| 48 | +2. 旧会话（无 screen_id/bbox）：聚类屏正常展示（降级 2 级），列表不劣化（零回归） |
| 49 | +3. 直播平台新会话：`1人正在看`/`发送`/频道名不进屏卡；切窗到 IDE 期间画面要点不落库 |
| 50 | +4. 表格/公式屏：停止后自动精修，屏卡内 Markdown/LaTeX 渲染；模型缺失时徽标降级 |
| 51 | +5. 转笔记：画面要点 = 屏段落+配图，数量与 full 图对应；预览过滤统计按屏口径 |
| 52 | + |
| 53 | +## 五、文件清单（实施中，按提交逐步更新） |
| 54 | + |
| 55 | +**Rust**：`screen_merge.rs`（新：纯函数聚合/去重/行合并/角色）· `screen_tracker.rs`（新：在线屏状态机）· `db.rs`/`db_sessions.rs`（bbox/screen_id 列 + 双写 + 屏聚合查询）· `live_keyframes.rs`/`import_frame.rs`（落库双写 + 前台过滤）· `live_frame_process.rs`（ScreenTracker 挂载 + live:ocr 带屏号）· `ui_junk.rs`（直播元素扩充）· `types.rs`（SessionScreen 契约）· `commands_session.rs`/`db_sessions.rs`（SessionDetail.screens）· `note_filter.rs`（屏段落输出）· `refine_screen.rs`（新：refine_screen_structures）· `outline.rs`/`db_ocr_search.rs`（按屏）· `lib.rs`（注册）· 测试文件若干 |
| 56 | + |
| 57 | +**前端**：`types.ts`（SessionScreen/ScreenStructure）· `SessionDetailPanel.tsx`（屏卡流）· `NotePreviewView.tsx`（屏段落+配图）· `LiveActivityPanel.tsx`（按屏摘要）· `OutlinePanel`（大纲按屏） |
| 58 | + |
| 59 | +## 六、后续批次（本版本不做） |
| 60 | + |
| 61 | +- AI 精修屏内容（路线 C：OCR 文本走云端整理——留给 v0.8.0 REQ-141 管线对接，图像永不出本机） |
| 62 | +- 持久元素自学习（同 bbox 位置+长期不变小块自动标记 UI，第二波） |
| 63 | +- 章节检测升级（屏标题变化=精确章节边界，可选第二波） |
| 64 | +- 屏卡图注（C6 REQ-088 影子层接线，产物配图） |
0 commit comments