@modusensus/dsh-mneme 0.10.1 → 0.11.0

package/src/tools.js

@@ -76,7 +76,10 @@ const MEMORY_PROVENANCE = (m) => {
   return parts.length ? ` | ${parts.join(" | ")}` : "";
 };
 
-export function createTools(ctx, service, config, embedder, sessionGate = null) {
+// choro（M1）：chorography 只读查询对象（createChoroQueries 产物）。缺省 null =
+// 装配层没接（headless/测试），三个 choro_* 工具走 hiddenTools 闸根本不注册。
+// 它与 service 刻意分开传——chorography 的所有权模型与记忆域相反（spec §3）。
+export function createTools(ctx, service, config, embedder, sessionGate = null, choro = null) {
   const toolsRegistry = ctx.tools;
   let registration = REGISTERED_TOOLS.get(toolsRegistry);
   if (!registration) {
@@ -89,6 +92,16 @@ export function createTools(ctx, service, config, embedder, sessionGate = null)
   // flag 关闭时恒返回 null——写入不标注，检索不加权，行为与 A1 前完全一致。
   // logger 透传：registry 反查失败时 warnOnce 才有出口（否则静默降级无观测）。
   const resolveSessionScope = createScopeResolver({ ctx, config, logger: ctx.logger });
+  // choro 工具共用的 repo 解析（M1）：不带 repo 且只有一个登记仓时自动收敛；
+  // 多仓歧义时把可选清单带回给模型（render 层会把它转成人话）。三个 execute 里
+  // 都先走这里，错误形状统一 { error, ... }，output.schema 容忍多余键由
+  // additionalProperties:false + render 兜底——错误分支直接透传给渲染层判。
+  const resolveChoroRepo = (ref) => {
+    const row = choro ? choro.resolveRepo(ref) : null;
+    if (!row) return { error: "no-repos", hint: "run `dsh-mneme-choro <repo> --apply` first (registers the repository)" };
+    if (row.ambiguous) return { error: "repo-ambiguous", repos: row.ambiguous, hint: "pass repo id or name" };
+    return row;
+  };
   // #249 能力说明（injectGuidanceEnabled）：开启时给「何时用」最有歧义的两个
   // 工具补一句判断指引。工具描述常驻、不进每轮上下文，这个位子零注入成本；
   // 关闭时描述逐字节不变，也不动其他工具的文案。
@@ -1032,6 +1045,111 @@ export function createTools(ctx, service, config, embedder, sessionGate = null)
           ...(report.reason ? { reason: report.reason } : {})
         };
       }
+    }),
+
+    // --- chorography（仓库地志）只读工具（M1，spec §7）------------------
+    // 三个全只读（红线 3：写操作一个不注册——生成只走 dsh-mneme-choro CLI，
+    // 那是人按的按钮，不是模型的权利）。默认不在场：chorographyEnabled 关着时
+    // 走下面的 hiddenTools 闸，模型连名字都看不到（与 memory_organize 同款反向
+    // 语义）。执行器包 sessionGate 由注册循环统一做——仓库地志是文档不是会话
+    // 派生内容，无痕会话里被一并关掉是保守取向，可接受。
+    defineTool({
+      name: "choro_module_map",
+      description: "Show the chorography module map of a registered repository: module list (slug, title, file count, status) and cross-module dependency edges. Read-only. Use it to orient yourself in a codebase before reading pages; requires the user to have enabled chorography and generated the wiki (T0 skeleton).",
+      parameters: {
+        repo: { type: "string", description: "Repository id or display name; omit when exactly one repository is registered" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            repo: { type: "string", required: true },
+            modules: { type: "array", required: true, items: { type: "object", additionalProperties: true } },
+            edges: { type: "array", required: true, items: { type: "object", additionalProperties: true } }
+          }
+        },
+        render: (_args, value) => {
+          const mods = value.modules ?? [];
+          const edges = value.edges ?? [];
+          const lines = mods.map((m) =>
+            `- ${m.slug} — ${m.title}（${m.file_count} 文件${m.page_status ? `，页 ${m.page_status}` : "，无页"}）`
+          );
+          for (const e of edges) lines.push(`  ↳ ${e.from_slug} → ${e.to_slug} ×${e.weight}`);
+          return TEXT_OUTPUT(`${mods.length} modules, ${edges.length} edges:\n${lines.join("\n")}`);
+        }
+      },
+      async execute(args) {
+        const repo = resolveChoroRepo(args?.repo);
+        if (repo.error) return repo;
+        const { modules, edges } = choro.moduleMap(repo.id);
+        return { repo: repo.name, modules, edges };
+      }
+    }),
+
+    defineTool({
+      name: "choro_read_page",
+      description: "Read one chorography wiki page (module skeleton: file list, entries, internal/external dependencies) of a registered repository by slug. Use choro_module_map first to learn the slugs. Read-only.",
+      parameters: {
+        slug: { type: "string", description: "Page slug as listed by choro_module_map" },
+        repo: { type: "string", description: "Repository id or display name; omit when exactly one repository is registered" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            slug: { type: "string", required: true },
+            content: { type: "string", required: true }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(value.content)
+      },
+      async execute(args) {
+        const repo = resolveChoroRepo(args?.repo);
+        if (repo.error) return repo;
+        const page = choro.readPage(repo.id, args?.slug);
+        if (!page) return { error: "page-not-found", slug: String(args?.slug ?? ""), hint: "use choro_module_map to list slugs" };
+        if (page.error) return page;
+        return { slug: page.slug, content: page.content };
+      }
+    }),
+
+    defineTool({
+      name: "choro_search",
+      description: "Keyword search over a repository's chorography wiki pages. Returns matching sections with page slug, section title, line number and excerpt (case-insensitive substring; matches frontmatter too — sections let you tell metadata hits from body hits). Read-only.",
+      parameters: {
+        query: { type: "string", description: "Keyword substring to search for" },
+        repo: { type: "string", description: "Repository id or display name; omit when exactly one repository is registered" },
+        module: { type: "string", description: "Restrict to one module slug" },
+        limit: { type: "integer", description: "Max hits (default 20, cap 100)" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            hits: { type: "array", required: true, items: { type: "object", additionalProperties: true } }
+          }
+        },
+        render: (_args, value) => {
+          const hits = value.hits ?? [];
+          if (hits.length === 0) return TEXT_OUTPUT("0 hits.");
+          return TEXT_OUTPUT(hits
+            .map((hit) => `${hit.slug} · ${hit.section} · L${hit.line}: ${hit.excerpt}`)
+            .join("\n"));
+        }
+      },
+      async execute(args) {
+        const repo = resolveChoroRepo(args?.repo);
+        if (repo.error) return repo;
+        return {
+          hits: choro.search(repo.id, args?.query, {
+            moduleSlug: args?.module ?? null,
+            limit: args?.limit
+          })
+        };
+      }
     })
   ];
 
