dsh-mastery-loop 0.1.0 → 0.2.0

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

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// 账本脚本
+//
+// 用途：本脚本管 sys/ledger.jsonl（复习账本，真值）—— 算达标、按 60/30/10 划范围清单、把批改结果写回。
+// 契约正文：../templates.md（第十一节）
+//
+// 用法：
+//   node ledger.mjs stats <工作区根> [--scope 深度学习/L3] [--target 0.9]
+//   node ledger.mjs pick  <工作区根> [--scope …] [--target 0.9] [--n 20]
+//   node ledger.mjs write <工作区根> <updates.jsonl>
+//
+// write 的输入：一行一条 {"知识点":"梯度","做对":1,"总共出过":1,"是否学习过":true,"最后复习日期":"2026-10-15"}
+//   其中 做对 / 总共出过 按**增量**累加；熟练程度自动 = 做对 / 总共出过。
+
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { SYS, NOTES, readJson, readJsonl, writeJsonl, collectNotes, readNote, readIfPossible } from './_lib.mjs';
+
+function load(root) {
+  const cfg = readJson(join(root, SYS, 'config.json'));
+  const led = readJsonl(join(root, SYS, 'ledger.jsonl'));
+  if (!led.ok) return { err: led.reason };
+  const notes = new Map();
+  for (const [name, p] of collectNotes(root)) {
+    const n = readNote(root, name, p, cfg.ok ? cfg.data : null);
+    notes.set(name, n.分类);
+  }
+  return { cfg: cfg.ok ? cfg.data : null, header: led.header, rows: led.rows, classes: notes };
+}
+
+function inScope(classes, scopeParts) {
+  if (!scopeParts) return true;
+  const list = classes || [];
+  return list.some((parts) => {
+    if (parts.length < scopeParts.length) return false;
+    return scopeParts.every((s, i) => parts[i] === s);
+  });
+}
+
+function proficiency(row) {
+  const done = Number(row['总共出过'] || 0);
+  const right = Number(row['做对'] || 0);
+  if (!done) return null;
+  return Math.round((right / done) * 1000) / 1000;
+}
+
+function flag(row, target) {
+  const done = Number(row['总共出过'] || 0);
+  const p = proficiency(row);
+  if (done < 5) return '样本不足';
+  if (p !== null && p >= target) return '达标';
+  return '未达标';
+}
+
+function cmdStats(root, scopeParts, target) {
+  const L = load(root);
+  if (L.err) {
+    console.log(`❌ ${L.err}`);
+    return 1;
+  }
+  const rows = L.rows.filter((r) => inScope(L.classes.get(r['知识点']), scopeParts));
+  console.log(`范围：${scopeParts ? scopeParts.join('/') : '全库'} · 知识点 ${rows.length} 个 · 目标正确率 ${target}`);
+  console.log('');
+  let ok = 0;
+  let thin = 0;
+  let bad = 0;
+  for (const r of rows) {
+    const f = flag(r, target);
+    if (f === '达标') ok++;
+    else if (f === '样本不足') thin++;
+    else bad++;
+    const p = proficiency(r);
+    console.log(
+      `- ${r['知识点']} · 出过 ${r['总共出过'] ?? 0} · 做对 ${r['做对'] ?? 0} · 熟练程度 ${p === null ? 'NULL' : p} · ${f}` +
+        (r['最后复习日期'] ? ` · 最后 ${r['最后复习日期']}` : '')
+    );
+  }
+  console.log('');
+  console.log(`达标 ${ok} · 未达标 ${bad} · 样本不足 ${thin}`);
+  return 0;
+}
+
+function cmdPick(root, scopeParts, target, n) {
+  const L = load(root);
+  if (L.err) {
+    console.log(`❌ ${L.err}`);
+    return 1;
+  }
+  const rows = L.rows.filter((r) => inScope(L.classes.get(r['知识点']), scopeParts));
+  const weakest = [...rows].sort((a, b) => {
+    const pa = proficiency(a);
+    const pb = proficiency(b);
+    if (pa === null && pb === null) return Number(a['总共出过'] || 0) - Number(b['总共出过'] || 0);
+    if (pa === null) return -1;
+    if (pb === null) return 1;
+    return pa - pb;
+  });
+  const never = rows.filter((r) => r['是否学习过'] !== true);
+  const oldest = [...rows]
+    .filter((r) => r['最后复习日期'])
+    .sort((a, b) => String(a['最后复习日期']).localeCompare(String(b['最后复习日期'])));
+
+  const total = n || rows.length;
+  const nA = Math.round(total * 0.6);
+  const nB = Math.round(total * 0.3);
+  const nC = Math.max(0, total - nA - nB);
+
+  const chosen = [];
+  const seen = new Set();
+  const take = (list, k, label) => {
+    for (const r of list) {
+      if (chosen.length >= total) return;
+      if (k <= 0) return;
+      const key = r['知识点'];
+      if (seen.has(key)) continue;
+      seen.add(key);
+      chosen.push({ ...r, bucket: label });
+      k--;
+    }
+  };
+  take(weakest, nA, '60% 熟练度最低');
+  take(never, nB, '30% 没学过');
+  take(oldest.length ? oldest : weakest, nC, '10% 最久没碰');
+  take(weakest, total, '补齐');
+
+  console.log(`本次范围：${scopeParts ? scopeParts.join('/') : '全库'} · 目标正确率 ${target} · 题量 ${total}`);
+  console.log('');
+  let last = '';
+  for (const r of chosen) {
+    if (r.bucket !== last) {
+      console.log(`## ${r.bucket}`);
+      last = r.bucket;
+    }
+    const p = proficiency(r);
+    console.log(`- ${r['知识点']}　（出过 ${r['总共出过'] ?? 0} · 做对 ${r['做对'] ?? 0} · 熟练程度 ${p === null ? 'NULL' : p}）`);
+  }
+  return 0;
+}
+
+function cmdWrite(root, updatesPath) {
+  const L = load(root);
+  if (L.err) {
+    console.log(`❌ ${L.err}`);
+    return 1;
+  }
+  const text = readIfPossible(resolve(updatesPath));
+  if (text === null) {
+    console.log(`❌ 读不了更新文件：${updatesPath}`);
+    return 1;
+  }
+  const updates = text
+    .split(/\r?\n/)
+    .filter((l) => l.trim())
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  const byName = new Map(L.rows.map((r) => [r['知识点'], r]));
+  let changed = 0;
+  for (const u of updates) {
+    const row = byName.get(u['知识点']);
+    if (!row) {
+      console.log(`⚠️  账本里没有「${u['知识点']}」（跳过）`);
+      continue;
+    }
+    if (u['做对'] !== undefined) row['做对'] = Number(row['做对'] || 0) + Number(u['做对']);
+    if (u['总共出过'] !== undefined) row['总共出过'] = Number(row['总共出过'] || 0) + Number(u['总共出过']);
+    if (u['是否学习过'] !== undefined) row['是否学习过'] = u['是否学习过'] === true;
+    if (u['最后复习日期'] !== undefined) row['最后复习日期'] = u['最后复习日期'];
+    const p = proficiency(row);
+    row['熟练程度'] = p === null ? null : p;
+    changed++;
+  }
+
+  writeJsonl(join(root, SYS, 'ledger.jsonl'), L.header || { kind: 'header', '用途': '本文件是复习账本：逐条记每个知识点的复习统计。' }, L.rows);
+  console.log(`已写回 ${changed} 行（共 ${L.rows.length} 行）。`);
+  return 0;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  const rest = argv.slice(1).filter((a) => !a.startsWith('--'));
+  const opt = (name, dflt) => {
+    const i = argv.indexOf(name);
+    return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : dflt;
+  };
+
+  if (!['stats', 'pick', 'write'].includes(cmd)) {
+    console.log('用法：');
+    console.log('  node ledger.mjs stats <工作区根> [--scope 深度学习/L3] [--target 0.9]');
+    console.log('  node ledger.mjs pick  <工作区根> [--scope …] [--target 0.9] [--n 20]');
+    console.log('  node ledger.mjs write <工作区根> <updates.jsonl>');
+    return 2;
+  }
+
+  const root = resolve(rest[0] || '.');
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.log(`❌ 工作区根不存在：${root}`);
+    return 1;
+  }
+  const scope = opt('--scope', '')
+    .split('/')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const target = Number(opt('--target', '0.9')) || 0.9;
+
+  if (cmd === 'stats') return cmdStats(root, scope.length ? scope : null, target);
+  if (cmd === 'pick') return cmdPick(root, scope.length ? scope : null, target, Number(opt('--n', '0')) || 0);
+  return cmdWrite(root, rest[1]);
+}
+
+try {
+  process.exit(main());
+} catch (err) {
+  console.log('❌ ledger.mjs 自身出错：' + (err && err.message ? err.message : String(err)));
+  process.exit(1);
+}

