Skip to content

v4-roadmap-build-order-analysis.md

Latest commit

 

History

History
128 lines (93 loc) · 10.8 KB

v4-roadmap-build-order-analysis.md

File metadata and controls

128 lines (93 loc) · 10.8 KB
Raw

v4 路线图代码建设顺序规划

状态: 已裁决采纳（2026-08-22 用户全盘采纳；弹性承诺首版就做）；执行进度：Step 0 清算完成，v0.11.0~3 全系列代码已交付（2026-08-22，真机验收待执行） 日期：2026-08-22（重新规划版，取代 2026-08-21 基于 v3 的分析） 依据：pain-points-v4.md §11 实施路线图 + §7 产品架构 + §10 统一 Pre-mortem + 代码库实态盘点（dev 分支，v0.10.2 交付后） 立项后本文档迁移至 versions/ 跟踪并按归档机制处置。

〇、本版相对 v3 版规划的增量

v2/v3 已整合为 v4 统一卷（2026-08-22）。重新规划后，Step 0~7 骨架不变，三处实质增量：

# 增量 来源 对规划的影响
1 理论节点远期映射表 v4 §11.2 L1 引擎层→Phase 2 闪卡体系的最小实现；L2 飞轮层→组级循环建成后按组粒度重建；L3 骨折层→组结算（Phase 3）是其组级版——每个 Step 的职责边界更清晰
2 动机App化 ★★★★★ 死法 v4 §10（统一死法排序） 硬约束：叙事层建设不得跑在引擎层真能力之前。Step 5 的 UI 保持最小，闪卡必须有"真牙"（提取优先），不先建华丽叙事界面
3 统一北极星与过程指标 v4 §8 北极星=笔记组学习循环完成（复习记录＋自测记录＋经历过结算）；三个过程指标（碎片升级率/组结算执行率/主题组活跃数）= 精确埋点清单

一、现状盘点：v4 架构中"已建成"与"零代码"的边界

公共底座（v4 §7.1 称"已建成"）——代码验证属实：

v4 声称 代码实证
ASR/OCR/引擎池 asr.rs / ocr.rs / engine.rs 等全量在位
四维解耦（结构密度的可计算代理） video_profile_spec.rs（7 形态）+ video_tier_detect.rs（4 画面档）+ video_profile_domain.rs（领域标签），v0.9.0 已交付并真机验收
PlatformAdapter platform_adapter.rs 已落地（v0.9.0 M4）

容器地形管线——高度成熟：捕获→流式 ASR→字幕 OCR 融合→屏卡体系（v0.7.3）→净化链（v0.7.5/6）→结构图（v0.7.7→v0.10.2 重构）→AI 精修/补充/版本链（v0.8.0）→单笔记全功能（v0.10.0，含 tags/properties/pin/时间戳回链）。注意：这是"提取管线"成熟，不是"学习循环"成熟——L1/L2/L3 学习层节点全部未建。

v4 Phase 1-4 所需的一切——零代码（全仓 grep terrain/note_group/flashcard/sm2 均无命中）：

  1. terrain 标记与笔记组模型（Phase 1 核心）完全不存在
  2. feed 地形进料口不存在——唯一导入路径是 import.rs 的视频文件→会话，没有"短碎片（几句话+几张图）"的采集/导入面
  3. 学习循环不存在——闪卡 SM-2（REQ-019/020）自 v0.4.0 起两度顺延至今未建；Phase 2 的"组级复习/自测"依赖它从零建起
  4. 组结算与过程指标埋点不存在

既有半基建：series_detect.rs（v0.7.2 合集检测）+ REQ-078（课程级分组，未实施）——容器地形"组"的现成基础。

二、建设顺序规划

