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

package/src/diary/library.js

@@ -1,189 +1,189 @@
-/**
- * 日记库：把 `<memoryDir>/diaries/` 底下的所有分桶读成「谁写了多少篇」的清单。
- *
- * 和 `dir.js` 的分工：那边管**一个桶在哪**（给定 projectRoot 算键与路径），
- * 这边管**有哪些桶**——左侧面板要的是后者，它拿不到「当前会话的项目」，
- * 因为 `main` 座位不注入 sessionId。
- *
- * 「谁写的」只记在正文 frontmatter 里（`persona: settings (amarre)`），库里
- * 没有第二份。所以这里读最新一篇的 frontmatter 来认人：读不到就退回桶名，
- * 绝不猜——猜错会把 A 的日记挂到 B 名下，而那在界面上看不出来。
- */
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { DIARY_FILE_RE, diaryRoot } from "./dir.js";
-
-/** frontmatter 块：文件必须以 `---` 起头，第二道横线收尾。 */
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
-
-/**
- * 桶键 → 项目根与写日记的 agent。来源是 diaries/state.json（compose 自己写的账本）。
- *
- * 为什么面板要这个：一个桶就是一份 `projectKey(projectRoot)` 的产物，桶名里只有
- * 目录名和 8 位哈希，**反推不回绝对路径**。而「现在再写一篇」必须给 `project`。
- * 读不到就返回空表——那是「这个桶是别人手工放的」或「账本丢了」，面板那时候
- * 就不该长出一个点了必然 400 的按钮。
- */
-function readBucketState(root) {
-  let raw;
-  try {
-    raw = JSON.parse(readFileSync(join(root, "state.json"), "utf8"));
-  } catch {
-    return {};
-  }
-  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
-}
-
-/**
- * 桶名合法性：**不按字符集白名单**，按「它是个单层目录名」判。
- *
- * 一开始写的是 `^[A-Za-z0-9._-]+$`，理由是路径成分越严越好——但现场就有一个
- * 保留中文的桶（`QQ对话-4f061790`，用户那天让另一个会话手工写的）。白名单会把
- * 那一本从导航栏里抹掉，等于把用户写过的日记藏起来，而界面上看不出来。
- *
- * 所以要挡的是**路径语义**，不是字符：分隔符、上跳、控制字符、首尾空白、
- * 以及 `.` / `..` 这两个特殊目录名。挡完这些，桶名就只剩「单层目录名」这一种
- * 可能，下游可以直接拼路径，不需要再比一次路径前缀（见 `bucketDir` 的注释）。
- */
-export function isBucketName(name) {
-  const s = String(name ?? "");
-  if (!s || s !== s.trim()) return false;
-  if (s === "." || s === "..") return false;
-  if (/[/\\]/.test(s)) return false;
-  // eslint-disable-next-line no-control-regex
-  if (/[\u0000-\u001f\u007f]/.test(s)) return false;
-  return true;
-}
-
-/**
- * 桶名 → 目录绝对路径。名字不合法就是 `null`。
- *
- * 这里**没有**第二道「解析后比对根前缀」的校验：`isBucketName` 已经挡住了
- * 分隔符与上跳，剩下的只可能是单层名字，前缀比对永远走不到。试过写它，
- * 变异测试（把比对删掉）一跑八条用例全绿，正说明它是死代码——那就别留，
- * 留着的防御没人能验证，反而让人以为这里有一层额外的兜底。
- */
-function bucketDir(root, bucket) {
-  if (!isBucketName(bucket)) return null;
-  return join(root, bucket);
-}
-
-function readFrontmatter(path) {
-  let text;
-  try {
-    text = readFileSync(path, "utf8");
-  } catch {
-    return {};
-  }
-  const hit = FRONTMATTER_RE.exec(text);
-  if (!hit) return {};
-  const out = {};
-  for (const line of hit[1].split(/\r?\n/)) {
-    const at = line.indexOf(":");
-    if (at <= 0) continue;
-    const key = line.slice(0, at).trim();
-    const value = line.slice(at + 1).trim();
-    if (key) out[key] = value;
-  }
-  return out;
-}
-
-/**
- * 列一个桶里的日记文件。与 `export.js` 的 `listDiaries` 同一口径
- * （只认 `YYYY-MM-DD.md`、跳过空文件、新的在前），这里不重复实现。
- */
-function diaryFiles(dir) {
-  let names;
-  try {
-    names = readdirSync(dir);
-  } catch {
-    return [];
-  }
-  const rows = [];
-  for (const name of names) {
-    if (!DIARY_FILE_RE.test(name)) continue;
-    const path = join(dir, name);
-    let st;
-    try {
-      st = statSync(path);
-    } catch {
-      continue;
-    }
-    if (!st.isFile() || st.size <= 0) continue;
-    rows.push({ date: name.slice(0, 10), path, bytes: st.size, mtime: st.mtimeMs });
-  }
-  return rows.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
-}
-
-/**
- * 全部桶。读不到根目录返回空清单而不是抛——「还没写过第一篇」与「路径坏了」
- * 在面板上是两种不同的话，但这一层分不出来，交给调用方去看 `root`。
- */
-export function listDiaryLibrary({ memoryDir, configured = "" } = {}) {
-  const root = diaryRoot({ memoryDir, configured });
-  let names;
-  try {
-    names = readdirSync(root);
-  } catch {
-    return { root, buckets: [] };
-  }
-  const buckets = [];
-  const state = readBucketState(root);
-  for (const name of names) {
-    // `.deleted` 一类是回收站，不是日记。
-    if (name.startsWith(".")) continue;
-    if (!isBucketName(name)) continue;
-    const dir = join(root, name);
-    let st;
-    try {
-      st = statSync(dir);
-    } catch {
-      continue;
-    }
-    if (!st.isDirectory()) continue;
-    const files = diaryFiles(dir);
-    // 空桶（文件被删光、只剩 runs.jsonl）不列：导航栏里挂一个点开是空的项
-    // 比不列更糟。
-    if (!files.length) continue;
-    let persona = "";
-    let project = "";
-    for (const file of files) {
-      const fm = readFrontmatter(file.path);
-      if (!project && fm.project) project = fm.project;
-      // persona 只认第一篇带它的：同一桶里可能先后住过两个人格（#613 要拆的那种），
-      // 面板先按最新那篇记的人显示，不混。
-      if (fm.persona) {
-        persona = fm.persona;
-        break;
-      }
-    }
-    const meta = state[name] && typeof state[name] === "object" ? state[name] : {};
-    buckets.push({
-      key: name,
-      project,
-      // 「现在再写一篇」需要的两样：绝对路径与写作者身份。账本里没有就留空，
-      // 面板据此把按钮禁掉——不猜路径，猜错会写在别的项目里。
-      projectRoot: typeof meta.projectRoot === "string" ? meta.projectRoot : "",
-      agentId: typeof meta.agentId === "string" ? meta.agentId : "",
-      persona,
-      latest: files[0].date,
-      count: files.length,
-      entries: files.map((file) => ({ date: file.date, bytes: file.bytes, mtime: file.mtime }))
-    });
-  }
-  buckets.sort((a, b) => (a.latest < b.latest ? 1 : a.latest > b.latest ? -1 : 0));
-  return { root, buckets };
-}
-
-/** 读一篇的正文。桶名与日期都要过校验：这条路径直接拼文件系统。 */
-export function readLibraryEntry({ memoryDir, configured = "", bucket, date } = {}) {
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date ?? ""))) return null;
-  const root = diaryRoot({ memoryDir, configured });
-  const dir = bucketDir(root, bucket);
-  if (dir === null) return null;
-  try {
-    return readFileSync(join(dir, `${date}.md`), "utf8");
-  } catch {
-    return null;
-  }
-}
+/**
+ * 日记库：把 `<memoryDir>/diaries/` 底下的所有分桶读成「谁写了多少篇」的清单。
+ *
+ * 和 `dir.js` 的分工：那边管**一个桶在哪**（给定 projectRoot 算键与路径），
+ * 这边管**有哪些桶**——左侧面板要的是后者，它拿不到「当前会话的项目」，
+ * 因为 `main` 座位不注入 sessionId。
+ *
+ * 「谁写的」只记在正文 frontmatter 里（`persona: settings (amarre)`），库里
+ * 没有第二份。所以这里读最新一篇的 frontmatter 来认人：读不到就退回桶名，
+ * 绝不猜——猜错会把 A 的日记挂到 B 名下，而那在界面上看不出来。
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { DIARY_FILE_RE, diaryRoot } from "./dir.js";
+
+/** frontmatter 块：文件必须以 `---` 起头，第二道横线收尾。 */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/**
+ * 桶键 → 项目根与写日记的 agent。来源是 diaries/state.json（compose 自己写的账本）。
+ *
+ * 为什么面板要这个：一个桶就是一份 `projectKey(projectRoot)` 的产物，桶名里只有
+ * 目录名和 8 位哈希，**反推不回绝对路径**。而「现在再写一篇」必须给 `project`。
+ * 读不到就返回空表——那是「这个桶是别人手工放的」或「账本丢了」，面板那时候
+ * 就不该长出一个点了必然 400 的按钮。
+ */
+function readBucketState(root) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(join(root, "state.json"), "utf8"));
+  } catch {
+    return {};
+  }
+  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+}
+
+/**
+ * 桶名合法性：**不按字符集白名单**，按「它是个单层目录名」判。
+ *
+ * 一开始写的是 `^[A-Za-z0-9._-]+$`，理由是路径成分越严越好——但现场就有一个
+ * 保留中文的桶（`QQ对话-4f061790`，用户那天让另一个会话手工写的）。白名单会把
+ * 那一本从导航栏里抹掉，等于把用户写过的日记藏起来，而界面上看不出来。
+ *
+ * 所以要挡的是**路径语义**，不是字符：分隔符、上跳、控制字符、首尾空白、
+ * 以及 `.` / `..` 这两个特殊目录名。挡完这些，桶名就只剩「单层目录名」这一种
+ * 可能，下游可以直接拼路径，不需要再比一次路径前缀（见 `bucketDir` 的注释）。
+ */
+export function isBucketName(name) {
+  const s = String(name ?? "");
+  if (!s || s !== s.trim()) return false;
+  if (s === "." || s === "..") return false;
+  if (/[/\\]/.test(s)) return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(s)) return false;
+  return true;
+}
+
+/**
+ * 桶名 → 目录绝对路径。名字不合法就是 `null`。
+ *
+ * 这里**没有**第二道「解析后比对根前缀」的校验：`isBucketName` 已经挡住了
+ * 分隔符与上跳，剩下的只可能是单层名字，前缀比对永远走不到。试过写它，
+ * 变异测试（把比对删掉）一跑八条用例全绿，正说明它是死代码——那就别留，
+ * 留着的防御没人能验证，反而让人以为这里有一层额外的兜底。
+ */
+function bucketDir(root, bucket) {
+  if (!isBucketName(bucket)) return null;
+  return join(root, bucket);
+}
+
+function readFrontmatter(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return {};
+  }
+  const hit = FRONTMATTER_RE.exec(text);
+  if (!hit) return {};
+  const out = {};
+  for (const line of hit[1].split(/\r?\n/)) {
+    const at = line.indexOf(":");
+    if (at <= 0) continue;
+    const key = line.slice(0, at).trim();
+    const value = line.slice(at + 1).trim();
+    if (key) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * 列一个桶里的日记文件。与 `export.js` 的 `listDiaries` 同一口径
+ * （只认 `YYYY-MM-DD.md`、跳过空文件、新的在前），这里不重复实现。
+ */
+function diaryFiles(dir) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const rows = [];
+  for (const name of names) {
+    if (!DIARY_FILE_RE.test(name)) continue;
+    const path = join(dir, name);
+    let st;
+    try {
+      st = statSync(path);
+    } catch {
+      continue;
+    }
+    if (!st.isFile() || st.size <= 0) continue;
+    rows.push({ date: name.slice(0, 10), path, bytes: st.size, mtime: st.mtimeMs });
+  }
+  return rows.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+}
+
+/**
+ * 全部桶。读不到根目录返回空清单而不是抛——「还没写过第一篇」与「路径坏了」
+ * 在面板上是两种不同的话，但这一层分不出来，交给调用方去看 `root`。
+ */
+export function listDiaryLibrary({ memoryDir, configured = "" } = {}) {
+  const root = diaryRoot({ memoryDir, configured });
+  let names;
+  try {
+    names = readdirSync(root);
+  } catch {
+    return { root, buckets: [] };
+  }
+  const buckets = [];
+  const state = readBucketState(root);
+  for (const name of names) {
+    // `.deleted` 一类是回收站，不是日记。
+    if (name.startsWith(".")) continue;
+    if (!isBucketName(name)) continue;
+    const dir = join(root, name);
+    let st;
+    try {
+      st = statSync(dir);
+    } catch {
+      continue;
+    }
+    if (!st.isDirectory()) continue;
+    const files = diaryFiles(dir);
+    // 空桶（文件被删光、只剩 runs.jsonl）不列：导航栏里挂一个点开是空的项
+    // 比不列更糟。
+    if (!files.length) continue;
+    let persona = "";
+    let project = "";
+    for (const file of files) {
+      const fm = readFrontmatter(file.path);
+      if (!project && fm.project) project = fm.project;
+      // persona 只认第一篇带它的：同一桶里可能先后住过两个人格（#613 要拆的那种），
+      // 面板先按最新那篇记的人显示，不混。
+      if (fm.persona) {
+        persona = fm.persona;
+        break;
+      }
+    }
+    const meta = state[name] && typeof state[name] === "object" ? state[name] : {};
+    buckets.push({
+      key: name,
+      project,
+      // 「现在再写一篇」需要的两样：绝对路径与写作者身份。账本里没有就留空，
+      // 面板据此把按钮禁掉——不猜路径，猜错会写在别的项目里。
+      projectRoot: typeof meta.projectRoot === "string" ? meta.projectRoot : "",
+      agentId: typeof meta.agentId === "string" ? meta.agentId : "",
+      persona,
+      latest: files[0].date,
+      count: files.length,
+      entries: files.map((file) => ({ date: file.date, bytes: file.bytes, mtime: file.mtime }))
+    });
+  }
+  buckets.sort((a, b) => (a.latest < b.latest ? 1 : a.latest > b.latest ? -1 : 0));
+  return { root, buckets };
+}
+
+/** 读一篇的正文。桶名与日期都要过校验：这条路径直接拼文件系统。 */
+export function readLibraryEntry({ memoryDir, configured = "", bucket, date } = {}) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date ?? ""))) return null;
+  const root = diaryRoot({ memoryDir, configured });
+  const dir = bucketDir(root, bucket);
+  if (dir === null) return null;
+  try {
+    return readFileSync(join(dir, `${date}.md`), "utf8");
+  } catch {
+    return null;
+  }
+}

