Skip to content

Commit bcf6783

Browse files
AparenciaAparencia
committed
docs(v0.14): 体验与质量攻坚系列版本文档落位（A~D 四子项目设计定稿）
1 parent 2b868f0 commit bcf6783

2 files changed

Lines changed: 139 additions & 0 deletions

File tree

‎docs/versions/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
| v0.12.7 | [v0.12.7.md](./v0.12.7.md) — 会话内部 ID 不外显：采集/导入/融合/任务中心等用户可见文案全部去掉「会话 #N」，仅保留显示序号 display_no（与内部 id 解耦） | 版本文档（代码已交付 2026-08-23） |
4040
| v0.12.8 | [v0.12.8.md](./v0.12.8.md) — 笔记列表级批量删除：行内勾选 + 底部批量操作栏（全选三态/计数/批量删除），与会话管理台同操作逻辑，无需先打开笔记 | 版本文档（代码已交付 2026-08-23） |
4141
| v0.13 | [v0.13.md](./v0.13.md) — 大目标版本系列：知识体系层（v0.13.0 理念修订批/ADR-024 / v0.13.1 体系基建 / v0.13.2 概念双面体 / v0.13.3 决策与应用 / v0.13.4 审计与整合；方案 B：全局+领域双层、组仍唯一容器、REQ-202~212；v0.13.7 体系上手路径：入口补全+具象化；v0.13.8 画布可视化：React Flow 节点式无限画布） | 系列文档（v0.13.1 代码已交付 2026-08-23，真机验收待执行；v0.13.2~4 未启动，REQ-146 门控；v0.13.7 代码已交付 2026-08-24；v0.13.8 代码已交付 2026-08-24，真机验收待执行） |
42+
| v0.14 | [v0.14.md](./v0.14.md) — 体验与质量攻坚系列：A 编辑器基础体验（CodeMirror 6）/ B 视觉系统（四级颜色）/ C 知识体系架构（Obsidian 式组侧栏 + 多关系分层图谱 + 深度联动 v2）/ D 采集质量（章节级混合形态 + 质量门控 + 版面重建/行合并/跨帧增量 + 平台模板适配） | 版本文档（2026-08-27~28 头脑风暴定稿；A spec 已提交，B/C/D 设计完成待实施） |
4243

4344
## 沉淀规则
4445