@@ -1046,6 +1164,14 @@ export function createTools(ctx, service, config, embedder, sessionGate = null)
   // 注册。仍走同一个闸门而不是在数组里条件展开——模型看不到就不会调，这比在描述里
   // 劝它别用可靠（上面那段 v0.8.5 的定性对两个方向都成立）。
   if (config?.organizeEnabled !== true) hiddenTools.add("memory_organize");
+  // chorography 三个只读工具（M1）：默认不在场，chorographyEnabled 打开才注册。
+  // 与 organizeEnabled 同款反向语义；queries 未装配（null）时同样藏——「开了开关
+  // 但装配缺件」与「没开」对模型都是不可见，可区分性由面板路由的 409/503 负责。
+  if (config?.chorographyEnabled !== true || !choro) {
+    hiddenTools.add("choro_module_map");
+    hiddenTools.add("choro_read_page");
+    hiddenTools.add("choro_search");
+  }
 
   for (const tool of tools) {
     if (hiddenTools.has(tool.name)) {

package/src/wiki/inject.js

@@ -0,0 +1,164 @@
+// dsh-mneme/src/wiki/inject.js
+// chorography 的注入面（M3）：会话开局往 systemPrompt 里塞一小块「仓库地志提纲」。
+//
+// 三条边界（spec §7 / P24–P33）：
+// 1. **只注标题级**——模块名 + 文件数 + 页状态 + 页相对路径，不读页正文。正文要
+//    模型自己用 choro_read_page 取，那不是「开局就该付的成本」。
+// 2. **不上热路径的硬活**——不 fork git、不 stat 磁盘、不解析 markdown。这里只吃
+//    DB 里已有的行；过期判定留给 /choro（人主动触发，付得起一次 git rev-parse）。
+// 3. **绝不抛**——本块折在既有的 memory context 里，一个附属信息块把整轮
+//    systemPrompt 搞崩是不成比例的失败。任何异常都退化成空串（= 本帧不注入，
+//    宿主契约里空文本会被过滤，不占位）。
+import { escapePromptVars } from "../user-settings.js";
+import { STR } from "../lang.js";
+
+/** 档位枚举（与 config.js 的 chorographyInject 同一份取值，配置闸门在 settings.js）。 */
+export const INJECT_TIERS = Object.freeze(["off", "light", "full"]);
+
+/**
+ * light 档最多列几个模块。
+ *
+ * 定 6 是照着 spec §7 的「≤8 行」倒推的：块头 1 行 + 模块行 6 行 + 「还有 N 个」
+ * 1 行 = 8 行。多给两行要挤掉「还有 N 个」那句，读者就不知道清单被截断了——
+ * 静默截断比明说「还有 30 个」更坏。
+ */
+export const LIGHT_MODULE_LIMIT = 6;
+
+/** 各档字符硬上限。宿主侧没有任何体积预算（V3 实测），所以上限只能自己兜。 */
+export const MAX_BLOCK_CHARS = Object.freeze({ light: 900, full: 6000 });
+
+/**
+ * 配置 → 档位。纯函数，无副作用，供注入侧与 /choro 共用同一份判据。
+ *
+ * 轻量档（lightMode）在这里被压成 off 而不是进 LIGHT_MODE_OFF：那张表对平铺键
+ * 一律赋 false，枚举键塞进去会得到与 schema 不符的 false，而 false !== "off"
+ * 时注入照样渲染——比不关更糟（P26）。
+ */
+export function resolveInjectTier(config) {
+  if (!config || config.chorographyEnabled !== true) return "off";
+  if (config.lightMode === true) return "off";
+  const raw = config.chorographyInject;
+  return INJECT_TIERS.includes(raw) ? raw : "light";
+}
+
+/** 页状态 → 标签。skeleton 不出标签（那是默认态，全标一遍等于没标）。 */
+function statusLabel(status, language) {
+  if (status === "enriched") return STR.choroStatusEnriched[language];
+  if (status === "failed") return STR.choroStatusFailed[language];
+  if (status === "stale") return STR.choroStatusStale[language];
+  return "";
+}
+
+/**
+ * light 档取哪些模块。
+ *
+ * 按文件数降序、同数按 slug 升序——**不是**取字母序前 6 个：字母序会永远只显示
+ * 同一批（通常还是 src 这种大而空的目录页），而大模块是「被问到的概率」最高的
+ * 那批。排序里带 slug 是为了同一份库每次渲染字节一致（缓存与测试都靠它）。
+ */
+function pickModules(modules, tier) {
+  // 两档用同一份排序：light 与 full 若各按各的排，同一份地志在两个档位下会给出
+  // 不同次序，读起来像「刚才那份被重扫过了」。大模块在前对两档都成立——
+  // 被问到的概率最高的那批，本来就该排前面。
+  const ordered = [...modules].sort((a, b) => {
+    const d = (b.fileCount ?? 0) - (a.fileCount ?? 0);
+    if (d !== 0) return d;
+    return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
+  });
+  if (tier === "full") return { shown: ordered, rest: 0 };
+  return { shown: ordered.slice(0, LIGHT_MODULE_LIMIT), rest: Math.max(0, ordered.length - LIGHT_MODULE_LIMIT) };
+}
+
+/** 生成时间只留日期部分：注入块里精确到毫秒没有信息量，只挤体积。 */
+function dateOnly(iso) {
+  const match = /^(\d{4}-\d{2}-\d{2})/.exec(String(iso ?? ""));
+  return match ? match[1] : String(iso ?? "");
+}
+
+/**
+ * 渲染地志提纲块。纯函数（入参进、字符串出），注入侧与 /choro 的「看提纲」
+ * 共用这一份——两张皮在这里只剩档位与语言两个参数之差。
+ *
+ * @param {object|null} outline createChoroQueries().outline() 的产物
+ * @param {"light"|"full"} tier 已解析的档位（off 不该调到这里）
+ * @param {"zh"|"en"} language
+ * @returns {string} 空串 = 不注入
+ */
+export function renderChoroBlock(outline, tier, language = "zh") {
+  if (!outline || !Array.isArray(outline.modules) || outline.modules.length === 0) return "";
+  const lang = language === "en" ? "en" : "zh";
+  const cap = MAX_BLOCK_CHARS[tier] ?? MAX_BLOCK_CHARS.light;
+  const picked = pickModules(outline.modules, tier);
+
+  const lines = [
+    STR.choroBlockHeader[lang](outline.repo.name, outline.modules.length, dateOnly(outline.generatedAt))
+  ];
+  for (const mod of picked.shown) {
+    lines.push(STR.choroBlockLine[lang](mod.title, mod.fileCount ?? 0, statusLabel(mod.status, lang), mod.relPath ?? ""));
+  }
+  if (picked.rest > 0) lines.push(STR.choroBlockMore[lang](picked.rest));
+
+  // 逐行累加而不是拼完再切：切在行中间会让最后一条模块行变成半句话，
+  // 模型读到的「路径」就可能是断的——宁可少一行，不可半行。
+  const kept = [];
+  let used = 0;
+  for (const line of lines) {
+    if (used + line.length + 1 > cap) break;
+    kept.push(line);
+    used += line.length + 1;
+  }
+  if (kept.length <= 1) return "";
+  return kept.join("\n");
+}
+
+/**
+ * 注入器（给 src/inject.js 用）。
+ *
+ * 缓存键用 **outline.generatedAt**（页级生成时间的最大值），不是 choro_repos.
+ * updated_at：T1 富化只推 choro_pages.generated_at，不动仓库行——若按仓库行做键，
+ * 用户刚在终端跑完 `--t1 --apply`，注入块还写着「骨架」，而 /choro（无缓存）已经
+ * 报「已富化」。两个面说同一件事却给出不同答案，比慢一点糟得多。
+ * 每轮仍查一次库取提纲（一次索引查询，几十微秒，不 fork git、不 stat 磁盘），
+ * 只是**渲染**走缓存——省的是拼字符串，不是正确性。
+ *
+ * @param {object} opts.choro createChoroQueries() 的产物（注入侧只读它）
+ * @param {object} opts.config 合并后的配置
+ * @param {object} [opts.logger]
+ * @param {() => string} [opts.language] 语言取值器（跟随配置，不在创建时定死）
+ * @returns {{ text: (cwd: string|null|undefined) => string, tier: string, dispose: () => void }}
+ */
+export function createChoroInject({ choro, config, logger = null, language = null } = {}) {
+  const langOf = typeof language === "function" ? language : () => "zh";
+  const tier = resolveInjectTier(config);
+  let cache = null; // { key, text }
+
+  function text(cwd) {
+    if (tier === "off" || !choro) return "";
+    try {
+      const repo = typeof choro.repoByCwd === "function" ? choro.repoByCwd(cwd) : null;
+      if (!repo) return "";
+      const lang = langOf() === "en" ? "en" : "zh";
+      const outline = typeof choro.outline === "function" ? choro.outline(repo.id) : null;
+      // 键取页级生成时间：T0 重算与 T1 富化都会推进它，两种「地志变了」都命中。
+      const key = tier + "|" + lang + "|" + repo.id + "|" + (outline?.generatedAt ?? repo.updated_at ?? "");
+      if (cache && cache.key === key) return cache.text;
+      // 转义只在这一层做：/choro 的 UI 回执也调 renderChoroBlock，但它不进宿主模板，
+      // 转义了反而会显示成一串反斜杠。这里的 config 与 inject.js 同一份开关。
+      const rendered = escapePromptVars(config, renderChoroBlock(outline, tier, lang));
+      cache = { key, text: rendered };
+      return rendered;
+    } catch (error) {
+      // P31：注入永远不抛。日志留一次线索，但本帧就当没有地志。
+      logger?.warn?.("[dsh-mneme] chorography 注入块渲染失败，本帧跳过：" + String(error?.message ?? error));
+      return "";
+    }
+  }
+
+  return {
+    text,
+    tier,
+    dispose() {
+      cache = null;
+    }
+  };
+}

package/src/wiki/partition.js

@@ -0,0 +1,200 @@
+// dsh-mneme/src/wiki/partition.js
+// 模块划分（spec §6 步 4）：目录为初稿，用图的内聚度做合并，超 max_files_per_page
+// 再逐级下切。全流程确定性：同输入两次划分给出逐项相同的结果（spec §9 的可重建
+// 不变量要求划分本身也稳定）。
+//
+// 启发式只有两条、都便宜到可解释（V2 要人判质量，判据必须能口述）：
+//   合并——同一父目录下的两个兄弟组，互相指向的内部边 ≥ MERGE_EDGE_MIN 且合并不超
+//   上限时并成一组（典型收益：utils/ 与它唯一的消费者；典型损失：两个互不相干的
+//   小目录被文件夹布局凑到一起，代价是页变大，不会错分语义）。
+//   下切——超上限的组按下一级目录段切开；直属文件自成一组；叶子组仍超上限时按
+//   文件名字典序切块（此时语义已无从谈起，保住「每页不超过上限」的契约）。
+import { posix } from "node:path";
+import { createHash } from "node:crypto";
+
+const MERGE_EDGE_MIN = 3;
+
+/**
+ * @param {string[]} files 仓库相对路径（已排序）
+ * @param {{edges: {from:string,to:string}[], external: Map<string,Set<string>>}} graph scan 的产物
+ * @param {number} maxFilesPerPage plan.yaml 的上限
+ * @returns {Array<{slug,title,dir,fileCount,files,parentSlug,internalEdges,externalDeps,fingerprint}>}
+ */
+export function partitionModules({ files, graph, maxFilesPerPage, repoName }) {
+  const cap = Math.max(1, Math.floor(maxFilesPerPage));
+
+  // 步 1：目录初稿——前两级目录段；根直属文件一组。
+  const groups = new Map();
+  for (const file of files) {
+    const key = groupKeyOf(file);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(file);
+  }
+
+  // 步 2：兄弟组合并（单遍、按 key 字典序，确定性）。
+  mergeSiblingGroups(groups, graph.edges, cap);
+
+  // 步 3：超限下切。
+  const finalGroups = [];
+  for (const key of [...groups.keys()].sort()) {
+    splitOversized(key, groups.get(key), cap, finalGroups);
+  }
+
+  // 步 4：slug / title / 父链 / 边聚合。
+  const modules = finalGroups
+    .map((g) => materialize(g, graph))
+    .sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : a.slug < b.slug ? -1 : 1));
+
+  assignSlugsAndParents(modules, repoName);
+  for (const mod of modules) mod.fingerprint = moduleFingerprint(mod);
+  return modules;
+}
+
+function groupKeyOf(file) {
+  const dir = posix.dirname(file);
+  if (dir === ".") return "";
+  const segments = dir.split("/");
+  return segments.slice(0, 2).join("/");
+}
+
+function mergeSiblingGroups(groups, edges, cap) {
+  // 文件级边先折算到组级（两次查找的 Map，组数 = 目录数，量级无所谓）。
+  const cross = new Map(); // "a|b" -> count（a、b 为组 key，字典序小的在前）
+  for (const e of edges) {
+    const ga = groupKeyOf(e.from);
+    const gb = groupKeyOf(e.to);
+    if (ga === gb || !groups.has(ga) || !groups.has(gb)) continue;
+    const [x, y] = ga < gb ? [ga, gb] : [gb, ga];
+    const k = `${x}|${y}`;
+    cross.set(k, (cross.get(k) ?? 0) + 1);
+  }
+
+  const keys = [...groups.keys()].sort();
+  for (const key of keys) {
+    if (!groups.has(key)) continue; // 已被并走
+    const parent = posix.dirname(key || "·");
+    for (const [pairKey, count] of [...cross.entries()].sort()) {
+      if (count < MERGE_EDGE_MIN) continue;
+      const [a, b] = pairKey.split("|");
+      if (a !== key) continue;
+      if (!groups.has(a) || !groups.has(b)) continue;
+      if (posix.dirname(a || "·") !== parent || posix.dirname(b || "·") !== parent) continue;
+      if (groups.get(a).length + groups.get(b).length > cap) continue;
+      // 并入字典序小的组；被并组从账上消失（cross 里的旧键自然失效）。
+      groups.set(a, [...groups.get(a), ...groups.get(b)].sort());
+      groups.delete(b);
+    }
+  }
+}
+
+function splitOversized(key, files, cap, out) {
+  if (files.length <= cap) {
+    out.push({ dir: key, files });
+    return;
+  }
+  // 按下一级目录段细分；直属文件（无更深层）留在本组（subKey = key）。key 为空
+  // （根直属组）时 dirname 是 "."，嵌套文件直接用完整相对目录做子键——根组没有
+  // 「前缀可剥」。
+  const sub = new Map();
+  for (const file of files) {
+    const dir = posix.dirname(file);
+    let subKey;
+    if (key === "") {
+      subKey = dir === "." ? key : dir;
+    } else {
+      const rest = dir.startsWith(key + "/") ? dir.slice(key.length + 1) : "";
+      subKey = rest === "" ? key : `${key}/${rest.split("/")[0]}`;
+    }
+    if (!sub.has(subKey)) sub.set(subKey, []);
+    sub.get(subKey).push(file);
+  }
+  if (sub.size === 1) {
+    const [onlyKey] = sub.keys();
+    if (onlyKey === key) {
+      // 已是最深层目录、没有可下的子级：按文件名切块，块名带序号（语义无可言，保契约）。
+      chunkFiles(key, files, cap, out);
+      return;
+    }
+    // 整组都在一个更深的子目录里：继续往下切。
+    splitOversized(onlyKey, sub.get(onlyKey), cap, out);
+    return;
+  }
+  for (const subKey of [...sub.keys()].sort()) {
+    splitOversized(subKey, sub.get(subKey), cap, out);
+  }
+}
+
+function chunkFiles(key, files, cap, out) {
+  for (let i = 0; i < files.length; i += cap) {
+    const slice = files.slice(i, i + cap);
+    out.push({ dir: i === 0 ? key : `${key}#${Math.floor(i / cap) + 1}`, files: slice });
+  }
+}
+
+function materialize(group, graph) {
+  const fileSet = new Set(group.files);
+  const internalEdges = graph.edges.filter((e) => fileSet.has(e.from) && fileSet.has(e.to));
+  const extCounts = new Map();
+  for (const [pkg, users] of graph.external) {
+    const n = [...users].filter((f) => fileSet.has(f)).length;
+    if (n > 0) extCounts.set(pkg, n);
+  }
+  return {
+    dir: group.dir,
+    files: group.files,
+    fileCount: group.files.length,
+    internalEdges,
+    externalDeps: [...extCounts.entries()]
+      .map(([pkg, count]) => ({ pkg, count }))
+      .sort((a, b) => (a.pkg < b.pkg ? -1 : a.pkg > b.pkg ? 1 : b.count - a.count)),
+  };
+}
+
+function assignSlugsAndParents(modules, repoName) {
+  // slug：目录段连字化；重复加序号。空目录段（根直属）用 "root"。
+  const used = new Map();
+  for (const mod of modules) {
+    const base = mod.dir === "" ? "root" : slugify(mod.dir);
+    const n = used.get(base) ?? 0;
+    used.set(base, n + 1);
+    mod.slug = n === 0 ? base : `${base}-${n + 1}`;
+    mod.title = titleOf(mod, repoName);
+  }
+  // 父链：slug 集里目录包含关系最近的祖先（重名块 #2 算同层）。
+  for (const mod of modules) {
+    mod.parentSlug = null;
+    let best = null;
+    for (const other of modules) {
+      if (other === mod) continue;
+      if (other.dir === "") continue;
+      if (mod.dir === other.dir || mod.dir === "") continue;
+      if (!mod.dir.startsWith(other.dir + "/")) continue;
+      if (best === null || other.dir.length > best.dir.length) best = other;
+    }
+    if (best) mod.parentSlug = best.slug;
+  }
+}
+
+function slugify(dir) {
+  return dir
+    .toLowerCase()
+    .replace(/[^a-z0-9/]+/g, "-")
+    .replace(/\/+/g, "-")
+    .replace(/^-+|-+$/g, "") || "root";
+}
+
+function titleOf(mod, repoName) {
+  if (mod.dir === "") return repoName ? `${repoName}（仓库根）` : "仓库根";
+  const segments = mod.dir.split("/");
+  const last = segments[segments.length - 1];
+  // 目录名直接当标题（保持原文大小写）；切块组带序号（dir 里的 # 是切块标记，
+  // slugify 之后 slug 里已无 #，所以判断要看 dir）。
+  return mod.dir.includes("#") ? `${last.replace(/#\d+$/, "")}（续 ${mod.dir.match(/#(\d+)$/)?.[1] ?? ""}）` : last;
+}
+
+function moduleFingerprint(mod) {
+  const hash = createHash("sha256");
+  for (const f of mod.files) hash.update(`f:${f}\n`);
+  for (const e of mod.internalEdges) hash.update(`e:${e.from}>${e.to}\n`);
+  return hash.digest("hex");
+}