Document mastery exam and responsive review design

docs/plans/2026-06-29-mastery-exam-and-responsive-review-design.md

@@ -0,0 +1,123 @@
+# Smart Review 掌握检验与响应式复习设计
+
+## 目标
+
+在不改变现有四档动态复习算法的前提下，增加两条彼此独立的退出路径：
+
+- 用户可主动暂停复习，并随时从 Review Center 或当前笔记恢复。
+- 有强检验意愿的用户可配置自己的 AI 模型，完成可追溯的掌握检验。
+
+同时修复 Review Center 在 Obsidian 侧栏内因容器过窄导致的文字竖排、按钮重叠问题，并确保 Ribbon 打开入口回到主区域标签页。
+
+## 状态模型
+
+使用独立字段 `review_status`，不复用笔记已有的通用 `status`：
+
+- `active`：参与普通复习计划。
+- `paused`：退出普通计划，可设置恢复日期或无限期暂停。
+- `mastery_pending`：第一次 AI 检验通过，等待延迟复检。
+- `mastered`：延迟复检通过，退出普通复习计划。
+
+暂停不代表掌握。扫描器不把暂停笔记放入逾期、今日或未来计划，而是放入独立的可折叠“已暂停”区域。该区域提供“恢复复习”，当前笔记也提供恢复命令，不要求用户修改 frontmatter。
+
+## 普通复习与暂停
+
+普通任务继续显示 Again、Hard、Good、Easy，并使用当前动态倍率更新 `next_review`。任务的更多菜单提供“暂停复习”和“发起 AI 掌握检验”。
+
+暂停选项包括 30 天、90 天、自定义日期和无限期。记录：
+
+```yaml
+review_status: paused
+review_paused_at: 2026-06-29
+review_resume_at: 2026-09-27
+```
+
+暂停期满只在界面中提示，不在后台静默修改笔记。用户点击恢复后写入 `review_status: active`，清理暂停字段，并将 `next_review` 设置为当天。已掌握笔记提供“重新学习”，执行相同的重新激活流程。
+
+## AI 模型连接
+
+AI 掌握检验是可选能力；没有配置模型时，普通复习和暂停功能完全可用。点击掌握检验时若没有可用连接，直接引导到插件设置。
+
+设置支持多个连接配置，并可选择考官连接和复核连接。首批适配：
+
+- OpenAI 与 OpenAI-compatible
+- Anthropic
+- Google Gemini
+- Azure OpenAI
+- Ollama
+
+每个配置包含名称、厂商类型、API 地址、API Key、模型名、自定义请求头和超时，并提供测试连接和模型列表刷新；无法发现模型时允许手工填写。网络请求统一使用 Obsidian `requestUrl`。密钥只存放在插件 `data.json`，不写入笔记或检验记录。README 必须披露网络使用、发送的数据范围和本地密钥存储限制。
+
+内部通过统一 `AIExaminerProvider` 接口调用各厂商。模型必须返回受 JSON Schema 约束的结构化结果；解析失败时只允许一次格式修复。任意厂商错误、超时、取消或不完整响应都不得改变笔记掌握状态。
+
+## 掌握检验流程
+
+用户可从当前笔记、普通任务、暂停笔记或系统推荐候选发起。候选条件仅作为建议：至少复习 3 次、最近两次为 Good/Easy、最近三次无 Again、当前间隔至少 60 天。
+
+第一次检验：
+
+1. 读取当前文章内容和稳定标识，不读取整个知识库。
+2. AI 从原文提取核心主张、边界条件和隐藏评分基准。
+3. AI 生成保持、辨析、迁移、生成四类题目。
+4. 用户闭卷回答；草稿保存在插件数据中。
+5. AI 按原文证据评分，输出每项 0/1/2、满足点、缺失点、原文依据、参考答案和判定理由。
+6. 通过或临界结果执行第二次独立复核。复核不读取第一次考官的最终结论，只读取原文、问题、回答和评分基准。
+7. 两次结论冲突或证据不足时标记为 `inconclusive`，不得判定掌握。
+
+硬门槛：保持为 2、辨析至少 1、迁移为 2、生成至少 1，任意一项为 0 均不通过。第一次通过后写入 `mastery_pending` 并安排 30 天后的保持与新场景迁移复检；延迟复检通过后才写入 `mastered`。
+
+## 置信度
+
+不直接采用模型自报的百分比。系统根据可验证信号计算 `high / medium / low`：
+
+- 评分基准覆盖率。
+- 每个结论是否提供可定位的原文依据。
+- 回答与原文是否存在关键冲突。
+- 考官与复核者是否一致。
+- 模型输出是否完整通过结构校验。
+
+只有门槛通过且置信度为 `high` 或 `medium`、复核结论一致时，才能进入下一阶段。`low` 一律视为 `inconclusive`。提交后向用户展示参考答案、原文依据、缺失点和改进建议，但不在作答前泄露。
+
+## 检验记录
+
+用户可在设置中选择记录目录，默认 `Smart Review/Mastery Records`。目录不存在时在首次正式提交时递归创建。
+
+同一篇源文章只维护一份纵向掌握记录。原笔记使用 `review_mastery_record` 链接该文件；后续失败、重试和延迟复检都向同一文件追加带时间戳的章节，不为每次尝试创建新文件。记录包含：
+
+- 源文章双向链接及内容指纹。
+- 尝试编号、日期、模型和提供商。
+- 问题、用户回答、参考答案。
+- 分项评分、证据、缺失点、置信度和复核结果。
+- 本次结论与下一步安排。
+
+如果记录文件被移动，优先通过 Obsidian 链接解析定位；如果被删除，则在配置目录重建并从下一次尝试继续。未提交草稿只放在插件数据中，取消时允许保留或丢弃。
+
+## Review Center 布局与打开行为
+
+Review Center 根容器启用 CSS container query。布局根据 leaf 实际宽度变化，而不是根据整个 Obsidian 窗口宽度变化：
+
+- 中等宽度时任务信息改为纵向，评分按钮改为 2x2。
+- 更窄时按钮改为单列，标题、状态和元数据独立换行。
+- 已暂停、待复检和已掌握区域默认折叠。
+
+Ribbon 和“打开 Review Center”命令只复用主区域中的现有 leaf。如果唯一现有 leaf 位于左右侧栏，则在主区域打开新标签页、显示成功后再关闭旧侧栏 leaf。插件启动时不主动迁移，避免无用户操作地改变 workspace。用户手动拖回侧栏后，容器响应式规则仍保证可用。
+
+## 错误处理与安全
+
+- AI 请求前明确显示将发送当前文章和本次回答。
+- 不发送其他笔记、整个索引或 API Key。
+- 请求可取消，失败后保留草稿。
+- 状态变更和记录追加采用先写记录、再更新 frontmatter 的顺序。
+- 记录写入失败时不得标记通过。
+- 自定义路径必须规范化并限制在 vault 内。
+- 不记录客户端遥测。
+
+## 测试范围
+
+- 状态转换、暂停恢复、重新学习和扫描过滤单元测试。
+- 单篇文章多次检验只追加同一记录文件的测试。
+- AI 适配器、Schema 校验、超时、取消、格式修复和冲突复核测试。
+- 置信度计算与硬门槛测试。
+- 中英文、深浅主题、主标签页、左右侧栏和窄容器视觉测试。
+- Ribbon 从持久化侧栏迁移到主区域的行为测试。
+- 构建、类型检查、官方 ESLint、CSS lint 和现有回归测试。