Skip to content

v0.13.md

Latest commit

 

History

History
178 lines (136 loc) · 23 KB

v0.13.md

File metadata and controls

178 lines (136 loc) · 23 KB
Raw

v0.13 大目标版本系列：知识体系层（方案 B）

状态：v0.13.0 已交付；v0.13.1 代码已交付（2026-08-23，M1-M3，真机验收待执行）；v0.13.2~4 已立项（仅系列规划与 REQ 登记，设计规格未写、开发未启动）；v0.13.5 已立项（规划）；v0.13.6 已交付（2026-08-23，全量 M1-M5，设计规格 + 代码；真机验收待执行）；v0.13.7 代码已交付（2026-08-24，上手路径：入口补全 + 具象化，设计规格已批准；真机验收待执行）；v0.13.8 代码已交付（2026-08-24，画布可视化：React Flow 节点式无限画布，设计规格已批准；真机验收待执行）；v0.13.9 代码已交付（2026-08-25，笔记编辑修复 + 问题树层级 + 画布链接与接线修复批，设计规格已批准；真机验收待执行）；发布门控：REQ-146 真机验收（组级学习循环通过） 依据：整合分析·方案 B（[ ] 已归档）（已裁决：B 模块新增型＋全局/领域双层＋保持定位局部修订理念）· 竞品调研（[ ] 已归档）（零竞品带＝应用/决策层）· 品类深化调研（[ ] 已归档） · 指南原文（[ ] 已归档）（源文档）· 用户裁决（2026-08-23）：落位 v0.13 系列并执行 里程碑：① v0.13.0 理念修订批 ✅（ADR-024 已接受＋pain-points-v4 §7.6＋需求池 REQ-029；product-design-philosophy 修订＝原则 4 表格/原则 5/§6.1 图/§6.4 节/§七 防线行，与知识体系设计理念文档同批提交） ② v0.13.1 设计规格 ✅（2026-08-23-v0.13.1-knowledge-system-foundation-design.md）

一句话

结构在问题里的，成为体系——组回答"我在学什么"，体系回答"我为什么学、学了怎么用"；体系只引用、不收纳，组仍是唯一容器。

系列总览

