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

package/lib/attachment-text.js

@@ -1,122 +1,122 @@
-// 图块抽取：会话消息里的 `type:"image"` 块到纯文本占位（Issue #611）。
-//
-// 为什么单独一个模块：在本次改动之前，`textOf` 的实现在 summarize / continuity /
-// hot-memory 三处各有一份副本（各写一份的理由不同，注释里都写了）。三份都是
-// `p?.type && p.type !== "text"` → 空串，于是图片一律被丢。给三份各加一遍 image
-// 分支，等于给同一件事写三份实现——而这三份本来就该同一个口径。所以为 image
-// 单独抽一个**只做一件事**的模块：给定一个 content 块，回答它的可读文本。
-//
-// 口径（维护者 2026-11-08 定，先只做 off 档）：
-// - 不调 vision、不读字节、不落原图。宿主有 `attachments.readImage()`，但记忆库
-//   已 273MB，原图档明确不做。
-// - 占位形如 `[图: 屏幕截图 2026-10-19.png]`，带文件名与宽高，够人回看时定位；
-//   拿不到名字时退化成 `[图: image/png]`、再退化成 `[图]`，**绝不返回空串**——
-//   返回空串正是本次要修的那个 bug（图-only 消息整条被丢，静默）。
-// - 这里只回答「这一块读出什么文本」，不回答「这个模型能不能看图」。后者要看
-//   `llm.resolveModelInfo(...).inputModalities`，属于描述档的准入判断，本批不做。
-
-/** 图片块的占位前缀：审计与测试都按它计数。 */
-export const IMAGE_PLACEHOLDER_PREFIX = "[图";
-
-/** 标签里单段元数据的长度上限。文件名可以任意长，但占位不该被一个长名字撑开。 */
-const LABEL_PART_MAX = 80;
-
-/**
- * 把一段外部可写的元数据（文件名 / mediaType）压成占位符里安全的一段。
- *
- * 为什么必须做：占位形如 `[图: <name>]`，而 `name` 是**外部可写的字符串**（附件的
- * 原始文件名，用户可以随便起）。名字里出现 `]` 就能提前闭合占位，后面的内容随
- * 即冒充占位符之外的正文——那是把元数据升格成转录文本的一条路，和 `#493` 的
- * 围栏断链是同一类问题。换行同理：一段元数据不该能凭空造出一行「用户：…」。
- * 所以 `[`、`]`、控制字符、连续空白一律折成单个空格，再按长度截断。
- *
- * @param {unknown} value
- * @returns {string}
- */
-function sanitizeLabelPart(value) {
-  if (typeof value !== "string") return "";
-  // eslint-disable-next-line no-control-regex
-  const flattened = value.replace(/[\u0000-\u001f\u007f[\]\\]/g, " ").replace(/\s+/g, " ").trim();
-  if (flattened.length <= LABEL_PART_MAX) return flattened;
-  // 按 UTF-16 长度切会切在代理对中间（emoji 占两个单元），留下一个孤立的高位代理——
-  // 那一半写进 SQLite 就是 `�`，落盘后原文再也拼不回来（CodeRabbit 2026-11-08 指出）。
-  // 所以先切到上限，再回头检查末位是不是高位代理：是就再退一格。
-  let cut = flattened.slice(0, LABEL_PART_MAX - 1);
-  const last = cut.charCodeAt(cut.length - 1);
-  if (last >= 0xd800 && last <= 0xdbff) cut = cut.slice(0, -1);
-  return `${cut}…`;
-}
-
-/** 一个图片块读出的人类可读标签（不含方括号）。什么元数据都没有时返回空串。 */
-export function imageLabel(block) {
-  const attachment = block?.attachment ?? {};
-  const name = sanitizeLabelPart(attachment.name);
-  const mediaType = sanitizeLabelPart(attachment.mediaType);
-  const width = Number.isFinite(attachment.width) ? attachment.width : undefined;
-  const height = Number.isFinite(attachment.height) ? attachment.height : undefined;
-  const size = width !== undefined && height !== undefined ? `${width}x${height}` : "";
-  // 没有名字也没有 mediaType 时返回空串，由调用方退化成裸 `[图]`——宁可写「有一张图」，
-  // 也不要写「[图: image]」这种把类型名当名字的假标签。
-  const head = name || mediaType;
-  if (!head) return "";
-  const tail = [mediaType && name ? mediaType : "", size].filter(Boolean).join(" ");
-  return tail ? `${head} ${tail}` : head;
-}
-
-/**
- * 把一个 content 块读成文本。
- *
- * @param {unknown} block  content 数组里的一项
- * @param {object} [options]
- * @param {boolean} [options.imagePlaceholder=true]  false 时图片块返回空串（旧行为，
- *   留给需要严格「只要文字」的调用方，例如把同一批内容喂给不支持图的模型）。
- * @returns {string}
- */
-export function blockToText(block, options = {}) {
-  if (typeof block === "string") return block;
-  if (!block || typeof block !== "object") return "";
-  if (block.type === "image") {
-    if (options.imagePlaceholder === false) return "";
-    const label = imageLabel(block);
-    return label ? `${IMAGE_PLACEHOLDER_PREFIX}: ${label}]` : `${IMAGE_PLACEHOLDER_PREFIX}]`;
-  }
-  if (block.type === undefined || block.type === "text") {
-    return typeof block.text === "string" ? block.text : "";
-  }
-  // reasoning 等私有块：刻意不采集（各调用方的注释都写了理由，这里不重复）。
-  return "";
-}
-
-/**
- * 把一个 content 数组读成多行文本。字符串数组（宽松形状）与严格块数组都认。
- *
- * @param {unknown} content
- * @param {object} [options] 透传给 blockToText
- * @returns {string}
- */
-export function contentToText(content, options = {}) {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .map((block) => blockToText(block, options))
-    .filter((s) => s)
-    .join("\n");
-}
-
-/**
- * 数一段 content 里有几个图片块（审计用）。
- *
- * 为什么单独一个函数而不是在 contentToText 里顺带返回：调用方要的是「这一窗有多少
- * 张图」这个数，而 contentToText 的返回值是字符串，签名不想为一个计量改成对象。
- *
- * @param {unknown} content
- * @returns {number}
- */
-export function countImages(content) {
-  if (!Array.isArray(content)) return 0;
-  let n = 0;
-  for (const block of content) {
-    if (block && typeof block === "object" && block.type === "image") n += 1;
-  }
-  return n;
-}
+// 图块抽取：会话消息里的 `type:"image"` 块到纯文本占位（Issue #611）。
+//
+// 为什么单独一个模块：在本次改动之前，`textOf` 的实现在 summarize / continuity /
+// hot-memory 三处各有一份副本（各写一份的理由不同，注释里都写了）。三份都是
+// `p?.type && p.type !== "text"` → 空串，于是图片一律被丢。给三份各加一遍 image
+// 分支，等于给同一件事写三份实现——而这三份本来就该同一个口径。所以为 image
+// 单独抽一个**只做一件事**的模块：给定一个 content 块，回答它的可读文本。
+//
+// 口径（维护者 2026-11-08 定，先只做 off 档）：
+// - 不调 vision、不读字节、不落原图。宿主有 `attachments.readImage()`，但记忆库
+//   已 273MB，原图档明确不做。
+// - 占位形如 `[图: 屏幕截图 2026-10-19.png]`，带文件名与宽高，够人回看时定位；
+//   拿不到名字时退化成 `[图: image/png]`、再退化成 `[图]`，**绝不返回空串**——
+//   返回空串正是本次要修的那个 bug（图-only 消息整条被丢，静默）。
+// - 这里只回答「这一块读出什么文本」，不回答「这个模型能不能看图」。后者要看
+//   `llm.resolveModelInfo(...).inputModalities`，属于描述档的准入判断，本批不做。
+
+/** 图片块的占位前缀：审计与测试都按它计数。 */
+export const IMAGE_PLACEHOLDER_PREFIX = "[图";
+
+/** 标签里单段元数据的长度上限。文件名可以任意长，但占位不该被一个长名字撑开。 */
+const LABEL_PART_MAX = 80;
+
+/**
+ * 把一段外部可写的元数据（文件名 / mediaType）压成占位符里安全的一段。
+ *
+ * 为什么必须做：占位形如 `[图: <name>]`，而 `name` 是**外部可写的字符串**（附件的
+ * 原始文件名，用户可以随便起）。名字里出现 `]` 就能提前闭合占位，后面的内容随
+ * 即冒充占位符之外的正文——那是把元数据升格成转录文本的一条路，和 `#493` 的
+ * 围栏断链是同一类问题。换行同理：一段元数据不该能凭空造出一行「用户：…」。
+ * 所以 `[`、`]`、控制字符、连续空白一律折成单个空格，再按长度截断。
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function sanitizeLabelPart(value) {
+  if (typeof value !== "string") return "";
+  // eslint-disable-next-line no-control-regex
+  const flattened = value.replace(/[\u0000-\u001f\u007f[\]\\]/g, " ").replace(/\s+/g, " ").trim();
+  if (flattened.length <= LABEL_PART_MAX) return flattened;
+  // 按 UTF-16 长度切会切在代理对中间（emoji 占两个单元），留下一个孤立的高位代理——
+  // 那一半写进 SQLite 就是 `�`，落盘后原文再也拼不回来（CodeRabbit 2026-11-08 指出）。
+  // 所以先切到上限，再回头检查末位是不是高位代理：是就再退一格。
+  let cut = flattened.slice(0, LABEL_PART_MAX - 1);
+  const last = cut.charCodeAt(cut.length - 1);
+  if (last >= 0xd800 && last <= 0xdbff) cut = cut.slice(0, -1);
+  return `${cut}…`;
+}
+
+/** 一个图片块读出的人类可读标签（不含方括号）。什么元数据都没有时返回空串。 */
+export function imageLabel(block) {
+  const attachment = block?.attachment ?? {};
+  const name = sanitizeLabelPart(attachment.name);
+  const mediaType = sanitizeLabelPart(attachment.mediaType);
+  const width = Number.isFinite(attachment.width) ? attachment.width : undefined;
+  const height = Number.isFinite(attachment.height) ? attachment.height : undefined;
+  const size = width !== undefined && height !== undefined ? `${width}x${height}` : "";
+  // 没有名字也没有 mediaType 时返回空串，由调用方退化成裸 `[图]`——宁可写「有一张图」，
+  // 也不要写「[图: image]」这种把类型名当名字的假标签。
+  const head = name || mediaType;
+  if (!head) return "";
+  const tail = [mediaType && name ? mediaType : "", size].filter(Boolean).join(" ");
+  return tail ? `${head} ${tail}` : head;
+}
+
+/**
+ * 把一个 content 块读成文本。
+ *
+ * @param {unknown} block  content 数组里的一项
+ * @param {object} [options]
+ * @param {boolean} [options.imagePlaceholder=true]  false 时图片块返回空串（旧行为，
+ *   留给需要严格「只要文字」的调用方，例如把同一批内容喂给不支持图的模型）。
+ * @returns {string}
+ */
+export function blockToText(block, options = {}) {
+  if (typeof block === "string") return block;
+  if (!block || typeof block !== "object") return "";
+  if (block.type === "image") {
+    if (options.imagePlaceholder === false) return "";
+    const label = imageLabel(block);
+    return label ? `${IMAGE_PLACEHOLDER_PREFIX}: ${label}]` : `${IMAGE_PLACEHOLDER_PREFIX}]`;
+  }
+  if (block.type === undefined || block.type === "text") {
+    return typeof block.text === "string" ? block.text : "";
+  }
+  // reasoning 等私有块：刻意不采集（各调用方的注释都写了理由，这里不重复）。
+  return "";
+}
+
+/**
+ * 把一个 content 数组读成多行文本。字符串数组（宽松形状）与严格块数组都认。
+ *
+ * @param {unknown} content
+ * @param {object} [options] 透传给 blockToText
+ * @returns {string}
+ */
+export function contentToText(content, options = {}) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => blockToText(block, options))
+    .filter((s) => s)
+    .join("\n");
+}
+
+/**
+ * 数一段 content 里有几个图片块（审计用）。
+ *
+ * 为什么单独一个函数而不是在 contentToText 里顺带返回：调用方要的是「这一窗有多少
+ * 张图」这个数，而 contentToText 的返回值是字符串，签名不想为一个计量改成对象。
+ *
+ * @param {unknown} content
+ * @returns {number}
+ */
+export function countImages(content) {
+  if (!Array.isArray(content)) return 0;
+  let n = 0;
+  for (const block of content) {
+    if (block && typeof block === "object" && block.type === "image") n += 1;
+  }
+  return n;
+}

