@modusensus/dsh-mneme 0.14.0-beta.1 → 0.14.0-beta.2

package/src/wiki/cli-hint.js

@@ -1,90 +1,90 @@
-// dsh-mneme/src/wiki/cli-hint.js
-// issue #607：面板空态让用户「在仓库目录里跑 `dsh-mneme-choro <仓库路径> --apply`」，
-// 但插件是装在 profile 依赖里的，npm 只为**全局**安装把 shim 放进 PATH。profile 的
-// shim 落在 `<profile>/node_modules/.bin`，那里不在 PATH 上 —— 用户照着抄必然
-// command not found。issue 作者实测后的原话是「完全就是 AI 自己编的」。
-//
-// 所以提示里的命令必须**能直接粘贴就跑**：给绝对路径的入口，而不是一个只对全局
-// 安装成立的光名字。入口从插件自身位置推导（不信 PATH、不信 cwd）。
-//
-// 做法是逐级向上找「同时存在 bin/dsh-mneme-choro.mjs 与 package.json」的目录，
-// 而不是固定 dirname 几次：本仓库的 src 与 lib 是同一层，但 wiki/ 是第二层，
-// bin/ 里的脚本又在第一层 —— 写死层数的推导只要有一处调用方挪个位置就悄悄算错，
-// 而算错的表现正是「又给出一条跑不起来的命令」，与这条 issue 的病因同源。
-//
-// 这条对 hoisted 与 pnpm isolated 两种 linker 都成立：后者的真实路径在
-// `.pnpm/<pkg>/node_modules/@modusensus/dsh-mneme/`，包根照样是它的父目录。
-//
-// 刻意**只给 `node <entry>` 这一种形态**：`.bin` 的 shim 在 hoisted 布局下位于
-// 包根的 `../../../node_modules/.bin`，isolated 布局下却在 profile 根 —— 猜错就是
-// 再给一条跑不起来的命令。宁可只给一条一定对的，也不并列两条一条错的。
-//
-// 找不到入口就返回 null（源码树被裁剪、或调用方在包外），调用方退回通用说法，
-// 不硬编一个假路径。
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const ENTRY_BASENAME = "dsh-mneme-choro.mjs";
-// 从 `src/wiki/` 到包根是 2 层，从 `bin/` 是 1 层；留到 6 层是为了 pnpm 的
-// `.pnpm/<pkg>/node_modules/@modusensus/<name>/` 这种深路径，同时不至于一路走到盘符。
-const MAX_LEVELS = 6;
-
-/**
- * choro CLI 入口的绝对路径；找不到（源码树被裁剪、调用方在包外）返回 null。
- *
- * @param {string} fromModuleUrl - 调用方自己的 `import.meta.url`。
- * @returns {string|null}
- */
-export function choroCliEntry(fromModuleUrl) {
-  let dir;
-  try {
-    dir = dirname(fileURLToPath(fromModuleUrl));
-  } catch {
-    return null;
-  }
-  for (let level = 0; level <= MAX_LEVELS; level += 1) {
-    const entry = join(dir, "bin", ENTRY_BASENAME);
-    // 两个条件都要：只有 bin/ 没有 package.json 的目录可能是别人的同名 bin；
-    // 只有 package.json 没有 bin/ 的是源码树被裁剪（`files` 少了 bin）。
-    if (existsSync(entry) && existsSync(join(dir, "package.json"))) return entry;
-    const up = dirname(dir);
-    if (up === dir) break;
-    dir = up;
-  }
-  return null;
-}
-
-/**
- * 给一句可直接粘贴的命令。只负责引号与形态，仓库路径由调用方给（面板给
- * `<仓库路径>` 占位符，工具报错给 `<repo>`）。
- *
- * 引号按平台分：Windows 的 cmd / PowerShell 用双引号；POSIX 用单引号并把内嵌
- * 单引号转成 `'\''` —— 安装路径里带空格是常态（`C:\Program Files\`），不带引号的
- * 示例等于又给人一条跑不起来的命令。
- *
- * @param {string|null} entry - `choroCliEntry()` 的产物。
- * @param {string} repoPlaceholder - 仓库路径占位符的展示形态。
- * @param {string} [platform] - 覆盖 `process.platform`（测试用）。
- * @returns {string|null}
- */
-export function choroCliCommand(entry, repoPlaceholder, platform = process.platform) {
-  if (!entry) return null;
-  const quoted = platform === "win32"
-    ? `"${entry}"`
-    : `'${entry.replace(/'/g, "'\\''")}'`;
-  return `node ${quoted} ${repoPlaceholder} --apply`;
-}
-
-/**
- * 一站式的便捷口：从调用方的 `import.meta.url` 直接拿到命令串。
- * 找不到入口返回 null，调用方据此选通用说法。
- *
- * @param {string} fromModuleUrl
- * @param {string} repoPlaceholder
- * @param {string} [platform]
- * @returns {string|null}
- */
-export function choroCliCommandFrom(fromModuleUrl, repoPlaceholder, platform = process.platform) {
-  return choroCliCommand(choroCliEntry(fromModuleUrl), repoPlaceholder, platform);
-}
+// dsh-mneme/src/wiki/cli-hint.js
+// issue #607：面板空态让用户「在仓库目录里跑 `dsh-mneme-choro <仓库路径> --apply`」，
+// 但插件是装在 profile 依赖里的，npm 只为**全局**安装把 shim 放进 PATH。profile 的
+// shim 落在 `<profile>/node_modules/.bin`，那里不在 PATH 上 —— 用户照着抄必然
+// command not found。issue 作者实测后的原话是「完全就是 AI 自己编的」。
+//
+// 所以提示里的命令必须**能直接粘贴就跑**：给绝对路径的入口，而不是一个只对全局
+// 安装成立的光名字。入口从插件自身位置推导（不信 PATH、不信 cwd）。
+//
+// 做法是逐级向上找「同时存在 bin/dsh-mneme-choro.mjs 与 package.json」的目录，
+// 而不是固定 dirname 几次：本仓库的 src 与 lib 是同一层，但 wiki/ 是第二层，
+// bin/ 里的脚本又在第一层 —— 写死层数的推导只要有一处调用方挪个位置就悄悄算错，
+// 而算错的表现正是「又给出一条跑不起来的命令」，与这条 issue 的病因同源。
+//
+// 这条对 hoisted 与 pnpm isolated 两种 linker 都成立：后者的真实路径在
+// `.pnpm/<pkg>/node_modules/@modusensus/dsh-mneme/`，包根照样是它的父目录。
+//
+// 刻意**只给 `node <entry>` 这一种形态**：`.bin` 的 shim 在 hoisted 布局下位于
+// 包根的 `../../../node_modules/.bin`，isolated 布局下却在 profile 根 —— 猜错就是
+// 再给一条跑不起来的命令。宁可只给一条一定对的，也不并列两条一条错的。
+//
+// 找不到入口就返回 null（源码树被裁剪、或调用方在包外），调用方退回通用说法，
+// 不硬编一个假路径。
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ENTRY_BASENAME = "dsh-mneme-choro.mjs";
+// 从 `src/wiki/` 到包根是 2 层，从 `bin/` 是 1 层；留到 6 层是为了 pnpm 的
+// `.pnpm/<pkg>/node_modules/@modusensus/<name>/` 这种深路径，同时不至于一路走到盘符。
+const MAX_LEVELS = 6;
+
+/**
+ * choro CLI 入口的绝对路径；找不到（源码树被裁剪、调用方在包外）返回 null。
+ *
+ * @param {string} fromModuleUrl - 调用方自己的 `import.meta.url`。
+ * @returns {string|null}
+ */
+export function choroCliEntry(fromModuleUrl) {
+  let dir;
+  try {
+    dir = dirname(fileURLToPath(fromModuleUrl));
+  } catch {
+    return null;
+  }
+  for (let level = 0; level <= MAX_LEVELS; level += 1) {
+    const entry = join(dir, "bin", ENTRY_BASENAME);
+    // 两个条件都要：只有 bin/ 没有 package.json 的目录可能是别人的同名 bin；
+    // 只有 package.json 没有 bin/ 的是源码树被裁剪（`files` 少了 bin）。
+    if (existsSync(entry) && existsSync(join(dir, "package.json"))) return entry;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+/**
+ * 给一句可直接粘贴的命令。只负责引号与形态，仓库路径由调用方给（面板给
+ * `<仓库路径>` 占位符，工具报错给 `<repo>`）。
+ *
+ * 引号按平台分：Windows 的 cmd / PowerShell 用双引号；POSIX 用单引号并把内嵌
+ * 单引号转成 `'\''` —— 安装路径里带空格是常态（`C:\Program Files\`），不带引号的
+ * 示例等于又给人一条跑不起来的命令。
+ *
+ * @param {string|null} entry - `choroCliEntry()` 的产物。
+ * @param {string} repoPlaceholder - 仓库路径占位符的展示形态。
+ * @param {string} [platform] - 覆盖 `process.platform`（测试用）。
+ * @returns {string|null}
+ */
+export function choroCliCommand(entry, repoPlaceholder, platform = process.platform) {
+  if (!entry) return null;
+  const quoted = platform === "win32"
+    ? `"${entry}"`
+    : `'${entry.replace(/'/g, "'\\''")}'`;
+  return `node ${quoted} ${repoPlaceholder} --apply`;
+}
+
+/**
+ * 一站式的便捷口：从调用方的 `import.meta.url` 直接拿到命令串。
+ * 找不到入口返回 null，调用方据此选通用说法。
+ *
+ * @param {string} fromModuleUrl
+ * @param {string} repoPlaceholder
+ * @param {string} [platform]
+ * @returns {string|null}
+ */
+export function choroCliCommandFrom(fromModuleUrl, repoPlaceholder, platform = process.platform) {
+  return choroCliCommand(choroCliEntry(fromModuleUrl), repoPlaceholder, platform);
+}

package/src/wiki/inject.js

@@ -1,164 +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;
-    }
-  };
-}
+// 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;
+    }
+  };
+}