小版本 范围 交付内容（预估）
v0.13.0（✅ 已交付 2026-08-23，无代码） 理念局部修订 ADR-024（已接受：有界体系通过、自由双链/图谱仍出局）＋pain-points-v4 §7.6 P13 加注＋需求池 REQ-029 联动备注；product-design-philosophy（原则 4 表格 P13 重裁决＋体系≠工作区边界句；原则 5 学习链＋体系枝；§6.1 模块关系图）修订已编入工作区文件——随预存 v4 理念更新批提交
v0.13.1（✅ 代码已交付 2026-08-23，M1-M3；真机验收待执行） 结构层 knowledge_systems/nodes/concepts/models/links/audits schema（db_migrations 惯例）＋体系/节点/概念/模型 CRUD 命令＋全局体系创建向导（极简启动模板：核心问题一句→3-5 领域入口→本周第一个输出）＋领域体系；纯函数 TDD：audit_due/concept_stale/promote_rules；REQ-202~205；设计规格
v0.13.2 概念双面体 思辨×记忆 flashcards.kind='model' 落地（卡面契约：front=概念名，back=三问（本质/边界/联系）＋锚点回链——延迟揭示＝必要难度）＋卡→概念升格（回填三问；AI 可选增强默认关）＋概念库 UI（三问一用卡片：本质/边界/联系/最近应用）；REQ-206~207
v0.13.3 决策与应用 应用闭环 knowledge_decisions 一表两面（kind=decision/application：内容/预期/实际/反思 四行＋used_refs 引用必填）＋入口：概念页/组/复习面"记一次使用"＋决策日志 UI＋metrics_events 扩展（concept_promoted/decision_logged/application_logged/system_audited）；REQ-208~210
v0.13.4 审计与整合 反馈环 体系审计（季度触发复用 settlement_due 范式；审计清单＝指南附录 D 六项）＋组结算第三步增强（概念失效检查：180 天未应用→待观察/归档建议）＋交叉点派生提示（概念被 ≥2 领域引用时提示，默认关）＋审计报告视图（思辨动作 vs 学习动作并列，诚实）；REQ-211~212
v0.13.5（立项 2026-08-23） 书籍笔记组＋知识树附加（方案 C） books 元数据壳（group_id UNIQUE——一本书＝一个组；不存书内容）＋note_groups.kind='book'＋书籍组卡片（书名/作者/状态/评分）＋体会模板（含"应用"字段）＋体会→应用记录/升卡接线（复用）＋知识树节点/概念"附加书籍"区（link 复用，树侧零 schema）＋阅读状态生命周期与 book_stale 审计联动；REQ-213~218；规划 §
v0.13.6（✅ 已交付 2026-08-23，全量 M1-M5；设计规格（[ ] 已归档）） 视频档案分类细化＋修复批 形态 7→10（新增会议/直播/影视——挂既有模板）＋领域两层（粗 15→20：美食/摄影视频/历史人文/写作阅读/数码硬件；细目 curated 84 项多选 chips）＋检测链升级（平台分区映射表＋词表扩展＋细目种子 hotwords 细分＋领域记忆）＋修复批（add_knowledge_node 契约 type→nodeType；笔记编辑完成即时刷新）；REQ-219~223；用户裁决"是 全量"
v0.13.7（✅ 代码已交付 2026-08-24，真机验收待执行；设计规格（[ ] 已归档）） 体系上手路径 入口补全三触点：组行体系徽标（GroupSidebar + SystemBadge）/ 笔记详情「挂到体系」（NoteLinkToSystem，修复手工输 id 断点）/ 结算体系简报（RouteInfoPopover 两行只读提示）；具象化：摄影示例体系（knowledgeSample 浏览 + 一键复制，全局前置检查）/ 向导内嵌「例如」参照行；纪律裁决：示例≠预填（假燃料纪律局部修订）；全部前端零新命令；M1→M3
v0.13.8（✅ 代码已交付 2026-08-24，真机验收待执行；设计规格（[ ] 已归档）） 画布可视化 React Flow 节点式无限画布（@xyflow/react）：问题/概念/模型三类自定义节点 + 父子连线 + MiniMap/Controls；辐射布局初始位置（BFS 算法，用户拖拽后不再自动排布）；canvas_x/y 两列 + knowledge_canvas_states 表；4 条新命令（update_node_canvas_position/batch_initialize_canvas_positions/save_canvas_viewport/get_canvas_viewport——规格列 3 条但视口恢复需读路径，复盘补第 4 条闭环，见交付记录）；树视图↔画布浮钮切换；REQ-029 力导向图仍 P3 维持（画布=手动画布非自动图）；M1→M3
v0.13.9（✅ 代码已交付 2026-08-25，真机验收待执行；设计规格（[ ] 已归档）） 笔记编辑修复 + 问题树层级 + 画布链接与接线 H1 跳顶修复：headingLines 纯函数逐行转标题（多行全选不再只首行生效）+ 可视区定位（滚动后未聚焦时插入落在"正在看的行"，所见即所得）；问题树层级：depth 驱动缩进 16px/层 + 树状引导线（折叠随子树隐藏）；画布体系根卡：领域体系=体系名卡（新增 systemName prop）+ 根节点虚线连入 core（展示层虚拟边不落库；修复 autoLayout 漏加 core 卡的遗留 Bug）+ 节点类型 chip（❓问题/🎯场景/📂领域入口，与树视图同口径）；接线动态化：四边 Handle + resolveEdgeHandles 按源/目标相对方位选接入方向（移动后接线随方位变化）+ RING_STEP 200→160 缩短长边；全部纯前端零 schema 零新命令；M1→M3

