@modusensus/dsh-mneme 0.10.1 → 0.12.0

package/src/tools.js

@@ -11,6 +11,8 @@ import { normalizeScopeStateDimension, normalizeScopeStateValue, normalizeScopeS
 import { lastUserQuery } from "./inject.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
+const incompleteChoroSearch = (pages) =>
+  `Search was incomplete because these pages could not be read (${pages.join(", ")}). Check the local checkout and page permissions.`;
 // Per-registry tool-name registry: guards against duplicate registration on
 // live patch reload (DSH Desktop `patchReload: "live"`) where a plugin may be
 // re-applied on the same tools registry without an intervening unregister.
@@ -76,7 +78,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 +94,19 @@ export function createTools(ctx, service, config, embedder, sessionGate = null)
   // flag 关闭时恒返回 null——写入不标注，检索不加权，行为与 A1 前完全一致。
   // logger 透传：registry 反查失败时 warnOnce 才有出口（否则静默降级无观测）。
   const resolveSessionScope = createScopeResolver({ ctx, config, logger: ctx.logger });
+  // 宿主在 render 前按成功 schema 校验返回值，仓库解析失败要走工具错误通道。
+  const resolveChoroRepo = (ref) => {
+    const row = choro.resolveRepo(ref);
+    if (!row) {
+      const reason = ref ? `Repository ${JSON.stringify(ref)} is not registered.` : "No repository is registered for chorography.";
+      throw new Error(`${reason} Run \`dsh-mneme-choro <repo> --apply\` to register a repository.`);
+    }
+    if (row.ambiguous) {
+      const choices = row.ambiguous.map(({ id, name }) => `${id} (${name})`).join(", ");
+      throw new Error(`More than one repository is registered. Pass one of these repository IDs (${choices}).`);
+    }
+    return row;
+  };
   // #249 能力说明（injectGuidanceEnabled）：开启时给「何时用」最有歧义的两个
   // 工具补一句判断指引。工具描述常驻、不进每轮上下文，这个位子零注入成本；
   // 关闭时描述逐字节不变，也不动其他工具的文案。
@@ -466,6 +484,110 @@ export function createTools(ctx, service, config, embedder, sessionGate = null)
       }
     }),
 
