dsh-mastery-loop 0.0.0-stage → 0.2.0

package/skills/mastery-loop/templates.md

@@ -0,0 +1,255 @@
+# 契约正文（Contract）
+
+> **本文件是这套 skill 的契约正文**：库长什么样、每个文件干什么、什么能脚本化。
+> `SKILL.md`（*复习主流程*）与 `mastery-loop-setup`（*一次性初始化*）都**只链接到这里**，不各写一份。
+> 改契约**只改这个文件**。出题 / 判分 / 考前 list 的模板在 [exam-templates.md](exam-templates.md)。
+
+---
+
+## 一、库的布局
+
+工作区根下**两个并列文件夹**：`kb/`（内容区，给人看）与 `sys/`（机器区，给脚本读）。
+
+```
+<工作区根>/
+├── kb/
+│   ├── knowledge/          # 知识点笔记，一篇一个知识点
+│   └── MOC/                # 聚合产物：镜像分类层级
+│       ├── 00 总览.md        # 全库视图（可选）
+│       └── <类1>/<类2>/…    # 每层一份「该层的索引」，叶子层是讲次级 MOC
+└── sys/
+    ├── config.json         # 设定：路径 / 分类 / 语言 / 确认标记
+    ├── graph.json          # 关系图：知识点的前置关系（真值）
+    ├── ledger.jsonl        # 账本：逐知识点的复习统计（真值）
+    ├── errors.jsonl        # 错误原因表
+    ├── error-taxonomy.json # 失分原因分类（初始为空，agent 维护）
+    ├── paper-format.json   # 卷面参数（每个课程的每场考试一条）
+    ├── state.jsonl         # 状态：内容哈希 / schema 版本 / 检查时间（用于跳过重扫）
+    └── changes.jsonl       # 变更流水 —— **只在没有 git 且用户不装 git 时启用**
+```
+
+**文件夹命名**：固定结构文件夹一律**英文、无特殊符号**（`kb` `knowledge` `MOC` `sys`）。
+**类值目录**（`MOC/<类1>/…`）用**用户自己的分类值**（可以是中文）；`config.json` 里给每个类值记一个 **ASCII slug** 供外部工具用。
+
+**每个文件开头一句「本文件是什么」**：
+
+- Markdown：第一行就是这句话；
+- JSON：第一个字段是 `"用途"`；
+- JSONL：第一行是一条 `{"kind":"header","用途":"…"}` 记录（脚本跳过它）。
+
+---
+
+## 二、知识点契约
+
+### frontmatter
+
+```yaml
+---
+类型: 知识点
+归属: ["[[Deep Learning/doc/Lecture/W1L1 Introduction to the Unit.pdf|深度学习 L1]]"]
+aliases: ["Backpropagation"]
+标签: [深度学习, 神经网络, 核心]
+---
+```
+
+| 字段 | 值 | 说明 |
+| --- | --- | --- |
+| `类型` | `知识点` | 结构化字段，不是标签 |
+| `分类` | **类路径，多值** | **生成这篇知识点时就附上**（哪个类、哪个子类）。一条一个类路径，层级用 `分类.分隔符`（默认 `/`）分隔。脚本**只读这个字段**做聚合，不解析路径 |
+| `归属` | **来源文件，多值，必填** | 这个知识点**出自哪份资料**（PDF / DOCX / 网页快照都算）。元素是带路径的 wikilink + 人类可读别名 |
+| `aliases` | 英文名列表 | Obsidian 原生别名 |
+| `标签` | 既有标签 | 既有标签（用于搜索/标签面板） |
+
+**铁律**
+
+- **没有 `课程:`、没有 `主题:`、没有 `难度:`** —— 课程与讲次是**从 `归属` 解析出来的**（见第四节），不是存的字段。
+- **`归属` 是「来源」，不是「关系」** —— 前置/后置在 `sys/graph.json` 里。
+- **列表字段不止 `归属`** —— `标签`、`aliases` 同样是列表。
+- frontmatter 里的 **wikilink 必须加引号**（`[` 会被 YAML 当数组开头）。
+- **契约之外的字段原样保留**，不清理。
+
+### 正文（固定顺序）
+
+```markdown
+# <中文名> <英文名>
+
+## 一句话
+## 核心内容
+## 前置知识
+## 后置知识
+## 易错点 / 考点
+## 讲义出处
+```
+
+- `## 前置知识` = **逻辑判定**，唯一判据：**删掉它，本篇的核心内容就解释不通**（只收**直接**前置）。
+- `## 后置知识` = **由图反算，绝不手写**（脚本渲染）。
+- 每条前置后面带 `—— <理由>`，与 `graph.json` 里该边的 `reason` **逐字一致**。
+- **没有 `## 平行关联`**。
+
+### 链接写法
+
+- **一律带路径**，**相对工作区根**（= Obsidian vault 根），**带后缀**，**带人类可读别名**：
+  `[[kb/knowledge/梯度.md|梯度]]` · `[[Deep Learning/doc/Lecture/W1L1 ….pdf|深度学习 L1]]`
+- 代价：改名 / 搬目录会断链 —— 由 `scan.mjs`（*扫库脚本*）发现、`rewrite-links.mjs`（*重写链接脚本*）修。
+
+---
+
+## 三、关系图 `sys/graph.json`
+
+```json
+{
+  "用途": "本文件是知识点关系图：只存边（from 是 to 的前置），节点就是 knowledge/ 里的笔记本身。",
+  "规则": "判据：删掉 from，to 的核心内容就解释不通。只收直接前置；同一篇的前置集合内两两不可比。",
+  "导出": "后置 = 本表的反向（脚本算）；没有「平行」段。",
+  "version": 1,
+  "updatedAt": "2026-10-14 20:30",
+  "coverage": { "深度学习": { "done": ["L1"], "todo": ["L2"] } },
+  "edges": [
+    { "from": "梯度", "to": "最速下降与参数空间", "reason": "没有梯度就没有下降方向" }
+  ]
+}
+```
+
+- **边不带课程** —— 课程归属由知识点的 `归属`/标签解析，边只是纯逻辑。
+- `reason` **≤30 字**，指出 `to` 依赖 `from` 的**那一步**。
+- `coverage`：**按分类层级**记「哪些做完了、哪些没做」。
+- 图**允许分批**：`coverage` 里没做的部分，校验不报错。
+
+---
+
+## 四、分类与范围
+
+**分类是全库级定义**（层级与类值记在 `sys/config.json`），但**每篇知识点属于哪个类，是在生成这篇知识点的时候就附在它身上的** —— 存在 frontmatter 的 `分类` 字段里。**脚本只读这个字段做聚合**，不解析路径、不猜、不写正则。
+
+```yaml
+分类: ["深度学习/L3", "机器学习/L5"]   # 一条一个类路径；层级用 `分类.分隔符`（默认 /）分隔
+```
+
+`config.json` 里记：
+
+```json
+"分类": {
+  "层级": ["课程", "讲次"],
+  "字段": "分类",
+  "分隔符": "/",
+  "类值": {
+    "课程": [ { "值": "深度学习", "slug": "dl" } ],
+    "讲次": [ { "值": "L3", "slug": "l3" } ]
+  },
+  "确认": "（用户于 <YYYY-MM-DD HH:MM> 确认）"
+}
+```
+
+- **一篇可以属于多个类**（`归属` 是多值的，类也跟着多值）；
+- **归类在生成知识点时定**，不由后面的脚本推；规则怎么算、按什么分，由 agent 在 setup 时**看这个库**再和用户确认（**不预设形状**：课程 / 章 / 模块 / 主题都行）；
+- **范围 = 分类里的一个或多个类路径**（例：`深度学习/L3`），脚本按它筛。
+
+---
+
+## 五、聚合与两区
+
+`kb/MOC/` 下的一切都是**从 `归属` + 图聚合出来的**，不是手写枚举。每份 MOC / 索引里分两区：
+
+```markdown
+<!-- AUTO:BEGIN -->
+- [[kb/knowledge/梯度.md|梯度]] —— ∇J 是代价函数对全部参数的一阶偏导向量
+<!-- AUTO:END -->
+
+## 主线（手写区）
+```
+
+- **机器区**：`aggregate.mjs`（*聚合脚本*）生成与覆盖（按分类层级列 `- [[链接]] —— 一句话`、覆盖进度）。
+- **手写区**：agent / 人写，**脚本永不碰**（主线、脉络、指定阅读、考点提示）。
+- 聚合脚本**只做聚合**：不写待办、不打印摘要 —— **要说话的是 `scan.mjs`**。
+- 「分组」不是独立概念：**分类有几层就分几层**；只有两层时 MOC 内部不再分组。
+
+---
+
+## 六、脚本边界
+
+**脚本只做重复性、机械性、不需要变通的事。** 要理解内容、要随机应变、要交互的**留给 agent**。
+
+| 脚本 | 干什么 | 谁触发 |
+| --- | --- | --- |
+| `graph.mjs` | 读写 `sys/graph.json`；六项校验；由图渲染两段 | agent |
+| `aggregate.mjs` | 从 `归属` + 图聚合 MOC / 索引的**机器区** | agent |
+| `scan.mjs` | 扫库五项（见第七节）；读 `state.jsonl` **按哈希跳过没变的**；发现坏链接就提示跑 `rewrite-links.mjs` | agent |
+| `rewrite-links.mjs` | 改名 / 搬目录后重写所有带路径链接 | agent（由 scan 触发） |
+| `ledger.mjs` | 按 60/30/10 筛清单、算达标、**批改写回** | agent |
+| `validate.mjs` | 查 `kb/` 与 `sys/` 的结构是否齐 | agent / setup |
+
+**不能脚本化**（明确留 agent）：判断谁是谁的前置、写 `reason`、出题、批改、**错误原因去重**（脚本会把「把 A1 和 B 弄混」和「把 A2 和 B 弄混」误判成重复）、frontmatter 规范化、分类协商。
+
+**脚本纪律**：Node（零依赖，`node xxx.mjs`）；**不拼 shell**（路径含中文 / 空格）；只读写自己那类文件。
+
+---
+
+## 七、校验
+
+### 图（`graph.mjs check`，六项）
+
+| # | 名称 | 判据 |
+| --- | --- | --- |
+| 1 | 双向自洽 | 边 `from→to` ⟺ `to` 的前置里有 `from` 且 `from` 的后置里有 `to`；正文里出现的关系必须在图里有边 |
+| 2 | 无自链 | 没有 `from == to` |
+| 3 | 无悬空 | `from` / `to` 都能找到对应笔记 |
+| 4 | 同段无重复 | 同一小节里同一目标只出现一次 |
+| 5 | 前后置互斥 | 同一篇的前置集合 ∩ 后置集合 = ∅ |
+| 6 | 前置两两不可比 | 同一篇的前置里，任两条不可互为前置/后置（只收直接前置） |
+
+### 扫库（`scan.mjs`，五项）
+
+① 悬空链接 ② 带路径链接与当前目录结构不符 ③ `config.json` 的分类 / 版本与现状不符 ④ 图与笔记两段不一致（= 图校验）⑤ 账本 / 错误原因里引用的知识点是否还存在。
+
+---
+
+## 八、排序（可选，不是契约）
+
+本机**若装了 Miyo**，可以在**已按知识深度排好之后**，对「深度上并列、拿不准先后」的条目问一次相关度作参考：
+`POST http://127.0.0.1:8742/v0/search/related`，body `{"file_path":"<已注册 folder 名>/<库内相对路径>","limit":N}`。
+
+- **知识深度是定序者**，Miyo 只作参考；分数**不写进** frontmatter / 图；
+- **没装就跳过**：不报错、不检查、不阻塞 —— 发布版**不依赖** Miyo；
+- 实测提醒：`file_path` 三种分隔符都能用；真正 404 的是「缺已注册 folder 前缀 / 绝对路径 / 不带 `.md` / 路径不在索引里」。
+
+---
+
+## 九、git 与历史
+
+**能用 git 就用 git** —— 这条管两件事，都优先走 git：
+
+| 要回答的问题 | 有 git | 没有 git（且用户不装） |
+| --- | --- | --- |
+| **哪些文件变过**（决定要不要重看） | `git status` + 上次检查的提交号之后 `git diff` | `sys/state.jsonl` 里逐文件的内容哈希 |
+| **发生过什么**（决定怎么追溯） | git 历史（skill **不自动 `commit`、绝不 `push`**，只提示） | `sys/changes.jsonl`（*变更流水*）：一行一条，只追加不改 |
+
+```json
+{"at":"2026-10-14 20:30","by":"user","what":"config:分类","from":"","to":"课程 × 讲次","why":"用户确认"}
+```
+
+- `sys/state.jsonl` 在 git 模式下**只有一行**（`{"mode":"git","last":"<commit>",…}`）；没有 git 时才逐文件记哈希；
+- 管「要不要重看」的是它，管「发生过什么」的是 git（或 `changes.jsonl`）—— **两者不是一回事**；
+- 沙箱里抓子进程输出会被拒（EPERM），所以脚本调 git 时把输出**重定向到文件描述符**再读回来，而不是用管道。
+
+---
+
+## 十、用户确认标记
+
+**问出来的信息**（分类、路径、语言、范围、融合决定）后面跟一个括号：
+
+```
+（用户于 2026-10-14 20:30 确认）
+```
+
+- **精确到分钟**；**只标问出来的**（agent 自己推的不标）；
+- **就地只留最新一条**；历史翻 git（无 git 时翻 `changes.jsonl`）；
+- 适用范围：**发布出去的库同样适用**（不是开发者专用）。
+
+---
+
+## 十一、复习循环里用到的量
+
+- **配比**（按本次范围题池统算）：60% 熟练度最低 · 30% `是否学习过 = 否` · 10% `最后复习日期` 最久远。
+- **达标**（逐点）：`总共出过 ≥ 5` **且** `熟练程度 ≥ 本次目标正确率`；`总共出过 < 5` 标「样本不足」。
+- **账本字段**：`知识点 / 是否学习过 / 做对 / 总共出过 / 熟练程度 / 最后复习日期`。
+- **做对** = 思维链对 **且** 答案对（蒙对不算）。

