Skip to content

v0.14.md

Latest commit

 

History

History
138 lines (104 loc) · 11.1 KB

v0.14.md

File metadata and controls

138 lines (104 loc) · 11.1 KB
Raw

v0.14 — 体验与质量攻坚（编辑器 / 视觉 / 知识体系 / 采集质量）

系列文档：4 个子项目并行推进（A 编辑器基础体验 / B 视觉系统 / C 知识体系架构 / D 采集质量）。 2026-08-27~28 头脑风暴定稿；各子项目设计规格见 docs/superpowers/specs/。

背景与目标

v0.13 知识体系层交付后，用户基于实际使用提出 8+1 大痛点，全部纳入 v0.14：

  1. 编辑状态下图片位置不可视（新增，排第 1）
  2. H2/H3 添加有问题（工具栏点击不生效/行为不对）
  3. 没有撤销能力
  4. 笔记没有颜色能力
  5. 笔记能否对齐 Word（暂缓）
  6. 分组分类方式有问题（确认：展示混乱）
  7. 知识体系能否对齐 Obsidian 的同时与项目本身深度联动（挂接后体系页不显示）
  8. 采集转化质量：PPT 型视频知识内容可视但笔记仍口语化；OCR 产物质量低，喂 AI 只增 token 消耗

成功标准：编辑体验达到 Obsidian 心智、采集-转化质量逼近"转文字+手动梳理"。

子项目 A：编辑器基础体验（CodeMirror 6）

设计规格：2026-08-27-v0.14-editor-experience-design.md（[ ] 已归档——A 子项目实施完成，交付 7b01da58）

  • 引擎：CodeMirror 6 替换 textarea（选型演进：TipTap → CodeMirror 6——存储零变更、版本链零风险，编辑 Markdown 源码而非富文本）
  • 图片内联渲染：Decoration.replace widget + React createRoot 挂载 NoteImage（点击放大保留）；destroy() 必须 root.unmount()
  • 撤销：CM 内建 history（零自研）
  • H2/H3：输入驱动 + 折叠（Obsidian 心智：## 空格 触发标题，未配命令按钮）
  • 保存：双计时器平移 + localStorage 草稿恢复层（note-draft:{noteId}，节流 1s，崩溃/强杀后恢复，updatedAt 对比 DB 提示）
  • 降级护栏：CM 挂载失败回退原 textarea（NoteEditView 保留为降级路径）
  • 边界：markdownEdit.ts 纯函数保留给 textarea 降级路径（headingCommand 不复用——字符串模型 vs CM Text 模型）

子项目 B：视觉系统（四级颜色）

设计要点（已获用户确认）：

  • 四级颜色体系：笔记级（properties.color）/ 标签级（tag_colors 新表）/ 组级（note_groups 加列）/ 正文级（==文本== 荧光笔）
  • 正文高亮：单色荧光笔 ==文本==（Obsidian 式，黄色；多色是伪需求——零自研解析，现成 remark 插件）
  • 固定 12 色语义色板：双主题安全（浅/深色均可用）
  • 渲染优先级：笔记显式 > 组色继承 > 标签色 > 默认灰
  • Word 对齐：用户裁决跳过（暂缓）

子项目 C：知识体系架构（Obsidian 对齐 + 深度联动）

C1 组侧栏：Obsidian 式改造

  • 按 kind 分区（课程 / 主题 / 独立 / feed）+ 折叠记忆
  • 组过滤 + 拖拽归组（复用已有 move_note_to_group 命令）
  • 最近使用区
  • 三条设计契约（v0.11 系列延续）：粒度对齐 DomainTag 拒绝大类聚合；组是学习单元；组结算防沼泽（禁止父子组）

C2 图谱：A' 多关系分层图谱

  • 基于已有 React Flow（@xyflow/react ^12.11.3），非 Obsidian 同款毛线球
  • 三种边类型可开关图层：🔗 引用 / 🧬 溯源 / 📁 归属
  • 局部聚焦模式（1~2 度邻居），点击节点跳转导航
  • 后端 graph_snapshot() 聚合命令

