docs: 建立LPT概念与设计文档

2026-08-05 23:28:52 +08:00
commit 9d80275ef3
20 changed files with 586 additions and 0 deletions
@@ -0,0 +1,26 @@
+# LPT 文档项目规则
+
+## 职责
+
+- 维护 LPT 系统的概念定义和设计思路。
+- 文档面向系统本身，而不是面向开发过程。
+
+## 保留内容
+
+- 系统概念：学习任务、学习会话、学习预期、知识碎片、学习报告、复习、思维导图、回忆对比等。
+- 设计思路：为什么采用某个概念、概念之间如何协作、模块边界在哪里。
+- 稳定的术语映射：例如“学习报告残片”与“知识碎片”的关系。
+- 所有文档放在 `docs/` 下，`concepts/` 放概念，`design/` 放设计思路。
+
+## 禁止内容
+
+- 开发笔记、日志、个人感想、时间线。
+- 系统中间态、废弃方案、历史迁移过程。
+- 文件路径、代码片段、接口清单、环境配置、构建与部署信息。
+- 性能指标、问题修复记录、交付记录。
+
+## 更新流程
+
+- 概念变更时先更新对应概念文档，再更新术语表和设计文档。
+- 新增概念时按现有模板补充“定义、设计意图、相关概念、当前系统体现”。
+- 修改后同步 meta 仓库 `docs/README.md` 的文档地图。
@@ -0,0 +1,24 @@
+# LPT 概念与设计文档
+
+> 更新日期：2026-08-05
+
+本项目只维护 LPT（Learning Progress Tracker）的系统概念与设计思路，不保存开发记录、系统中间态或开发过程中的中间产物。
+
+## 文档结构
+
+| 目录 | 内容 |
+|------|------|
+| `docs/concepts/` | 系统概念的定义、设计意图和概念间关系 |
+| `docs/design/` | 贯穿多个概念的设计思路与模块边界 |
+
+## 阅读路径
+
+1. 从 [系统总览](docs/concepts/overview.md) 了解系统要解决的问题和核心闭环。
+2. 从 [术语表](docs/concepts/README.md) 查找具体概念。
+3. 需要理解“为什么这样设计”时阅读 `docs/design/` 下的文档。
+
+## 维护规则
+
+- 只保留“这个概念是什么、为什么存在、与哪些概念关联”的描述。
+- 不加入开发时间线、问题排查、环境配置、代码位置、提交记录或性能指标。
+- 新增或修改概念后，同步更新术语表和本文档。
@@ -0,0 +1,18 @@
+# 术语表
+
+以下是系统稳定使用的概念。每个概念都只在描述系统内容和设计意图，不包含开发过程。
+
+| 概念 | 一句话定义 | 详细文档 |
+|------|-----------|----------|
+| 学习任务 | 一份学习材料或学习目标对应的最小可管理单元 | [学习任务](learning-task.md) |
+| 学习会话 | 针对某个学习任务的一次连续学习过程 | [学习会话](study-session.md) |
+| 学习预期 | 开始学习前对本次学习目标的描述 | [学习预期](learning-expectation.md) |
+| 知识碎片 | 学习中随手记录的不完整内容，也称“学习报告残片” | [知识碎片](knowledge-fragment.md) |
+| 学习报告 | 一次学习结束后汇总出的完整学习结果 | [学习报告](learning-report.md) |
+| 有效学习时间 | 学习会话中未暂停的实际投入时间 | [时间与效率](time-and-efficiency.md) |
+| 任务优先级 | 由多个维度综合计算出的学习任务排序依据 | [任务优先级](priority.md) |
+| 应用场景 | 学到的知识可以被使用到什么地方 | [应用场景](application-scenario.md) |
+| 复习 Feed | 滚动展示知识碎片和学习报告的记忆触发物 | [复习 Feed](review-feed.md) |
+| 标准思维导图 | 每个学习任务对应的知识结构基准 | [标准思维导图](standard-mind-map.md) |
+| 回忆对比 | 用户凭记忆重建知识结构并与标准导图比较 | [回忆对比](recall-review.md) |
+| AI 任务 | 系统借助 AI 完成报告聚合、导图生成和语义对比 | [AI 任务](ai-task.md) |
@@ -0,0 +1,27 @@
+# AI 任务
+
+## 定义
+
+AI 任务是系统使用 AI 完成的三类学习处理能力：
+
+- 聚合报告：把知识碎片整理成学习报告草稿。
+- 生成导图：从报告、碎片和应用场景中提取标准思维导图。
+- 回忆对比：对用户回忆与标准导图进行语义层面的比较。
+
+## 设计意图
+
+AI 用于降低用户的书写和整理负担：
+
+- 报告不必从零开始写，AI 先给草稿，用户再修改。
+- 导图不必用户手工搭建，AI 可以先提取结构。
+- 回忆对比可以容忍同义表达，而不只是机械文字匹配。
+
+## 设计思路
+
+AI 是增强能力，而不是单点依赖。AI 不可用时，系统应能用内置规则继续完成报告拼接、导图生成和字符串匹配，保证核心学习流程不中断。
+
+## 相关概念
+
+- 学习报告：AI 聚合碎片的产出。
+- 标准思维导图：AI 生成或增量更新的对象。
+- 回忆对比：AI 负责语义匹配的环节。
@@ -0,0 +1,19 @@
+# 应用场景
+
+## 定义
+
+应用场景描述一个学习任务学完后可以被用在哪里，例如“用 Java 并发知识优化项目接口”或“用英语阅读技术文档”。
+
+## 设计意图
+
+复习最自然的动力是“学完的东西能用上”。应用场景把学习目标从“学会”延伸到“用来做什么”，为复习和练习提供真实语境。
+
+## 设计思路
+
+应用场景属于学习任务，而不是复习模块。它更像是任务的最终验收目标：完成整个任务后，用户希望自己具备什么产出能力。
+
+## 相关概念
+
+- 学习任务：应用场景挂载在任务下。
+- 标准思维导图：应用场景参与导图生成，让知识结构与实际用途关联。
+- 复习：应用场景提供“为什么值得掌握这些知识”的上下文。
@@ -0,0 +1,26 @@
+# 知识碎片
+
+## 定义
+
+知识碎片是学习过程中随手记下的不完整内容，系统中也称为“学习报告残片”。它不要求是完整总结，只要求记录刚刚学到、想到或需要记住的内容。
+
+知识碎片是学习记录的主要单元。
+
+## 设计意图
+
+完整报告有仪式感和书写压力，用户不一定每次都有动力写。知识碎片把记录成本降到最低：
+
+- 在休息、暂停或完成一个小阶段时快速记录。
+- 保留学习发生时的上下文。
+- 为学习报告、复习 Feed 和思维导图提供原始素材。
+
+## 相关概念
+
+- 学习会话：碎片在会话中产生。
+- 学习报告：碎片被聚合、整理成完整报告。
+- 复习 Feed：碎片是滚动展示的核心内容。
+- 标准思维导图：碎片参与导图生成，并可追溯到原文。
+
+## 设计思路
+
+碎片不应被要求“整理得非常完美”。它是学习过程的原料，后续由用户或 AI 汇总成更结构化的内容。
@@ -0,0 +1,25 @@
+# 学习预期
+
+## 定义
+
+学习预期是用户在开始一次学习会话前写下的目标描述，例如“理解线程池的核心参数”或“读完第三章并整理要点”。
+
+学习预期在会话开始时必须填写，不能为空。
+
+## 设计意图
+
+学习预期的价值不是“填一个必填项”，而是：
+
+1. 让学习从模糊的“开始学习”变成有目标的行动。
+2. 在会话结束时与“实际学到了什么”进行对照，形成元认知闭环。
+3. 帮助用户判断本次学习是否达到预期，而不是只看学了多少时间。
+
+## 相关概念
+
+- 学习会话：预期属于一次会话。
+- 学习报告：预期用于和实际学习结果对比。
+- 学习任务：多个会话的预期共同反映任务级学习进展。
+
+## 当前系统体现
+
+学习预期在会话页面常驻展示，用户可以随时查看；结束会话时会同时看到预期和实际结果，确认是否达成目标。
@@ -0,0 +1,24 @@
+# 学习报告
+
+## 定义
+
+学习报告是一次学习会话结束后的完整学习结果汇总。它由本次会话产生的知识碎片综合而来，而不是要求用户从零开始写一篇长文。
+
+## 设计意图
+
+学习报告的价值在于：
+
+1. 把零散碎片收拢成一次学习可回顾的结果。
+2. 与学习预期对照，判断学习目标是否达成。
+3. 作为复习材料和标准思维导图的输入。
+
+## 相关概念
+
+- 知识碎片：报告的主要来源。
+- 学习预期：报告中回答“实际学了什么”。
+- 标准思维导图：报告参与导图生成。
+- 复习 Feed：报告也参与碎片化展示。
+
+## 设计思路
+
+降低报告的仪式感：用户的主要书写单元是知识碎片，报告允许先由系统根据碎片生成草稿，再由用户修改确认。
@@ -0,0 +1,30 @@
+# 学习任务
+
+## 定义
+
+学习任务是系统中最小的可管理单元。它通常对应一份学习材料、一个课程或一个明确想掌握的知识领域，例如“Java 并发编程”“英语阅读”或“数据结构”。
+
+一个学习任务至少包含：
+
+- 任务名称。
+- 学习材料的描述或位置信息。
+- 用于参与优先级计算的多个评价维度。
+
+## 设计意图
+
+学习任务承担两个作用：
+
+1. 把零散的学习内容组织成可追踪的单元，让用户知道自己有哪些学习目标。
+2. 作为学习会话、知识碎片、学习报告、思维导图和应用场景的共同挂载点。
+
+## 相关概念
+
+- 学习会话：属于某个学习任务。
+- 知识碎片与学习报告：在一次会话中产生，最终属于该任务。
+- 标准思维导图：每个学习任务对应一份知识结构基准。
+- 应用场景：挂在学习任务下，表示该任务最终能用来做什么。
+- 任务优先级：决定多个学习任务之间的先后顺序。
+
+## 当前系统体现
+
+学习任务拥有可配置的多维度优先级权重，用户可以调整权重后让系统重新排序。应用场景被设计为任务级能力，而不是复习模块的一部分。
@@ -0,0 +1,33 @@
+# 系统总览
+
+## 系统要解决的问题
+
+1. 想学的东西很多，但对自己的学习能力、学习速度和学习投入没有清晰的时间感。
+2. 学习缺少计划与优先级，容易想到什么学什么，忽略真正重要的内容。
+3. 没有复习习惯，学过的内容容易遗忘，也很难判断自己到底掌握到什么程度。
+
+## 系统的基本立场
+
+LPT 是辅助学习的工具，而不是监督学习的 KPI 系统。它帮助用户量化学习、安排优先级、产生复习机会，但不强制用户按某种固定节奏学习。
+
+## 核心闭环
+
+```text
+学习任务
+   ↓
+学习会话（开始前记录学习预期）
+   ↓
+学习中产生知识碎片
+   ↓
+结束后汇总为学习报告
+   ↓
+复习：碎片滚动 → 标准思维导图 → 回忆对比
+   ↓
+应用场景：把学到的知识用起来
+```
+
+## 三条设计主线
+
+- **量化学习过程**：用学习会话、有效学习时间和知识碎片让学习过程可见。
+- **合理安排优先级**：用可配置的多维度权重决定先学什么。
+- **让复习自然发生**：用碎片化提醒降低复习阻力，用思维导图和回忆对比暴露掌握缺口。
@@ -0,0 +1,30 @@
+# 任务优先级
+
+## 定义
+
+任务优先级是根据多个维度计算出的学习任务排序依据，用于回答“接下来先学什么”。
+
+系统使用五个维度：
+
+- 主观判断：用户对任务重要性的直觉。
+- 未来价值：这项知识对长期目标的价值。
+- 内容难度：学习这项内容的困难程度。
+- 必要性：这项内容是否是其他学习的基础。
+- 紧急性：是否存在时间压力。
+
+## 设计意图
+
+优先级不能只靠用户“拍脑门”。多个维度可以暴露用户容易忽略的方面，例如：
+
+- 必要性高的内容往往是其他学习的基础，应该提前学。
+- 紧急性负责兜底，避免真正临近截止的学习内容被长期忽略。
+- 主观判断和未来价值反映兴趣与长期方向。
+
+## 设计思路
+
+不同维度的权重可以配置。系统提供默认权重，但用户可以通过界面调整，使排序更符合个人偏好。设计上倾向于“重要但不紧急”的任务优先，紧急性作为安全网而不是唯一决定因素。
+
+## 相关概念
+
+- 学习任务：优先级作用于任务。
+- 学习计划：排序结果帮助用户决定学习顺序。
@@ -0,0 +1,30 @@
+# 回忆对比
+
+## 定义
+
+回忆对比是用户凭记忆重建某个学习任务的知识结构，并把它与标准思维导图进行比较的过程。
+
+对比结果把节点分为：
+
+- 命中：用户回忆出的内容与标准导图匹配。
+- 遗漏：标准导图中有、用户没有回忆出来的内容。
+- 额外：用户回忆起但标准导图中没有明确出现的内容。
+
+## 设计意图
+
+回忆对比把“是否记住了”变成可见的结构差异：
+
+- 用户不需要按顺序处理所有碎片，可以从任意节点开始。
+- 遗漏项可以直接定位到原始报告或碎片，回看原文。
+- 多次对比记录可以反映掌握程度的变化。
+
+## 相关概念
+
+- 标准思维导图：对比的基准。
+- 复习起点：用户可以选择从某个节点开始，只复习该子树。
+- 知识碎片与学习报告：遗漏项可追溯回原文。
+- AI 任务：语义对比可以由 AI 完成，也可降级到文本相似度匹配。
+
+## 设计思路
+
+复习应该“围绕一个知识点自由展开”，而不是强迫用户从头到尾处理所有材料。回忆对比的反馈要直观，最好直接在导图上用颜色标记命中、遗漏和额外内容。
@@ -0,0 +1,23 @@
+# 复习 Feed
+
+## 定义
+
+复习 Feed 是滚动展示用户自己写过的知识碎片和学习报告的轻量复习入口。它只显示内容摘要，用户看到后可以回想上下文，也可以点击进入详情。
+
+## 设计意图
+
+复习的主要阻力是“不知道从哪里开始”和“不想面对一长串待复习内容”。滚动 Feed 让复习变成低成本的偶然接触：
+
+- 无意识看到的内容可能触发记忆。
+- 如果看到后想不起来，点击进入详情形成一次主动回忆。
+- 内容不是完全随机，系统可以让更需要复习的内容优先出现。
+
+## 相关概念
+
+- 知识碎片与学习报告：Feed 的内容来源。
+- 回忆卡片：点击 Feed 内容后，先让用户尝试回忆再展开原文。
+- 回忆对比：Feed 是进入深度复习的入口之一。
+
+## 设计思路
+
+滚动展示适合“播种”记忆，主动回忆适合“巩固”记忆。系统把两者结合：先低门槛展示，再在用户点击时引导回忆。
@@ -0,0 +1,24 @@
+# 标准思维导图
+
+## 定义
+
+标准思维导图是每个学习任务对应的知识结构基准，由系统从该任务的学习报告、知识碎片和应用场景中提取整理而成。用户可以查看、编辑它，也可以用它作为复习的对照对象。
+
+## 设计意图
+
+思维导图不是普通附件，而是复习的主要交互形式：
+
+1. 用户复习时可以在脑中重绘这张图。
+2. 想不起来的部分就是需要重新看的地方。
+3. 如果能顺利重绘出结构，复习效果就体现在过程中。
+
+## 相关概念
+
+- 学习报告与知识碎片：导图的生成素材。
+- 应用场景：作为独立分支进入导图。
+- 回忆对比：标准导图是用户回忆结果的对照基准。
+- 节点溯源：导图节点可以关联回原始报告、碎片或应用场景。
+
+## 设计思路
+
+标准导图应同时适合人工编辑和机器处理。它既可以用缩进大纲的形式让用户直接修改，也可以用树结构参与算法比较。
@@ -0,0 +1,30 @@
+# 学习会话
+
+## 定义
+
+学习会话是用户针对某个学习任务进行的一次连续学习过程。一个会话从开始学习算起，到暂停或结束时结束。
+
+会话拥有明确的阶段状态：
+
+- 进行中：用户正在学习。
+- 暂停：用户暂时离开，学习进度被保留。
+- 已结束：本次学习完成，并产出学习报告。
+
+## 设计意图
+
+学习会话把“学习”从模糊的时间块变成可记录、可恢复、可比较的过程。系统通过会话记录：
+
+- 开始、暂停、恢复和结束的时间。
+- 实际使用时间与有效学习时间。
+- 学习预期、知识碎片和学习报告的归属关系。
+
+## 相关概念
+
+- 学习预期：会话开始时必须记录。
+- 知识碎片：会话过程中产生。
+- 学习报告：会话结束时汇总生成。
+- 学习任务：会话所属的上层对象。
+
+## 设计思路
+
+一个会话应当是连续的单元，而不是把一次学习拆成多个互不相关的片段。会话可以暂停和恢复，但不鼓励长时间搁置；长时间未继续的会话应被视为自然结束，避免遗留无意义的“进行中”状态。
@@ -0,0 +1,24 @@
+# 时间与效率
+
+## 定义
+
+系统用三个时间概念描述一次学习会话：
+
+- 实际使用时间：会话从开始到结束的总体时间。
+- 有效学习时间：会话中真正处于学习状态的时间，即扣除暂停时间后的投入。
+- 有效时间比：有效学习时间占实际使用时间的比例，用于观察学习是否被频繁中断。
+
+## 设计意图
+
+时间数据帮助用户建立对学习投入的感知，而不是用来评判用户。用户看到一次学习真正投入了多久，可以更合理地估计完成一个任务需要多长时间。
+
+## 设计思路
+
+- 暂停是一个显式动作：暂停之前的时间都属于有效学习时间。
+- 番茄钟等时间刻度只是辅助参考，不是强制约束。
+- 系统记录数据，不把“效率低”当成错误，而是让用户看到实际情况。
+
+## 相关概念
+
+- 学习会话：时间数据记录在会话上。
+- 学习任务：任务层面的累计学习时间来自多次会话。
@@ -0,0 +1,43 @@
+# 学习闭环
+
+## 闭环结构
+
+```text
+学习任务
+   ↓
+开始学习会话
+   ↓
+记录学习预期
+   ↓
+学习中产生知识碎片
+   ↓
+结束会话并汇总学习报告
+   ↓
+进入复习与应用
+```
+
+## 各环节的设计意图
+
+### 学习任务
+
+学习任务是长期组织的单元。用户先确定要学什么，再围绕它开展多次会话。
+
+### 学习预期
+
+预期让每次学习有明确目标。目标不需要宏大，只需要让用户知道自己这次要完成什么。
+
+### 知识碎片
+
+碎片是学习过程中的真实记录。它降低了“边学边记”的成本，让学习内容不会在会话结束时才靠回忆重建。
+
+### 学习报告
+
+报告把碎片收敛成一次学习的完整结果。它可以由系统先聚合，再由用户修正，避免把完整报告变成书写压力。
+
+### 复习与应用
+
+复习让学习结果被再次激活，应用场景让复习有现实意义。两者共同决定“这次学习到底留下了什么”。
+
+## 闭环意义
+
+系统不把学习看成一次性的“开始-结束”，而是看成“计划、执行、记录、复习、应用”的循环。每个学习任务都可以在这个循环中不断推进。
@@ -0,0 +1,49 @@
+# 模块边界
+
+## 任务管理
+
+负责学习任务的创建、修改、删除和优先级计算。
+
+任务管理关心“有哪些学习任务”和“接下来先学什么”，不负责具体学习过程中的记录。
+
+## 学习执行
+
+负责一次学习会话从开始到结束的完整过程：
+
+- 记录学习预期。
+- 产生知识碎片。
+- 汇总学习报告。
+- 追踪时间与状态。
+
+学习执行产生学习过程中的原始材料。
+
+## 复习
+
+负责消费学习执行产生的材料：
+
+- 滚动展示知识碎片和学习报告。
+- 维护标准思维导图。
+- 提供回忆对比和遗漏项回溯。
+
+复习模块不要求用户逐条整理学习材料，材料是自动整理和对照分析的数据来源。
+
+## 应用场景
+
+应用场景属于学习任务，而不是复习模块。它表示任务完成后用户希望具备的应用能力，参与标准导图生成，为复习提供现实语境。
+
+## AI 能力
+
+AI 是独立于核心业务流程的增强层：
+
+- 聚合知识碎片为报告草稿。
+- 从学习材料中生成标准导图。
+- 对用户回忆进行语义对比。
+
+AI 能力可替换、可降级，不影响学习执行和复习的基本流程。
+
+## 边界总结
+
+- 执行模块产生数据。
+- 复习模块消费数据并形成反馈。
+- 应用场景定义学习目标。
+- AI 模块增强整理与对比，但不承担核心闭环的完整性。
@@ -0,0 +1,35 @@
+# 设计原则
+
+## 工具，不是约束
+
+LPT 是辅助学习与生活的工具。系统可以量化、提醒、建议，但不应该强迫用户按固定节奏学习。
+
+例如：
+
+- 时间刻度是参考，不是 KPI。
+- 休息和暂停由用户决定，系统只在需要时提供支持。
+- 复习入口可以低门槛出现，但不要求用户逐条处理所有内容。
+
+## 量化，但不评判
+
+系统记录学习时间、知识碎片、回忆覆盖率和任务优先级，目的是让用户看见自己的学习过程，而不是给用户打分数。
+
+“有效学习时间低”是一种可观察的事实，不应当被当作错误处理。系统要做的只是呈现数据，并帮助用户做出下一步选择。
+
+## 低阻力优先
+
+任何需要用户付出大量整理成本的功能，都可能让学习流程中断。因此：
+
+- 用知识碎片代替必须写完整的报告。
+- 用滚动 Feed 代替强制复习清单。
+- 用 AI 草稿降低从碎片到报告的书写负担。
+
+## 引导，而不是要求
+
+系统可以推断“哪些内容更需要复习”，并让这些内容优先出现，但不应替用户决定必须学什么。
+
+随机展示是为了制造偶然接触，智能排序是为了让偶然接触更接近真正需要复习的内容。两者结合，而不是互相替代。
+
+## AI 增强，但不依赖
+
+AI 负责降低书写负担、提取知识结构和进行语义比较。核心学习流程必须在 AI 不可用时仍然可用，通过内置规则继续完成基本功能。
@@ -0,0 +1,46 @@
+# 复习回路
+
+## 复习的两种机制
+
+系统把两种记忆机制组合在一起：
+
+1. 偶然接触：通过滚动 Feed 让用户无意识看到自己写过的内容，为记忆“播种”。
+2. 主动回忆：用户点击内容后先尝试回忆，再展开原文，通过提取练习巩固记忆。
+
+## 从轻量复习到深度复习
+
+```text
+滚动 Feed
+   ↓
+看到内容并尝试回忆
+   ↓
+点击进入详情
+   ↓
+标准思维导图
+   ↓
+选择复习起点
+   ↓
+回忆对比
+   ↓
+定位遗漏项并回看原文
+```
+
+## 标准思维导图的作用
+
+标准思维导图是复习的基准结构：
+
+- 用户可以在脑中重绘它，检验自己记住了多少。
+- 用户可以从任意节点开始复习，不必按顺序处理所有碎片。
+- 系统可以用它判断哪些内容被回忆到、哪些内容遗漏。
+
+## 回忆对比的作用
+
+回忆对比把“我好像学过”变成可定位的差异：
+
+- 命中的内容说明已经掌握。
+- 遗漏的内容直接指出需要回看哪里。
+- 额外回忆的内容可能是用户自己的联想，也值得保留。
+
+## 智能排序与随机性
+
+复习内容不应完全随机，也不应被强制排序。系统可以综合“多久没复习”和“上次回忆覆盖率”让更需要复习的内容更常出现，同时保留随机感。