关键决策与纪律

  • 体系只引用、不收纳（引用不复制，与笔记引用原料同一条纪律）：体系无内容入口——碎片/笔记/卡只能先落组，再被体系引用（knowledge_links）。
  • 双面体单向升格：闪卡（组内，记忆面）→ 概念（体系，思辨面）单向；概念→卡不反向。杜绝"概念卡与闪卡重复记账"。
  • 一表两面：knowledge_decisions 用 kind 区分 decision/application——决策=思辨面，应用=学习面（动手闭环 N12 最小环），不双表双记。
  • 只记"我的决策"：产物层 ArtifactKind::Decision（内容里的决策）禁止自动升格（假证据）；used_refs 引用非空才计入指标（防记录膨胀）。
  • 审计＝体系级结算：与 settlement_due 同范式；审计产出建议、用户确认后生效——无 streak、无惩罚继承（弹性承诺纪律延续）。
  • 门控：REQ-146 真机验收总清（组级学习循环通过）为前提——引擎未验收不建上层（假燃料放大器死法）。
  • 开关：体系默认开（叙事层主枝）；交叉点派生提示默认关；AI 增强（卡→概念回填）默认关。
  • 不做图可视化：体系用树＋列表渲染；REQ-029（知识图谱可视化）维持 P3（Heptabase 已占"图谱"心智，且 P13 出局）。
  • 无新北极星：北极星＝组学习循环完成＋第二组启动率不变；新增观察指标：第一体系创建率/审计执行率/决策引用率/概念升格率。
  • AI 测量，人类见证：ai 只做补缝与提示（三问回填建议、审计建议），不做自动写决策/自动建体系（假燃料）。
  • 示例 ≠ 预填（v0.13.7 裁决）：预填=把内容写进用户输入框（假燃料，禁止）；示例=用户可见的完整参照物（真燃料，允许）。浏览示例是被动的；复制示例是主动的（一键获得骨架，改不改由用户决定）——复制后体系处于"待改造"状态，不是"已完成"状态。
  • 演进候选（v0.13.9 登记）：画布体系根卡当前为展示层虚拟边（core 虚拟节点，不落库）；「根节点真实化」（knowledge_nodes type='root'，体系名/核心问题迁移为真实节点，画布/树视图/引用全链路统一）为 v0.14 候选——需 ADR + schema 迁移，本次不动。

数据模型增量

（完整 SQL 见整合分析 §四.2；db_migrations.rs 惯例：建表幂等＋ensure_column；零破坏原则）

knowledge_systems(id, parent_system_id→self, name, kind global/domain, core_question, status, created_at, updated_at)
knowledge_nodes(id, system_id, parent_id, type question/scenario/domain_entry, text, order_idx, status, created_at)
knowledge_concepts(id, system_id, name UNIQUE(全局唯一→交叉点判定), essence, boundary, relation,
                   status core/watching/archived, last_applied_at, created_at, updated_at)
knowledge_models(id, system_id, name, disciplines JSON(≥1 学科), claim, valid_when, invalid_when,
                 cross_checks JSON(交叉验证记录), status, created_at, updated_at)
knowledge_decisions(id, kind decision/application, system_id?, question_id?, used_refs JSON(引用必填),
                    content, expectation, actual, reflection, decided_at, created_at)
knowledge_links(id, system_id, node_id?, concept_id?, model_id?, target_type note_group/note/flashcard/fragment,
                target_id, created_at)          -- 引用层；组仍是唯一容器
knowledge_audits(id, system_id, items_json(附录D 六项), stats_json(失效数等), created_at)
-- 既有结构不动：flashcards.kind 补值 'model'（REQ-199 预埋）；metrics_events.kind 新增 4 值

