dsh-mastery-loop 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.2.0
+
+**架构重写（不兼容）** —— 库的布局、文件格式、脚本边界全变了。已有的库要重新对齐一次。
+
+**修复（自 0.1.0 起就坏的 bug）**：`mastery-loop-setup` 的 frontmatter 是**非法 YAML** —— `description` 写成裸标量，里面含 `mastery-loop: explore` 的「冒号 + 空格」。DSH 加载器对非法 frontmatter 的处理是**把整个 skill 丢弃**，所以 **`/mastery-loop-setup` 从 0.1.0 起就从未出现过**（模型侧、用户侧都没有），不是开关问题。已改成 `>-` 折行块标量（文字未改）。
+
+**布局**：工作区根下两个并列文件夹 —— `kb/`（内容区，给人看）+ `sys/`（机器区，给脚本读）。
+
+- `kb/knowledge/` 知识点 · `kb/MOC/` 聚合产物（镜像分类层级）
+- `sys/config.json` · `sys/graph.json` · `sys/ledger.jsonl` · `sys/errors.jsonl` · `sys/error-taxonomy.json` · `sys/paper-format.json` · `sys/state.jsonl`
+- `sys/changes.jsonl` 只在「没有 git 且用户不装 git」时启用
+
+**知识点契约**
+
+- `归属` = **来源文件**（多值、必填）；**删 `课程:` / `主题:` / `难度:`** —— 课程与讲次改为**从 `归属` 解析**
+- 正文固定六节，**删 `## 平行关联`**；`## 后置知识` 由图反算、不手写
+- 链接一律**带路径、相对工作区根、带后缀、带别名**
+
+**分类与范围**：分类是**全库级定义**（层数不固定、每层一条解析规则、类值经用户确认后写进 config）；**范围 = 分类里的一个或多个类值**。
+
+**关系图**：`sys/graph.json`（`用途` / `规则` / `coverage` / `edges`）；边带 **≤30 字**理由；**后置由图反算**；**六项校验**（双向自洽 / 无自链 / 无悬空 / 同段无重复 / 前后置互斥 / 前置两两不可比）。
+
+**聚合与两区**：`kb/MOC/` 的**机器区**由 `aggregate.mjs` 从「`归属` + 图」生成并覆盖；**手写区**（主线、脉络、考点提示）脚本**永不碰**。
+
+**脚本边界**：脚本只做重复性、机械性、不需要变通的事（校验 / 渲染 / 聚合 / 哈希跳过 / 账本运算 / 批量写回）；判断前置、写理由、出题、批改、**错误原因逐字去重**留给 agent。
+
+**git 不硬依赖**：有 git 就用它承担历史（**不自动 commit、绝不 push**）；没有且用户不装 → 回退 `sys/changes.jsonl`。
+
+**其它**：删掉 `index.md`（索引 = 聚合结果的层级视图）；Miyo 仍为**可选**、发布版不依赖。
+
 ## 0.1.0
 
 首个版本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mastery-loop",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Opt-in DeepSeek Harness skill bundle: mastery-loop — an exam-revision loop that drills until every knowledge point reaches your target accuracy. / 通用应试复习闭环。",
   "license": "MIT",
   "type": "module",

package/skills/mastery-loop/SKILL.md

@@ -12,11 +12,13 @@ description: >-
 
 ---
 
-## 0 · 三条硬规矩
+## 0 · 四条硬规矩
 
 1. **不主动扫库。** 初始化之后只在三种情况下才动知识库：① 读到**不符合要求**的文件 → 处理那**一个**；② 出现**新文件** → 处理；③ **用户主动调用** → 才做。
-2. **笔记的定义部分不动。** 只写那几个记录文件（`ledger.md` / `errors.md` / `index.md` / `paper-format.md`），以及 MOC 的「知识点清单」。**知识点正文与 frontmatter 不碰。**
+2. **笔记的定义部分默认不动。** 平时只写 `sys/`（*机器区：账本 / 错误原因 / 关系图 / 状态*）与 `kb/MOC/` 的**机器区**。
+   **没有新增或修订知识点时不碰；当知识库的架构本身要改（如关系图重建）时，改写是正当的。**
 3. **不声称符合 ASD-STE100。** 错误原因**尽可能按 STE 的规则写**，这是借用它的原则，不是合规声明。