‎docs/versions/v0.14.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# v0.14 — 体验与质量攻坚（编辑器 / 视觉 / 知识体系 / 采集质量）
2+
3+
> 系列文档：4 个子项目并行推进（A 编辑器基础体验 / B 视觉系统 / C 知识体系架构 / D 采集质量）。
4+
> 2026-08-27~28 头脑风暴定稿；各子项目设计规格见 `docs/superpowers/specs/`。
5+
6+
## 背景与目标
7+
8+
v0.13 知识体系层交付后，用户基于实际使用提出 **8+1 大痛点**，全部纳入 v0.14：
9+
10+
1. 编辑状态下图片位置不可视（新增，排第 1）
11+
2. H2/H3 添加有问题（工具栏点击不生效/行为不对）
12+
3. 没有撤销能力
13+
4. 笔记没有颜色能力
14+
5. 笔记能否对齐 Word（暂缓）
15+
6. 分组分类方式有问题（确认：展示混乱）
16+
7. 知识体系能否对齐 Obsidian 的同时与项目本身深度联动（挂接后体系页不显示）
17+
8. 采集转化质量：PPT 型视频知识内容可视但笔记仍口语化；OCR 产物质量低，喂 AI 只增 token 消耗
18+
19+
成功标准：编辑体验达到 Obsidian 心智、采集-转化质量逼近"转文字+手动梳理"。
20+
21+
## 子项目 A：编辑器基础体验（CodeMirror 6）
22+
23+
设计规格：[2026-08-27-v0.14-editor-experience-design.md](../../docs/superpowers/specs/2026-08-27-v0.14-editor-experience-design.md)（已提交 d445b3cc）
24+
25+
- **引擎**：CodeMirror 6 替换 textarea（选型演进：TipTap → CodeMirror 6——存储零变更、版本链零风险，编辑 Markdown 源码而非富文本）
26+
- **图片内联渲染**：`Decoration.replace` widget + React `createRoot` 挂载 NoteImage（点击放大保留）；`destroy()` 必须 `root.unmount()`
27+
- **撤销**：CM 内建 history（零自研）
28+
- **H2/H3**：输入驱动 + 折叠（Obsidian 心智：`## 空格` 触发标题，未配命令按钮）
29+
- **保存**：双计时器平移 + **localStorage 草稿恢复层**（`note-draft:{noteId}`，节流 1s，崩溃/强杀后恢复，updatedAt 对比 DB 提示）
30+
- **降级护栏**：CM 挂载失败回退原 textarea（NoteEditView 保留为降级路径）
31+
- **边界**：markdownEdit.ts 纯函数保留给 textarea 降级路径（headingCommand 不复用——字符串模型 vs CM Text 模型）
32+
33+
## 子项目 B：视觉系统（四级颜色）
34+
35+
设计要点（已获用户确认）：
36+
37+
- **四级颜色体系**：笔记级（properties.color）/ 标签级（tag_colors 新表）/ 组级（note_groups 加列）/ 正文级（`==文本==` 荧光笔）
38+
- **正文高亮**：单色荧光笔 `==文本==`（Obsidian 式，黄色；多色是伪需求——零自研解析，现成 remark 插件）
39+
- **固定 12 色语义色板**：双主题安全（浅/深色均可用）
40+
- **渲染优先级**：笔记显式 > 组色继承 > 标签色 > 默认灰
41+
- **Word 对齐**：用户裁决**跳过**（暂缓）
42+
43+
## 子项目 C：知识体系架构（Obsidian 对齐 + 深度联动）
44+
45+
### C1 组侧栏：Obsidian 式改造
46+
47+
- **按 kind 分区**（课程 / 主题 / 独立 / feed）+ 折叠记忆
48+
- **组过滤** + **拖拽归组**（复用已有 `move_note_to_group` 命令）
49+
- **最近使用区**
50+
- 三条设计契约（v0.11 系列延续）：粒度对齐 DomainTag 拒绝大类聚合；组是学习单元；组结算防沼泽（禁止父子组）
51+
52+
### C2 图谱：A' 多关系分层图谱
53+
54+
- 基于已有 React Flow（@xyflow/react ^12.11.3），非 Obsidian 同款毛线球
55+
- **三种边类型可开关图层**：🔗 引用 / 🧬 溯源 / 📁 归属
56+
- **局部聚焦模式**（1~2 度邻居），点击节点跳转导航
57+
- 后端 `graph_snapshot()` 聚合命令
58+
59+
### C3 深度联动 v2：体验闭环（修复"挂接后体系页不显示"）
60+
61+
- 根因 A：NoteLinkToSystem 只支持挂到 node（问题节点），UI 无概念/模型选项
62+
- 根因 B：体系页按选中实体 entityType 过滤，挂载实体与查看实体不一致时引用"消失"
63+
- 修复：`list_links_by_target` 反查命令 + 挂接增强（支持概念/模型、可直接切换目标）+ 体系页聚合引用视图 + 跨页即时同步（refreshToken 机制）
64+
65+
## 子项目 D：采集质量攻坚（结构 / 质量 / 算法 / 平台 四层）
66+
67+
### D1 结构层：章节级混合形态笔记
68+
69+
- 痛点根因：v0.11.5 决策（OCR 画面要点移出笔记正文，`assemble_markdown` 只输出口语转写）
70+
- 用户纠正：**不能做视频级二分法**（不是所有视频都有 PPT，一个视频内也可能存在两个部分）
71+
- 方案：复用章节边界检测 → **每章独立决策形态** → 整篇笔记 = 图文章节 / 口语章节混编
72+
- OCR 密度高的章节 → 图文章节（OCR 屏卡要点为主体 + 口语降级为引用块）
73+
- OCR 密度低 → 口语章节（现状形态）
74+
- 边界：无章节边界 → 退化现状；全高密度 → 整篇图文；空章节跳过
75+
76+
### D2 质量层：双维决策 + 质量门控
77+
78+
- 章节级决策两维信号：**OCR 密度 × OCR 质量分**（全纯规则零 token）
79+
- 密度高 + 质量高 → 图文章节；密度高 + 质量低 → 口语章节（OCR 弃用，仅会话原料视图可查）；密度低 → 口语章节
80+
- **质量分 `ocr_quality_score`**（章节窗口内）：字符置信度加权均值（OcrBlock.score）+ 碎片率（短块占比）+ 连贯性（句长分布）+ 噪音比（复用 UiJunkList）
81+
- **门控双出口**：质量分 < 阈值 → OCR 不进正文（劣质不沉淀）+ **该章节 OCR 不喂 AI（省 token）**；达标图文章节进精修时提示词标注"以下为屏幕 OCR 内容，请优先修正错字后使用"
82+
- 质量分同步成为质量报告的诚实指标（quality_report.rs 哲学延续："指标从恒 ≈0 变真实"）
83+
84+
### D3 算法层：屏内版面重建 + 行合并 + 跨帧增量
85+
86+
- **现状缺陷**：净化链按时间戳线性拼接（字幕思维），PPT 版面结构性错误；bbox 从 v0.5.0 已落库但从未使用
87+
- **屏内版面重建**（简化 XY-Cut，纯规则零 token）：行聚类（y 容差）→ 行内 x 排序 → 栏检测（列间隙稳定 → 多栏分组）→ 标题识别（字号/最短文本，复用屏标题资产）→ 块间拼接成段落
88+
- **行合并评分器（B）**：相邻块按几何信号（垂直重叠 > 50% / 水平间隙 < 半字宽 / 行高一致）+ 文本信号（尾字符虚词续接 / 尾标点断开 / 项目符号护栏）打分合并；护栏：合并超长回退、字体差 > 30% 不合并
89+
- **跨帧增量合并（C）**：PPT 动画逐行出现——后帧文本包含前帧 + bbox 位置锚定 → 同屏增量合并；bbox 整体位移 → 翻页新屏
90+
- **行级重识别（A）自研裁决**：
91+
- oar-ocr 0.9.2 无 rec-only API（`predict` 为 det+rec 一体）→ 原方案 A 否决
92+
- **官方 `TextRecognitionAdapter` 是公共 API**（`oar_ocr::domain::adapters`，CRNN + 预处理 + CTC 解码全封装，`supports_batching() = true`）→ **编排自研可行**
93+
- 自研 `line_rec_engine.rs`（~200 行）：行聚类 → 行图裁剪（image crate）→ 官方 adapter 批量识别 → 行级结果替换碎片；仅"疑碎行"（碎片率高/置信度低）触发二次识别
94+
- 降级：adapter 构建失败保留碎片结果
95+
- **净化链落位**：排序 → ① 行合并评分器 → ② 行级重识别（疑碎行）→ ③ 跨帧增量 → 净化 → 去重
96+
97+
### D4 平台层：平台模板 + 通用几何兜底
98+
99+
- 现状：窗口级捕获，无平台版面适配（B站弹幕/推荐流、抖音竖屏、Edge 无固定模式）
100+
- **C 混合方案**（用户确认）：
101+
- 平台识别（窗口标题/URL）→ 平台模板（视频区 ROI / 字幕带位置 / 噪音区掩码）
102+
- 未命中 → 通用几何兜底（黑边检测定位视频区 / 动态区域检测 / 宽高比判定横竖屏）
103+
- 全失败 → 现状行为（能力降级不失效）
104+
- **模板是数据不是代码**：JSON 配置 `{platform, videoRoi, subtitleBand, noiseMasks}`，改版只改配置不改代码
105+
- 收益：OCR 只在视频区 ROI 内跑 → 弹幕/推荐流/评论区噪音从源头消失；字幕带先验让 subtitle_detect 从"盲找"变"带先验找"
106+
107+
## 决策记录（"有更好方案吗"驱动的主要演进）
108+
109+
| 痛点 | 初案 | 演进 | 裁决 |
110+
|---|---|---|---|
111+
| 编辑器 | TipTap（Markdown↔JSON 切换）| → CodeMirror 6（零转换、内建 history）| 采用 CM6 |
112+
| 图片渲染 | widget 原生 img | → widget + React 挂载 NoteImage | 保留点击放大 |
113+
| H2/H3 | 命令式按钮 | → 输入驱动 + 折叠 | Obsidian 心智 |
114+
| 保存 | 双计时器平移 | → + localStorage 草稿恢复层 | 崩溃零丢失 |
115+
| 正文高亮 | 多色 | → 单色 `==文本==` | 多色是伪需求 |
116+
| 组侧栏 | 分区 | → 分区 + 过滤 + 拖拽 + 最近使用 | Obsidian 式 |
117+
| 图谱 | Obsidian 同款毛线球 | → A' 多关系分层（三类边可开关）| 避免毛线球 |
118+
| 采集质量 | 视频级二分法 | → **章节级混合形态** | 覆盖无 PPT / 双部分视频 |
119+
| OCR 质量 | 事后过滤 | → 双维决策质量门控 + 版面重建 + 行合并 + 行级重识别 | 零 token 纯规则 |
120+
| OCR 引擎 | 依赖 rec-only API（不存在）| → 官方 TextRecognitionAdapter 编排自研 | 公共 API 已确认 |
121+
122+
## 验收标准（各子项目）
123+
124+
- **A**：编辑态图片可见可点放大；`## 空格` 输入驱动标题；Ctrl+Z 撤销；强杀进程后重启恢复未保存编辑；CM 异常回退 textarea 可编辑
125+
- **B**：四级颜色全部生效且双主题可读；`==文本==` 渲染为荧光笔；渲染优先级正确
126+
- **C**：组侧栏分区/拖拽/最近使用可用；图谱三类边图层可开关、聚焦模式正确；笔记挂概念/模型后体系页即时可见
127+
- **D**：含 PPT 章节的视频会话生成图文混编笔记；低质量 OCR 章节退回口语形态；质量分显示在会话详情；B站/抖音采集时弹幕/推荐流不入 OCR 产物
128+
129+
## 状态
130+
131+
| 子项目 | 状态 | 说明 |
132+
|---|---|---|
133+
| A 编辑器 | 设计定稿 | spec 已提交（d445b3cc），待实施 |
134+
| B 视觉系统 | 设计完成 | 待落 spec + 实施 |
135+
| C 知识体系 | 设计完成 | 待落 spec + 实施 |
136+
| D 采集质量 | 设计完成（含引擎 API 裁决）| 待落 spec + 实施 |
137+
138+
> 实施策略：用户裁决**并行推进**（A 实施另开会话，B/C/D 设计完成后各自进入实施会话）。

0 commit comments

Comments
 (0)