市场依据摘要（详见竞品调研）

  • 五层竞品地图中"提取→记忆→应用→决策"完整闭环无人做；整合型「决策日志/审计＋概念引用」为零竞品带（孤立决策日志 App 存在，见知识体系类软件调研（[ ] 已归档））。
  • 最像样对手：Ai好记（整理端，无 SRS/无组循环/云端）；NotebookLM（免费 AI 问答冲击，无 SRS/无本地/无应用闭环）；思源笔记（本地优先＋闪卡，无视频提取/无组循环）。
  • 定价锚点：国内"免费核心＋年付会员 ¥100–300"；转写按量（本地优先的价值论据）；obsidian "免费核心＋增值"，Anki 免费开源——v0.13 只留定价桩不实现商业化。
  • 应战定理：不与之比"AI 问答多聪明"，比"被 AI 问"（成为隐喻）＋人类判断领地（体系层）。

测试与验证

  • 纯函数全 TDD（AAA＋golden）：audit_due（阈值/周期边界）、concept_stale（90/180 天边界）、promote_rules（卡→概念升格规则：同名合并/跨体系提示/幂等）、四行法字段校验、used_refs 引用校验。
  • 数据层 :memory: 库；command 层仅参数校验与编排（AGENTS.md §6）；模型零依赖。
  • 前端 vitest：三问一用卡片渲染（延迟揭示）、审计清单交互、决策日志表单（引用选择器）。
  • 真机走查（REQ-146 批）：创建体系→挂组→概念升格→记一次使用→季度审计→交叉点提示 全链路。

边界（不做清单）

体系图谱可视化（力导向图）· 跨体系自由引用（图谱化入口）· 全局概念库收纳内容 · AI 自动生成决策/概念 · 决策质量评级 · 领域体系嵌套 · 承接 REQ-030（学习计划系统）· 承接 REQ-029（仅数据结构可视化补充，P3 维持）· 移动端 · 内容供给 · 社交/见证结构 · 商业化（会员/云同步）落地

后续门控

  • 应用记录/决策日志数据（decision_logged/application_logged）为 Phase 4 测量层（显影报告"应用率"维度）新增输入——从 v0.13.3 第一天积累。
  • 交叉点提示若数据反映有效（升格率/引用率），v0.14 评估转正默认。
  • 体系审计执行率低于基线时，评估"体系沼泽化"防御加强（降级引导强化，不增加打扰）。

v0.13.5 规划：书籍笔记组与知识树附加（方案 C，2026-08-23 用户决策立项）

状态：已立项（规划 2026-08-23） 来源：个人电子图书馆调研（"管书"与"助学"断裂带）＋用户脑暴裁决：知识树附加书籍／书籍笔记组／体会模板"应用"字段／阅读状态生命周期／交叉点复用／生成效应升卡 定位：书籍 = "证据＋体会"——不存书内容（版权/存储负担/内容供给红线零触碰），只存用户体会（自己产出＝生成效应，记忆深 2-5 倍）；与 Readwise 的隐喻分界：它存高亮（书的内容片段），熵减存"书对我的改变"——"书→判断"贯通正是竞品空白带

一、范围（方案 C 组合：实体在组、展示在树）

1. 数据层

-- note_groups.kind 扩展 'book'（现有 kind 无 CHECK，command 层白名单+1 即可）
CREATE TABLE IF NOT EXISTS books (            -- 元数据壳，不存内容
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  group_id INTEGER NOT NULL UNIQUE REFERENCES note_groups(id) ON DELETE CASCADE,
  title TEXT NOT NULL,
  author TEXT, isbn TEXT,
  status TEXT NOT NULL DEFAULT 'reading',     -- toread/reading/finished/abandoned
  rating INTEGER,                             -- 1-5，可选
  lesson TEXT,                                -- 一句话"这本书对我的意义"
  created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
);

2. 命令（commands_books.rs）

  • create_book_group(title, author?, isbn?, status?)——事务：建 kind=book 组（组名＝书名）＋ books 行
  • update_book_group(group_id, title?/author?/isbn?/status?/rating?/lesson?)；list_book_groups(status?)
  • 删除＝走既有组归档路径（不删数据）；体会＝组内手动笔记（复用既有笔记创建/编辑），零新命令