+    // #249 第二批：显式 pin。注入侧原来靠「type 是 constraint/preference 就算
+    // 重要」推断谁该每轮置顶，那是隐含假设——库里 1100+ 条自动成了「每轮必进」
+    // 的候选而预算只有 5，真正该进去的反而排到二十名外。这个工具是那条推断的
+    // 唯一人工替代口：钉住 = 每轮注入块最前面那几条（受 pinnedInjectBudget 约束），
+    // 与类型无关（写得最全的那版常常是 pattern）。
+    //
+    // 三个边界写在这里：
+    // - 它不改记忆内容，也不改任何「记忆行」字段，只动 pinned_memories 这张关系
+    //   表，所以与 memory_forget / memory_archive / set_scope_state 都是**不同的轴**：
+    //   遗忘/归档/暂停作用域仍然优先——被它们处理掉的行就算钉着也不会注入，
+    //   回执里的 injectable 就是如实告诉我们这件事。
+    // - 存在性校验走 visibleForTool：strictScope 下 he scope 的行按「不存在」处理，
+    //   与 memory_delete 同款无存在性泄漏。
+    // - unpin 幂等：本来没钉也返回 pinned:false，不报错。
+    defineTool({
+      name: "memory_pin",
+      description:
+        "Pin a memory so it is injected at the top of the memory block every turn, regardless of its type or how it ranks against other memories. " +
+        "Use this only when the user explicitly says an entry must always be present (a hard rule, a standing preference); it is not a way to mark something as important — importance already affects ranking. " +
+        "Pinned entries still obey forgetting, archiving, the scope gate and the two injection switches: when autoInject is off the host registers no injector at all, and when pinnedInjectBudget is 0 the pin pool is off (its default). In either case a pinned entry is not injected through the pin channel, and the receipt reports injectable: false. The receipt answers \"is the pin channel open right now\", not \"is this memory kept out of every block\": a row reported false can still be picked up by the ordinary candidate path on its own merits. " +
+        "Pass unpin: true to release it. Pin order is first-pinned-first, so the oldest pin holds its slot when the budget is tight.",
+      parameters: {
+        id: { type: "string", required: true, description: "Memory id to pin (or unpin with unpin: true)" },
+        note: { type: "string", description: "Optional short reason to keep with the pin, so a later reader knows why it is pinned" },
+        unpin: { type: "boolean", description: "true releases the pin instead of setting it" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            memory_id: { type: "string", required: true },
+            pinned: { type: "boolean", required: true },
+            // 如实回显库现值，不是回显入参：重钉一条已有的 pin 不刷新 created_at，
+            // 回显它才看得出「这次其实没改变顺序」。
+            created_at: { type: "string" },
+            note: { type: "string" },
+            // 钉着 ≠ 会注入。遗忘/归档/暂停作用域/autoInject 关/pinnedInjectBudget=0
+            // 都优先于 pin，把这件事放进回执，而不是让用户以为钉完就一定出现在上下文里。
+            // 回执回答的是「pin 这条通道此刻开不开」：报 false 不等于这条记忆一定不在
+            // 上下文里——它仍可能凭自身重要性走常规候选路进块。
+            // autoInject 是这条通道的总闸：关着时宿主根本不注册注入器
+            // （src/index.js:617 的 if (cfg.autoInject)），pin 段自然也不执行。
+            injectable: { type: "boolean", required: true }
+          }
+        },
+        render: (_args, value) => {
+          if (!value.pinned) return TEXT_OUTPUT(`Memory ${value.memory_id} is no longer pinned.`);
+          const when = value.created_at ? ` (pinned at ${value.created_at})` : "";
+          const blocked = value.injectable
+            ? ""
+            : " The pin channel is closed right now (forgotten, archived, inside a paused scope, autoInject off, or pinnedInjectBudget is 0 — the pin pool is off by default), so it is not placed at the top of the block; the ordinary candidate path can still pick it up on its own merits.";
+          return TEXT_OUTPUT(`Memory ${value.memory_id} is pinned${when}.${blocked}`);
+        }
+      },
+      async execute(args) {
+        // 不可见（explicit 他 scope）= 视作不存在，无存在性泄漏。
+        const target = visibleForTool(args.id, arguments[1]);
+        if (target === undefined) throw new Error("memory not found");
+        // 钉着 ≠ 会注入。这里必须跟注入侧用同一个出口判定，否则回执照样会说谎：
+        // 暂停作用域的行在 enforce 档会被 scopeStateGate 剔掉，但 forgotten/archived
+        // 两个标志位对此一无所知——只算这两项，一条被暂停作用域挡住的行就会报
+        // injectable: true 而实际一条都没注入。filterPaused 正是那个出口（开关关、
+        // 或只开观察档时它原样返回，于是此时报 true 是对的：那种状态下本来就不拦）。
+        // #593 遗留缺口：pin 池整体由 pinnedInjectBudget 开关（src/service.js:1885 的
+        // pinnedBudget > 0 才读表选路），而它默认 0 = 关闭。只看遗忘/归档/暂停作用域时，
+        // 预算为 0 的一条回执照样报 injectable: true——钉住的动作确实成功了，但它此刻
+        // 一条都不会被注入，这正是「返回成功不等于生效」。预算 0 必须报 false。
+        //
+        // 同一类谎话的第二处（CodeRabbit 在 #596 指出）：autoInject 才是 pin 通道的总闸
+        // ——关着时 src/index.js:617 根本不注册注入器，pin 段无从执行，而回执仍会报
+        // true。config schema 里它的默认值是 true（src/config.js:10），所以按「只有显式
+        // false 才算关」判：拿不到已填 defaults 的 config（测试直连 createTools）时不会
+        // 被误报成 false。
+        //
+        // 仍然没建模的：候选池侧的 type / importance / codingGate 闸（一条被钉的
+        // document 行同样进不了注入块）。那几道闸随候选池变化，回执不做猜测；
+        // 这里只回答「pin 这条通道此刻开不开」——报 false 也不等于这条记忆一定不在
+        // 上下文里，它仍可能凭自身重要性走常规候选路进块。
+        const pinnedBudget = Math.max(0, Math.min(5, Math.floor(config?.pinnedInjectBudget ?? 0)));
+        const autoInjectOn = config?.autoInject !== false;
+        const injectable =
+          autoInjectOn &&
+          pinnedBudget > 0 &&
+          !target.forgotten &&
+          !target.archived &&
+          service.filterPaused([target]).length > 0;
+        if (args.unpin === true) {
+          service.unpinMemory(target.id);
+          return { memory_id: target.id, pinned: false, injectable };
+        }
+        const row = service.pinMemory(target.id, { note: args.note });
+        if (row === undefined) throw new Error("pin could not be recorded");
+        return {
+          memory_id: row.memory_id,
+          pinned: true,
+          created_at: row.created_at,
+          // 没写过理由时键整个不出现（output schema 是闭合的，留 undefined 等于空壳）。
+          ...(row.note === undefined ? {} : { note: row.note }),
+          injectable
+        };
+      }
+    }),
+
     defineTool({
       name: "memory_archive",
       description:
@@ -1032,6 +1154,119 @@ 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);
+        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);
+        const page = choro.readPage(repo.id, args?.slug);
+        if (!page) {
+          throw new Error(`Page ${JSON.stringify(args?.slug ?? "")} was not found. Use choro_module_map to list page slugs.`);
+        }
+        if (page.error === "page-missing") {
+          throw new Error(`Page ${JSON.stringify(page.slug)} is missing from disk (${page.relPath}). Check the local checkout or run \`dsh-mneme-choro <repo> --apply\` to rebuild it.`);
+        }
+        if (page.error) {
+          throw new Error(`Page ${JSON.stringify(page.slug)} could not be read (${page.relPath}). Check the local file and its permissions.`);
+        }
+        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 } },
+            unreadablePages: { type: "array", items: { type: "string" }, description: "Page slugs that could not be read during the search" }
+          }
+        },
+        render: (_args, value) => {
+          const { hits, unreadablePages } = value;
+          if (hits.length === 0) return TEXT_OUTPUT("0 hits.");
+          const lines = hits.map((hit) => `${hit.slug} · ${hit.section} · L${hit.line}: ${hit.excerpt}`);
+          if (unreadablePages?.length) lines.push("", incompleteChoroSearch(unreadablePages));
+          return TEXT_OUTPUT(lines.join("\n"));
+        }
+      },
+      async execute(args) {
+        const repo = resolveChoroRepo(args?.repo);
+        const unreadablePages = [];
+        const hits = choro.search(repo.id, args?.query, {
+          moduleSlug: args?.module ?? null,
+          limit: args?.limit,
+          onUnreadablePage: (slug) => unreadablePages.push(slug)
+        });
+        if (unreadablePages.length === 0) return { hits };
+        if (hits.length === 0) throw new Error(incompleteChoroSearch(unreadablePages));
+        return { hits, unreadablePages };
+      }
     })
   ];
 
