@modusensus/dsh-mneme 0.10.1 → 0.12.0

package/src/wiki/queries.js

@@ -0,0 +1,360 @@
+// dsh-mneme/src/wiki/queries.js
+// chorography 的读侧（M1）：仓库列表 / 模块图 / 页面正文 / 关键词检索。
+// 收尾档追加：向量检索（P37–P39，惰性物化 + cosine）。
+// 检索读侧零写路径的例外只有一处——向量物化写 choro_vectors（P37：检索时惰性
+// 补嵌，host 侧才有 embedder；那是向量账本，不是页面真源）。
+//
+// 真源纪律（spec §4 / P12）：页面正文永远读仓库磁盘的 MD（root_path + DB 里的
+// rel_path），库里的表只是索引与状态账。slug 只从 DB 白名单解析，路径拼装零用户
+// 输入——面板与工具传进来的 slug 查不到模块行就返回 null，绝不用它拼路径。
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+
+// 页正文去 frontmatter / CHORO 标记行后作为嵌入文本（P40：嵌页级全文）。
+function pageEmbedText(content) {
+  const lines = String(content ?? "").split("\n");
+  let start = 0;
+  if (lines[0]?.trim() === "---") {
+    start = 1;
+    while (start < lines.length && lines[start].trim() !== "---") start++;
+    start++;
+  }
+  return lines
+    .slice(start)
+    .filter((l) => !l.startsWith("<!-- CHORO:T1:") && !l.startsWith("<!-- CHORO:HUMAN:"))
+    .join("\n")
+    .trim();
+}
+
+function cosine(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+export function createChoroQueries({ store }) {
+  const db = store.db;
+
+  /** 已登记仓库（含模块/页面计数，面板仓库选择器与工具的 repo 解析共用）。 */
+  function listRepos() {
+    const rows = db.prepare(
+      `SELECT r.id, r.root_path, r.name, r.plan_fingerprint, r.git_baseline, r.updated_at,
+              (SELECT COUNT(*) FROM choro_modules m WHERE m.repo_id = r.id) AS module_count,
+              (SELECT COUNT(*) FROM choro_pages p JOIN choro_modules m2 ON p.module_id = m2.id
+                 WHERE m2.repo_id = r.id) AS page_count
+         FROM choro_repos r ORDER BY r.id`
+    ).all();
+    return rows;
+  }
+
+  /** repo 解析：数字 id 或显示名（root_path 是本机私有路径，不作为对外键）。 */
+  function resolveRepo(ref) {
+    if (ref === undefined || ref === null || ref === "") {
+      const rows = listRepos();
+      if (rows.length === 1) return rows[0];
+      if (rows.length === 0) return null;
+      return { ambiguous: rows.map((r) => ({ id: r.id, name: r.name })) };
+    }
+    const byId = db.prepare("SELECT * FROM choro_repos WHERE id = ?").get(Number(ref));
+    if (byId) return byId;
+    const byName = db.prepare("SELECT * FROM choro_repos WHERE name = ?").get(String(ref));
+    return byName ?? null;
+  }
+
+  /** 模块表 + 跨模块边（choro_module_map 与面板左侧树共用同一份数据）。 */
+  function moduleMap(repoId) {
+    const modules = db.prepare(
+      `SELECT m.id, m.slug, m.title, m.parent_id, m.file_count, m.fingerprint, m.updated_at,
+              p.status AS page_status, p.rel_path AS page_rel_path
+         FROM choro_modules m
+         LEFT JOIN choro_pages p ON p.module_id = m.id
+        WHERE m.repo_id = ? ORDER BY m.slug`
+    ).all(repoId);
+    const edges = db.prepare(
+      `SELECT from_slug, to_slug, weight FROM choro_edges WHERE repo_id = ?
+        ORDER BY from_slug, to_slug`
+    ).all(repoId);
+    return { modules, edges };
+  }
+
+  /**
+   * 读一页正文。slug 必须命中 DB 的模块行（P12：路径零用户输入）；索引仍在但
+   * 文件缺失或不可读时带回相对路径，让调用方给出对应的恢复提示。
+   */
+  function readPage(repoId, slug) {
+    const row = db.prepare(
+      `SELECT m.slug, m.title, m.file_count, m.parent_id, p.rel_path, p.status,
+              p.git_baseline, p.template_version, p.generated_at, p.human_block_count
+         FROM choro_modules m JOIN choro_pages p ON p.module_id = m.id
+        WHERE m.repo_id = ? AND m.slug = ?`
+    ).get(repoId, String(slug));
+    if (!row) return null;
+    const repo = db.prepare("SELECT root_path, name FROM choro_repos WHERE id = ?").get(repoId);
+    const abs = join(repo.root_path, row.rel_path);
+    let content;
+    try {
+      content = readFileSync(abs, "utf8");
+    } catch (cause) {
+      const error = cause.code === "ENOENT" || cause.code === "ENOTDIR" ? "page-missing" : "page-unreadable";
+      return { error, slug: row.slug, relPath: row.rel_path };
+    }
+    return {
+      slug: row.slug,
+      title: row.title,
+      fileCount: row.file_count,
+      status: row.status,
+      gitBaseline: row.git_baseline,
+      templateVersion: row.template_version,
+      generatedAt: row.generated_at,
+      humanBlockCount: row.human_block_count,
+      repoName: repo.name,
+      relPath: row.rel_path,
+      content,
+    };
+  }
+
+  /**
+   * 关键词检索（P10）：按 `## ` 分节做大小写不敏感子串匹配，命中返回页 slug、
+   * 节标题、起始行号与摘录。只扫 DB 里登记过的页面文件（不是全目录 glob——
+   * 划分变更后未重算的孤儿文件不该被搜出来）。需要提示检索不完整的调用方可接收
+   * 不可读的页 slug。q 为空返回空数组不报错。
+   */
+  function search(repoId, q, { moduleSlug = null, limit = 20, onUnreadablePage } = {}) {
+    const needle = String(q ?? "").trim().toLowerCase();
+    if (needle === "") return [];
+    const cap = Math.max(1, Math.min(100, Number(limit) || 20));
+    const pages = db.prepare(
+      `SELECT m.slug, m.title AS module_title, p.rel_path
+         FROM choro_modules m JOIN choro_pages p ON p.module_id = m.id
+        WHERE m.repo_id = ? AND (? IS NULL OR m.slug = ?)
+        ORDER BY m.slug`
+    ).all(repoId, moduleSlug, moduleSlug);
+    const repo = db.prepare("SELECT root_path FROM choro_repos WHERE id = ?").get(repoId);
+    const hits = [];
+    for (const page of pages) {
+      const abs = join(repo.root_path, page.rel_path);
+      let text;
+      try {
+        text = readFileSync(abs, "utf8");
+      } catch {
+        onUnreadablePage?.(page.slug);
+        continue;
+      }
+      const lines = text.split("\n");
+      // 分节：每个 `## ` 标题开启一节，节内所有行都属于该节；文件头（frontmatter
+      // 之后到第一个 `## `）算 "（页首）" 一节，保证对 title/摘要的命中也有落点。
+      let section = "（页首）";
+      let sectionStart = 1;
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (i > 0 && /^## /.test(line)) {
+          section = line.replace(/^## /, "").trim();
+          sectionStart = i + 1;
+        }
+        if (line.toLowerCase().includes(needle)) {
+          hits.push({
+            slug: page.slug,
+            moduleTitle: page.module_title,
+            section,
+            line: i + 1,
+            sectionStart,
+            excerpt: line.trim().slice(0, 200),
+          });
+          if (hits.length >= cap) return hits;
+        }
+      }
+    }
+    return hits;
+  }
+
+  /**
+   * 按会话工作目录找已登记仓库（M3 开局注入的唯一入口）。
+   *
+   * 三个刻意的取舍：
+   * 1. **祖先前缀匹配**而不是精确相等——真实会话的 cwd 常常是仓库子目录
+   *    （`D:/repo/src`），精确相等会让绝大部分会话匹配不到，等于逼用户
+   *    「必须在仓库根开会话」这条暗规则。
+   * 2. 两侧都做 realpath 归一：Windows 上盘符大小写、8.3 短名、符号链接
+   *    会让同一个目录写出不同字符串；t0 落库时存的就是 realpath。
+   * 3. **最长前缀胜出**——仓库嵌套（子模块、`.worktrees/`）时取最深那层，
+   *    否则内层会话会被外层仓库抢走。
+   * cwd 不存在或不是目录时返回 null（不是抛错）：注入在热路径上，失败只
+   * 意味着「本帧不注入」。
+   */
+  function repoByCwd(cwd) {
+    const raw = String(cwd ?? "").trim();
+    if (raw === "") return null;
+    let normalized;
+    try {
+      normalized = realpathSync(resolve(raw));
+    } catch {
+      return null;
+    }
+    const cmp = (p) => (process.platform === "win32" ? p.toLowerCase() : p);
+    const target = cmp(normalized);
+    const rows = db.prepare("SELECT * FROM choro_repos ORDER BY id").all();
+    let best = null;
+    for (const row of rows) {
+      const root = cmp(String(row.root_path ?? ""));
+      if (root === "") continue;
+      const hit = target === root || target.startsWith(root.endsWith(sep) ? root : root + sep);
+      if (!hit) continue;
+      if (!best || root.length > cmp(String(best.root_path)).length) best = row;
+    }
+    return best ?? null;
+  }
+
+  /**
+   * 注入与 /choro 共用的最小提纲（M3）：模块名 + 文件数 + 页状态 + 页相对路径。
+   * **不读页正文**——spec §7 要求「只注标题级不注正文」，正文走 readPage。
+   * parentSlug 单独解出来给渲染层做层级缩进（DB 里存的是 parent_id）。
+   */
+  function outline(repoId) {
+    const repo = db.prepare(
+      "SELECT id, root_path, name, git_baseline, plan_fingerprint, updated_at FROM choro_repos WHERE id = ?"
+    ).get(repoId);
+    if (!repo) return null;
+    const rows = db.prepare(
+      `SELECT m.id, m.slug, m.title, m.parent_id, m.file_count,
+              p.status AS page_status, p.rel_path AS page_rel_path, p.generated_at
+         FROM choro_modules m
+         LEFT JOIN choro_pages p ON p.module_id = m.id
+        WHERE m.repo_id = ? ORDER BY m.slug`
+    ).all(repoId);
+    const slugById = new Map(rows.map((r) => [r.id, r.slug]));
+    let generatedAt = null;
+    const modules = rows.map((r) => {
+      if (r.generated_at && (generatedAt === null || r.generated_at > generatedAt)) generatedAt = r.generated_at;
+      return {
+        slug: r.slug,
+        title: r.title,
+        fileCount: r.file_count,
+        parentSlug: r.parent_id === null || r.parent_id === undefined ? null : slugById.get(r.parent_id) ?? null,
+        status: r.page_status ?? null,
+        relPath: r.page_rel_path ?? null,
+      };
+    });
+    return {
+      repo: {
+        id: repo.id,
+        name: repo.name,
+        rootPath: repo.root_path,
+        gitBaseline: repo.git_baseline,
+        updatedAt: repo.updated_at,
+      },
+      generatedAt: generatedAt ?? repo.updated_at ?? null,
+      modules,
+    };
+  }
+
+  // --- chorography 向量（收尾档 P37–P39）---------------------------------
+  // 惰性物化（P37）：只在 host 侧检索路径调用（embedder 由 index.js 注入）；
+  // CLI 环境没有 embedder → 向量永不物化，检索退关键词。staleness 两维：
+  // 页 generated_at 变了（内容变了）、行 dim ≠ 本次查询向量 dim（换 embedder
+  // 模型了，P38）→ 重嵌。dim 失配是全表性的，遇到一次就把整仓重嵌（几十页）。
+  async function embedPageVectors(repoId, embedder, { limit = 200, expectDim = null } = {}) {
+    const pages = db.prepare(
+      `SELECT p.id, p.generated_at, m.slug, m.title, p.rel_path
+         FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id
+        WHERE m.repo_id = ? ORDER BY m.slug`
+    ).all(repoId);
+    const repo = db.prepare("SELECT root_path FROM choro_repos WHERE id = ?").get(repoId);
+    const embedOne = embedder.embedSingle ? (t) => embedder.embedSingle(t) : (t) => embedder.embed(t);
+    const rows = store.getChoroPageVectors(repoId);
+    const bySlug = new Map(rows.map((r) => [r.slug, r]));
+    const result = { embedded: 0, skipped: 0, stale: 0, failed: [], dimMismatch: false };
+    // dim 失配的全量重嵌（P38）：expectDim 来自查询向量（调用方先嵌查询再物化，
+    // 维度免费拿到）。expectDim 与任何现存行失配 → 本轮 fresh 检查失效，全量重嵌；
+    // 没给 expectDim（无查询场景）退化为只按 generated_at 判 staleness。
+    const dimDrift = expectDim !== null && rows.some((r) => r.dim !== expectDim);
+    if (dimDrift) result.dimMismatch = true;
+    for (const page of pages) {
+      if (result.embedded >= limit) break;
+      const row = bySlug.get(page.slug);
+      const fresh = !dimDrift && row && row.source_generated_at === page.generated_at && row.vector;
+      if (fresh) { result.skipped++; continue; }
+      if (row && row.vector) result.stale++;
+      const abs = join(repo.root_path, page.rel_path);
+      if (!existsSync(abs)) continue;
+      let text;
+      try {
+        text = pageEmbedText(readFileSync(abs, "utf8"));
+      } catch {
+        result.failed.push({ slug: page.slug, reason: "page-unreadable" });
+        continue;
+      }
+      if (text.trim() === "") { result.skipped++; continue; }
+      let vector;
+      try {
+        vector = await embedOne(text);
+      } catch (err) {
+        result.failed.push({ slug: page.slug, reason: String(err?.message ?? err).slice(0, 120) });
+        continue;
+      }
+      if (!Array.isArray(vector) || vector.length === 0) {
+        result.failed.push({ slug: page.slug, reason: "embedder-returned-no-vector" });
+        continue;
+      }
+      if (row && row.dim !== vector.length) result.dimMismatch = true;
+      store.saveChoroPageVector(page.id, {
+        vector,
+        dim: vector.length,
+        model: String(embedder.model ?? "choro"),
+        sourceGeneratedAt: page.generated_at,
+        createdAt: new Date().toISOString(),
+      });
+      result.embedded++;
+    }
+    return result;
+  }
+
+  /** 嵌查询文本（宿主侧）。embedder 缺席 / 不可用 → null。 */
+  async function embedQueryText(embedder, q) {
+    if (!embedder) return null;
+    const embedOne = embedder.embedSingle ? (t) => embedder.embedSingle(t) : (t) => embedder.embed(t);
+    try {
+      const v = await embedOne(String(q ?? ""));
+      return Array.isArray(v) && v.length > 0 ? v : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** 纯余弦 Top-N：向量已给定时零嵌入。行 dim 与查询失配的行过滤掉（P38）。 */
+  function semanticTopN(repoId, queryVector, { limit = 10 } = {}) {
+    if (!Array.isArray(queryVector) || queryVector.length === 0) return [];
+    const rows = store.getChoroPageVectors(repoId).filter((r) => r.vector && r.dim === queryVector.length);
+    return rows
+      .map((r) => ({
+        slug: r.slug,
+        title: r.title,
+        score: Number(cosine(queryVector, JSON.parse(r.vector)).toFixed(4)),
+      }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(1, Math.min(50, Number(limit) || 10)));
+  }
+
+  /** 便捷组合：嵌查询 + Top-N（P39：独立数组，不与 keyword hits 混排序）。
+   * 空查询 → []（空白查询的「语义」是噪声，面板逐键触发时尤其如此）；
+   * embedder 缺席 → null（调用方退纯关键词）。 */
+  async function searchSemantic(repoId, embedder, q, { limit = 10 } = {}) {
+    if (!embedder) return null;
+    if (String(q ?? "").trim() === "") return [];
+    const queryVector = await embedQueryText(embedder, q);
+    if (!queryVector) return [];
+    return semanticTopN(repoId, queryVector, { limit });
+  }
+
+  return {
+    listRepos, resolveRepo, moduleMap, readPage, search, repoByCwd, outline,
+    embedPageVectors, searchSemantic, embedQueryText, semanticTopN,
+  };
+}

package/src/wiki/render.js

@@ -0,0 +1,187 @@
+// dsh-mneme/src/wiki/render.js
+// T0 骨架页与 index.md 的确定性渲染（spec §6 步 6），以及混合所有权的保留区机制
+// （spec §4：`<!-- CHORO:HUMAN -->` 标记块重生成时逐字节保留）。
+//
+// 确定性纪律（spec §9 可重建不变量）：正文零时间戳、零随机——所有列表先排序再拼；
+// 页面唯一的时刻 frontmatter.generatedAt 由 t0.js 从 state.json 沿用（实现计划
+// P3：时刻收进 state.json，失败不推进，页面字节才可能跨 run 稳定）。
+//
+// 保留区规则（写死、可测）：
+//   1. 抽取：START…END 之间连同两行标记整体抽出，一个字节不动；
+//   2. 回填：新正文之后按原相对顺序接回全部块；
+//   3. 重生成永不删块、永不改写块内内容（包括缩进与格式）——红线 6；
+//   4. 没有块时整页覆盖（spec：人在块外的手改不保证存活，是明说语义不是事故）。
+
+export const TEMPLATE_VERSION = "1";
+
+export const HUMAN_START = "<!-- CHORO:HUMAN:START -->";
+export const HUMAN_END = "<!-- CHORO:HUMAN:END -->";
+
+// T1 语义段的包装标记。写的人是 t1.js，读的人还有 t0.js——重跑 T0 时它要能认出
+// 「这页已经被富化过」，否则 enriched → skeleton 的退回是静默的。标记随页面格式
+// 走，所以与 HUMAN 标记同住这里，t1.js 转出给调用方。
+export const T1_SECTION_START = "<!-- CHORO:T1:START -->";
+export const T1_SECTION_END = "<!-- CHORO:T1:END -->";
+
+/** 抽出全部保留区。返回 { blocks: string[]（含标记本身，原样）, count }。 */
+export function extractHumanBlocks(pageText) {
+  if (typeof pageText !== "string") return { blocks: [], count: 0 };
+  const blocks = [];
+  const re = new RegExp(`${escapeRegExp(HUMAN_START)}[\\s\\S]*?${escapeRegExp(HUMAN_END)}`, "g");
+  let m;
+  while ((m = re.exec(pageText)) !== null) blocks.push(m[0]);
+  return { blocks, count: blocks.length };
+}
+
+/** 新正文 + 保留区（按原顺序接在页尾，各隔一个空行）。 */
+export function injectHumanBlocks(newContent, blocks) {
+  if (!blocks || blocks.length === 0) return newContent;
+  return `${newContent.replace(/\n*$/, "\n")}\n${blocks.join("\n\n")}\n`;
+}
+
+/**
+ * 渲染一页骨架。meta: { slug, title, parents[], sourceFiles[], gitBaseline,
+ * generatedAt, status }；mod 是 partition 的产物。
+ */
+export function renderSkeletonPage(mod, meta) {
+  const lines = [];
+  lines.push("---");
+  lines.push("choro: v1");
+  lines.push(`slug: ${meta.slug}`);
+  lines.push(`title: ${yamlScalar(meta.title)}`);
+  if (meta.parents && meta.parents.length > 0) {
+    lines.push("parents:");
+    for (const p of meta.parents) lines.push(`  - ${p}`);
+  } else {
+    lines.push("parents: []");
+  }
+  lines.push("sourceFiles:");
+  for (const f of meta.sourceFiles) lines.push(`  - ${f}`);
+  lines.push(`gitBaseline: ${meta.gitBaseline}`);
+  lines.push(`templateVersion: ${TEMPLATE_VERSION}`);
+  lines.push(`language: ${meta.language ?? "zh"}`);
+  lines.push(`status: ${meta.status}`);
+  lines.push(`generatedAt: ${meta.generatedAt}`);
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${meta.title}`);
+  lines.push("");
+  // 注意：这行说明里**不得出现成对的标记字面量**——抽取用的是全局正则，说明行
+  // 里一旦同时含 START 与 END，下一轮重生成就会把它当成一块保留区接在页尾
+  // （实测：第二轮页面凭空多两行）。所以说标记时用名字，不用原文。
+  lines.push(
+    `> 确定性骨架（T0，零模型）：由文件树与 import 图生成。` +
+    `CHORO:HUMAN 标记对（START/END 两个 HTML 注释）包住的内容在重生成时逐字节保留；` +
+    `标记对之外的手改不保留（想保住一段就把它挪进标记对里）。`
+  );
+  lines.push("");
+  lines.push(`## 文件清单（${mod.fileCount} 个）`);
+  lines.push("");
+  lines.push("| 文件 | 行数 |");
+  lines.push("| --- | ---: |");
+  for (const [file, lines2] of mod.fileLines) lines.push(`| ${file} | ${lines2} |`);
+  lines.push("");
+  lines.push("## 入口");
+  lines.push("");
+  if (mod.entries.length > 0) {
+    for (const e of mod.entries) lines.push(`- \`${e}\``);
+  } else {
+    lines.push("- 无（没有 index/main 命名的文件，也不是包入口）");
+  }
+  lines.push("");
+  lines.push("## 内部依赖");
+  lines.push("");
+  if (mod.upstream.length > 0) {
+    lines.push(`- 上游依赖（本模块引用的模块）：${mod.upstream.map((s) => `\`${s}\``).join("、")}`);
+  }
+  if (mod.downstream.length > 0) {
+    lines.push(`- 下游（引用本模块的模块）：${mod.downstream.map((s) => `\`${s}\``).join("、")}`);
+  }
+  if (mod.upstream.length === 0 && mod.downstream.length === 0) {
+    lines.push("- 无内部依赖边（孤立模块）");
+  }
+  lines.push("");
+  lines.push("## 外部依赖");
+  lines.push("");
+  if (mod.externalDeps.length > 0) {
+    for (const d of mod.externalDeps) lines.push(`- \`${d.pkg}\` ×${d.count}`);
+  } else {
+    lines.push("- 无外部 npm 依赖");
+  }
+  lines.push("");
+  lines.push("## 生成说明");
+  lines.push("");
+  lines.push(
+    `- 模块划分：目录初稿 + 兄弟组内聚合并（内部边 ≥3），超上限逐级下切；` +
+    `本组 ${mod.fileCount} 个文件。`
+  );
+  if (mod.unresolvedCount > 0) {
+    lines.push(`- ${mod.unresolvedCount} 条相对引用没有解析到仓库内文件（别名/动态路径），未计入依赖图。`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** index.md：模块目录 + 仓库级信息。同样零时间戳（时刻在 state.json）。 */
+export function renderIndex(modules, repoMeta) {
+  const lines = [];
+  lines.push("---");
+  lines.push("choro: v1");
+  lines.push(`repo: ${yamlScalar(repoMeta.name)}`);
+  lines.push(`gitBaseline: ${repoMeta.gitBaseline}`);
+  lines.push(`templateVersion: ${TEMPLATE_VERSION}`);
+  lines.push(`generatedAt: ${repoMeta.generatedAt}`);
+  lines.push("language: zh");
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${repoMeta.name} · 仓库地志`);
+  lines.push("");
+  lines.push(
+    `T0 确定性骨架（零模型）。页面在 \`modules/\` 下，真源是本目录的 Markdown；` +
+    `本文件整页机器所有、可随时重算（spec §4）。`
+  );
+  lines.push("");
+  lines.push(`- 扫描 ${repoMeta.fileCount} 个文件，划出 ${modules.length} 个模块。`);
+  if (repoMeta.skipped > 0) lines.push(`- ${repoMeta.skipped} 个文件读取失败，已跳过（页脚与 receipt 都有记）。`);
+  if (repoMeta.unresolved > 0) lines.push(`- ${repoMeta.unresolved} 条相对引用未解析（别名/动态路径），未计入依赖图。`);
+  lines.push("");
+  lines.push("## 模块目录");
+  lines.push("");
+  lines.push("| 模块 | 页面 | 文件数 | 内部边 | 外部依赖 |");
+  lines.push("| --- | --- | ---: | ---: | ---: |");
+  for (const mod of modules) {
+    const pageRel = `modules/${mod.slug}.md`;
+    lines.push(
+      `| ${mod.title} | [${mod.slug}](${pageRel}) | ${mod.fileCount} | ` +
+      `${mod.internalEdges.length} | ${mod.externalDeps.length} |`
+    );
+  }
+  lines.push("");
+  lines.push("## 脚本命令（根 package.json）");
+  lines.push("");
+  const scriptNames = Object.keys(repoMeta.scripts ?? {}).sort();
+  if (scriptNames.length > 0) {
+    lines.push("| 命令 | 内容 |");
+    lines.push("| --- | --- |");
+    for (const name of scriptNames) lines.push(`| \`${name}\` | ${escapeCell(String(repoMeta.scripts[name]))} |`);
+  } else {
+    lines.push("- 无 scripts 字段或没有根 package.json。");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// YAML 标量：含冒号/引号等特殊字符时加引号（frontmatter 里的 title/repo 是人名或
+// 目录名，通常无害，但这层便宜且省掉转义 bug）。
+function yamlScalar(text) {
+  const s = String(text ?? "");
+  return /[:#'\"[\]{},&*?|>%@`]/.test(s) || s.trim() !== s ? JSON.stringify(s) : s;
+}
+
+function escapeCell(text) {
+  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}