+4. **脚本只做机械重复的事。** 校验、渲染、聚合、哈希比对、账本运算交给 `scripts/`（Node，零依赖，`node xxx.mjs`）；**判断谁是谁的前置、写理由、出题、批改、错误原因逐字去重**留给自己。**不自动 `commit`、绝不 `push`。**
 
 ---
 
@@ -24,11 +26,11 @@ description: >-
 
 ### 1.1 先确认初始化过
 
-读 `config.md` → 找**知识库根目录** → 读 `ledger.md`。
+读 `sys/config.json` → 找**工作区根** → 读 `sys/ledger.jsonl`。
 
-- **`ledger.md` 不存在，或顶部没有「首次对齐」标记行** → **停下来**，告诉用户：
+- **`sys/ledger.jsonl` 不存在** → **停下来**，告诉用户：
 
-  > 这个知识库还没初始化过。先跑一次 `/mastery-loop-setup`，它会把 6 个文件建好，之后我再开工。
+  > 这个知识库还没初始化过。先跑一次 `/mastery-loop-setup`，它会把 `kb/` 与 `sys/` 建好，之后我再开工。
 
   **不要自己进初始化流程** —— 那件事归 `mastery-loop-setup`。
 
@@ -39,9 +41,9 @@ description: >-
 顺序固定：
 
 ```
-config.md（路径 + 每门课的成员选择 + 语言标准）
-   → ledger.md（进度；标记行已确认）
-   → paper-format.md（本次考试的格式）
+sys/config.json（路径 + 分类 + 语言标准）
+   → sys/ledger.jsonl（进度）
+   → sys/paper-format.json（本次考试的格式）
 ```
 
 然后**把读到的状态摆出来**：
@@ -79,11 +81,11 @@ config.md（路径 + 每门课的成员选择 + 语言标准）
 
 ### 3.1 先给复习清单
 
-按 `ledger.md` 排：**熟练度低的在前**，`NULL`（没学过）和「样本不足」标出来。
+按 `sys/ledger.jsonl` 排：**熟练度低的在前**，`NULL`（没学过）和「样本不足」标出来。
 
 ### 3.2 出题
 
-**卷子参数从 `paper-format.md` 查**对应考试的那一条 —— **不要从往年卷现抄**。
+**卷子参数从 `sys/paper-format.json` 查**对应考试的那一条 —— **不要从往年卷现抄**。
 查不到 → 用**默认出卷法：判断题 + 每题说明理由**。
 
 配比（按本次范围的题池算，不按课程切分）：
@@ -94,7 +96,7 @@ config.md（路径 + 每门课的成员选择 + 语言标准）
 | 30% | `是否学习过 = 否` 的点 |
 | 10% | `最后复习日期` 最久远的点（防遗忘） |
 