package/lib/bootstrap-http.js

@@ -1,105 +1,105 @@
-// 从目录引导（bootstrap）的 HTTP 口径 —— 唯一实现。
-//
-// 为什么要单独一个模块：这张脸原本只有一个入口（Bearer 数据面 src/api-standalone.js
-// 的 POST /bootstrap），#386 第 6 条要给面板补入口，于是就有了第二个。历史教训写在
-// reclaim-http.js 的开头：#410 修好面板侧之后数据面还停在旧形态（#411），整段复制
-// 必然漂移。所以解析、校验、答复形状从第一份就落在这里，两个入口只留路径与鉴权不同。
-//
-// 这里只做协议层的事：解析、校验、把 bootstrapFromDirectory 的结果包成答复。真正的
-// 解析在 src/bootstrap.js——它读目录、抽六类确定性产物，零 LLM。
-//
-// 与 reclaim-http.js 的一处刻意不同：这里**不做 confirm 两步确认**。bootstrap 是
-// 幂等的（吃 saveWithDedupe 的 (type,title,scope) 去重，`_overwrite` 只刷新内容），
-// 重复跑不会翻倍，也不会删任何东西，所以不需要「先看报告再执行」那道门。
-
-/**
- * 「引导能力没接线」的错误码。两个入口各有一次顺序敏感的显式检查（503 要赢过 400：
- * 端点整个没接线时报「dir 不合法」是误导），所以这条不能只藏在 bootstrapReply 里；
- * 但也必须是同一份字符串。
- */
-export const BOOTSTRAP_UNAVAILABLE = "bootstrap-unavailable";
-
-/**
- * 记日志这一手，只许经这里。
- *
- * 照 `share-http.js` 的同一份理由抄（C5 评审裁定）：warn 裸调时，宿主 logger 自己坏掉就会
- * 从 catch 块里再抛出去，而两侧 handler 那个外层 try 在 .then 的回调里早已退栈——现场
- * 就是「一个字节都没回」（#410）。守卫住在层里，两张脸（in-process 与 Bearer 数据面）
- * 拿到的就是同一个脾气，不必每张脸各记一次。
- */
-function warnSafely(warn, message) {
-  try {
-    warn?.(message);
-  } catch { /* 记日志是自己的事，坏了的日志不许把已经算好的答复一起带走 */ }
-}
-
-/** 引导失败的 warn 文案。两条路径共用，日志里不会出现两种拼法。 */
-function bootstrapWarnMessage(error) {
-  return `[dsh-mneme] bootstrap failed: ${String(error)}`;
-}
-
-/**
- * 解析 POST body（已读成文本）的结构。只判 JSON 与顶层形状，dir 在 readBootstrapDir
- * 里读——两步分开是为了保住「invalid-json → invalid-body → 能力是否接线 → dir」这个
- * 顺序，这个顺序是既有对外行为。
- *
- * 不用 api.js 的 parseBody：它把坏 JSON 吞成 {}，而 invalid-json 与 invalid-body 是
- * 两个不同的错（前者是调用方发坏了，后者是发成了数组/null）。
- *
- * @returns {{ok: true, body: object} | {ok: false, error: string}}
- */
-export function parseBootstrapJson(text) {
-  let body;
-  try {
-    body = JSON.parse(text || "{}");
-  } catch {
-    return { ok: false, error: "invalid-json" };
-  }
-  if (body === null || typeof body !== "object" || Array.isArray(body)) {
-    return { ok: false, error: "invalid-body" };
-  }
-  return { ok: true, body };
-}
-
-/**
- * 读 dir 并归一化。
- *
- * 只收非空字符串：插件没有「工作区根目录」的概念，绝不猜路径（猜错就会去读一个
- * 与用户意图无关的目录，然后把里面的东西写进记忆库）。`trim()` 之后再判空，
- * 但**回传原串**而不是 trim 后的——两端空白在 Windows 路径里不合法，交给 fs 报
- * dir-not-found 比在这里静默改写更诚实。
- *
- * @returns {{ok: true, dir: string} | {ok: false, error: string}}
- */
-export function readBootstrapDir(body) {
-  if (typeof body.dir !== "string" || !body.dir.trim()) {
-    return { ok: false, error: "missing-dir" };
-  }
-  return { ok: true, dir: body.dir };
-}
-
-/**
- * 把一次引导请求变成 { status, body }。调用方只管 sendJson，不自己拼答复。
- *
- * 报告一律不加包装层（就是 bootstrapFromDirectory 的原样返回）：面板与数据面都直接
- * 读 created / merged / items 这几格。
- *
- * `BootstrapError` 带 `code`（missing-dir / dir-not-found / not-a-directory），它们
- * 是**调用方的输入问题**，回 400 并把 code 当错误码；其余异常是内部问题，回 500，
- * 且不能让 warn 把异常本身吞掉。
- *
- * @param {{bootstrapper: ((input: {dir: string}) => Promise<object>)|null,
- *          dir: string, warn?: ((msg: string) => void)|null}} input
- * @returns {Promise<{status: number, body: object}>}
- */
-export function bootstrapReply({ bootstrapper, dir, warn = null }) {
-  if (!bootstrapper) return Promise.resolve({ status: 503, body: { error: BOOTSTRAP_UNAVAILABLE } });
-  return Promise.resolve()
-    .then(() => bootstrapper({ dir }))
-    .then((summary) => ({ status: 200, body: summary }))
-    .catch((error) => {
-      if (error?.code) return { status: 400, body: { error: error.code } };
-      warnSafely(warn, bootstrapWarnMessage(error));
-      return { status: 500, body: { error: "internal" } };
-    });
-}
+// 从目录引导（bootstrap）的 HTTP 口径 —— 唯一实现。
+//
+// 为什么要单独一个模块：这张脸原本只有一个入口（Bearer 数据面 src/api-standalone.js
+// 的 POST /bootstrap），#386 第 6 条要给面板补入口，于是就有了第二个。历史教训写在
+// reclaim-http.js 的开头：#410 修好面板侧之后数据面还停在旧形态（#411），整段复制
+// 必然漂移。所以解析、校验、答复形状从第一份就落在这里，两个入口只留路径与鉴权不同。
+//
+// 这里只做协议层的事：解析、校验、把 bootstrapFromDirectory 的结果包成答复。真正的
+// 解析在 src/bootstrap.js——它读目录、抽六类确定性产物，零 LLM。
+//
+// 与 reclaim-http.js 的一处刻意不同：这里**不做 confirm 两步确认**。bootstrap 是
+// 幂等的（吃 saveWithDedupe 的 (type,title,scope) 去重，`_overwrite` 只刷新内容），
+// 重复跑不会翻倍，也不会删任何东西，所以不需要「先看报告再执行」那道门。
+
+/**
+ * 「引导能力没接线」的错误码。两个入口各有一次顺序敏感的显式检查（503 要赢过 400：
+ * 端点整个没接线时报「dir 不合法」是误导），所以这条不能只藏在 bootstrapReply 里；
+ * 但也必须是同一份字符串。
+ */
+export const BOOTSTRAP_UNAVAILABLE = "bootstrap-unavailable";
+
+/**
+ * 记日志这一手，只许经这里。
+ *
+ * 照 `share-http.js` 的同一份理由抄（C5 评审裁定）：warn 裸调时，宿主 logger 自己坏掉就会
+ * 从 catch 块里再抛出去，而两侧 handler 那个外层 try 在 .then 的回调里早已退栈——现场
+ * 就是「一个字节都没回」（#410）。守卫住在层里，两张脸（in-process 与 Bearer 数据面）
+ * 拿到的就是同一个脾气，不必每张脸各记一次。
+ */
+function warnSafely(warn, message) {
+  try {
+    warn?.(message);
+  } catch { /* 记日志是自己的事，坏了的日志不许把已经算好的答复一起带走 */ }
+}
+
+/** 引导失败的 warn 文案。两条路径共用，日志里不会出现两种拼法。 */
+function bootstrapWarnMessage(error) {
+  return `[dsh-mneme] bootstrap failed: ${String(error)}`;
+}
+
+/**
+ * 解析 POST body（已读成文本）的结构。只判 JSON 与顶层形状，dir 在 readBootstrapDir
+ * 里读——两步分开是为了保住「invalid-json → invalid-body → 能力是否接线 → dir」这个
+ * 顺序，这个顺序是既有对外行为。
+ *
+ * 不用 api.js 的 parseBody：它把坏 JSON 吞成 {}，而 invalid-json 与 invalid-body 是
+ * 两个不同的错（前者是调用方发坏了，后者是发成了数组/null）。
+ *
+ * @returns {{ok: true, body: object} | {ok: false, error: string}}
+ */
+export function parseBootstrapJson(text) {
+  let body;
+  try {
+    body = JSON.parse(text || "{}");
+  } catch {
+    return { ok: false, error: "invalid-json" };
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return { ok: false, error: "invalid-body" };
+  }
+  return { ok: true, body };
+}
+
+/**
+ * 读 dir 并归一化。
+ *
+ * 只收非空字符串：插件没有「工作区根目录」的概念，绝不猜路径（猜错就会去读一个
+ * 与用户意图无关的目录，然后把里面的东西写进记忆库）。`trim()` 之后再判空，
+ * 但**回传原串**而不是 trim 后的——两端空白在 Windows 路径里不合法，交给 fs 报
+ * dir-not-found 比在这里静默改写更诚实。
+ *
+ * @returns {{ok: true, dir: string} | {ok: false, error: string}}
+ */
+export function readBootstrapDir(body) {
+  if (typeof body.dir !== "string" || !body.dir.trim()) {
+    return { ok: false, error: "missing-dir" };
+  }
+  return { ok: true, dir: body.dir };
+}
+
+/**
+ * 把一次引导请求变成 { status, body }。调用方只管 sendJson，不自己拼答复。
+ *
+ * 报告一律不加包装层（就是 bootstrapFromDirectory 的原样返回）：面板与数据面都直接
+ * 读 created / merged / items 这几格。
+ *
+ * `BootstrapError` 带 `code`（missing-dir / dir-not-found / not-a-directory），它们
+ * 是**调用方的输入问题**，回 400 并把 code 当错误码；其余异常是内部问题，回 500，
+ * 且不能让 warn 把异常本身吞掉。
+ *
+ * @param {{bootstrapper: ((input: {dir: string}) => Promise<object>)|null,
+ *          dir: string, warn?: ((msg: string) => void)|null}} input
+ * @returns {Promise<{status: number, body: object}>}
+ */
+export function bootstrapReply({ bootstrapper, dir, warn = null }) {
+  if (!bootstrapper) return Promise.resolve({ status: 503, body: { error: BOOTSTRAP_UNAVAILABLE } });
+  return Promise.resolve()
+    .then(() => bootstrapper({ dir }))
+    .then((summary) => ({ status: 200, body: summary }))
+    .catch((error) => {
+      if (error?.code) return { status: 400, body: { error: error.code } };
+      warnSafely(warn, bootstrapWarnMessage(error));
+      return { status: 500, body: { error: "internal" } };
+    });
+}