Skip to content

ADR-027-goal-layer-modeling.md

Latest commit

 

History

History
46 lines (31 loc) · 5.38 KB

ADR-027-goal-layer-modeling.md

File metadata and controls

46 lines (31 loc) · 5.38 KB
Raw

ADR-027：学习目标层建模——意图层对象（N:M / 判据配方 / 四态状态机 / 库即记忆）

状态：已接受（2026-09-02，随 v0.18.0 M1 实施批补登） 关联：v0.18 设计规格（已批准，[ ] 已归档） · v0.18.0 版本文档 · REQ-030 激活/REQ-248~250 · ADR-010（AI 为增强层·本地兜底铁律）· ADR-018（FSRS 调度）· ADR-024（知识体系层）

背景

提取管线（v0.1~0.9）、学习循环（v0.11：FSRS/周契约/组结算/指标）、知识体系层（v0.13）、AI 平台（v0.11.6/v0.16/v0.17）均已交付——但缺「意图轴」：用户「我要学 Python」没有对象化，周契约/组结算/概念升格各自为政，AI 对话没有意图上下文可注入。2026-09-02 用户裁决：目标层按意图层建模（不并入知识体系层、不接 agent 框架/记忆模块），本 ADR 补登数据建模与硬约束。

决策

  1. 目标＝组的容器（N:M）：组仍是唯一容器（v4 契约二不破）。goals 主表 + goal_milestones（判据型里程碑）+ goal_groups（UNIQUE(goal_id, group_id)）三表；组删除走既有 CASCADE 纪律——goal_groups 级联清、goal_milestones.ref_group_id SET NULL（绑定该组的 group_settled 里程碑降级手动确认，提示 UI 属 M2）。
  2. 判据配方＝快照：success_criteria_json（tier 档位展开为可观测信号要求值：组结算历史数/应用记录数/自测通过率（M1/M2 占位不判定）/近 90 天复习活跃天数），毕业后冻结；进度信号一律现算（聚合皆毫秒级 SQLite），目标层零进度副本/零缓存（优化评审 #1：缓存层是过度设计）。
  3. 四态状态机无 draft：active⇄paused、active→graduated（毕业仪式用户确认，M2 落 goal_settle 写快照）、active/paused→abandoned（显式动作+可选原因，无惩罚）；grad/abandon 为终态（无复活——弹性承诺的放弃不追责也不回滚）。
  4. 库即记忆（预算硬约束）：唯一事实源=本地库；AI 无记忆模块/无状态/无缓存层，每次调用经「检索管道」（L1/L2/L3 + L4.5 目标摘要每次现算）取现拼；调用成本与库规模解耦——上下文预算档位化（轻量 ~4K/标准 ~10K/深度 ~30K，默认标准），检索点查代替全量注入（库增长 O(N)、调用成本 O(1)）；深读/跨片段综合走「先预估后确认」（复用 ai_refine_estimate 范式）。
  5. M1/M2 零 AI 代码：goal_interview/progress/rules 全部本地纯函数；AI 教练（目标摘要注入/复盘/追问/概念低激活弱项/图片影子缓存）严格属 M3 且默认关（content_gate 双闸门）；生成式复习（REQ-021）单独立项。

备选（否决）

  • agent 记忆模块/自主规划（裁决引用）：本地 SQLite 即比任何 agent 记忆更可靠的长记忆（结构化/版本化/可审计/不出本机）；agent 循环不可确定性 vs 项目可测试性与防御性降级两条铁律；桌面单用户无多代理编排需求。
  • 目标嵌入体系层（知识结构=意图）：体系层是「知识结构」（概念/模型/决策），目标是「意图轴」（要成为什么）——分开建模，概念库不塞进目标（意义链 ≠ 体系）。
  • 目标进度缓存列/派生表：读少写多 + 现算毫秒级，缓存/物化引入双写一致性风险（优化评审 #1 采纳删除）。
  • 目标间依赖/优先级图、FTS5 检索重排、AI 动态自适应预算：YAGNI/不可测（优化评审主动排除）。

影响

  • 正向：学习循环获得意图上下文（"被 AI 问"的原料）；里程碑有客观判据信号（结算历史/FSRS 弱项/应用记录）；本地优先零云端依赖（M1/M2 全本地）。
  • 代价：三表 + 一处既有模块最小钩子（execute_settlement 后自动通过 group_settled 里程碑——目标层为只读聚合+事件钩子，不侵入结算状态机；钩子失败仅记日志，结算仪式不因目标层失败）。
  • 兼容：新表幂等建表（旧库升级零破坏）；notes/groups/settlements/flashcards/review_logs/contracts/knowledge_decisions 只读复用不加列；metrics_events.kind 补值式扩展（既有读取不受影响）。

合规性验证

  • 三表 :memory: CRUD + 组删除 CASCADE 行为测试（绑定消除/ref SET NULL/里程碑保留降级手动）
  • 判据配方 table-driven golden（6 条端到端 + 参数矩阵）；四态状态机 16 对转移矩阵 + 终态守卫（重复毕业/放弃后毕业非法）
  • 进度聚合边界测试（0 结算/历史计数/周契约双达标/90 天窗口/弱项占比与排序/应用记录 GROUP 引用命中）
  • 回归：cargo test / clippy 零警告 / vitest / tsc 全绿（v0.18.0 验收 9）

相关决策

  • ADR-010（AI 为增强层·本地兜底铁律）· ADR-018（FSRS 调度——弱项信号 state_json 读取）· ADR-024（知识体系层——本 ADR 与其明确划界）· ADR-026（AI 精修策略化——预算估费范式复用）

参考