-卷子模板 → [templates.md](templates.md#试卷模板)。
+卷子模板 → [exam-templates.md](exam-templates.md#试卷模板)。
 
 ### 3.3 每题后面必须挂两行
 
@@ -126,7 +128,7 @@ config.md（路径 + 每门课的成员选择 + 语言标准）
 2. **详细解析** —— 引用材料原文逻辑；计算题给完整中间步骤
 3. **薄弱点定位** —— 说清**为什么错**（从思维链里看），别笼统说「理解不到位」
 
-判分口径 → [templates.md](templates.md#判分口径)。
+判分口径 → [exam-templates.md](exam-templates.md#判分口径)。
 
 ### 3.5 提炼错误原因（只在错 ≥1 时）
 
@@ -139,19 +141,18 @@ config.md（路径 + 每门课的成员选择 + 语言标准）
 - **动词开头**且**必须带对象**（禁 `wrong`、`didn't know`）
 - **指代不悬空**
 
-然后**去 `errors.md` 里查**：
+然后**去 `sys/errors.jsonl` 里查**：
 
 1. **在该知识点分组内全量检索**
 2. 有**逐字一样**的 → **只追加日期**，**绝不重新措辞**
 3. 没有 → 新增一条
 
-### 3.6 写回文件
+### 3.6 写回（顺序写死，不许反向；契约正文 → [templates.md](templates.md)）
 
-- **`ledger.md`** —— 更新 `做对` / `总共出过` / `熟练程度` / `最后复习日期` / `是否学习过`。
-  （`做对` 只在**思维链对且答案对**时 +1。）
-- **`errors.md`** —— 按上面的规则追加日期或新增条目（**先按知识点分组，再按错误原因分组**）。
-- **`index.md`** —— 有变动时**先改索引**。
-- **MOC 清单** —— 再从索引刷新受影响 MOC 的「## 知识点清单」。**永不反向。**
+- **关系图** —— 本次**若新增或修订了知识点**：先改 `sys/graph.json`（逻辑定前置 → 写边与 ≤30 字理由），再由 `graph.mjs` 算后置并渲染 `## 前置知识` / `## 后置知识`，最后跑六项校验。**没动知识点就跳过这一步。**
+- **账本** —— 你只输出字段（做对 / 总共出过 / 熟练程度 / 最后复习日期 / 是否学习过），由 `ledger.mjs` 写进 `sys/ledger.jsonl`。（`做对` 只在**思维链对且答案对**时 +1。）
+- **错误原因** —— 逐字去重由**你**做（脚本会把「把 A1 和 B 弄混」和「把 A2 和 B 弄混」误判成重复），写完让脚本写进 `sys/errors.jsonl`。
+- **`kb/MOC/` 的机器区** —— 跑 `aggregate.mjs` 从「`归属` + 图」聚合；**手写区一个字不动**。
 
 ### 3.7 达标与继续
 
@@ -171,13 +172,13 @@ config.md（路径 + 每门课的成员选择 + 语言标准）
 
 **从第一轮批改就开始攒。** 每轮出错，就把该点的 `规则 / ⚠️ 常见错误 / 🔑 锚` 三行补进去 —— 出错的那一刻正是信息最鲜活的时候。到复习结束时，它**已经**是成品。
 
-模板 → [templates.md](templates.md#考前-list)。
+模板 → [exam-templates.md](exam-templates.md#考前-list)。
 
 ---
 
 ## 4 · 产出：考前 list
 
-**独立成文**（一篇笔记，与那 6 个文件并列）。**只收出过错的点**，按知识点一条，三行结构：
+**独立成文**（一篇 Markdown 笔记，放在 `kb/` 下）。**只收出过错的点**，按知识点一条，三行结构：
 
 ```
 ### <知识点>

package/skills/mastery-loop/exam-templates.md

@@ -0,0 +1,102 @@
+# 出题 · 判分 · 考前 list 模板
+
+> **本文件是三个固定模板**：试卷骨架、判分口径、考前 list。契约正文（*库长什么样*）在 [templates.md](templates.md)。
+> **按需查，别通读。**
+
+---
+
+## 试卷模板
+
+> ⚠️ **参数从 `sys/paper-format.json` 查**对应考试的那一条 —— **不要从往年卷现抄**。
+> 查不到 → 用**默认出卷法：判断题 + 每题说明理由**。
+
+```markdown
+# PRACTICE EXAM PAPER — ROUND N
+
+**Based on**: <paper-format.json 里的考试名>
+**Time Allowed**: <抄自 paper-format.json>
+**Total Marks**: <抄自 paper-format.json>
+
+---
+
+## Question 1 (<marks> marks)
+
+<题干>
+
+(a) <小问> (<marks> marks)
+(b) ...
+
+答案：
+思维链：
+
+## Question 2 (<marks> marks)
+
+...
+
+答案：
+思维链：
+
+**END OF PAPER**
+```
+
+硬性要求：
+
+- **Round N** 每轮递增；**跨轮保持同一套卷子参数**，这样正确率才可比。
+- **每道题后面必须挂 `答案：` / `思维链：` 两行** —— 选择题也要。
+- 判断正误类小题，题干里就写明「**先判对错，再给理由**」。
+- 分值分配**照 `sys/paper-format.json`**，不要自己发明比例。
+- 卷尾之后**不得**出现任何答案、提示、「解析见下」的字样。
+
+---
+
+## 判分口径
+
+| 题型 | 给分 | 扣分 / 零分 |
+| --- | --- | --- |
+| 判断正误 | 分类正确 + 解释命中关键词 | 只写 T/F 没解释 → 0；解释不引材料逻辑 → 减半 |
+| 计算 | 结果正确 + 中间步骤齐全 | 结果对但无 working → 扣步骤分；结果错但步骤对 → 给步骤分 |
+| 定义 | 关键词出现 + 给出具体示例 | 只背课本句式、无示例 → 不满分 |
+| 画图 / 证明 | 图元齐全（轴标签、方向、边界）/ 每步有依据 | 图对但无标注 → 扣分 |
+
+**总分与正确率按卷面原始分算**，不折算、不向上取整。
+
+### ⚠️ 与「做对」的区别
+
+- **判分**用的是上面这张表（看答案）。
+- **账本里的「做对」是另一回事**：必须 **思维链对 且 答案对**。
+  **蒙对**在评分表里可能得分，但在账本里**不算做对** —— 而且**要提炼一条错误原因**。
+
+批改纪律：
+
+- **给分严格，只认关键词。** 别给「思路对了」这种虚分。
+- 判错要**指到用户具体的句子**（在思维链里找），不要笼统说「理解不到位」。
+- 也要指出**答得好**的部分 —— 避免用户误以为整块都薄弱。
+
+---
+
+## 考前 list
+
+**独立成文**（一篇 Markdown 笔记，放在 `kb/` 下）。**只收出过错的点**，按知识点一条。
+
+**从第一轮批改就开始攒** —— 每轮出错就把三行补进去，别等最后生成。
+
+```markdown
+# 考前 list
+
+## Section A: <分类里的类值>
+
+### <知识点>
+> **规则**：<正确说法>
+> ⚠️ **常见错误**：<我实际犯的错 —— 与 sys/errors.jsonl 里的错误原因一致>
+> 🔑 **锚**：<一句话记忆钩子 / 反例>
+
+## ⏱️ 考前 15 分钟速查
+- <最致命的 N 条，一行一条>
+```
+
+要求：
+
+- 一个知识点**只占三行**，超过说明还没提炼干净。
+- **`⚠️ 常见错误` 必须与 `sys/errors.jsonl` 里的错误原因逐字一致** —— 那是同一份事实，不要换措辞。
+- 锚点优先用**反例**或**极端情形**，不要口诀式废话。
+- 涵盖**全部轮次**，不重复同一意思的条目。

package/skills/mastery-loop/scripts/_lib.mjs

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+// 共享工具（不单独使用）
+//
+// 用途：本文件是其它脚本共用的最小工具集 —— 读写 JSON / JSONL、解析 frontmatter、
+//       收集知识点、扫 wikilink、替换 AUTO 区。**零依赖、不拼 shell。**
+
+import { readFileSync, writeFileSync, existsSync, statSync, readdirSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, relative, dirname, sep } from 'node:path';
+
+export const KB = 'kb';
+export const NOTES = join('kb', 'knowledge');
+export const MOC = join('kb', 'MOC');
+export const SYS = 'sys';
+export const AUTO_BEGIN = '<!-- AUTO:BEGIN -->';
+export const AUTO_END = '<!-- AUTO:END -->';
+
+export function readIfPossible(p) {
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export function writeText(p, text) {
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, text, 'utf8');
+}
+
+export function sha1(text) {
+  return 'sha1:' + createHash('sha1').update(text, 'utf8').digest('hex').slice(0, 16);
+}
+
+export function readJson(p) {
+  const t = readIfPossible(p);
+  if (t === null) return { ok: false, reason: `读不了：${p}` };
+  try {
+    return { ok: true, data: JSON.parse(t) };
+  } catch (err) {
+    return { ok: false, reason: `${p} 不是合法 JSON：${err.message}` };
+  }
+}
+
+/** JSONL：第一行是 header（kind: header），其余是数据行 */
+export function readJsonl(p) {
+  const t = readIfPossible(p);
+  if (t === null) return { ok: false, reason: `读不了：${p}` };
+  const lines = t.split(/\r?\n/).filter((l) => l.trim());
+  const rows = [];
+  let header = null;
+  lines.forEach((l, i) => {
+    let obj;
+    try {
+      obj = JSON.parse(l);
+    } catch {
+      return;
+    }
+    if (i === 0 && obj && obj.kind === 'header') header = obj;
+    else rows.push(obj);
+  });
+  return { ok: true, header, rows };
+}
+
+export function writeJsonl(p, header, rows) {
+  const text = [JSON.stringify(header), ...rows.map((r) => JSON.stringify(r))].join('\n') + '\n';
+  writeText(p, text);
+}
+
+// ---------- frontmatter（只支持契约用到的那几种写法） ----------
+
+/** 切出 frontmatter 文本与正文 */
+export function splitFrontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/.exec(text);
+  if (!m) return { fm: null, body: text };
+  return { fm: m[1], body: text.slice(m[0].length) };
+}
+
+function parseScalar(s) {
+  let v = s.trim();
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    v = v.slice(1, -1);
+  }
+  return v;
+}
+
+/** 行内列表：["a/b", "c"] —— 引号内的逗号/括号不切 */
+function parseInlineList(s) {
+  const inner = s.trim().replace(/^\[/, '').replace(/\]$/, '');
+  const out = [];
+  let cur = '';
+  let quote = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      cur += ch;
+      continue;
+    }
+    if (ch === ',') {
+      out.push(cur);
+      cur = '';
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur.trim()) out.push(cur);
+  return out.map(parseScalar).filter((x) => x !== '');
+}
+
+/** 极简 YAML 子集 → 对象（够契约用） */
+export function parseFrontmatter(fmText) {
+  const data = {};
+  if (!fmText) return data;
+  for (const line of fmText.split(/\r?\n/)) {
+    const m = /^([A-Za-z0-9_\u4e00-\u9fa5]+)\s*:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const key = m[1];
+    const raw = m[2].trim();
+    if (raw === '' || raw === '>-' || raw === '|') {
+      data[key] = '';
+      continue;
+    }
+    if (raw.startsWith('[')) data[key] = parseInlineList(raw);
+    else data[key] = parseScalar(raw);
+  }
+  return data;
+}
+
+// ---------- 知识点 ----------
+
+export function collectNotes(root) {
+  const map = new Map();
+  const dir = join(root, NOTES);
+  const walk = (d, depth) => {
+    if (depth > 4) return;
+    let entries = [];
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p, depth + 1);
+      else if (/\.md$/i.test(e.name)) map.set(e.name.replace(/\.md$/i, ''), p);
+    }
+  };
+  walk(dir, 0);
+  return map;
+}
+
+export function noteName(raw) {
+  let s = String(raw || '').trim();
+  s = s.replace(/^\[\[/, '').replace(/\]\]$/, '');
+  const pipe = s.indexOf('|');
+  if (pipe !== -1) s = s.slice(0, pipe);
+  s = s.replace(/\.md$/i, '');
+  const parts = s.split(/[\\/]/);
+  return parts[parts.length - 1].trim();
+}
+
+/** 笔记名 + 分类值 + 一句话 */
+export function readNote(root, name, path, cfg) {
+  const text = readIfPossible(path) || '';
+  const { fm, body } = splitFrontmatter(text);
+  const data = parseFrontmatter(fm);
+  const field = cfg?.分类?.字段 || '分类';
+  const csep = cfg?.分类?.分隔符 || '/';
+  const raw = data[field];
+  const 分类 = Array.isArray(raw) ? raw : raw ? [raw] : [];
+  const one = /##\s*一句话\s*\n+([^\n#]+)/.exec(body);
+  return {
+    name,
+    path,
+    rel: relative(root, path).split(sep).join('/'),
+    分类: 分类.map((c) => String(c).split(csep).map((x) => x.trim()).filter(Boolean)),
+    一句话: one ? one[1].trim() : '',
+    text,
+    data,
+  };
+}
+
+// ---------- 正文小节 ----------
+
+export function sectionRange(text, heading) {
+  const re = new RegExp('^##\\s*' + heading + '\\s*$', 'm');
+  const m = re.exec(text);
+  if (!m) return null;
+  const after = text.indexOf('\n', m.index);
+  if (after === -1) return { headStart: m.index, bodyStart: text.length, end: text.length };
+  const rest = text.slice(after + 1);
+  const nextRel = rest.search(/^##[ \t]/m);
+  const end = nextRel === -1 ? text.length : after + 1 + nextRel;
+  return { headStart: m.index, bodyStart: after + 1, end };
+}
+
+export function sectionBullets(text, heading) {
+  const r = sectionRange(text, heading);
+  if (!r) return null;
+  const body = text.slice(r.bodyStart, r.end);
+  const names = [];
+  for (const line of body.split(/\r?\n/)) {
+    const mm = line.match(/^\s*[-*]\s+\[\[([^\]]+?)\]\]/);
+    if (mm) names.push(noteName(mm[1]));
+  }
+  return names;
+}
+
+export function replaceSection(text, heading, bullets) {
+  const r = sectionRange(text, heading);
+  if (!r) return { text, found: false };
+  const body = bullets.length ? bullets.join('\n') : '_（暂无）_';
+  return {
+    text: `${text.slice(0, r.headStart)}## ${heading}\n\n${body}\n\n${text.slice(r.end)}`,
+    found: true,
+  };
+}
+
+// ---------- AUTO 区 ----------
+
+export function replaceAutoZone(text, lines) {
+  const b = text.indexOf(AUTO_BEGIN);
+  const e = text.indexOf(AUTO_END);
+  const block = `${AUTO_BEGIN}\n${lines.join('\n')}\n${AUTO_END}`;
+  if (b === -1 || e === -1 || e < b) {
+    // 没有标记：原地补一个，放在第一个 `## ` 之前（或文件末尾）
+    const at = text.search(/^##[ \t]/m);
+    const body = `${block}\n\n`;
+    return at === -1 ? text.trimEnd() + '\n\n' + body : text.slice(0, at) + body + text.slice(at);
+  }
+  return text.slice(0, b) + block + text.slice(e + AUTO_END.length);
+}
+
+// ---------- 链接 ----------
+
+export function parseLinks(text) {
+  const out = [];
+  const re = /\[\[([^\]\n]+?)\]\]/g;
+  let m;
+  while ((m = re.exec(text))) {
+    const raw = m[1];
+    const pipe = raw.indexOf('|');
+    const target = (pipe === -1 ? raw : raw.slice(0, pipe)).trim();
+    const alias = pipe === -1 ? '' : raw.slice(pipe + 1).trim();
+    out.push({ raw, target, alias });
+  }
+  return out;
+}
+
+export function walkMarkdown(root, dirRel = '.', depth = 0, out = []) {
+  if (depth > 5) return out;
+  const dir = join(root, dirRel);
+  let entries = [];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.')) continue;
+    const rel = dirRel === '.' ? e.name : join(dirRel, e.name);
+    if (e.isDirectory()) walkMarkdown(root, rel, depth + 1, out);
+    else if (/\.md$/i.test(e.name)) out.push(join(root, rel));
+  }
+  return out;
+}
+
+export function existsDir(p) {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+
+// ⚠️ 下面是**未被调用的副本**：图的单一实现是 `graph.mjs` 的 `check()`（`scan.mjs` 直接 import 它）。
+//    保留只为对照；下次清理时删掉，别再往这里加逻辑。
+
+export function checkGraph(root) {
+  const problems = [];
+  const warnings = [];
+  const g = readJson(join(root, SYS, 'graph.json'));
+  if (!g.ok) {
+    return { ok: false, reason: g.reason, problems, warnings, edges: [], notes: new Map(), involved: new Set() };
+  }
+  const data = g.data;
+  const edges = Array.isArray(data.edges) ? data.edges : [];
+  const notes = collectNotes(root);
+  const hasNote = (name) => notes.has(name);
+
+  const fwd = new Map();
+  const bwd = new Map();
+  const addTo = (m, k, v) => {
+    if (!m.has(k)) m.set(k, new Set());
+    m.get(k).add(v);
+  };
+
+  edges.forEach((e, i) => {
+    const at = `edges[${i}]`;
+    const from = noteName(e && e.from);
+    const to = noteName(e && e.to);
+    const reason = e && typeof e.reason === 'string' ? e.reason.trim() : '';
+    if (!from || !to) {
+      problems.push(`${at}：缺 from 或 to`);
+      return;
+    }
+    if (from === to) problems.push(`无自链 ✖ ${at}：${from} → ${to}`);
+    if (!hasNote(from)) problems.push(`无悬空 ✖ ${at}：找不到笔记「${from}」`);
+    if (!hasNote(to)) problems.push(`无悬空 ✖ ${at}：找不到笔记「${to}」`);
+    if (!reason) problems.push(`${at}：缺 reason（每条边必须 ≤30 字理由）`);
+    else if ([...reason].length > 30) problems.push(`${at}：reason ${[...reason].length} 字 > 30（${reason}）`);
+    addTo(fwd, from, to);
+    addTo(bwd, to, from);
+  });
+
+  const involved = new Set([...fwd.keys(), ...bwd.keys()]);
+
+  for (const [name, path] of notes) {
+    const text = readIfPossible(path);
+    if (text === null) {
+      warnings.push(`读不了：${path}`);
+      continue;
+    }
+    const pre = sectionBullets(text, '前置知识');
+    const post = sectionBullets(text, '后置知识');
+    if (involved.has(name)) {
+      if (pre === null) warnings.push(`「${name}」缺 \`## 前置知识\` 小节`);
+      if (post === null) warnings.push(`「${name}」缺 \`## 后置知识\` 小节`);
+    }
+    for (const [label, list] of [['前置知识', pre], ['后置知识', post]]) {
+      if (!list) continue;
+      const seen = new Set();
+      for (const n of list) {
+        if (seen.has(n)) problems.push(`同段无重复 ✖ 「${name}」\`## ${label}\` 里「${n}」出现两次`);
+        seen.add(n);
+      }
+    }
+    if (pre && post) {
+      const both = [...new Set(pre.filter((n) => post.includes(n)))];
+      if (both.length) problems.push(`前后置互斥 ✖ 「${name}」同时出现在前置与后置：${both.join('、')}`);
+    }
+    if (pre) {
+      for (const n of new Set(pre)) {
+        if (!(bwd.get(name) || new Set()).has(n)) {
+          problems.push(`双向自洽 ✖ 「${name}」的 \`## 前置知识\` 里有「${n}」，但图里没有这条边`);
+        }
+      }
+    }
+    if (post) {
+      for (const n of new Set(post)) {
+        if (!(fwd.get(name) || new Set()).has(n)) {
+          problems.push(`双向自洽 ✖ 「${name}」的 \`## 后置知识\` 里有「${n}」，但图里没有这条边`);
+        }
+      }
+    }
+  }
+
+  for (const [from, tos] of fwd) {
+    for (const to of tos) {
+      const t1 = notes.has(from) ? readIfPossible(notes.get(from)) : null;
+      if (t1 !== null) {
+        const post = sectionBullets(t1, '后置知识') || [];
+        if (!post.includes(to)) problems.push(`双向自洽 ✖ 「${from}」的 \`## 后置知识\` 缺「${to}」（图里有这条边）`);
+      }
+      const t2 = notes.has(to) ? readIfPossible(notes.get(to)) : null;
+      if (t2 !== null) {
+        const pre = sectionBullets(t2, '前置知识') || [];
+        if (!pre.includes(from)) problems.push(`双向自洽 ✖ 「${to}」的 \`## 前置知识\` 缺「${from}」（图里有这条边）`);
+      }
+    }
+  }
+
+  const reach = (start) => {
+    const seen = new Set([start]);
+    const stack = [...(fwd.get(start) || [])];
+    while (stack.length) {
+      const cur = stack.pop();
+      if (seen.has(cur)) continue;
+      seen.add(cur);
+      for (const t of fwd.get(cur) || []) if (!seen.has(t)) stack.push(t);
+    }
+    seen.delete(start);
+    return seen;
+  };
+  for (const name of involved) {
+    const path = notes.get(name);
+    if (!path) continue;
+    const list = sectionBullets(readIfPossible(path) || '', '前置知识');
+    if (!list) continue;
+    const uniq = [...new Set(list)];
+    for (let i = 0; i < uniq.length; i++) {
+      for (let j = i + 1; j < uniq.length; j++) {
+        const a = uniq[i];
+        const b = uniq[j];
+        if (reach(a).has(b)) problems.push(`前置两两不可比 ✖ 「${name}」的前置里「${a}」已经是「${b}」的前置 —— 只收直接前置`);
+        else if (reach(b).has(a)) problems.push(`前置两两不可比 ✖ 「${name}」的前置里「${b}」已经是「${a}」的前置 —— 只收直接前置`);
+      }
+    }
+  }
+
+  if (data['用途'] === undefined) warnings.push('graph.json 缺「用途」字段');
+  if (data['规则'] === undefined) warnings.push('graph.json 缺「规则」字段');
+
+  return { ok: true, data, edges, notes, involved, problems, warnings, fwd, bwd };
+}