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

package/lib/summarize.js

@@ -9,6 +9,8 @@ import { createScopeResolver } from "./scope.js";
 // #493 补充 §③：断链与巩固侧同一份实现（src/fence.js）。转录里出现闭合标记时
 // 原先能提前闭合围栏——那是把用户消息升格成指令最短的一条路。
 import { breakFenceMarkers } from "./fence.js";
+// Issue #611：图片块的文本口径（占位，不是空串）。三个 textOf 副本共用这一份。
+import { contentToText, countImages } from "./attachment-text.js";
 // #512：每轮蒸馏一个 run id（归因主体）。store 侧也能铸造，但这里必须知道它——
 // 写记忆时要把它一路带到 saveMemoryProvenance / 落 run 行，拿回来再写就是两次往返。
 import { randomUUID } from "node:crypto";
@@ -292,13 +294,13 @@ const SUBAGENT_MESSAGE_KINDS = new Set(["agent-message", "subagent-settled"]);
 
 // 兼容严格形状 [{type:"text",text}] 与宽松形状 ["字符串", ...]（lib-smoke 用例
 // 直接传字符串数组）。只取公开文本块；reasoning 私有推理块不进蒸馏上下文。
+//
+// Issue #611：图片块曾经在这里一律变空串，于是图-only 消息整条被丢、图+文消息只剩
+// 文字——静默，没有任何计数。现在改由 attachment-text 统一产占位，
+// `[图: 屏幕截图 … 1543x983]`。抽取口径只有一份，三个调用方（本文件 /
+// continuity / hot-memory）共用，避免同一件事写成三份会漂移的实现。
 function textOf(content) {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .map((block) => (typeof block === "string" ? block : (block && block.type === "text" && typeof block.text === "string" ? block.text : "")))
-    .filter((s) => s)
-    .join("\n");
+  return contentToText(content);
 }
 
 /**
@@ -333,6 +335,10 @@ function publicTranscriptParts(event) {
     parts.push({
       role: "agent",
       text,
+      // Issue #611：把产文本的那份 content 一起带出去。判定与文本同源，计量才能
+      // 跟着同一份判定走（见 collectMessages 里的 imageCount）——另写一套「哪些块
+      // 算公开」给计量用，就是第二份实现，迟早与这份漂移。
+      blocks: Array.isArray(message?.content) ? message.content : [],
       // 同一条子会话消息可能同时出现在 user/message 与 agent/inbox/spliced
       // 里（投递路径重叠），按 id（无 id 时按内容）去重，否则转录会重复。
       key: typeof message?.id === "string" && message.id
@@ -346,7 +352,7 @@ function publicTranscriptParts(event) {
       const text = textOf(data?.content);
       if (!text.trim()) break;
       if (SUBAGENT_MESSAGE_KINDS.has(kind)) pushAgentMessage(data);
-      else parts.push({ role: "user", text });
+      else parts.push({ role: "user", text, blocks: Array.isArray(data?.content) ? data.content : [] });
       break;
     }
     case "agent/inbox/spliced": {
@@ -358,7 +364,7 @@ function publicTranscriptParts(event) {
       const blocks = Array.isArray(data?.message?.content) ? data.message.content : [];
       const text = textOf(blocks);
       // 私有推理块（reasoning）刻意不采集：蒸馏记忆不得沉淀模型私有思考链。
-      if (text.trim()) parts.push({ role: "assistant", text });
+      if (text.trim()) parts.push({ role: "assistant", text, blocks });
       break;
     }
     default:
@@ -395,6 +401,10 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
   const events = snapshotSessionEvents(session, afterSeq, throughSeq);
   const lines = [];
   const seenSubagentMessages = new Set();
+  // Issue #611：这一窗里被折成占位的图片张数。占位本身不丢信息，但「折了几张」
+  // 必须是个能读到的数——否则 off 档和旧版静默丢弃在观测上无法区分，下次再有人
+  // 问「图到底进来没有」还是得翻源码。计量只数窗口内事件，不受截断影响。
+  let imageCount = 0;
   const trim = (s, n) => (typeof s === "string" && s.length > n ? `${s.slice(0, n)}…` : s);
   const trimTranscript = (s, n) => {
     if (typeof s !== "string" || s.length <= n) return s;
@@ -421,9 +431,20 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
       if (part.role === "agent") {
         if (part.key && seenSubagentMessages.has(part.key)) continue;
         if (part.key) seenSubagentMessages.add(part.key);
-        lines.push(STR.transcriptAgent[language](part.text));
-      } else if (part.role === "user") {
+      }
+      // Issue #611 计量：数「真正进了转录的图块」，所以按 part 数、并且在去重之后
+      // ——同一条子会话消息会同时出现在 user/message 与 agent/inbox/spliced 里
+      // （投递路径重叠），按事件数会把它算两遍。
+      //
+      // 不按事件数还有个更要紧的理由：被 publicTranscriptParts 挡掉的注入消息
+      // （工具结果、插件注入、陌生 source.kind）里的图根本进不了转录，按事件累加
+      // 会报「这一窗有 2 张图」而转录里一张都没有。part 是渲染与落盘共用的同一份
+      // 判定，计量跟着它走，两处不会再各有一套口径。
+      imageCount += countImages(part.blocks);
+      if (part.role === "user") {
         lines.push(STR.transcriptUser[language](part.text));
+      } else if (part.role === "agent") {
+        lines.push(STR.transcriptAgent[language](part.text));
       } else {
         lines.push(STR.transcriptAssistant[language](part.text));
       }
@@ -485,6 +506,9 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
       : [],
     hasEvents: events.length > 0,
     lastSeq,
+    // Issue #611：这一窗折成占位的图片张数。调用方把它写进审计 metadata，
+    // 让「图进来了几张」成为可对账的事实而不是推断。
+    imageCount,
     // Issue #493：只数**转录正文**的字符数。minWindowChars 闸门与审计里的
     // distillChars 量的都是「这一窗有多少可提炼内容」，不是「我们额外包了多少
     // 提示词」——若把围栏与角色句算进去，一条「短」也会凭空越过任何阈值，
@@ -850,6 +874,7 @@ export function createSummarizer(ctx, service, config, deps = {}, sessionGate =
         0
       );
       const minWindowChars = config.summarizeMinWindowChars ?? 0;
+      const imageCount = collected.imageCount ?? 0;
       if (minWindowChars > 0 && distillChars < minWindowChars) {
         commitCursor(session.id, nextSeq);
         writeAudit({
@@ -857,7 +882,7 @@ export function createSummarizer(ctx, service, config, deps = {}, sessionGate =
           model_id: route ? `${route.provider}:${route.model}` : "unknown",
           status: "skipped",
           error_message: "window-too-small",
-          metadata: { distillChars, minWindowChars }
+          metadata: { distillChars, minWindowChars, ...(imageCount > 0 ? { imageCount } : {}) }
         });
         return;
       }
@@ -1064,6 +1089,7 @@ export function createSummarizer(ctx, service, config, deps = {}, sessionGate =
           audit.errorMessage = failureAudit.errorMessage;
           audit.metadata = {
             distillChars,
+            ...(imageCount > 0 ? { imageCount } : {}),
             ...failureAudit.metadata,
             streak,
             ...(maxParseRetries > 0 ? { maxRetries: maxParseRetries } : {}),
@@ -1203,6 +1229,7 @@ export function createSummarizer(ctx, service, config, deps = {}, sessionGate =
       if (audit) {
         audit.metadata = {
           distillChars,
+          ...(imageCount > 0 ? { imageCount } : {}),
           parsed: parsed.length,
           ...(parsedResult.salvaged ? { json_salvaged: true } : {}),
           ...(capped > 0 ? { capped } : {}),

package/lib/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/lib/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/lib/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. */