C3 深度联动 v2：体验闭环（修复"挂接后体系页不显示"）

  • 根因 A：NoteLinkToSystem 只支持挂到 node（问题节点），UI 无概念/模型选项
  • 根因 B：体系页按选中实体 entityType 过滤，挂载实体与查看实体不一致时引用"消失"
  • 修复：list_links_by_target 反查命令 + 挂接增强（支持概念/模型、可直接切换目标）+ 体系页聚合引用视图 + 跨页即时同步（refreshToken 机制）

子项目 D：采集质量攻坚（结构 / 质量 / 算法 / 平台 四层）

D1 结构层：章节级混合形态笔记

  • 痛点根因：v0.11.5 决策（OCR 画面要点移出笔记正文，assemble_markdown 只输出口语转写）
  • 用户纠正：不能做视频级二分法（不是所有视频都有 PPT，一个视频内也可能存在两个部分）
  • 方案：复用章节边界检测 → 每章独立决策形态 → 整篇笔记 = 图文章节 / 口语章节混编
    • OCR 密度高的章节 → 图文章节（OCR 屏卡要点为主体 + 口语降级为引用块）
    • OCR 密度低 → 口语章节（现状形态）
    • 边界：无章节边界 → 退化现状；全高密度 → 整篇图文；空章节跳过

D2 质量层：双维决策 + 质量门控

  • 章节级决策两维信号：OCR 密度 × OCR 质量分（全纯规则零 token）
    • 密度高 + 质量高 → 图文章节；密度高 + 质量低 → 口语章节（OCR 弃用，仅会话原料视图可查）；密度低 → 口语章节
  • 质量分 ocr_quality_score（章节窗口内）：字符置信度加权均值（OcrBlock.score）+ 碎片率（短块占比）+ 连贯性（句长分布）+ 噪音比（复用 UiJunkList）
  • 门控双出口：质量分 < 阈值 → OCR 不进正文（劣质不沉淀）+ 该章节 OCR 不喂 AI（省 token）；达标图文章节进精修时提示词标注"以下为屏幕 OCR 内容，请优先修正错字后使用"
  • 质量分同步成为质量报告的诚实指标（quality_report.rs 哲学延续："指标从恒 ≈0 变真实"）

D3 算法层：屏内版面重建 + 行合并 + 跨帧增量

  • 现状缺陷：净化链按时间戳线性拼接（字幕思维），PPT 版面结构性错误；bbox 从 v0.5.0 已落库但从未使用
  • 屏内版面重建（简化 XY-Cut，纯规则零 token）：行聚类（y 容差）→ 行内 x 排序 → 栏检测（列间隙稳定 → 多栏分组）→ 标题识别（字号/最短文本，复用屏标题资产）→ 块间拼接成段落
  • 行合并评分器（B）：相邻块按几何信号（垂直重叠 > 50% / 水平间隙 < 半字宽 / 行高一致）+ 文本信号（尾字符虚词续接 / 尾标点断开 / 项目符号护栏）打分合并；护栏：合并超长回退、字体差 > 30% 不合并
  • 跨帧增量合并（C）：PPT 动画逐行出现——后帧文本包含前帧 + bbox 位置锚定 → 同屏增量合并；bbox 整体位移 → 翻页新屏
  • 行级重识别（A）自研裁决：
    • oar-ocr 0.9.2 无 rec-only API（predict 为 det+rec 一体）→ 原方案 A 否决
    • 官方 TextRecognitionAdapter 是公共 API（oar_ocr::domain::adapters，CRNN + 预处理 + CTC 解码全封装，supports_batching() = true）→ 编排自研可行
    • 自研 line_rec_engine.rs（~200 行）：行聚类 → 行图裁剪（image crate）→ 官方 adapter 批量识别 → 行级结果替换碎片；仅"疑碎行"（碎片率高/置信度低）触发二次识别
    • 降级：adapter 构建失败保留碎片结果
  • 净化链落位：排序 → ① 行合并评分器 → ② 行级重识别（疑碎行）→ ③ 跨帧增量 → 净化 → 去重