3. 体会模板与接线（复用优先）

  • 前端"写体会"模板：这本书改变了我哪个判断？/ 我打算怎么用？（应用字段，可空）＋常规体会正文
  • 应用字段 → "记一次使用"：一键复用 v0.13.3 knowledge_decisions(kind=application)（content=应用字段，挂概念/问题）——"书→判断"贯通
  • 升卡/复习：复用 generate_group_cards（组→卡，v0.11.2 已就绪）＋复习面/周契约对书组天然生效——零新代码
  • 元数据拉取（书名/ISBN→作者/封面）＝可选增强，默认关（纯元数据，无版权问题，v0.13.5 只留桩不做）

4. 知识树附加书籍（方案 C 展示层，树侧零 schema）

  • 节点/概念详情面板新增"附加书籍"区：list_knowledge_links(target_type=note_group) ＋ 书籍元数据 JOIN 渲染书卡（书名/作者/状态徽标/体会计数）
  • 添加＝复用 link_knowledge_target（选已有书组或现场新建书组）；交叉点：一本书挂多个问题→v0.13.4 交叉点提示自动适用（零新代码）

5. 阅读状态生命周期与审计联动

  • 状态机：toread → reading → finished / abandoned（command 白名单校验）
  • book_stale 纯函数（复用 concept_stale 范式）：finished 书组 90 天无访问 → 审计提示"这本书还在影响你吗？"（可写新体会、归档或标记"已不再影响"）；随 v0.13.4 审计清单展示（书版沼泽化防御）

二、边界（不做清单）

书籍内容导入/格式转换/阅读器 · 全文检索（没有内容可检）· 书评社交 · 周阅读目标（≈学习计划 REQ-030，另议）· 书库管理（Calibre 已占位）· AI 摘要书评（获取隐喻；AI 只做建议）· 移动端

三、测试与验收

  • books：事务建组＋group_id 唯一约束／状态白名单／rating 1-5 / title 非空
  • 纯函数：book_stale（90 天边界，AAA＋golden）；体会模板"应用字段"解析（可空/多行/含引号转义）
  • 接线：应用字段→application 记录（v0.13.3 复用）；书组→generate_group_cards 幂等；link_knowledge_target 挂书组校验
  • 前端 vitest：书籍卡渲染（状态徽标）／节点面板附加书籍区挂接／体会模板表单
  • 真机走查：建书组→写体会（带应用）→挂问题树→升卡复习→（审计）"这本书还在影响你吗？"提示

四、需求登记

REQ-213 books 表＋note_groups.kind='book' 扩展 · REQ-214 书籍组 CRUD 命令＋组卡片（元数据/状态徽标）· REQ-215 知识树"附加书籍"（节点/概念面板＋挂接）· REQ-216 体会模板（应用字段）＋应用记录接线 · REQ-217 阅读状态生命周期＋book_stale 审计联动 · REQ-218 体会升卡与复习（复用接线＋书组徽标）

v0.13.8 交付记录（2026-08-24）

交付范围＝设计规格全部 M1→M3（画布可视化）；详细测试口径见根目录 CHANGELOG。

一、与规格的差异登记（实现裁决）

差异 内容 理由
命令数 3 → 4 增补 get_canvas_viewport（只读） 规格 §4.5 要求"切回画布时视口恢复"，§4.6 只列 save——恢复需要读路径，无读命令则 knowledge_canvas_states 无法生效（写死数据）。第 4 条为规格遗漏的闭环补全，非新需求
概念/模型位置不持久 仅 knowledge_nodes 有 canvas_x/y；概念/模型每次打开按辐射布局重排并置 draggable:false 规格 DB 变更只给 nodes 两列（§4.6）；浮动参照无存储列，拖了不持久——禁拖防"拖了没反应"困惑
核心问题虚拟节点 coreQuestion 存在时圆心渲染不可拖/不可选的核心卡（非 DB 实体） 规格 §4.4 步骤 2 允许"coreQuestion 虚拟节点在圆心"；渲染侧实现，不落库（零破坏）
自动排列按钮语义 触发全量重算 + 批量覆盖 + fitView 规格 §4.4 明确"用户想重置布局可点自动排列（覆盖已存位置）"
缩放分级边界 >0.7 全文 / 0.4~0.7 仅标题 / <0.4 缩略卡 规格 §七（React Flow zoom 量纲 1=100%）