@@ -1046,6 +1281,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/user-settings.js

@@ -1,5 +1,5 @@
 // dsh-mneme/src/user-settings.js
-// 「用户设置」注入块（人格 / 画像 / 规则）的唯一渲染处。
+// 「用户设置」注入块（人格 / 画像 / 自动画像事实 / 规则）的唯一渲染处。
 //
 // 为什么要单独成模块：面板「Agent 眼中的画像」那张卡原本自己在前端拼了一份 profile +
 // rules 的列表，注释写着「注入生效文本」——但它没有表头、没有「- 用户画像：」前缀，
@@ -7,10 +7,18 @@
 // 「看着像」。现在注入器与预览路由调同一个函数，前端只显示后端给的文本。
 //
 // 顺序是设计口径（人格设计稿⑥）：特化指令（人格）先出，画像与规则后出、后写覆盖占
-// 上风，rules 恒最硬。改这个顺序等于改提示词权重，别顺手调。
+// 上风，rules 恒最硬。改这个顺序等于改提示词权重，别顺手调。自动画像事实（2026-11-06，
+// src/profile-facts.js）插在画像之后、规则之前——它是「画像的 agent 侧补充」，与
+// 手填画像物理分离（模型对 user_settings.profile 永远只有读权）。
 
 import { STR, langOf } from "./lang.js";
 
+// 事实段的注入预算（本块此前无任何截断机制——它是「身份文本」，从不轮换）。
+// 不设上限的话，一次失控的维护轮能把每帧 systemPrompt 撑爆；行数与总字符双帽，
+// 截断不静默（尾注如实说还剩几条，与 #164① 同一纪律）。
+const PROFILE_FACTS_MAX_LINES = 40;
+const PROFILE_FACTS_MAX_CHARS = 1200;
+
 /**
  * 提示词变量转义：宿主模板插值对 `{{`/`}}` 会按变量名解析并在缺失时抛错，整轮崩掉。
  * 所以把 2 个以上连续花括号逐字符插 `\`，让任何 `{{`/`}}` 子串都不残留；转换幂等，
@@ -35,22 +43,49 @@ export function escapePromptVars(config, text) {
  * - 开：不注入人格（`source: "none"`）。default 退回它的本意：只兜「这一帧解析不到
  *   身份」的会话（无名会话本来就是 default 卡的受众）。
  * 默认关是有意的：这是一次口径变更，不能让老用户的注入文本在升级后静默变化。
+ *
+ * 严格模式有一格例外（#587）：`byAgent` **整体为空**时仍回落 default。两种处境必须
+ * 分开——「建了卡、只是没这张身份的卡」是真该按 none 处理（否则关掉一张卡等于没关），
+ * 而「一张身份卡都没建」时 default 是用户手里唯一的一张卡，按 none 处理等于把它永久
+ * 废掉，且面板不报错。DS Bot 这类宿主里所有 bot 会话共用 `agentPreset: "standard"`
+ * （`ds-bot/src/host/roster.js:72-80` 强制写入），用户按 bot 名字建卡永远不会命中，
+ * 于是必然落进后一种处境：开了严格寻址就把唯一那张卡静默关死。
  */
 export function resolvePersonaCard(settings, agentId, { strict = false } = {}) {
   const store = settings.getPersona();
   const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
   const card = id ? store.byAgent[id] : null;
   if (card && card.enabled === true) return { card, source: "byAgent" };
-  if (id && strict) return { card: {}, source: "none" };
+  // 严格模式只在「确实建过身份卡」时才拒绝兜底：一张都没建时兜底是唯一的出路。
+  if (id && strict && Object.keys(store.byAgent).length > 0) return { card: {}, source: "none" };
   return { card: store.default, source: "default" };
 }
 