D4 平台层：平台模板 + 通用几何兜底

  • 现状：窗口级捕获，无平台版面适配（B站弹幕/推荐流、抖音竖屏、Edge 无固定模式）
  • C 混合方案（用户确认）：
    • 平台识别（窗口标题/URL）→ 平台模板（视频区 ROI / 字幕带位置 / 噪音区掩码）
    • 未命中 → 通用几何兜底（黑边检测定位视频区 / 动态区域检测 / 宽高比判定横竖屏）
    • 全失败 → 现状行为（能力降级不失效）
  • 模板是数据不是代码：JSON 配置 {platform, videoRoi, subtitleBand, noiseMasks}，改版只改配置不改代码
  • 收益：OCR 只在视频区 ROI 内跑 → 弹幕/推荐流/评论区噪音从源头消失；字幕带先验让 subtitle_detect 从"盲找"变"带先验找"

决策记录（"有更好方案吗"驱动的主要演进）

痛点 初案 演进 裁决
编辑器 TipTap（Markdown↔JSON 切换） → CodeMirror 6（零转换、内建 history） 采用 CM6
图片渲染 widget 原生 img → widget + React 挂载 NoteImage 保留点击放大
H2/H3 命令式按钮 → 输入驱动 + 折叠 Obsidian 心智
保存 双计时器平移 → + localStorage 草稿恢复层 崩溃零丢失
正文高亮 多色 → 单色 ==文本== 多色是伪需求
组侧栏 分区 → 分区 + 过滤 + 拖拽 + 最近使用 Obsidian 式
图谱 Obsidian 同款毛线球 → A' 多关系分层（三类边可开关） 避免毛线球
采集质量 视频级二分法 → 章节级混合形态 覆盖无 PPT / 双部分视频
OCR 质量 事后过滤 → 双维决策质量门控 + 版面重建 + 行合并 + 行级重识别 零 token 纯规则
OCR 引擎 依赖 rec-only API（不存在） → 官方 TextRecognitionAdapter 编排自研 公共 API 已确认

验收标准（各子项目）

  • A：编辑态图片可见可点放大；## 空格 输入驱动标题；Ctrl+Z 撤销；强杀进程后重启恢复未保存编辑；CM 异常回退 textarea 可编辑
  • B：四级颜色全部生效且双主题可读；==文本== 渲染为荧光笔；渲染优先级正确
  • C：组侧栏分区/拖拽/最近使用可用；图谱三类边图层可开关、聚焦模式正确；笔记挂概念/模型后体系页即时可见
  • D：含 PPT 章节的视频会话生成图文混编笔记；低质量 OCR 章节退回口语形态；质量分显示在会话详情；B站/抖音采集时弹幕/推荐流不入 OCR 产物

状态

子项目 状态 说明
A 编辑器 代码已交付（2026-08-28） 实施：CM 富编辑（图片内联/撤销/标题/草稿恢复/降级护栏），259 单测全绿，真机验收待执行；spec 已归档
B 视觉系统 代码已交付（2026-08-28） 实施：tag_colors 迁移（db_colors 表 CRUD）+ colors 命令（list/set/reset）+ 前端 12 色色板/选择器/==文本== 高亮渲染/组色继承色条；spec 已归档
C 知识体系 代码已交付（2026-08-28） 实施：C1 组侧栏 Obsidian 式（分区/拖拽/最近使用）/ C2 graph_snapshot 聚合 + 图谱页（三边图层/局部聚焦）/ C3 反查 + 挂接增强 + refreshToken；spec 已归档
D 采集质量 代码已交付（2026-08-28） 实施：D1 纯函数层（chapter_morph/ocr_quality/layout_reorder/line_merge/incremental_merge）/ D2 line_rec_engine + platform_layout + 净化链①②③ / D3 章节级混合形态组装 + 质量门控；D4 ROI 应用接线留 v0.14.1（模板/兜底资产已就绪）；spec 已归档

实施策略：用户裁决并行推进（A 实施已交付，B/C/D 设计完成后各自进入实施会话）。