package/skills/mastery-loop-setup/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: mastery-loop-setup
+description: >-
+  一次性初始化或迁移 mastery-loop 的知识库：探测材料与既有笔记，问清「按什么分类」「范围」「素材」「语言」「卷面格式」，把 kb/（内容区）与 sys/（机器区）建起来，或把已有库按契约重建结构（内容原样保留），最后跑校验。首次使用 mastery-loop 之前跑一次。
+  / One-time setup or migration for mastery-loop: explore materials and existing notes, ask about classification, scope, sources, language and exam format, then scaffold kb/ + sys/ (or rebuild an existing library's structure without touching its content) and verify it.
+disable-model-invocation: true
+user-invocable: true
+---
+
+# mastery-loop 初始化
+
+> **本文件是初始化 / 迁移流程。** 契约正文（*库长什么样、每个文件干什么*）在
+> [`../mastery-loop/templates.md`](../mastery-loop/templates.md) —— **它是权威，改契约只改那里**，本文件只讲「怎么建」。
+
+**产出：两个并列文件夹**
+
+| 路径 | 是什么 |
+| --- | --- |
+| `kb/knowledge/` | 知识点笔记（一篇一个知识点） |
+| `kb/MOC/` | 聚合产物，镜像分类层级（每层一份索引 + 叶子层讲次 MOC） |
+| `sys/config.json` | 设定：路径 / 分类 / 语言 / 确认标记 |
+| `sys/graph.json` | 关系图（前置关系的真值） |
+| `sys/ledger.jsonl` | 账本（逐知识点复习统计，真值） |
+| `sys/errors.jsonl` | 错误原因表 |
+| `sys/error-taxonomy.json` | 失分原因分类（初始为空，agent 维护） |
+| `sys/paper-format.json` | 卷面参数 |
+| `sys/state.jsonl` | 状态（哈希 / schema 版本 / 检查时间） |
+| `sys/changes.jsonl` | 变更流水 —— **只在没有 git 且用户不装 git 时才建** |
+
+> 这是 **prompt-driven skill，不是确定性脚本**。探索、把发现摆出来、问、确认，然后才写。
+
+---
+
+## 0 · 硬规矩
+
+- **材料目录只读。** 不改、不移、不改名用户给的任何课程材料。
+- **结构可重建，内容原样搬运。** 重建的只是 frontmatter 字段集、正文固定小节、链接写法、MOC / 索引；**内容是用户的**（一句话 / 核心内容 / 易错点 / 讲义出处），一个字节不动。
+- **改什么先给清单。** 动手前先把「哪篇要动、动什么」摆给用户过目。
+- **幂等。** 第二次跑必须零改动 —— 合规的文件**不重写**。
+- **问出来的信息要留痕**：`（用户于 <YYYY-MM-DD HH:MM> 确认）`，就地只留最新一条。
+- **不含任何真实路径进 skill 包** —— 真实路径只写进用户的 `sys/config.json`。
+- **不自动 `commit`、绝不 `push`。**
+
+---
+
+## 1 · Explore（先看，别假设）
+
+- **材料**：先列用户给的目录里**实际有什么**，不套固定清单（各课结构不同，有的课压根没有往年卷）。
+- **既有笔记库**：有没有已经成形的知识库？知识点在哪个目录？frontmatter 有哪些字段？正文有哪些小节？
+- **是否已经初始化过**：`sys/` 在不在？**在就先停下问用户**「要重新初始化，还是只补缺的」。
+- **git**：工作区是不是 git 仓库？（决定用 git 还是回退到 `sys/changes.jsonl` 记历史）
+
+### 1.1 合规扫描（**agent 做，不能脚本化** —— 初见的库状态无法预料）
+
+逐篇看三件事，产出清单：
+
+| 看什么 | 合规 |
+| --- | --- |
+| frontmatter 字段集 | `类型` / `归属`（来源文件，多值）/ `aliases` / `标签`；**没有** `课程:` / `主题:` / `难度:` |
+| 正文小节 | `一句话 / 核心内容 / 前置知识 / 后置知识 / 易错点 / 考点 / 讲义出处`；**没有 `## 平行关联`** |
+| 链接写法 | 带路径、相对工作区根、带后缀、带别名 |
+
+**合规的 → 一行不动**；不合规的 → 只改结构、内容原样搬。清单交给用户确认后再动（§6）。
+
+---
+
+## 2 · 分类与范围（**必问，不默认推荐**）
+
+**分类是全库级定义**，层数和每层有几个类都不固定。
+
+1. **先扫一遍材料**，给出一版候选建议（例如「你这里看起来是按『课程 → 讲次』分的」）；
+2. **问用户「按什么分类」** —— 用户可能不是按上课学的（比如「书 → 章」），**不要预设课程**；
+3. **问用户「每一层具体怎么认」** —— 得到**解析规则**（例：课程 = 来源路径第一层文件夹名；讲次 = 文件名里的 `W1L3`）；
+4. 用户校正后，把**层级 + 每条解析规则 + 每层类值（+ ASCII slug）**写进 `sys/config.json`，并带确认标记；
+5. **范围**：用户说「整理某部分」时，**从分类里选**（一个或多个类值）。不同范围**共用同一套分类**。
+
+---
+
+## 3 · 素材：两个类别
+
+**必需的只有两个类别**，不是两个确定的文件：
+
+| 类别 | 用来 | **默认成员** | 类里其他合格成员 |
+| --- | --- | --- | --- |
+| **建库参考** | 建知识库 | **讲义** | 教学大纲 / exam_topics / 课件 / 教科书章节 |
+| **出题参考** | 出题与判分 | **往年试卷** | 往年卷答案 / Lab sheet / Worksheet / Assessment 结构 |
+
+**判定分两级**：① **某一类整类为空** → 真缺，告诉用户缺什么、去哪找；② **类里有内容但没默认成员** → **不算缺**，问一句「用类里另一样顶吗」。
+
+**换成员必须问**，定了记进 `sys/config.json`（带确认标记），之后不再问。同时问一句：**「有没有你不想让我读的？」**
+
+---
+
+## 4 · 语言标准
+
+**按 6 个产物类别分别问**（用户可以用自然语言回答，如「全都中英双语对照」）：① 知识点笔记（正文 / 标题 / `aliases` / MOC）② 出的题 ③ 批改与解析 ④ 记录性文件 ⑤ 产出（复习清单 / 考前 list）⑥ 机制层（字段名 / config）。
+
+> ⚠️ **`sys/errors.jsonl` 里的错误原因默认用英文** —— 它要套 ASD-STE100 的规则，不跟别的类别走。
+> 📌 **不要预设双语。**
+
+---
+
+## 5 · 卷面格式
+
+**每个课程的每场考试各一条**（期中 / 期末 / in-class / coursework 形状不同，必须分开），落进 `sys/paper-format.json`：时间 / 总分 / 题数 / 题型 / 分值分布，并**记住来源**（抄自哪份文件）。
+
+**没有往年卷时**：先问用户；用户没更好的主意 → 用**默认出卷法 = 判断题 + 每题说明理由**，并在该条写明。
+
+---
+
+## 6 · 重建（合规检查 → 清单 → 动手）
+
+1. **先按 §1.1 逐篇判定**，把清单摆给用户（哪篇要动、动什么、为什么）；
+2. 用户点头后，**按分类分层一块一块做**（例：先 DL L1，做完跑校验，再下一块）；
+3. **安全网**：有 git → 提示用户先 commit；没有 git → 先把 `kb/` + `sys/` 复制一份到工作区外的备份目录再动手；
+4. 重建内容：frontmatter 字段集 · 正文小节顺序 · 链接改写 · MOC / 索引；
+5. **`## 平行关联` 里的链接不要丢** —— 转成 `sys/graph.json` 里的边（判据仍按契约第二节）。
+
+---
+
+## 7 · 落盘
+
+写进**工作区根**，按契约第一节的布局。**顺序写死，不许反向**：
+
+```
+① kb/knowledge/（知识点） + sys/graph.json（关系图）
+② kb/MOC/ 的机器区（由 aggregate.mjs 从「归属 + 图」聚合）
+③ kb/MOC/ 的手写区（agent / 人写：主线、脉络、考点提示）
+```
+
+种子模板（`seeds/`）→ 填好草稿、给用户过目、再写：
+
+| 种子 | 填什么 |
+| --- | --- |
+| `seeds/config.json` | 路径、分类（层级 / 解析规则 / 类值 / slug）、语言、git |
+| `seeds/graph.json` | `用途` / `规则` / `coverage` / `edges` |
+| `seeds/ledger.jsonl` | 先铺**本次范围内全部知识点**，`是否学习过 = 否`、`做对/总共出过 = 0`、`熟练程度 = null` |
+| `seeds/errors.jsonl` | 只有头部说明行，**初始没有条目** |
+| `seeds/error-taxonomy.json` | **保持为空** |
+| `seeds/paper-format.json` | §5 收来的每条考试一格 |
+| `seeds/state.jsonl` | 只有头部说明行 |
+| `seeds/note.md` | 单篇知识点的骨架（frontmatter + 固定小节） |
+| `seeds/moc.md` | 一份 MOC 的骨架（机器区标记 + 手写区） |
+
+---
+
+## 8 · 校验
+
+```bash
+node <skill>/scripts/validate.mjs <工作区根>     # 结构齐不齐
+node <skill>/scripts/graph.mjs  check <工作区根> # 六项图校验
+node <skill>/scripts/scan.mjs   <工作区根>       # 五项扫库
+```
+
+**结构齐 + 图六项全过 = 初始化完成。** 缺哪个补哪个，别靠感觉。
+
+---
+
+## 9 · Done
+
+告诉用户：初始化完了，`mastery-loop` 之后会读这些文件；想改直接编 `sys/config.json`；**只有要换素材来源、改分类、或从头再来时才需要重跑本 skill**。

package/skills/mastery-loop-setup/seeds/config.json

@@ -0,0 +1,39 @@
+{
+  "用途": "本文件是这套知识库的设定：路径、分类（层级与解析规则）、语言标准、git。凡「问用户才得到」的值后面跟确认标记。",
+  "schema_version": "0.2.0",
+  "路径": {
+    "工作区根": ".",
+    "材料": ["<相对工作区根的目录，例：Deep Learning/doc>"],
+    "知识库": "kb",
+    "机器区": "sys"
+  },
+  "分类": {
+    "层级": ["<第 1 层，例：课程>", "<第 2 层，例：讲次>"],
+    "字段": "分类",
+    "分隔符": "/",
+    "说明": "每篇知识点在生成时就带上 分类 字段（一条一个类路径，用分隔符拼层级）；脚本只读它，不解析路径。怎么算是哪个类，由 agent 看这个库后和用户确认，不预设形状。",
+    "类值": {
+      "<第 1 层>": [
+        { "值": "<类值，例：深度学习>", "slug": "<ASCII，例：dl>" }
+      ],
+      "<第 2 层>": []
+    },
+    "确认": "（用户于 <YYYY-MM-DD HH:MM> 确认）"
+  },
+  "范围": [
+    { "名称": "<范围名>", "值": ["<分类里的一个或多个类值>"], "确认": "（用户于 <YYYY-MM-DD HH:MM> 确认）" }
+  ],
+  "语言": {
+    "知识点笔记": "<正文 / 标题 / aliases / MOC 用什么语言>",
+    "出的题": "",
+    "批改与解析": "",
+    "记录性文件": "",
+    "产出": "",
+    "机制层": ""
+  },
+  "git": {
+    "使用": true,
+    "说明": "有 git 就用 git 承担历史（skill 不自动 commit、绝不 push）；没有且用户不装 → 启用 sys/changes.jsonl"
+  },
+  "排除": ["<用户说不想让我读的>"]
+}

package/skills/mastery-loop-setup/seeds/error-taxonomy.json

@@ -0,0 +1,4 @@
+{
+  "用途": "本文件是失分原因的分类表：初始为空，之后由 agent 维护（不由人维护）。",
+  "分类": []
+}

package/skills/mastery-loop-setup/seeds/errors.jsonl

@@ -0,0 +1 @@
+{"kind":"header","用途":"本文件是错误原因表：逐知识点登记用户实际犯过的错，供复习时逐字复用。初始没有条目。"}

package/skills/mastery-loop-setup/seeds/graph.json

@@ -0,0 +1,13 @@
+{
+  "用途": "本文件是知识点关系图：只存边（from 是 to 的前置），节点就是 kb/knowledge/ 里的笔记本身。",
+  "规则": "判据：删掉 from，to 的核心内容就解释不通。只收直接前置；同一篇的前置集合内两两不可比。顺序按知识深度，不是资料时间。",
+  "导出": "后置 = 本表的反向（脚本算）；没有「平行」段。",
+  "version": 1,
+  "updatedAt": "<YYYY-MM-DD HH:MM>",
+  "coverage": {
+    "<第 1 层类值，例：深度学习>": { "done": [], "todo": ["<例：L1>", "<例：L2>"] }
+  },
+  "edges": [
+    { "from": "<前置知识点名>", "to": "<后置知识点名>", "reason": "<≤30 字：to 依赖 from 的那一步>" }
+  ]
+}

package/skills/mastery-loop-setup/seeds/ledger.jsonl

@@ -0,0 +1,2 @@
+{"kind":"header","用途":"本文件是复习账本：逐条记每个知识点的复习统计。它是唯一不可重建的真值 —— 删了就永久丢进度。一行一个知识点，只追加/改行，不要重排。"}
+{"知识点":"<知识点名>","是否学习过":false,"做对":0,"总共出过":0,"熟练程度":null,"最后复习日期":null}

package/skills/mastery-loop-setup/seeds/moc.md

@@ -0,0 +1,15 @@
+# <类值> <下一层类值>（MOC）
+
+> 本文件是聚合产物：机器区由 `aggregate.mjs` 从「知识点的 `归属` + `sys/graph.json`」生成并覆盖；手写区脚本永不碰。
+
+<!-- AUTO:BEGIN -->
+- [[<相对工作区根的知识点路径>.md|<知识点>]] —— <一句话，抄自该篇的 `## 一句话`>
+<!-- AUTO:END -->
+
+## 主线（手写区）
+
+<这一讲的主线 / 脉络，agent 或人写>
+
+## 脉络图（手写区）
+
+<可选>

package/skills/mastery-loop-setup/seeds/note.md

@@ -0,0 +1,33 @@
+---
+类型: 知识点
+分类: ["<类路径 1>/<类路径 2>"]
+归属: ["[[<相对工作区根的来源文件路径>|<人类可读别名>]]"]
+aliases: ["<英文名>"]
+标签: [<标签>, <标签>]
+---
+
+# <中文名> <英文名>
+
+## 一句话
+
+<一句话说清它是什么>
+
+## 核心内容
+
+<正文>
+
+## 前置知识
+
+- [[<相对工作区根的知识点路径>.md|<前置知识点>]] —— <≤30 字理由，与 sys/graph.json 的 reason 逐字一致>
+
+## 后置知识
+
+_（由图反算，不手写）_
+
+## 易错点 / 考点
+
+- <易错点>
+
+## 讲义出处
+
+<哪份材料、第几页 / 第几张 slide>

package/skills/mastery-loop-setup/seeds/paper-format.json

@@ -0,0 +1,15 @@
+{
+  "用途": "本文件是卷面参数表：每个课程的每场考试各一条（期中 / 期末 / in-class / coursework 形状不同，必须分开），出题时从这里抄。",
+  "考试": [
+    {
+      "课程": "<课程名>",
+      "考试": "<例：期中 / 期末 / in-class>",
+      "时长": "<抄自材料>",
+      "总分": "<抄自材料>",
+      "题数": "<抄自材料>",
+      "题型与分值分布": "<抄自材料>",
+      "来源": "<抄自哪份文件>"
+    }
+  ],
+  "备注": "没有往年卷时用默认出卷法（判断题 + 每题说明理由），并在该条写明。"
+}

package/skills/mastery-loop-setup/seeds/state.jsonl

@@ -0,0 +1,2 @@
+{"kind":"header","用途":"本文件是状态表（变化检测）：有 git 时只记上次检查到的提交号；没有 git 时逐文件记内容哈希。管「要不要重看」，不管「发生过什么」（那是 git / changes.jsonl）。"}
+{"mode":"git","last":"<上次检查到的 commit>","schema":"0.2.0","checked":"<YYYY-MM-DD HH:MM>"}