@modusensus/dsh-mneme 0.11.0 → 0.12.0

package/lib/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.
@@ -92,14 +94,17 @@ 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 兜底——错误分支直接透传给渲染层判。
+  // 宿主在 render 前按成功 schema 校验返回值，仓库解析失败要走工具错误通道。
   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" };
+    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）：开启时给「何时用」最有歧义的两个
@@ -479,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:
@@ -1081,7 +1190,6 @@ export function createTools(ctx, service, config, embedder, sessionGate = null,
       },
       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 };
       }
@@ -1107,10 +1215,16 @@ export function createTools(ctx, service, config, embedder, sessionGate = null,
       },
       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;
+        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 };
       }
     }),
@@ -1129,26 +1243,29 @@ export function createTools(ctx, service, config, embedder, sessionGate = null,
           type: "object",
           additionalProperties: false,
           properties: {
-            hits: { type: "array", required: true, items: { type: "object", additionalProperties: true } }
+            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 = value.hits ?? [];
+          const { hits, unreadablePages } = value;
           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"));
+          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);
-        if (repo.error) return repo;
-        return {
-          hits: choro.search(repo.id, args?.query, {
-            moduleSlug: args?.module ?? null,
-            limit: args?.limit
-          })
-        };
+        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 };
       }
     })
   ];

package/lib/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/lib/wiki/queries.js

@@ -1,6 +1,8 @@
 // dsh-mneme/src/wiki/queries.js
 // chorography 的读侧（M1）：仓库列表 / 模块图 / 页面正文 / 关键词检索。
-// 只读，零写路径——写入口只有 M0 的 t0.js（红线 3：模型侧一个写工具都不注册）。
+// 收尾档追加：向量检索（P37–P39，惰性物化 + cosine）。
+// 检索读侧零写路径的例外只有一处——向量物化写 choro_vectors（P37：检索时惰性
+// 补嵌，host 侧才有 embedder；那是向量账本，不是页面真源）。
 //
 // 真源纪律（spec §4 / P12）：页面正文永远读仓库磁盘的 MD（root_path + DB 里的
 // rel_path），库里的表只是索引与状态账。slug 只从 DB 白名单解析，路径拼装零用户
@@ -8,6 +10,36 @@
 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;
 
@@ -54,8 +86,8 @@ export function createChoroQueries({ store }) {
   }
 
   /**
-   * 读一页正文。slug 必须命中 DB 的模块行（P12：路径零用户输入）；磁盘文件被手删
-   * 时返回 { error: "page-missing" }（索引还没重算，读侧如实报缺，不伪造内容）。
+   * 读一页正文。slug 必须命中 DB 的模块行（P12：路径零用户输入）；索引仍在但
+   * 文件缺失或不可读时带回相对路径，让调用方给出对应的恢复提示。
    */
   function readPage(repoId, slug) {
     const row = db.prepare(
@@ -67,7 +99,13 @@ export function createChoroQueries({ store }) {
     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);
-    if (!existsSync(abs)) return { error: "page-missing", slug: row.slug, relPath: 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,
@@ -79,16 +117,17 @@ export function createChoroQueries({ store }) {
       humanBlockCount: row.human_block_count,
       repoName: repo.name,
       relPath: row.rel_path,
-      content: readFileSync(abs, "utf8"),
+      content,
     };
   }
 
   /**
    * 关键词检索（P10）：按 `## ` 分节做大小写不敏感子串匹配，命中返回页 slug、
    * 节标题、起始行号与摘录。只扫 DB 里登记过的页面文件（不是全目录 glob——
-   * 划分变更后未重算的孤儿文件不该被搜出来）。q 为空返回空数组不报错。
+   * 划分变更后未重算的孤儿文件不该被搜出来）。需要提示检索不完整的调用方可接收
+   * 不可读的页 slug。q 为空返回空数组不报错。
    */
-  function search(repoId, q, { moduleSlug = null, limit = 20 } = {}) {
+  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));
@@ -102,11 +141,11 @@ export function createChoroQueries({ store }) {
     const hits = [];
     for (const page of pages) {
       const abs = join(repo.root_path, page.rel_path);
-      if (!existsSync(abs)) continue;
       let text;
       try {
         text = readFileSync(abs, "utf8");
       } catch {
+        onUnreadablePage?.(page.slug);
         continue;
       }
       const lines = text.split("\n");
@@ -216,5 +255,106 @@ export function createChoroQueries({ store }) {
     };
   }
 
-  return { listRepos, resolveRepo, moduleMap, readPage, search, repoByCwd, outline };
+  // --- 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 10 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/sync-test-badge.mjs

@@ -4,7 +4,7 @@
 //
 // 做三件事：
 //   1. 跑一遍全量测试（npm test），取套件总数（`ℹ tests N` 汇总行）；
-//   2. 把双 README 的 tests 徽章（img.shields.io/badge/tests-N%20passed）与
+//   2. 把双 README 的 tests 徽章（img.shields.io/badge/tests-N%20total）与
 //      开发命令注释（# N 个测试 / # 运行 N 个测试 / # N 个 node:test 测试 /
 //      # N tests）刷成该数字——形状集合收在 scripts/test-count-sync.mjs，与发版
 //      自动路径 scripts/release-prep.mjs 共用（两条路径各存一份曾导致 v0.8.11

package/scripts/test-count-sync.mjs

@@ -9,17 +9,21 @@
 // 四条注释留在 1431 —— 自动路径反而成了漂移的来源。规则收在这里共用，
 // 由 test/test-count-sync.test.js 锁住形状集合与「双 README 同数」这条不变量。
 //
-// 徽章正则刻意不带尾随 `-`：`tests-N%20passed` 既能命中 `…passed-3E63DD`（root）
-// 也能命中 `…passed-success`（包 README），将来出现无后缀写法也不会静默漏改。
+// 徽章正则刻意不带尾随 `-`：`tests-N%20total` 既能命中 `…total-3E63DD`（root）
+// 也能命中 `…total-success`（包 README），将来出现无后缀写法也不会静默漏改。
+//
+// 徽章报的是**套件总数**不是通过数，所以字面量写 `total` 而不是 `passed`（#599 评审指出）：
+// 本地 Windows 未开开发者模式时有一条符号链接用例被条件跳过，pass 数会比总数少 1，
+// 而徽章口径是 CI（ubuntu）的套件总数——写 `passed` 就在非 CI 平台上多报了一个通过。
 
-const BADGE = /tests-\d+%20passed/g;
+const BADGE = /tests-\d+%20total/g;
 const COMMENT_CJK = /(#\s*(?:运行\s*)?)\d+( 个(?:\s*node:test)?\s*测试)/g;
 const COMMENT_EN = /(#\s*)\d+( tests)/g;
 
 /** 把一段文本里所有测试数出现处刷成 count（含徽章与四种注释形状）。 */
 export function applyTestCount(text, count) {
   return text
-    .replace(BADGE, `tests-${count}%20passed`)
+    .replace(BADGE, `tests-${count}%20total`)
     .replace(COMMENT_CJK, `$1${count}$2`)
     .replace(COMMENT_EN, `$1${count}$2`);
 }
@@ -31,7 +35,7 @@ export function applyTestCount(text, count) {
  */
 export function readTestCounts(text) {
   const found = [];
-  for (const m of text.matchAll(/tests-(\d+)%20passed/g)) {
+  for (const m of text.matchAll(/tests-(\d+)%20total/g)) {
     found.push({ shape: "badge", value: Number(m[1]) });
   }
   for (const m of text.matchAll(/#\s*(?:运行\s*)?(\d+)\s*个(?:\s*node:test)?\s*测试/g)) {