@modusensus/dsh-mneme 0.12.0 → 0.13.0

package/src/tools.js

@@ -9,8 +9,16 @@ import { TOOL_GUIDE, CONTINUITY_TOOL_RULE } from "./guide.js";
 import { injectChildEnabled } from "./config.js";
 import { normalizeScopeStateDimension, normalizeScopeStateValue, normalizeScopeStateState } from "./scope-state.js";
 import { lastUserQuery } from "./inject.js";
+// issue #607：工具报错里的 CLI 命令同样要给绝对路径入口——profile 装的插件没有
+// 全局 shim，光写 `dsh-mneme-choro` 用户照抄只会 command not found。
+import { choroCliCommandFrom } from "./wiki/cli-hint.js";
+// 知识库三工具（契约 §3.4）：定义住在 kb/tools.js，本文件只决定注册不注册。
+import { kbToolDefinitions } from "./kb/tools.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
+// 工具报错里的命令串：本文件在 src/ 与 lib/ 同一层（bin/ 的父级），模块加载时推导一次。
+// 推导不出（源码树被裁剪）就返回 null，文案退回通用说法。
+const CHORO_CLI = choroCliCommandFrom(import.meta.url, "<repo>");
 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
@@ -81,7 +89,8 @@ const MEMORY_PROVENANCE = (m) => {
 // choro（M1）：chorography 只读查询对象（createChoroQueries 产物）。缺省 null =
 // 装配层没接（headless/测试），三个 choro_* 工具走 hiddenTools 闸根本不注册。
 // 它与 service 刻意分开传——chorography 的所有权模型与记忆域相反（spec §3）。
-export function createTools(ctx, service, config, embedder, sessionGate = null, choro = null) {
+// kb：知识库装配对象（createKb 产物）；缺省 null = 宿主没装它，三个 kb 工具不注册。
+export function createTools(ctx, service, config, embedder, sessionGate = null, choro = null, kb = null) {
   const toolsRegistry = ctx.tools;
   let registration = REGISTERED_TOOLS.get(toolsRegistry);
   if (!registration) {
@@ -99,7 +108,7 @@ export function createTools(ctx, service, config, embedder, sessionGate = null,
     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.`);
+      throw new Error(`${reason} ${CHORO_CLI ? `Run \`${CHORO_CLI}\`` : "Run `dsh-mneme-choro <repo> --apply`"} to register a repository.`);
     }
     if (row.ambiguous) {
       const choices = row.ambiguous.map(({ id, name }) => `${id} (${name})`).join(", ");
@@ -453,7 +462,11 @@ export function createTools(ctx, service, config, embedder, sessionGate = null,
       name: "memory_forget",
       description:
         "Stop a memory from being auto-injected and from appearing in searches and lists without deleting it. " +
-        "The entry stays in storage; pass forgotten: false to restore it.",
+        "The entry stays in storage; pass forgotten: false to restore it. " +
+        "#532: suppression is per ROW - facts fused into the same entry leave visibility together. " +
+        "When the request targets one fact among several held by a row, inspect the row first (memory_get), " +
+        "split it with memory_update if needed, or say in your reply what else the suppression took down " +
+        "(docs/FORGET.md records the supersession gap behind this).",
       parameters: {
         id: { type: "string", required: true },
         forgotten: { type: "boolean", description: "Suppress (true, default) or restore (false) the entry's visibility" }
@@ -1220,7 +1233,7 @@ export function createTools(ctx, service, config, embedder, sessionGate = null,
           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.`);
+          throw new Error(`Page ${JSON.stringify(page.slug)} is missing from disk (${page.relPath}). Check the local checkout or run ${CHORO_CLI ? `\`${CHORO_CLI}\`` : "`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.`);
@@ -1289,6 +1302,24 @@ export function createTools(ctx, service, config, embedder, sessionGate = null,
     hiddenTools.add("choro_read_page");
     hiddenTools.add("choro_search");
   }
+  // 知识库三工具（契约 §3.4）：与 choro 同款反向语义。装配缺件（kb 为 null）与没开
+  // 对模型同样不可见——可区分性归路由层（503 / 409），模型侧不需要看见半个知识库。
+  if (config?.kbEnabled !== true || !kb) {
+    hiddenTools.add("kb_list_collections");
+    hiddenTools.add("kb_search");
+    hiddenTools.add("kb_read_doc");
+  }
+
+  // 知识库工具定义在 kb/tools.js。**必须过 defineTool**：那里返回的是「describe 形状」
+  // （属性上的 required:true、output.schema 用 spec 写法），直接 ctx.tools.register
+  // 会被宿主的 JSON Schema 校验拒（"required is not supported on type string"）——
+  // 这是接线时踩到的真故障，不是可选加工。判定按 parameters.type==="object" 分：
+  // 已经是 JSON Schema 的说明调用方自己包过，再包一次会把 schema 转坏。
+  if (typeof kbToolDefinitions === "function") {
+    for (const def of kbToolDefinitions({ kb, cfg: config })) {
+      tools.push(def?.parameters?.type === "object" ? def : defineTool(def));
+    }
+  }
 
   for (const tool of tools) {
     if (hiddenTools.has(tool.name)) {

package/src/user-settings.js

@@ -36,6 +36,14 @@ export function escapePromptVars(config, text) {
  * 按会话身份取人格卡。返回 `{ card, source }`，`source` 是给面板解释「用的哪张卡」的
  * 读数，不参与判定。
  *
+ * 寻址维度（#606 起两维，子 agent 继承再加一维共三维）：`sessionId`（绑会话卡，
+ * 最具体）优先于 `parentSessionId`（子 agent 继承父会话卡），最后是 `agentId`（按预设建卡）。
+ * 理由是具体性——会话比预设更具体，而 DS Bot 这类宿主里 `agentPreset` 恒为
+ * `"standard"`（`ds-bot/src/host/roster.js:72-80` 强制写入，实测 50 个会话里 43 个是
+ * 它），若让 byAgent 优先，则谁给 `standard` 建一张卡就会盖掉所有按会话建的卡。
+ * 父会话卡排在 byAgent 之前：子 agent 自己没卡时，它属于哪段对话比它属于哪个预设
+ * 更能说明「该用谁的人格」。
+ *
  * `strict`（config.personaStrictAddressing，默认关）决定「有身份、没这张身份的卡」
  * 与「这张卡被显式关掉」这两种情况：
  * - 关（现状）：落 default 卡。default 于是变成「所有没建卡的 agent 都能拿到它」，
@@ -44,20 +52,45 @@ export function escapePromptVars(config, text) {
  *   身份」的会话（无名会话本来就是 default 卡的受众）。
  * 默认关是有意的：这是一次口径变更，不能让老用户的注入文本在升级后静默变化。
  *
- * 严格模式有一格例外（#587）：`byAgent` **整体为空**时仍回落 default。两种处境必须
- * 分开——「建了卡、只是没这张身份的卡」是真该按 none 处理（否则关掉一张卡等于没关），
- * 而「一张身份卡都没建」时 default 是用户手里唯一的一张卡，按 none 处理等于把它永久
- * 废掉，且面板不报错。DS Bot 这类宿主里所有 bot 会话共用 `agentPreset: "standard"`
- * （`ds-bot/src/host/roster.js:72-80` 强制写入），用户按 bot 名字建卡永远不会命中，
- * 于是必然落进后一种处境：开了严格寻址就把唯一那张卡静默关死。
+ * 严格模式有一格例外（#587）：两维**都没建过卡**时仍回落 default。两种处境必须
+ * 分开——「建了卡、只是没这一张的卡」是真该按 none 处理（否则关掉一张卡等于没关），
+ * 而「一张卡都没建」时 default 是用户手里唯一的一张卡，按 none 处理等于把它永久
+ * 废掉，且面板不报错。判据看两维合起来的键数（#606 起）：只建了 bySession 卡时，
+ * 一个按 byAgent 寻址的会话同样不该被 default 兜底——用户已经做过分区了。
  */
-export function resolvePersonaCard(settings, agentId, { strict = false } = {}) {
+export function resolvePersonaCard(
+  settings,
+  agentId,
+  { strict = false, sessionId = null, parentSessionId = null } = {}
+) {
   const store = settings.getPersona();
   const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+  const sid = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : "";
+  const pid =
+    typeof parentSessionId === "string" && parentSessionId.trim() ? parentSessionId.trim() : "";
+  // 第一维：绑会话卡（最具体）
+  const sessionCard = sid ? store.bySession?.[sid] : null;
+  if (sessionCard && sessionCard.enabled === true) return { card: sessionCard, source: "bySession" };
+  // 第二维（子 agent 继承）：自己没卡就取父会话的卡。
+  // 为什么必须有这一维：子 agent 是新会话，用户不可能给每个派生会话都建一张卡；而
+  // strict 一旦生效，「有身份、没这张身份的卡」= 不注入人格，子 agent 会从「自称父
+  // 会话的人格」变成「不知道自己是谁」——比串味更糟。继承父会话卡才是用户能预期的
+  // 语义：同一个 agent 派生出去的手脚，仍是同一个 agent。
+  // 注意与 `src/session-gate.js` 的口径区别：那里**刻意不**用 parentSession 判「是不是
+  // 子代理」（宿主 fork 出来的主会话同样带 parentSession，用它判会把主会话误关）。
+  // 这里要问的不是「你是不是子代理」而是「你自己有没有卡」，所以 fork 出的分支继承
+  // 父卡也是正确的（它就是同一段对话的副本）。父 id 与自身 id 相同（脏数据）时跳过，
+  // 免得一次寻址查两遍同一个键。
+  const parentCard = pid && pid !== sid ? store.bySession?.[pid] : null;
+  if (parentCard && parentCard.enabled === true) return { card: parentCard, source: "parentSession" };
+  // 第三维：按预设/身份建的卡
   const card = id ? store.byAgent[id] : null;
   if (card && card.enabled === true) return { card, source: "byAgent" };
-  // 严格模式只在「确实建过身份卡」时才拒绝兜底：一张都没建时兜底是唯一的出路。
-  if (id && strict && Object.keys(store.byAgent).length > 0) return { card: {}, source: "none" };
+  // 严格模式只在「确实建过卡」时才拒绝兜底：两维都空时兜底是唯一的出路。
+  const anyCard = Object.keys(store.byAgent ?? {}).length > 0 || Object.keys(store.bySession ?? {}).length > 0;
+  // 身份判定要把父会话 id 算进来：子 agent 只有父会话 id、没有自己的卡时，也是
+  // 「确实有身份」，不许被 default 兜底。
+  if ((id || sid || pid) && strict && anyCard) return { card: {}, source: "none" };
   return { card: store.default, source: "default" };
 }
 
@@ -78,57 +111,120 @@ export function resolveFactsCard(factsStore, agentId, { strict = false } = {}) {
 }
 
 /**
- * 渲染整块「用户设置」。`agentId` 是会话身份（解析不到传 null → 走 default 兜底）。
+ * 渲染整块「用户设置」。`agentId` 是会话身份（解析不到传 null → 走 default 兜底），
+ * `sessionId` 是绑会话卡的键（#606；解析不到传 null）。
  * `factsProvider` 是 profile-facts 域的读口（返回 `{ default: [...], byAgent: {...} }`），
  * 可选；**开关与 provider 双闸**——profileFactsEnabled 关着时连 provider 都不调，
- * 「关」必须是零读数而不是「读了不渲染」。返回 `{ text, source, agent, configGate }`：
+ * 「关」必须是零读数而不是「读了不渲染」。返回 `{ text, source, agent, session, configGate }`：
  * `text` 为最终注入文本（全空时 ""），`configGate` 是 personaEnabled 的现值——面板
  * 要靠它解释「卡开着为什么没生效」。
  */
-export function renderUserSettingsBlock({ settings, config, agentId = null, factsProvider = null }) {
+export function renderUserSettingsBlock({
+  settings,
+  config,
+  agentId = null,
+  sessionId = null,
+  parentSessionId = null,
+  factsProvider = null
+}) {
   const language = langOf(config);
   const profile = settings.getProfile().trim();
   const rules = settings.getRules();
   const enabled = config?.personaEnabled === true;
+  const strict = config?.personaStrictAddressing === true;
   const resolved = enabled
-    ? resolvePersonaCard(settings, agentId, { strict: config?.personaStrictAddressing === true })
+    ? resolvePersonaCard(settings, agentId, { strict, sessionId, parentSessionId })
     : { card: {}, source: "default" };
   const persona = resolved.card;
-  const personaLines = persona?.enabled === true
-    ? [
-        ...(typeof persona.name === "string" && persona.name.trim() ? [STR.personaNameLine[language](persona.name.trim())] : []),
-        ...(typeof persona.personality === "string" && persona.personality.trim() ? [STR.personaPersonalityLine[language](persona.personality.trim())] : []),
-        ...(typeof persona.replyStyle === "string" && persona.replyStyle.trim() ? [STR.personaReplyStyleLine[language](persona.replyStyle.trim())] : [])
-      ]
-    : [];
+  // 段（#600）：每一行都带上它的 kind 与写回所需的定位信息，供面板按段读、按段改。
+  // 段文本是**未转义**的原样行；整串 `text` 仍走原来的「先 join 再统一转义」，
+  // 所以注入字节不变（转义只动连续花括号，换行不参与，逐段转义与整串转义等价）。
+  //
+  // `text` 是**带模板前缀的整行**（如 `- 用户画像：xxx`），不能拿去当新值回写，
+  // 否则每写一次叠一层前缀。可回写的段另带 `value`＝原始值（无前缀、未转义）；
+  // 没有原始值的段（表头、事实表头、截断尾注）不带 `value` 键。
+  const personaLines = [];
+  if (persona?.enabled === true) {
+    if (typeof persona.name === "string" && persona.name.trim()) {
+      const value = persona.name.trim();
+      personaLines.push({ kind: "personaName", field: "name", value, text: STR.personaNameLine[language](value) });
+    }
+    if (typeof persona.personality === "string" && persona.personality.trim()) {
+      const value = persona.personality.trim();
+      personaLines.push({ kind: "personaPersonality", field: "personality", value, text: STR.personaPersonalityLine[language](value) });
+    }
+    if (typeof persona.replyStyle === "string" && persona.replyStyle.trim()) {
+      const value = persona.replyStyle.trim();
+      personaLines.push({ kind: "personaReplyStyle", field: "replyStyle", value, text: STR.personaReplyStyleLine[language](value) });
+    }
+    // scenario / mesExample（#606）：只有设置了才输出，未设置时本块逐字节不变。
+    if (typeof persona.scenario === "string" && persona.scenario.trim()) {
+      const value = persona.scenario.trim();
+      personaLines.push({ kind: "personaScenario", field: "scenario", value, text: STR.personaScenarioLine[language](value) });
+    }
+    if (typeof persona.mesExample === "string" && persona.mesExample.trim()) {
+      const value = persona.mesExample.trim();
+      personaLines.push({ kind: "personaMesExample", field: "mesExample", value, text: STR.personaMesExampleLine[language](value) });
+    }
+  }
   // 事实段：开关关 / 无 provider / 该卡没事实三种情况都不渲染，注入文本与
   // 未启用事实时逐字节一致（老用户零变化）。
   const factsResolved = config?.profileFactsEnabled === true && typeof factsProvider === "function"
-    ? resolveFactsCard(factsProvider(), agentId, { strict: config?.personaStrictAddressing === true })
+    ? resolveFactsCard(factsProvider(), agentId, { strict })
     : { 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));
+      const value = String(fact);
+      const line = STR.profileFactLine[language](value);
       if (shown >= PROFILE_FACTS_MAX_LINES || chars + line.length > PROFILE_FACTS_MAX_CHARS) break;
-      factLines.push(line);
+      factLines.push({ kind: "fact", index: shown, value, text: 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));
+    if (remaining > 0) factLines.push({ kind: "factsTruncated", remaining, text: STR.profileFactsTruncated[language](remaining) });
+    if (factLines.length) {
+      // 表头的 n 是**总条数**（含没注入的），与「另有 N 条未注入」互补，别改成 shown。
+      factLines.unshift({
+        kind: "factsHeader",
+        shown,
+        total: factsResolved.facts.length,
+        text: STR.profileFactsHeader[language](factsResolved.facts.length)
+      });
+    }
   }
   const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : null;
+  const sid = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : null;
+  const pid =
+    typeof parentSessionId === "string" && parentSessionId.trim() ? parentSessionId.trim() : null;
   if (!profile && !rules.length && !personaLines.length && !factLines.length) {
-    return { text: "", source: resolved.source, agent: id, configGate: enabled };
+    // `parent` 是读数（面板要能说清「这张卡是从父会话继承来的」），不参与判定。
+    return {
+      text: "",
+      segments: [],
+      source: resolved.source,
+      agent: id,
+      session: sid,
+      parent: pid,
+      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 };
+  const segments = [{ kind: "header", text: STR.userSettingsHeader[language] }];
+  segments.push(...personaLines);
+  if (profile) segments.push({ kind: "profile", value: profile, text: STR.profileLine[language](profile) });
+  segments.push(...factLines);
+  for (const rule of rules) segments.push({ kind: "rule", value: rule, text: STR.ruleLine[language](rule) });
+  const lines = segments.map((s) => s.text);
+  return {
+    text: escapePromptVars(config, lines.join("\n")),
+    segments,
+    source: resolved.source,
+    agent: id,
+    session: sid,
+    parent: pid,
+    configGate: enabled
+  };
 }

package/src/vector-index.js

@@ -65,35 +65,105 @@ export function createVectorIndex({ store, logger }) {
       return store.searchVector(queryVector, { limit, threshold });
     },
 
-    /** Re-embed every row missing an embedding. Returns indexed count. */
+    /**
+     * Re-embed every row whose vector is missing OR came from another model.
+     *
+     * Returns { indexed, failed, skipped, remaining, error? } — three distinct
+     * outcomes instead of one `skipped` bucket that meant "failed", "threw" and
+     * "did not fit in the limit" all at once. #604.
+     */
     async rebuildIndex(embedder, { limit = 1000 } = {}) {
       // The loop needs a single-text embedder. Native embedSingle is preferred;
       // embed-only OpenAI-compatible clients (issue #10) are accepted too via
       // their `embed` single-text interface, so /vector-reindex no longer
       // silently returns 0 for them. An embedder exposing neither is ignored.
+      // #604: prefer the detailed entry point when the embedder has one. The
+      // legacy OpenAI-compatible client drops the failure reason on its normal
+      // path (embedText returns only the vector), so a provider outage and an
+      // unembeddable row both surfaced here as a bare null. The reason is what
+      // tells them apart, and the operator needs it to know whether pressing
+      // the button again is worth anything.
       let embedOne = null;
+      let embedOneDetailed = null;
+      if (embedder && typeof embedder.embedSingleDetailed === "function") {
+        embedOneDetailed = (text) => embedder.embedSingleDetailed(text);
+      }
       if (embedder && typeof embedder.embedSingle === "function") {
         embedOne = (text) => embedder.embedSingle(text);
       } else if (embedder && typeof embedder.embed === "function") {
         embedOne = (text) => Promise.resolve(embedder.embed(text));
       }
-      if (!embedOne) return { indexed: 0, skipped: 0 };
-      const rows = store.needsEmbedding(limit);
+      if (!embedOne && !embedOneDetailed) {
+        return { indexed: 0, failed: 0, skipped: 0, remaining: 0, error: "no-embedder" };
+      }
+      const model = embedder?.modelHash ?? null;
+      // #604: this used to call needsEmbedding(), which only matches empty
+      // vectors. After a model switch every row already has a vector — from the
+      // previous model — so "reindex" selected nothing, embedded nothing, and
+      // reported {indexed: 0, skipped: 0} as if the index were already current.
+      // The boot sweep has always used the model-aware selector; using the same
+      // one here is what makes the button mean what it says.
+      const rows = model && typeof store.needsEmbeddingFor === "function"
+        ? store.needsEmbeddingFor(model, limit)
+        : store.needsEmbedding(limit);
       let indexed = 0;
+      let failed = 0;
+      const failureReasons = {};
+      const noteFailure = (reason) => {
+        failureReasons[reason] = (failureReasons[reason] ?? 0) + 1;
+      };
       for (const row of rows) {
         try {
           const text = [row.title, row.content].filter(Boolean).join("\n");
-          const vector = await embedOne(text);
+          let vector;
+          if (embedOneDetailed) {
+            const detailed = await embedOneDetailed(text);
+            vector = detailed ? detailed.vector : null;
+            if (!vector && detailed?.reason) noteFailure(`error:${detailed.reason}`);
+          } else {
+            vector = await embedOne(text);
+          }
           if (vector && vector.length) {
-            store.setEmbedding(row.id, vector);
+            // #604: the model fingerprint was omitted here, so every rebuilt
+            // row kept embedding_model NULL. needsEmbeddingFor() then treated
+            // it as stale forever: the boot sweep re-embedded it on each start,
+            // the panel counted it as unsearchable, and pressing reindex again
+            // found nothing (the vector was no longer empty). Passing the
+            // fingerprint closes the loop between the write and the selector.
+            store.setEmbedding(row.id, vector, model ?? undefined);
             indexed++;
+          } else {
+            failed++;
+            // A detailed adapter already recorded why; the plain path has no
+            // reason to record, so name the only thing it can mean.
+            if (!embedOneDetailed) noteFailure("empty-vector");
+            logger?.warn?.(`[dsh-mneme] rebuild produced no vector for ${row.id}`);
           }
         } catch (error) {
+          failed++;
+          noteFailure(`error:${String(error)}`);
           logger?.warn?.(`[dsh-mneme] rebuild embed failed for ${row.id}: ${String(error)}`);
         }
       }
       if (indexed > 0 && embedder.modelHash) this.markModel(embedder.modelHash, embedder.dimension);
-      return { indexed, skipped: rows.length - indexed };
+      // remaining = still selected by the same predicate after this run. Rows
+      // that failed stay in it (they were never written), which is exactly the
+      // number the caller needs to decide whether to run again.
+      const remaining = typeof store.countNeedsEmbeddingFor === "function"
+        ? store.countNeedsEmbeddingFor(model)
+        : null;
+      // `skipped` is 0 by definition here, not as a placeholder: every row the
+      // selector returned is attempted in the loop above, so nothing is left
+      // untouched. Rows that produced no vector are `failed`. The remaining
+      // bucket is the selector's own count, which is why a row can be both
+      // failed and remaining — it was tried and it is still stale.
+      //
+      // `failureReasons` mirrors the boot sweep's bucket names so the two paths
+      // read the same: `empty-vector` means this row will never embed, while an
+      // `error:` bucket means the provider or the store failed and the same
+      // press may well succeed next time. A run that only ever reports
+      // empty-vector is not a retry candidate.
+      return { indexed, failed, skipped: 0, remaining, failureReasons };
     },
 
     /** Index stats for the Web panel / debugging. */

package/src/wiki/cli-hint.js

@@ -0,0 +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);
+}

package/src/wiki/queries.js

@@ -9,6 +9,11 @@
 // 输入——面板与工具传进来的 slug 查不到模块行就返回 null，绝不用它拼路径。
 import { readFileSync, existsSync, realpathSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
+// 过期判定复用既有三件真源（t0 的 gitHead、plan 的指纹、render 的模板版本），
+// 面板侧不另造一套判据——两套判据迟早会对同一仓库给出两个答案。
+import { gitHead } from "./t0.js";
+import { loadPlanFromRepo } from "./plan.js";
+import { TEMPLATE_VERSION } from "./render.js";
 
 // 页正文去 frontmatter / CHORO 标记行后作为嵌入文本（P40：嵌页级全文）。
 function pageEmbedText(content) {
@@ -49,12 +54,114 @@ export function createChoroQueries({ store }) {
       `SELECT r.id, r.root_path, r.name, r.plan_fingerprint, r.git_baseline, r.updated_at,
               (SELECT COUNT(*) FROM choro_modules m WHERE m.repo_id = r.id) AS module_count,
               (SELECT COUNT(*) FROM choro_pages p JOIN choro_modules m2 ON p.module_id = m2.id
-                 WHERE m2.repo_id = r.id) AS page_count
+                 WHERE m2.repo_id = r.id) AS page_count,
+              (SELECT COUNT(*) FROM choro_claims c
+                 JOIN choro_pages p2 ON c.page_id = p2.id
+                 JOIN choro_modules m3 ON p2.module_id = m3.id
+                WHERE m3.repo_id = r.id) AS claim_count
          FROM choro_repos r ORDER BY r.id`
     ).all();
     return rows;
   }
 
+  /**
+   * 面板仓库列表（契约 §3.2）：在 listRepos 的行上补契约要求的字段。
+   *
+   * 为什么另开一个函数而不是改 listRepos 的返回形状：listRepos 的
+   * module_count / page_count 被工具层与查询层测试锁着（下划线命名），改名就是
+   * 破坏既有调用方；而契约要的是 modules / pages 这样的对外字段。两套名字并存
+   * 难看，但改名的连带面比难看贵得多——装饰层把它包一层，工具层照旧读原始行。
+   *
+   * 每个仓库都要 fork 一次 git 判过期：这是用户点开面板才走的路（不是每轮注入的
+   * 热路径），一次 rev-parse 几十毫秒在交互里不可感知。
+   */
+  /**
+   * 契约字段的仓库对象（stale 由调用方决定是否重算）。
+   *
+   * 注意区分两个入口：repoFacts 每次都会 fork git 判过期；repoFromRow 是纯行投影，
+   * 给「已经知道过期原因、手上有判定结果」的调用方用（例如自动重跑之后要紧着按
+   * 新基线说话，不能再拿旧行算一遍）。混用会得到自相矛盾的回执。
+   */
+  function repoFromRow(row) {
+    const rootPath = String(row.root_path ?? "");
+    return {
+      id: row.id,
+      name: row.name,
+      rootPath,
+      modules: Number(row.module_count ?? 0),
+      pages: Number(row.page_count ?? 0),
+      claims: Number(row.claim_count ?? 0),
+      // legacy = 这个仓库里有页面是用旧模板（或 M0 的 NULL）渲染的：重跑一次 T0 就
+      // 会把它们升级成当前模板，面板据此提示「建议重建」而不是让用户自己比对版本。
+      legacy: legacyPages(row.id) > 0,
+      lastRunAt: row.updated_at ?? null
+    };
+  }
+
+  function legacyPages(repoId) {
+    const hit = db.prepare(
+      `SELECT COUNT(*) AS n FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id
+        WHERE m.repo_id = ? AND (p.template_version IS NULL OR p.template_version <> ?)`
+    ).get(repoId, TEMPLATE_VERSION);
+    return Number(hit?.n ?? 0);
+  }
+
+  function repoFacts(row) {
+    const rootPath = String(row.root_path ?? "");
+    // git 优先：代码变了是更硬的「该重跑」信号，plan 变了才退而求其次——两者同时
+    // 成立时面板只说一句话，说「git」比说「plan」更贴近用户看到的现象（他刚改了码）。
+    const head = rootPath === "" ? null : gitHead(rootPath);
+    const baseline = String(row.git_baseline ?? "").trim();
+    let staleReason = null;
+    if (head && head !== baseline) {
+      staleReason = "git";
+    } else if (rootPath !== "") {
+      // 读不到 git（head 为 null）时不直接判「没过期」：plan.yaml 可能已经被改过，
+      // 那条判据不依赖 git，仍能给出答案。
+      let planFingerprintNow = null;
+      try { planFingerprintNow = loadPlanFromRepo(rootPath).fingerprint; } catch { planFingerprintNow = null; }
+      // plan.yaml 校验不过时 loadPlanFromRepo 会抛——那是「现在读不出结论」，不是
+      // 「过期了」，所以落 null 保持 stale=false，让重建按钮自己去报那条 YAML 错误。
+      if (planFingerprintNow && planFingerprintNow !== String(row.plan_fingerprint ?? "")) {
+        staleReason = "plan";
+      }
+    }
+    return {
+      ...repoFromRow(row),
+      stale: staleReason !== null,
+      staleReason
+    };
+  }
+
+  /** 单仓的原始 listRepos 行（自动重跑之后要拿推进过的基线，不能再用旧行）。 */
+  function listRepoRow(repoId) {
+    return listRepos().find((r) => Number(r.id) === Number(repoId)) ?? null;
+  }
+
+  /** 契约形状的仓库列表：listRepos 的原始行 → 对外字段。 */
+  function listRepoFacts() {
+    return listRepos().map((row) => repoFacts(row));
+  }
+
+  /** 仓库的契约字段（按 id/name，给 /choro/page 这类已知单仓的读路径用）。 */
+  function repoFactsById(repoId) {
+    const row = listRepoRow(repoId);
+    return row ? repoFacts(row) : null;
+  }
+
+  /**
+   * 按绝对路径找已登记仓库（面板「选目录 → 生成」必需）：T0 apply 落库时存的是
+   * realpath，所以这里也必须先 realpath 再比，否则 Windows 上盘符大小写/短名/符号
+   * 链接会让同一个目录被当成新仓库重复登记一次。
+   */
+  function repoByRoot(rootPath) {
+    const raw = String(rootPath ?? "").trim();
+    if (raw === "") return null;
+    let normalized;
+    try { normalized = realpathSync(resolve(raw)); } catch { return null; }
+    return db.prepare("SELECT * FROM choro_repos WHERE root_path = ?").get(normalized) ?? null;
+  }
+
   /** repo 解析：数字 id 或显示名（root_path 是本机私有路径，不作为对外键）。 */
   function resolveRepo(ref) {
     if (ref === undefined || ref === null || ref === "") {
@@ -82,6 +189,12 @@ export function createChoroQueries({ store }) {
       `SELECT from_slug, to_slug, weight FROM choro_edges WHERE repo_id = ?
         ORDER BY from_slug, to_slug`
     ).all(repoId);
+    // 纯加法补一个 camelCase 的 relPath：面板从地志页导入知识点要拼「根路径 + 页相对
+    // 路径」，而这里历史上直出 SQL 行的 snake_case（page_rel_path）。C 线按契约读的是
+    // mod.relPath，字段一缺就恒 undefined，用户选完模块点导入只会看到「请先选模块」。
+    // 原字段一律保留——src/tools.js 的 render 与 choro-command 都还在吃 file_count /
+    // page_status，改形状会波及它们；outline() 里的同名映射是这件事的正确写法。
+    for (const m of modules) m.relPath = m.page_rel_path ?? null;
     return { modules, edges };
   }
 
@@ -354,7 +467,8 @@ export function createChoroQueries({ store }) {
   }
 
   return {
-    listRepos, resolveRepo, moduleMap, readPage, search, repoByCwd, outline,
+    listRepos, listRepoFacts, repoFacts, repoFactsById, repoFromRow, listRepoRow, repoByRoot,
+    resolveRepo, moduleMap, readPage, search, repoByCwd, outline,
     embedPageVectors, searchSemantic, embedQueryText, semanticTopN,
   };
 }