+/**
+ * 按会话身份取自动事实卡（resolvePersonaCard 的镜像，形状不同：facts 没有
+ * enabled 位，「卡存在」就是非空数组）。strict 语义与人格一致：有身份但没这张
+ * 身份的卡时不落 default——两个 bot 对用户的认知不互串是 store 层分区（输入行）
+ * 与本层寻址（输出注入）共同守住的边界。与人格同一条例外（#587）：`byAgent` 整体
+ * 为空时仍落 default，「一张都没建」不等于「这一张没建」。
+ */
+export function resolveFactsCard(factsStore, agentId, { strict = false } = {}) {
+  const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+  const byAgent = factsStore?.byAgent ?? {};
+  const card = id ? (byAgent[id] ?? null) : null;
+  if (card && card.length) return { facts: card, source: "byAgent" };
+  if (id && strict && Object.keys(byAgent).length > 0) return { facts: [], source: "none" };
+  return { facts: factsStore?.default ?? [], source: "default" };
+}
+
 /**
  * 渲染整块「用户设置」。`agentId` 是会话身份（解析不到传 null → 走 default 兜底）。
- * 返回 `{ text, source, agent, configGate }`：`text` 为最终注入文本（全空时 ""），
- * `configGate` 是 personaEnabled 的现值——面板要靠它解释「卡开着为什么没生效」。
+ * `factsProvider` 是 profile-facts 域的读口（返回 `{ default: [...], byAgent: {...} }`），
+ * 可选；**开关与 provider 双闸**——profileFactsEnabled 关着时连 provider 都不调，
+ * 「关」必须是零读数而不是「读了不渲染」。返回 `{ text, source, agent, configGate }`：
+ * `text` 为最终注入文本（全空时 ""），`configGate` 是 personaEnabled 的现值——面板
+ * 要靠它解释「卡开着为什么没生效」。
  */
-export function renderUserSettingsBlock({ settings, config, agentId = null }) {
+export function renderUserSettingsBlock({ settings, config, agentId = null, factsProvider = null }) {
   const language = langOf(config);
   const profile = settings.getProfile().trim();
   const rules = settings.getRules();
@@ -66,13 +101,34 @@ export function renderUserSettingsBlock({ settings, config, agentId = null }) {
         ...(typeof persona.replyStyle === "string" && persona.replyStyle.trim() ? [STR.personaReplyStyleLine[language](persona.replyStyle.trim())] : [])
       ]
     : [];
+  // 事实段：开关关 / 无 provider / 该卡没事实三种情况都不渲染，注入文本与
+  // 未启用事实时逐字节一致（老用户零变化）。
+  const factsResolved = config?.profileFactsEnabled === true && typeof factsProvider === "function"
+    ? resolveFactsCard(factsProvider(), agentId, { strict: config?.personaStrictAddressing === true })
+    : { facts: [], source: "none" };
+  const factLines = [];
+  if (factsResolved.facts.length) {
+    let chars = 0;
+    let shown = 0;
+    for (const fact of factsResolved.facts) {
+      const line = STR.profileFactLine[language](String(fact));
+      if (shown >= PROFILE_FACTS_MAX_LINES || chars + line.length > PROFILE_FACTS_MAX_CHARS) break;
+      factLines.push(line);
+      chars += line.length;
+      shown += 1;
+    }
+    const remaining = factsResolved.facts.length - shown;
+    if (remaining > 0) factLines.push(STR.profileFactsTruncated[language](remaining));
+    if (factLines.length) factLines.unshift(STR.profileFactsHeader[language](factsResolved.facts.length));
+  }
   const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : null;
-  if (!profile && !rules.length && !personaLines.length) {
+  if (!profile && !rules.length && !personaLines.length && !factLines.length) {
     return { text: "", source: resolved.source, agent: id, configGate: enabled };
   }
   const lines = [STR.userSettingsHeader[language]];
   lines.push(...personaLines);
   if (profile) lines.push(STR.profileLine[language](profile));
+  lines.push(...factLines);
   for (const rule of rules) lines.push(STR.ruleLine[language](rule));
   return { text: escapePromptVars(config, lines.join("\n")), source: resolved.source, agent: id, configGate: enabled };
 }

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