Step 0：账务清算（半天~1 天，非代码为主）

  • 需求池同步（✅ 2026-08-22 已完成，提交 993c517+后续批）：v0.6.0~v0.7.7/v0.9.0 批量"已排期→已实施"；v0.11 大目标系列登记。
  • REQ-146 真机验收总清：组模型不应盖在未完成验收的屏卡/净化链上；至少清掉 v0.10.2 M3（会话 33 重跑）。（待用户真机执行）
  • 七轮安全加固代码批提交（✅ 2026-08-22 已完成）：验证（cargo test 1376 通过/clippy/前端构建）后拆 6 个原子 commit 提交（安全/重构/文档分域）。

Step 1：Phase 1a — 组数据模型与 terrain 标记（原子层）

  • note_groups 表：terrain（container/feed）、source（溯源）、domain_tag、kind（课程组/主题组/独立组）
  • notes.group_id（ensure_column 幂等迁移，项目惯例）
  • 结构密度路由纯函数：信号已全部就绪——形态 unknown 比例、画面档位、章节密度、OCR 文本密度、DomainTag 命中度，加权投票复用 vote_detect 范式；输出 自成一组 | 归主题组 | 建议（待确认）
  • 单测先行（TDD，golden 路由用例）
  • 决策点：路由误判是 ★★★★ 死法——路由结果可见可改（组卡片显示路由理由+一键改判），与 v0.9.0 检测卡"修改即记忆"交互哲学一致

Step 2：Phase 1b — 容器侧组化（接线优先，复用存量）

  • 会话→笔记落库时按 series_detect 结果自动归入课程组（兑现 REQ-078，语义升级为"容器组"）
  • 无系列会话按"结构密度高→自成一组"路由
  • 组列表 UI 按 v4 §7.5 按钟分域：容器组出现在每日视图/会话面；feed 产物只出现在组与结算面
  • 理由：feed 侧连进料口都没有；容器侧组化是对已验收资产的重新组织，风险低、价值立现

Step 3：Phase 1c — feed 进料口 + 碎片身份（功能开关，默认关）

  • 碎片快速捕获：文本 + 图片（剪贴板图片复用 REQ-132 预留）——与 v0.10.0 延后清单 #19"快速捕获"合流，一次建设两处兑现
  • 碎片存储：独立原料层 fragments 新表（不与课程笔记混装是 v4 契约明确要求；碎片不是笔记，身份诚实，防"假燃料"死法）
  • DomainTag 自动归组 + 用户自建主题组（契约一：粒度对齐领域，拒绝大类——判据：一个组能否回答"关于X，我学到了什么"）

Step 4：Phase 2a — 间隔重复引擎（学习循环的地基，L1 最小实现）

v4 §11.2 定位：L1 引擎层（提取优先/间隔调度/动手闭环/内容分型）以闪卡体系为最小实现。设计硬约束（反"动机App化"）：

  • 提取优先为默认（P4/P18/P25/P30 同原则）：一切复习"先回忆再看"，不做被动重读
  • 调度器选型 FSRS（SM-2 降级）（2026-08-22 用户提议采纳）：FSRS-6（fsrs-rs crate，Anki 23.10+ 默认调度器）——DSR 三变量模型（难度/稳定性/可提取性）基于遗忘曲线实证研究，按目标留存率反解间隔，大规模真实数据验证优于 SM-2；crate 为纯算法实现零网络依赖，契合本地优先；默认参数开箱即用，个性化参数优化是复习数据积累后的远期扩展（数据不出本机）；若依赖引入受限则手写 SM-2 纯函数兜底（调度接口不变）；v0.11.2 启动时补 ADR（依赖引入属技术决策）
  • 调度服务于飞轮而非打卡 KPI：调度逻辑纯函数化（AGENTS.md 明确列为关键纯逻辑必须单测）；弹性承诺——周契约替代连续 streak，断签不清零（N10 归零暴政防御）
  • 组→闪卡生成：先本地规则版（structure_note.rs 词汇表块、glossary、重点候选直供），AI 生成为可选增强（复用 ai_client 授权/成本/审计全套）
  • 绑定粒度从一开始就是"组"，不经历"会话级→再提升"的返工
  • 内容分型预埋（N13）：事实→卡片先做；动作→练习、心智模型→重建留接口不做