二、交付清单

  • M1 数据层：db_migrations 幂等——knowledge_nodes 补 canvas_x/canvas_y（新库建表内联 + 旧库 ensure_column，零破坏 §二.3）+ 新表 knowledge_canvas_states（system_id 1:1，upsert 覆盖）；db_knowledge_canvas.rs（单写/批量事务写入/视口读写）+ types.rs 扩 KnowledgeNode.canvas_x/y（serde default 兼容旧 JSON）
  • M1 命令层：commands_knowledge_canvas.rs 4 命令——坐标有限值（拒 NaN/Infinity）、zoom (0,10]、batch 全量预校验（体系归属/重复/缺失→原子拒绝，零部分写入）
  • M2 纯函数（TDD，8 golden）：layoutRadial（BFS 辐射：核心问题虚拟圆心／首根圆心；ring1=220px 每环+200px；环≥2 父角度扇区 spread=60°/(子数+1)；碰撞沿角度+50px 最多 2 次后下一环；孤儿/概念/模型 golden angle 确定性兜底——零随机零 React 可复现）
  • M2 前端：canvasElements（实体→RF 元素纯转换：q/c/m 前缀 key、parent_id→smoothstep 边、links→概念/模型徽标+引用计数）；三自定义节点（缩放分级 §七）；KnowledgeCanvasView（ReactFlow+MiniMap+Controls+工具栏；拖拽防抖保存/视口防抖保存/切回 setViewport 恢复/未存 fitView 兜底/首次缺位批量初始化）；KnowledgePage「🗺 画布」标签 + 树视图「🎨 画布」浮钮双入口（§4.5）——树常驻 display 切换（折叠展开保持），画布激活才挂载（首次切换语义精确；视口恢复走持久化）
  • 不做（§九 全守）：画布新建/编辑节点、手动连线、节点颜色自定义、导出图片、框选批量移动、移动端、AI 建议布局、力导向图（REQ-029 P3 维持）

三、验证

  • cargo test --test app_lib_tests knowledge：151/151 全绿（本版新增 11：命令 8 + 数据层 3）
  • 全量 cargo test --test app_lib_tests：1721 passed / 3 failed（预存基线：ai_client 默认 Provider 断言旧 SiliconFlow、note_filter 两条黄金用例——v0.12.4/v0.13.1 已登记，与本版无关）/ 6 ignored
  • clippy：本版新增文件零警告（预存警告 3 条与本版无关）
  • tsc --noEmit 零错误；vitest 34 文件 189 用例全绿（新增 layoutRadial 8 / canvasElements 7 / CanvasNodes 6 / KnowledgeCanvasView 10 / KnowledgePage 画布入口 2）；vite build 通过
  • 审查轮（新增代码七维审查）：接入/牵连/性能/冗余/规范/安全通过；逻辑性高×1（树↔画布往返重挂载时辐射布局重算覆盖已拖走位置——违反 §4.4 "位置只由用户决定"）/ 中×1（框选批量移动仅主节点持久化，回弹不一致）/ 低×1（测试 mock 死分支）全部即修 6464abd + 重挂载回归测试；观察 3 项登记不立债（浮点尾差、update 无体系校验——以规范为准、双枚举保留理由）
  • 真机走查（REQ-146 批）：创建体系 → 点「画布」→ 辐射布局出现 → 拖拽节点 → 切树/切回视口恢复 → 自动排列 全链路待执行