dsh-mastery-loop 0.0.0-stage → 0.2.0

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);
+}

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

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// mastery-loop 结构校验
+//
+// 用途：本脚本是结构校验器 —— 查 kb/ 与 sys/ 是否按契约建齐。
+// 契约正文：../templates.md （第一节「库的布局」）
+//
+// 用法：node validate.mjs <工作区根>
+//
+// 硬要求：**永远不要崩溃** —— 干净目录上应报「全缺」并以退出码 1 结束。
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const KB_FILES = [
+  { rel: 'kb/knowledge', kind: 'dir', label: '知识点笔记目录' },
+  { rel: 'kb/MOC', kind: 'dir', label: '聚合产物目录' },
+];
+
+const SYS_FILES = [
+  { rel: 'sys/config.json', kind: 'json', label: '设定（路径 / 分类 / 语言）' },
+  { rel: 'sys/graph.json', kind: 'json', label: '关系图' },
+  { rel: 'sys/ledger.jsonl', kind: 'jsonl', label: '账本（真值）' },
+  { rel: 'sys/errors.jsonl', kind: 'jsonl', label: '错误原因表' },
+  { rel: 'sys/error-taxonomy.json', kind: 'json', label: '失分原因分类' },
+  { rel: 'sys/paper-format.json', kind: 'json', label: '卷面参数' },
+  { rel: 'sys/state.jsonl', kind: 'jsonl', label: '状态（哈希）' },
+];
+
+function readIfPossible(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function countNotes(dir) {
+  let n = 0;
+  const walk = (d, depth) => {
+    if (depth > 3) return;
+    let entries = [];
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      if (e.isDirectory()) walk(join(d, e.name), depth + 1);
+      else if (/\.md$/i.test(e.name)) n++;
+    }
+  };
+  walk(dir, 0);
+  return n;
+}
+
+/** 返回问题列表（空 = 通过） */
+function inspect(rel, kind) {
+  const problems = [];
+  const path = rel;
+  const text = readIfPossible(path);
+
+  if (kind === 'json') {
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch (err) {
+      problems.push(`不是合法 JSON：${err.message}`);
+      return problems;
+    }
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+      problems.push('顶层不是对象');
+      return problems;
+    }
+    if (!data['用途']) problems.push('缺「用途」字段（每个文件开头要有一句「这个文件是干什么的」）');
+    if (rel.endsWith('config.json')) {
+      if (!data['分类'] || !Array.isArray(data['分类']?.['层级']) || data['分类']['层级'].length === 0) {
+        problems.push('缺「分类.层级」—— 分类是全库级定义，必填');
+      }
+      if (!data['路径'] || !data['路径']['知识库']) problems.push('缺「路径.知识库」');
+    }
+    if (rel.endsWith('graph.json')) {
+      if (!Array.isArray(data['edges'])) problems.push('缺「edges」数组');
+      if (!data['规则']) problems.push('缺「规则」字段（前置判据）');
+    }
+  }
+
+  if (kind === 'jsonl') {
+    const lines = String(text).split(/\r?\n/).filter((l) => l.trim());
+    if (!lines.length) {
+      problems.push('空文件 —— 至少要有一行 header');
+      return problems;
+    }
+    let head = null;
+    try {
+      head = JSON.parse(lines[0]);
+    } catch (err) {
+      problems.push(`第一行不是合法 JSON：${err.message}`);
+    }
+    if (head && head.kind !== 'header') problems.push('第一行不是 `{"kind":"header","用途":"…"}` 头部记录');
+    if (head && !head['用途']) problems.push('头部记录缺「用途」');
+    for (let i = 1; i < lines.length; i++) {
+      try {
+        JSON.parse(lines[i]);
+      } catch (err) {
+        problems.push(`第 ${i + 1} 行不是合法 JSON：${err.message}`);
+        break;
+      }
+    }
+  }
+
+  return problems;
+}
+
+function main() {
+  const arg = process.argv[2];
+  if (!arg) {
+    console.log('用法：node validate.mjs <工作区根>');
+    process.exit(2);
+  }
+
+  const root = resolve(arg);
+  console.log('校验工作区根：' + root);
+
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.log('❌ 这个目录不存在，或不是目录。');
+    process.exit(1);
+  }
+
+  let missing = 0;
+  let problematic = 0;
+
+  const dirs = [...KB_FILES, ...SYS_FILES].filter((f) => f.kind === 'dir');
+  const files = [...KB_FILES, ...SYS_FILES].filter((f) => f.kind !== 'dir');
+
+  for (const f of dirs) {
+    const p = join(root, f.rel);
+    if (!existsSync(p) || !statSync(p).isDirectory()) {
+      console.log(`❌ ${f.rel}/  —— 缺失（${f.label}）`);
+      missing++;
+    } else if (f.rel === 'kb/knowledge') {
+      const n = countNotes(p);
+      console.log(`✅ ${f.rel}/  —— ${f.label}（${n} 篇知识点）`);
+    } else {
+      console.log(`✅ ${f.rel}/  —— ${f.label}`);
+    }
+  }
+
+  for (const f of files) {
+    const p = join(root, f.rel);
+    if (!existsSync(p)) {
+      console.log(`❌ ${f.rel}  —— 缺失（${f.label}）`);
+      missing++;
+      continue;
+    }
+    const problems = inspect(p, f.kind);
+    if (!problems.length) {
+      console.log(`✅ ${f.rel}  —— ${f.label}`);
+    } else {
+      console.log(`⚠️  ${f.rel}  —— ${f.label}`);
+      for (const pr of problems) console.log(`      · ${pr}`);
+      problematic++;
+    }
+  }
+
+  console.log('');
+  if (missing === 0 && problematic === 0) {
+    console.log('✅ 结构齐：kb/ 与 sys/ 都按契约建好了。');
+    process.exit(0);
+  }
+  console.log(`未完成：缺 ${missing} 个、有问题的 ${problematic} 个。`);
+  console.log('跑一遍 `mastery-loop-setup` 补齐。');
+  process.exit(1);
+}
+
+try {
+  main();
+} catch (err) {
+  console.log('❌ 校验脚本自身出错：' + (err && err.message ? err.message : String(err)));
+  process.exit(1);
+}