package/skills/mastery-loop/scripts/rewrite-links.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// 重写链接脚本
+//
+// 用途：本脚本把「路径变了但链接没跟着改」的 wikilink 修回当前路径（名字唯一才敢改，重名的一律留给人）。
+// 契约正文：../templates.md（第二、七节）
+//
+// 用法：
+//   node rewrite-links.mjs <工作区根>            # 只列建议（不写盘）
+//   node rewrite-links.mjs <工作区根> --apply    # 真写
+
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { readIfPossible, writeText, walkMarkdown, parseLinks } from './_lib.mjs';
+
+function main() {
+  const argv = process.argv.slice(2);
+  const root = resolve(argv.find((a) => !a.startsWith('--')) || '.');
+  const apply = argv.includes('--apply');
+
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.log(`❌ 工作区根不存在：${root}`);
+    return 2;
+  }
+
+  const files = walkMarkdown(root, '.');
+  const rels = files.map((p) => p.slice(root.length + 1).split('\\').join('/'));
+  const relSet = new Set(rels);
+  const byBase = new Map();
+  for (const rel of rels) {
+    const base = rel.split('/').pop().replace(/\.md$/i, '');
+    if (!byBase.has(base)) byBase.set(base, []);
+    byBase.get(base).push(rel);
+  }
+
+  let planned = 0;
+  let written = 0;
+
+  for (let i = 0; i < files.length; i++) {
+    const path = files[i];
+    const rel = rels[i];
+    const text = readIfPossible(path);
+    if (text === null) continue;
+
+    let next = text;
+    let touched = false;
+    for (const link of parseLinks(text)) {
+      const t = link.target.replace(/^\.\//, '');
+      if (relSet.has(t) || relSet.has(t + '.md')) continue;
+      const base = t.split('/').pop().replace(/\.md$/i, '');
+      const hits = byBase.get(base) || [];
+      if (hits.length !== 1) continue;
+      const fixed = hits[0].endsWith('.md') ? hits[0] : hits[0] + '.md';
+      const before = link.alias ? `[[${link.target}|${link.alias}]]` : `[[${link.target}]]`;
+      const after = link.alias ? `[[${fixed}|${link.alias}]]` : `[[${fixed}]]`;
+      if (!next.includes(before)) continue;
+      next = next.replace(before, after);
+      touched = true;
+      planned++;
+      console.log(`${apply ? '改写' : '建议'}：${rel}\n    ${before}  →  ${after}`);
+    }
+    if (touched && apply && next !== text) {
+      writeText(path, next);
+      written++;
+    }
+  }
+
+  console.log('');
+  if (!planned) {
+    console.log('✅ 没有需要重写的链接。');
+    return 0;
+  }
+  console.log(apply ? `已写 ${written} 个文件、改 ${planned} 处链接。` : `共 ${planned} 处可自动修（加 --apply 才写盘；重名的链接已跳过）。`);
+  return 0;
+}
+
+try {
+  process.exit(main());
+} catch (err) {
+  console.log('❌ rewrite-links.mjs 自身出错：' + (err && err.message ? err.message : String(err)));
+  process.exit(1);
+}

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

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// 扫库脚本
+//
+// 用途：本脚本是健康检查 —— 查链接、查分类与配置是否对得上、查图与笔记是否一致、查账本引用；
+//       并读 sys/state.jsonl 按内容哈希跳过没变过的文件（--update-state 写回哈希）。
+// 契约正文：../templates.md（第七节）
+//
+// 用法：node scan.mjs <工作区根> [--update-state]
+
+import { existsSync, statSync, readdirSync, openSync, closeSync, unlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import {
+  SYS, readJson, readJsonl, writeJsonl, collectNotes, readNote, readIfPossible,
+  walkMarkdown, parseLinks, sha1,
+} from './_lib.mjs';
+import * as checkGraphModule from './graph.mjs';
+
+const EXPECTED_SCHEMA = '0.2.0';
+
+function main() {
+  const argv = process.argv.slice(2);
+  const root = resolve(argv.find((a) => !a.startsWith('--')) || '.');
+  const updateState = argv.includes('--update-state');
+
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.log(`❌ 工作区根不存在：${root}`);
+    return 2;
+  }
+
+  const problems = [];
+  const notes = [];
+
+  // ---------- 变化检测：**有 git 看 git**，没有 git 才用哈希兜底 ----------
+  // 注意：沙箱里**不能用管道**抓子进程输出（EPERM），所以把 stdout/stderr 重定向到文件描述符再读回来。
+  const TMPGIT = join(root, SYS, '.git-out.tmp');
+  const git = (args) => {
+    let fd = null;
+    try {
+      fd = openSync(TMPGIT, 'w');
+      const r = spawnSync('git', ['-C', root, '-c', 'core.quotePath=false', ...args], { stdio: ['ignore', fd, fd] });
+      closeSync(fd);
+      fd = null;
+      if (r.error || r.status !== 0) return null;
+      return readIfPossible(TMPGIT) || '';
+    } catch {
+      return null;
+    } finally {
+      if (fd !== null) {
+        try {
+          closeSync(fd);
+        } catch {}
+      }
+      try {
+        unlinkSync(TMPGIT);
+      } catch {}
+    }
+  };
+  const gitOk = (git(['rev-parse', '--is-inside-work-tree']) || '').trim() === 'true';
+
+  const st = readJsonl(join(root, SYS, 'state.jsonl'));
+  const stRows = st.ok ? st.rows : [];
+  const now = new Date().toISOString().slice(0, 16).replace('T', ' ');
+
+  const mdFiles = walkMarkdown(root, join('kb'));
+  let stateRows = [];
+  let changedFiles = [];
+  let unchanged = 0;
+  let mode = 'hash';
+
+  if (gitOk) {
+    mode = 'git';
+    const head = (git(['rev-parse', 'HEAD']) || '').trim();
+    const mark = stRows.find((r) => r && r.mode === 'git');
+    const last = mark && mark.last ? mark.last : '';
+
+    const inKb = (p) => p.startsWith('kb/') && /\.md$/i.test(p);
+    const set = new Set();
+
+    // ① 未提交的变化
+    const por = git(['status', '--porcelain']);
+    if (por !== null) {
+      for (const line of por.split(/\r?\n/)) {
+        if (!line.trim()) continue;
+        let p = line.slice(3).trim();
+        const arrow = p.indexOf(' -> ');
+        if (arrow !== -1) p = p.slice(arrow + 4);
+        p = p.replace(/^"|"$/g, '').split('\\').join('/');
+        if (inKb(p)) set.add(p);
+      }
+    }
+    // ② 上次检查之后提交过的变化
+    if (last && head) {
+      const diff = git(['diff', '--name-only', `${last}..HEAD`]);
+      if (diff !== null) {
+        for (const p of diff.split(/\r?\n/)) {
+          const norm = p.trim().split('\\').join('/');
+          if (inKb(norm)) set.add(norm);
+        }
+      }
+    } else if (!last) {
+      for (const p of mdFiles) set.add(p.slice(root.length + 1).split('\\').join('/'));
+    }
+
+    changedFiles = [...set];
+    const total = mdFiles.length;
+    unchanged = Math.max(0, total - changedFiles.length);
+    stateRows = [{ mode: 'git', last: head, schema: EXPECTED_SCHEMA, checked: now }];
+  } else {
+    const prev = new Map(stRows.map((r) => [r.path, r.hash]));
+    for (const p of mdFiles) {
+      const rel = p.slice(root.length + 1).split('\\').join('/');
+      const h = sha1(readIfPossible(p) || '');
+      stateRows.push({ path: rel, hash: h, schema: EXPECTED_SCHEMA, checked: now });
+      if (prev.get(rel) === h) unchanged++;
+      else changedFiles.push(rel);
+    }
+  }
+
+  // ---------- ①② 链接（在**所有文件**里解析：PDF 之类也要算存在） ----------
+  const allFiles = walkMarkdown(root, '.');
+  const allRel = new Set();
+  const allBase = new Map();
+  const collect = (dirRel, depth) => {
+    if (depth > 5) return;
+    let entries = [];
+    try {
+      entries = readdirSync(join(root, dirRel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      const rel = dirRel === '.' ? e.name : join(dirRel, e.name);
+      if (e.isDirectory()) {
+        collect(rel, depth + 1);
+        continue;
+      }
+      const norm = rel.split('\\').join('/');
+      allRel.add(norm);
+      const base = norm.split('/').pop().replace(/\.md$/i, '');
+      if (!allBase.has(base)) allBase.set(base, []);
+      allBase.get(base).push(norm);
+    }
+  };
+  collect('.', 0);
+
+  const normTarget = (t) => t.replace(/^\.\//, '').split('\\').join('/');
+
+  for (const p of allFiles) {
+    const rel = p.slice(root.length + 1).split('\\').join('/');
+    const text = readIfPossible(p) || '';
+    for (const link of parseLinks(text)) {
+      const t = normTarget(link.target);
+      if (allRel.has(t) || allRel.has(t + '.md')) continue;
+      const base = t.split('/').pop().replace(/\.md$/i, '');
+      const hits = allBase.get(base) || [];
+      if (hits.length === 1) {
+        problems.push(`② 路径与目录不符：\`${rel}\` 里的 [[${link.target}]] → 现在它在 \`${hits[0]}\`（跑 rewrite-links.mjs 修）`);
+      } else if (hits.length > 1) {
+        problems.push(`② 路径与目录不符：\`${rel}\` 里的 [[${link.target}]] → 同名有 ${hits.length} 处，得人来定`);
+      } else {
+        problems.push(`① 悬空链接：\`${rel}\` 里的 [[${link.target}]] 找不到目标`);
+      }
+    }
+  }
+
+  // ---------- ③ 分类与配置 ----------
+  const c = readJson(join(root, SYS, 'config.json'));
+  if (!c.ok) {
+    problems.push(`③ ${c.reason}`);
+  } else {
+    const cfg = c.data;
+    const field = cfg?.['分类']?.['字段'] || '分类';
+    const sep = cfg?.['分类']?.['分隔符'] || '/';
+    const levels = cfg?.['分类']?.['层级'] || [];
+    const values = cfg?.['分类']?.['类值'] || {};
+    if (cfg['schema_version'] && cfg['schema_version'] !== EXPECTED_SCHEMA) {
+      problems.push(`③ config.schema_version = ${cfg['schema_version']}，本套脚本按 ${EXPECTED_SCHEMA} 跑 —— 需要迁移`);
+    }
+    for (const [name, p] of collectNotes(root)) {
+      const n = readNote(root, name, p, cfg);
+      notes.push(n);
+      if (!n.分类.length) {
+        problems.push(`③ 「${name}」的 \`${field}\` 是空的 —— 生成知识点时就该附上分类`);
+        continue;
+      }
+      for (const parts of n.分类) {
+        if (levels.length && parts.length !== levels.length) {
+          problems.push(`③ 「${name}」的分类 \`${parts.join(sep)}\` 只有 ${parts.length} 层，配置里是 ${levels.length} 层`);
+        }
+        parts.forEach((v, i) => {
+          const level = levels[i];
+          if (!level) return;
+          const list = (values[level] || []).map((x) => x['值'] ?? x);
+          if (list.length && !list.includes(v)) {
+            problems.push(`③ 「${name}」用的类值 \`${v}\` 没在 config 的「${level}」里声明`);
+          }
+        });
+      }
+    }
+  }
+
+  // ---------- ④ 图与笔记一致（同进程调用 graph.mjs 的 check；沙箱下不能起子进程） ----------
+  const captured = [];
+  const origLog = console.log;
+  console.log = (...a) => captured.push(a.join(' '));
+  let gcode = 1;
+  try {
+    gcode = checkGraphModule.check(root);
+  } catch (err) {
+    captured.push('❌ graph check 抛错：' + (err && err.message ? err.message : String(err)));
+  } finally {
+    console.log = origLog;
+  }
+  if (gcode !== 0) {
+    const lines = captured.filter((l) => l.startsWith('❌'));
+    if (lines.length) for (const l of lines) problems.push(`④ ${l}`);
+    else problems.push(`④ 图校验没过：${captured.find((l) => l.trim()) || '（无输出）'}`);
+  }
+
+  // ---------- ⑤ 账本 / 错误原因引用 ----------
+  const known = new Set(notes.map((n) => n.name));
+  const led = readJsonl(join(root, SYS, 'ledger.jsonl'));
+  if (led.ok) {
+    for (const r of led.rows) {
+      const name = r['知识点'];
+      if (name && !known.has(name)) problems.push(`⑤ 账本里的「${name}」找不到对应知识点`);
+    }
+  }
+  const errs = readJsonl(join(root, SYS, 'errors.jsonl'));
+  if (errs.ok) {
+    for (const r of errs.rows) {
+      const name = r['知识点'];
+      if (name && !known.has(name)) problems.push(`⑤ 错误原因里的「${name}」找不到对应知识点`);
+    }
+  }
+
+  // ---------- 输出 ----------
+  console.log(`扫库：${root}`);
+  console.log(
+    `文件 ${mdFiles.length} 个 · 判定方式：${mode === 'git' ? 'git' : '哈希（这个库没有 git）'} · 没变过的 ${unchanged} 个${changedFiles.length ? ` · 变过的 ${changedFiles.length} 个` : ''} · 知识点 ${notes.length} 篇`
+  );
+  if (changedFiles.length) {
+    console.log('');
+    for (const f of changedFiles.slice(0, 20)) console.log(`· 变过：${f}${changedFiles.length > 20 ? '' : ''}`);
+    if (changedFiles.length > 20) console.log(`· …还有 ${changedFiles.length - 20} 个`);
+  }
+
+  if (updateState) {
+    writeJsonl(
+      join(root, SYS, 'state.jsonl'),
+      { kind: 'header', '用途': '本文件是状态表（变化检测）：有 git 时只记上次检查到的提交号；没有 git 时逐文件记内容哈希。管「要不要重看」，不管「发生过什么」（那是 git / changes.jsonl）。' },
+      stateRows
+    );
+    console.log('（已更新 sys/state.jsonl）');
+  }
+
+  if (problems.length) {
+    console.log('');
+    for (const p of problems) console.log(`❌ ${p}`);
+    console.log('');
+    console.log(`未过：${problems.length} 个问题。`);
+    return 1;
+  }
+  console.log('');
+  console.log('✅ 五项全过：链接 / 路径 / 分类与配置 / 图与笔记 / 账本引用。');
+  return 0;
+}
+
+try {
+  process.exit(main());
+} catch (err) {
+  console.log('❌ scan.mjs 自身出错：' + (err && err.message ? err.message : String(err)));
+  process.exit(1);
+}