Step 5：Phase 2b — 组级复习/自测界面 + 过程指标埋点

  • 复习面按组组织（容器组与碎片组同一界面同一循环——融合点的最终兑现）；UI 保持最小（动机App化防御：引擎先有真牙，叙事后置）
  • 主题自测（碎片组最小验证：碎片闪卡质量是否够用；隐性错误模型 N14 只留"追问为什么"的最轻形态）
  • 同步埋点（v4 §8 精确清单）：碎片升级率（碎片→闪卡比例）、组结算执行率、主题组活跃数、北极星读数（组有复习记录＋自测记录＋经历过结算）——Phase 4 的门控判据，必须从第一天就记

Step 6：Phase 3 — 组结算机制（L3 骨折层的组级版）

  • Pre-mortem 最高危项之一（组沼泽化 ★★★★★）；v4 §11.2 定位：毕业结算（N21＋P15）的组级实现
  • 阈值/周期触发器 → 结算向导（核心提炼复用 AiRefine 协议、重复合并复用去重纯函数、低价值归档）
  • 结算必须是用户可见的仪式而非静默后台——沼泽化的本质是用户不再回访组（N24 学期结算蒸发的组级防御）

Step 7：Phase 4 — 测量层增强（门控，默认不启动）

  • 显影报告/盲测仪器/常模库（feed 测量基座，v4 §7.3）只在 Step 5 碎片升级率数据验证通过后评估
  • 重资产（技能地图/常模库均标"高成本"），当前不排期

三、依赖图与顺序逻辑

Step 0 账务清算（需求池同步 + 验收总清 + 七轮代码批提交）
        ▼
Step 1 组模型+路由（原子层，TDD）
        │
        ├───────────────────────┐
        ▼                       ▼
Step 2 容器侧组化（存量接线）   Step 3 feed 进料口（新建，开关关闭）
        └───────────┬───────────┘
                    ▼
Step 4 间隔重复引擎（最大新建块，L1 最小实现：提取优先+弹性承诺）
                    ▼
Step 5 组级循环 UI（最小化）+ 北极星/过程指标埋点
                    ▼
Step 6 组结算（L3 组级版，防沼泽仪式）──► Step 7 测量层（门控）

三条判断依据（与 v3 版一致，v4 强化）：

  1. 先容器后 feed：容器资产已验收、组化是重组不是新建；feed 连进料口都要新建，且 v4 §11.3 裁决 feed 默认关闭。
  2. 学习循环（Step 4/5）是真正的瓶颈：Phase 2 名为"统一"，实为"从零建闪卡体系并直接按组粒度建"。既是工作量峰值也是融合成败分叉点（契约二），排在组模型之后立刻启动，不拖到组结算之后。
  3. 指标埋点与功能同批交付：v4 统一北极星和三个过程指标是 Phase 4 的门控判据，也是"强行融合"与"动机App化"两大死法的早期探测器，晚埋一个版本就少一个版本的真实数据。

四、裁决记录（2026-08-22 用户裁决）

# 事项 裁决
1 建设顺序是否采纳 全盘采纳（Step 0~7）
2 Step 0 的执行人与时间 代理先行（需求池同步即刻执行；REQ-146 真机验收需用户操作真机；七轮代码批提交待验证后提交）
3 首个实施版本立项 v0.11 = 大目标版本系列（用户裁决 2026-08-22：Phase 1-3 分四个小版本）：v0.11.0 笔记组基建·容器侧（REQ-195~198 已登记）→ v0.11.1 feed 进料 → v0.11.2 学习循环统一 → v0.11.3 组结算；Phase 4 门控另议不预占版本号
4 弹性承诺（周契约/断签不清零）是否首版做 首版做——N10 归零暴政防御从设计源头部署；streak 数据结构后补改造成本高