package/src/diary/qq-inbox.js

@@ -1,142 +1,142 @@
-/**
- * 素材来源之一：QQ 聊天收件箱（只读）。
- *
- * 这个模块**不 import `dsh-onebot-qq` 的任何东西**——那个包是 npm 装进来的普通目录，
- * 每次升级都会被覆盖，边界靠这个 provider 的入参/返回值切开，而不是靠 require 路径。
- *
- * 素材口径（实测 `D:\\DSH\\.dsh\\media\\onebot\\qq-inbox.jsonl` 的 decision 分布定下来的）：
- * 只取 `decision.stage === "dispatch" && decision.ok === true` 且消息里真有 text 段的行。
- * 同一份样本里 70 行中，白名单挡掉的群聊 20 行、投递成功但无有效文本 5 行——不滤掉，
- * 日记就会变成「今天什么也没干」的噪音，还占掉 document 注入预算。
- *
- * 已知缺口（照实写在这里，别当它不存在）：inbox 只有**入站**消息，机器人自己的回复
- * 不在其中（样本里 message_sent 命中 0）。所以日记能写「今天她说了什么」，
- * 写不了「我怎么回的」——需要时得另找来源，不能靠这一份编。
- */
-import { readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { localDateString } from "./rollover.js";
-import { memoryBase } from "./dir.js";
-
-/** `qq-inbox.jsonl` = 当前代（0），`qq-inbox.N.jsonl` = 越旧 N 越大。 */
-export const INBOX_FILE_RE = /^qq-inbox(?:\.(\d+))?\.jsonl$/;
-
-function generationOf(name) {
-  const m = INBOX_FILE_RE.exec(name);
-  return m && m[1] ? Number(m[1]) : 0;
-}
-
-/**
- * 收件箱文件，**新的在前**。
- *
- * 目录读不到返回 null（= 没有这个来源），与「目录在但没有消息」严格区分：
- * 前者是 `no-inbox-dir`，后者是 `no-material`，两者的处置完全不同。
- */
-export function inboxFiles(dir) {
-  if (!dir) return null;
-  let names;
-  try {
-    names = readdirSync(dir);
-  } catch {
-    return null;
-  }
-  return names
-    .filter((n) => INBOX_FILE_RE.test(n))
-    .sort((a, b) => generationOf(a) - generationOf(b));
-}
-
-/** 只打码长度 ≥6 的数字串（与 onebot `lib/record.js:47-49` 的 redactDigits 同口径）。 */
-export function redactDigits(text) {
-  return String(text ?? "").replace(/\d{6,}/g, (m) => m.slice(0, 3) + "****");
-}
-
-/** 一条消息里所有 text 段的拼接。图片/表情/语音段没有可读正文，直接跳过。 */
-export function textOf(frame) {
-  const msg = frame && frame.message;
-  if (!Array.isArray(msg)) return "";
-  return msg
-    .filter((s) => s && s.type === "text" && s.data && typeof s.data.text === "string")
-    .map((s) => s.data.text)
-    .join("")
-    .trim();
-}
-
-/** 有效投递：`dispatch` 且 `ok === true`。其余（whitelist / command / 失败）都不算素材。 */
-export function isEffective(frame) {
-  const d = frame && frame.decision;
-  return !!d && d.stage === "dispatch" && d.ok === true;
-}
-
-/**
- * 采一段窗口内的素材。
- *
- * 返回三选一：
- * - `{items, scanned, ignored}` 拿到东西（items 可以为空 = 当天确实没聊）
- * - `{error: "no-inbox-dir"}` 没有这个来源（目录不在）
- * - `{error: "inbox-unreadable", detail}` 目录在但一个文件都读不出来
- */
-export function collectQqInbox({ dir, dateLocal, maxItems = 400 } = {}) {
-  if (!dir) return { error: "no-inbox-dir" };
-  const files = inboxFiles(dir);
-  if (files === null) return { error: "no-inbox-dir", detail: String(dir) };
-  if (files.length === 0) return { error: "inbox-unreadable", detail: String(dir) };
-  const items = [];
-  let scanned = 0;
-  let ignored = 0;
-  let readable = 0;
-  for (const name of files) {
-    let text;
-    try {
-      text = readFileSync(join(dir, name), "utf8");
-    } catch {
-      continue;
-    }
-    readable += 1;
-    for (const line of text.split("\n")) {
-      if (!line.trim()) continue;
-      scanned += 1;
-      let row;
-      try {
-        row = JSON.parse(line);
-      } catch {
-        // 坏行跳过但计数（与 loadObservations 同一条纪律）。
-        ignored += 1;
-        continue;
-      }
-      if (!row || row.kind !== "message" || !isEffective(row.frame)) {
-        ignored += 1;
-        continue;
-      }
-      const ts = Number(row.ts);
-      if (!Number.isFinite(ts)) {
-        ignored += 1;
-        continue;
-      }
-      // 不在当天窗口内的行不算「忽略」，它属于别的日子。
-      if (localDateString(new Date(ts)) !== dateLocal) continue;
-      const body = textOf(row.frame);
-      if (!body) {
-        ignored += 1;
-        continue;
-      }
-      items.push({ ts, role: "user", text: redactDigits(body).slice(0, 2000) });
-    }
-  }
-  if (readable === 0) return { error: "inbox-unreadable", detail: String(dir) };
-  items.sort((a, b) => a.ts - b.ts);
-  return { items: items.slice(-maxItems), scanned, ignored };
-}
-
-/**
- * 把 `<DSH_HOME>/media/onebot` 推出来：memoryDir 默认就是 `<DSH_HOME>/memory`。
- *
- * 推不出来（memoryDir 被指到别处、或给了显式配置）就用配置值；两者都没有时这个来源
- * 直接报 `no-inbox-dir`——宁可这一路没有素材，也不去猜别的盘。
- */
-export function resolveInboxDir({ memoryDir, configured = "" } = {}) {
-  const custom = String(configured ?? "").trim();
-  if (custom) return custom;
-  // 必须走 memoryBase 而不是直接用配置串：默认值就是带 `~` 的字面量，
-  // 不展开的话 join 出来的路径永远落空，旁挂会静默读不到（CodeRabbit #458 F2）。
-  return join(memoryBase(memoryDir), "..", "media", "onebot");
-}
+/**
+ * 素材来源之一：QQ 聊天收件箱（只读）。
+ *
+ * 这个模块**不 import `dsh-onebot-qq` 的任何东西**——那个包是 npm 装进来的普通目录，
+ * 每次升级都会被覆盖，边界靠这个 provider 的入参/返回值切开，而不是靠 require 路径。
+ *
+ * 素材口径（实测 `D:\\DSH\\.dsh\\media\\onebot\\qq-inbox.jsonl` 的 decision 分布定下来的）：
+ * 只取 `decision.stage === "dispatch" && decision.ok === true` 且消息里真有 text 段的行。
+ * 同一份样本里 70 行中，白名单挡掉的群聊 20 行、投递成功但无有效文本 5 行——不滤掉，
+ * 日记就会变成「今天什么也没干」的噪音，还占掉 document 注入预算。
+ *
+ * 已知缺口（照实写在这里，别当它不存在）：inbox 只有**入站**消息，机器人自己的回复
+ * 不在其中（样本里 message_sent 命中 0）。所以日记能写「今天她说了什么」，
+ * 写不了「我怎么回的」——需要时得另找来源，不能靠这一份编。
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { localDateString } from "./rollover.js";
+import { memoryBase } from "./dir.js";
+
+/** `qq-inbox.jsonl` = 当前代（0），`qq-inbox.N.jsonl` = 越旧 N 越大。 */
+export const INBOX_FILE_RE = /^qq-inbox(?:\.(\d+))?\.jsonl$/;
+
+function generationOf(name) {
+  const m = INBOX_FILE_RE.exec(name);
+  return m && m[1] ? Number(m[1]) : 0;
+}
+
+/**
+ * 收件箱文件，**新的在前**。
+ *
+ * 目录读不到返回 null（= 没有这个来源），与「目录在但没有消息」严格区分：
+ * 前者是 `no-inbox-dir`，后者是 `no-material`，两者的处置完全不同。
+ */
+export function inboxFiles(dir) {
+  if (!dir) return null;
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  return names
+    .filter((n) => INBOX_FILE_RE.test(n))
+    .sort((a, b) => generationOf(a) - generationOf(b));
+}
+
+/** 只打码长度 ≥6 的数字串（与 onebot `lib/record.js:47-49` 的 redactDigits 同口径）。 */
+export function redactDigits(text) {
+  return String(text ?? "").replace(/\d{6,}/g, (m) => m.slice(0, 3) + "****");
+}
+
+/** 一条消息里所有 text 段的拼接。图片/表情/语音段没有可读正文，直接跳过。 */
+export function textOf(frame) {
+  const msg = frame && frame.message;
+  if (!Array.isArray(msg)) return "";
+  return msg
+    .filter((s) => s && s.type === "text" && s.data && typeof s.data.text === "string")
+    .map((s) => s.data.text)
+    .join("")
+    .trim();
+}
+
+/** 有效投递：`dispatch` 且 `ok === true`。其余（whitelist / command / 失败）都不算素材。 */
+export function isEffective(frame) {
+  const d = frame && frame.decision;
+  return !!d && d.stage === "dispatch" && d.ok === true;
+}
+
+/**
+ * 采一段窗口内的素材。
+ *
+ * 返回三选一：
+ * - `{items, scanned, ignored}` 拿到东西（items 可以为空 = 当天确实没聊）
+ * - `{error: "no-inbox-dir"}` 没有这个来源（目录不在）
+ * - `{error: "inbox-unreadable", detail}` 目录在但一个文件都读不出来
+ */
+export function collectQqInbox({ dir, dateLocal, maxItems = 400 } = {}) {
+  if (!dir) return { error: "no-inbox-dir" };
+  const files = inboxFiles(dir);
+  if (files === null) return { error: "no-inbox-dir", detail: String(dir) };
+  if (files.length === 0) return { error: "inbox-unreadable", detail: String(dir) };
+  const items = [];
+  let scanned = 0;
+  let ignored = 0;
+  let readable = 0;
+  for (const name of files) {
+    let text;
+    try {
+      text = readFileSync(join(dir, name), "utf8");
+    } catch {
+      continue;
+    }
+    readable += 1;
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      scanned += 1;
+      let row;
+      try {
+        row = JSON.parse(line);
+      } catch {
+        // 坏行跳过但计数（与 loadObservations 同一条纪律）。
+        ignored += 1;
+        continue;
+      }
+      if (!row || row.kind !== "message" || !isEffective(row.frame)) {
+        ignored += 1;
+        continue;
+      }
+      const ts = Number(row.ts);
+      if (!Number.isFinite(ts)) {
+        ignored += 1;
+        continue;
+      }
+      // 不在当天窗口内的行不算「忽略」，它属于别的日子。
+      if (localDateString(new Date(ts)) !== dateLocal) continue;
+      const body = textOf(row.frame);
+      if (!body) {
+        ignored += 1;
+        continue;
+      }
+      items.push({ ts, role: "user", text: redactDigits(body).slice(0, 2000) });
+    }
+  }
+  if (readable === 0) return { error: "inbox-unreadable", detail: String(dir) };
+  items.sort((a, b) => a.ts - b.ts);
+  return { items: items.slice(-maxItems), scanned, ignored };
+}
+
+/**
+ * 把 `<DSH_HOME>/media/onebot` 推出来：memoryDir 默认就是 `<DSH_HOME>/memory`。
+ *
+ * 推不出来（memoryDir 被指到别处、或给了显式配置）就用配置值；两者都没有时这个来源
+ * 直接报 `no-inbox-dir`——宁可这一路没有素材，也不去猜别的盘。
+ */
+export function resolveInboxDir({ memoryDir, configured = "" } = {}) {
+  const custom = String(configured ?? "").trim();
+  if (custom) return custom;
+  // 必须走 memoryBase 而不是直接用配置串：默认值就是带 `~` 的字面量，
+  // 不展开的话 join 出来的路径永远落空，旁挂会静默读不到（CodeRabbit #458 F2）。
+  return join(memoryBase(memoryDir), "..", "media", "onebot");
+}