@modusensus/dsh-mneme 0.11.0 → 0.13.0

package/lib/diary/compose.js

@@ -0,0 +1,440 @@
+/**
+ * 日记的合成管线：采集 → 生成 → 落盘 → 记账。
+ *
+ * ## 一条管线，三个入口
+ *
+ * 「跨天自动」「面板手动写一篇」「插件启动补写」必须汇到同一个 `compose`，只在入口处
+ * 分叉。为什么：失败路径（无素材 / 模型挂 / 目录不可写 / 同日已写）各写一遍就是各验一遍，
+ * 三份实现迟早长成三种行为——而那三种行为在用户眼里都是「今天没有日记」。
+ *
+ * ## 为什么正文落文件、摘要落记忆行
+ *
+ * 正文是人要读、要改、要能进 git 的东西，所以是 `YYYY-MM-DD.md`；记忆库里只留一条
+ * `type="document"` 的**指针行**（摘要 + doc_path），复用既有的 `registerDocument`——
+ * 那里已经把路径校验、去重（0.92 相似度）、supersede 记账做完了，一行不用重写。
+ *
+ * 反过来（正文进 SQLite）会把散文塞进注入预算，也会破掉 `src/document.js` 那条
+ * 「全文归 agent，管线零读零写零改」的契约。
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, openSync, fstatSync, readSync, closeSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { describeStreamFailure, resolveRoute, runAuditedLlm, streamText } from "../dream.js";
+import { writeFileAtomic } from "../pipeline-nudge.js";
+import { renderUserSettingsBlock } from "../user-settings.js";
+import { breakFenceMarkers } from "../fence.js";
+import { STR, langOf } from "../lang.js";
+import { collectQqInbox, resolveInboxDir } from "./qq-inbox.js";
+import { collectSessionTranscript } from "./session-provider.js";
+import { DIARY_FILE_RE, diaryAuditPath, diaryDir, diaryFilePath, diaryRoot } from "./dir.js";
+import { localDateString, shouldRollDay } from "./rollover.js";
+
+/** 正文太短当失败：模型偶尔只回一句「今天聊了聊天」，那不是日记，落盘就是噪音。 */
+export const MIN_BODY_CHARS = 80;
+/** 模型最多看多少条消息：一天几百条会把这轮 prompt 顶爆，而日记要的是轮廓不是逐条抄。 */
+export const MAX_MATERIAL_ITEMS = 120;
+
+/**
+ * 账本追加：先看尾 1 字节要不要补换行。
+ *
+ * 与 `src/pipeline-runs.js:364-382` 同一条纪律，但那份是私有函数。少了补换行，
+ * 追加会把上一条与本条粘成一行，一行坏 JSON 让整个账本读不出来——而账本恰好是
+ * 「刚跑完一次」时才动的文件。
+ */
+function appendAudit(file, record) {
+  mkdirSync(dirname(file), { recursive: true });
+  let prefix = "";
+  let fd = null;
+  try {
+    fd = openSync(file, "r");
+    const size = fstatSync(fd).size;
+    if (size > 0) {
+      const tail = Buffer.allocUnsafe(1);
+      readSync(fd, tail, 0, 1, size - 1);
+      if (tail[0] !== 0x0a) prefix = "\n";
+    }
+  } catch {
+    // 文件还不存在 = 空账本，不需要补。
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        // 关不掉也不影响写。
+      }
+    }
+  }
+  appendFileSync(file, prefix + JSON.stringify(record) + "\n", "utf8");
+}
+
+/** 目录里最新一篇的日期。用来在状态文件缺失时自愈（状态丢了不至于重写去年那篇）。 */
+export function latestDiaryDate(dir) {
+  if (!dir) return null;
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const dates = names.filter((n) => DIARY_FILE_RE.test(n)).map((n) => n.slice(0, 10)).sort();
+  return dates.length ? dates[dates.length - 1] : null;
+}
+
+/**
+ * 渲染素材块：一行一条，带时间和说话人。
+ *
+ * 角色标签不是装饰：素材同时来自「她说的话」和「我自己说的话」之后，没有标签模型
+ * 就会把两边混成一个人的独白——而日记的第一人称只属于助手自己。
+ * 没有时间戳（跨日手动写、事件不带时间）时省略时间，不编一个。
+ */
+function renderMaterial(items) {
+  return items
+    .map((it) => {
+      const tag = it.role === "assistant" ? "assistant" : "user";
+      if (!Number.isFinite(it.ts)) return `[${tag}] ${it.text}`;
+      const d = new Date(it.ts);
+      const hh = String(d.getHours()).padStart(2, "0");
+      const mm = String(d.getMinutes()).padStart(2, "0");
+      return `${hh}:${mm} [${tag}] ${it.text}`;
+    })
+    .join("\n");
+}
+
+/** 正文校验。任一不过即视为失败——半截文本落盘之后会被 registerDocument 当成合格文件。 */
+export function validateBody(body) {
+  const text = String(body ?? "").trim();
+  if (text.length < MIN_BODY_CHARS) return "too-short";
+  if (/^\s*```/.test(text) && !/```\s*$/.test(text)) return "unclosed-fence";
+  if (/<<<|>>>/.test(text)) return "marker-leak";
+  return null;
+}
+
+export function createDiaryComposer({ ctx, config, logger, service = null, settings = null, memoryDir, now = () => new Date() }) {
+  const lang = langOf(config);
+  // PROMPTS 不单独 export——它挂在 STR.prompts 上（src/lang.js:536）。走同一条出口，
+  // 免得 lang.js 多一个「既有具名导出又有默认导出」的双份形状。
+  const prompts = STR.prompts.diary[lang] ?? STR.prompts.diary.zh;
+  const str = (key, ...args) => {
+    const row = STR[key];
+    if (!row) return "";
+    const fn = row[lang] ?? row.zh;
+    return typeof fn === "function" ? fn(...args) : fn;
+  };
+  // 整条管线串行：跨天触发与手动按钮可能在同一秒撞上，两次都读到「今天没写过」
+  // 就会各写一篇（后一篇覆盖前一篇，或者拼成两段半截）。串行链的写法照抄
+  // src/summarize.js 的 enqueueDistill。
+  let chain = Promise.resolve();
+  const enqueue = (task) => {
+    const run = chain.then(task, task);
+    chain = run.then(
+      () => undefined,
+      () => undefined
+    );
+    return run;
+  };
+
+  async function readState(root) {
+    const file = join(root, "state.json");
+    try {
+      const raw = JSON.parse(readFileSync(file, "utf8"));
+      return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+    } catch {
+      return {};
+    }
+  }
+
+  function writeState(root, state) {
+    try {
+      writeFileAtomic(join(root, "state.json"), JSON.stringify(state, null, 2) + "\n");
+    } catch (error) {
+      // 状态写不进去只影响「下次判定要不要补」，不该让这一篇已经写好的日记报失败。
+      logger?.warn?.(`[dsh-mneme] diary state write failed: ${String(error)}`);
+    }
+  }
+
+  /**
+   * @param {object} input
+   * @param {"rollover"|"manual"|"startup"} input.trigger
+   * @param {string} input.projectRoot 这条会话属于哪个项目（`header.cwd`）
+   * @param {string|null} [input.chatId] QQ 会话 id，只进状态文件，不进文件名
+   * @param {object|null} [input.session] 当前会话对象：素材主来源
+   * @param {string|null} [input.agentId] 会话身份（`header.agentPreset`）：决定用哪张人格卡
+   */
+  async function compose({ trigger = "rollover", projectRoot, chatId = null, session = null, agentId = null } = {}) {
+    const at = now();
+    const today = localDateString(at);
+    const root = diaryDir({ memoryDir, projectRoot, configured: config?.diaryDir });
+    const auditFile = root ? diaryAuditPath(root) : null;
+    const audit = (record) => {
+      if (!auditFile) return;
+      try {
+        appendAudit(auditFile, { v: 1, ts: at.getTime(), date: today, trigger, ...record });
+      } catch {
+        // 账本写不进去不该改判主流程结果。
+      }
+    };
+    const skip = (reason, extra = {}) => {
+      audit({ status: "skipped", reason, ...extra });
+      return { ok: true, status: "skipped", reason, date: today };
+    };
+
+    if (!root) {
+      // 项目根为空 = 这条会话不属于任何项目。绝不能退回宿主 cwd 写日记，
+      // 那会把私密正文摊到启动目录里（与 /pipeline 拒 project-not-absolute 同语义）。
+      audit({ status: "skipped", reason: "project-unknown" });
+      return { ok: true, status: "skipped", reason: "project-unknown", date: today };
+    }
+
+    const state = await readState(join(root, ".."));
+    const key = root.split(/[\\/]/).filter(Boolean).pop() || "";
+    const entry = state[key] || {};
+    const lastDate = entry.lastDate || latestDiaryDate(root);
+    const roll = shouldRollDay(lastDate, today);
+    const manual = trigger === "manual";
+    const file = diaryFilePath(root, today);
+    const existed = existsSync(file);
+
+    if (!manual && !roll.roll) return skip("already-written", { lastDate });
+    if (!manual && existed && !roll.gap) {
+      // 文件已存在但状态文件说没写过（状态丢过一次）：以文件为准，不重写。
+      state[key] = { ...entry, projectRoot, lastDate: today, chatId: chatId ?? entry.chatId ?? null };
+      writeState(join(root, ".."), state);
+      return skip("already-written", { lastDate: today });
+    }
+
+    // 素材主来源是**这条会话自己的转录**——「拥有人格的 agent 写日记」，写的就是
+    // 它自己这一天经历过的事。QQ 收件箱只是兜底：启动补写时没有会话，只有 inbox。
+    //
+    // 顺序不能反过来：先读 inbox 的话，在 QQ 里聊的那一天会写出一篇「她说了什么」的
+    // 旁观者日记，而作者明明就在对话里。手动触发（按钮）不看日期窗口——用户按下去
+    // 的意思是「把现在这段写下来」，不是「写今天 00:00 到现在的」。
+    const source = { kind: "session", scanned: 0, ignored: 0 };
+    let collected = { items: [] };
+    if (session) {
+      const fromSession = collectSessionTranscript({
+        session,
+        dateLocal: trigger === "manual" ? null : today,
+        maxItems: MAX_MATERIAL_ITEMS
+      });
+      if (!fromSession.error) {
+        collected = fromSession;
+        source.kind = "session";
+      }
+    }
+    if (!collected.items.length) {
+      const inboxDir = resolveInboxDir({ memoryDir, configured: config?.diaryInboxDir });
+      const fromInbox = collectQqInbox({ dir: inboxDir, dateLocal: today, maxItems: MAX_MATERIAL_ITEMS });
+      if (!fromInbox.error && fromInbox.items.length) {
+        collected = fromInbox;
+        source.kind = "qq-inbox";
+      } else if (!session && fromInbox.error) {
+        return skip(fromInbox.error, { inboxDir });
+      }
+    }
+    if (!collected.items.length) {
+      // 当天零条有效消息：不调模型、不落盘。空素材调一次模型是纯浪费，
+      // 而它写出来的东西必然是编的。
+      state[key] = { ...entry, projectRoot, lastDate: today, chatId: chatId ?? entry.chatId ?? null };
+      writeState(join(root, ".."), state);
+      return skip("no-material", { scanned: collected.scanned, ignored: collected.ignored, source: source.kind });
+    }
+
+    const material = renderMaterial(collected.items);
+    let personaText = "";
+    let personaSource = "none";
+    let degraded = false;
+    try {
+      // agentId 必须传：不传就永远落 default 卡，那么「拥有人格的 agent 写日记」在
+      // 多角色宿主里会变成「所有角色共用同一个声音写日记」。宿主没给身份时传 null，
+      // 退回 default —— 那才是无名会话唯一该有的答案（user-settings.js:44-52）。
+      const block = renderUserSettingsBlock({ settings, config, agentId });
+      personaText = String(block?.text ?? "");
+      personaSource = String(block?.source ?? "none");
+    } catch (error) {
+      // 人格渲染失败不该挡住日记，但要如实标注这一篇少了一层信息。
+      degraded = true;
+      logger?.warn?.(`[dsh-mneme] diary persona render failed: ${String(error)}`);
+    }
+
+    const userText = [
+      personaText,
+      "",
+      str("diaryMaterialHeader", collected.items.length, today),
+      breakFenceMarkers(material),
+      "",
+      str("diaryMaterialFooter")
+    ]
+      .filter((s) => s !== null && s !== undefined)
+      .join("\n");
+
+    const log = logger || { info() {}, warn() {} };
+    const route = resolveRoute(ctx, config, log);
+    if (!route) {
+      audit({ status: "failed", reason: "no-route" });
+      return { ok: false, status: "failed", reason: "no-route", date: today };
+    }
+
+    let streamFailure = "";
+    let body;
+    try {
+      const text = await runAuditedLlm(
+        ctx,
+        service ?? {},
+        config,
+        {
+          triggerSource: "diary",
+          operationType: "diary_compose",
+          modelId: `${route.provider}:${route.model}`,
+          relatedMemoryIds: [],
+          streamError: () => streamFailure,
+          auditError: (out) => (String(out ?? "").trim() ? null : "empty diary body")
+        },
+        (reportUsage) =>
+          streamText(
+            ctx,
+            {
+              provider: route.provider,
+              model: route.model,
+              purpose: "diary",
+              messages: [
+                { role: "system", content: [{ type: "text", text: prompts }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
+                { role: "user", content: [{ type: "text", text: userText }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } }
+              ]
+            },
+            reportUsage,
+            (reason) => {
+              streamFailure = describeStreamFailure(reason);
+            }
+          )
+      );
+      if (text === undefined) {
+        audit({ status: "failed", reason: "llm-failed", detail: streamFailure || "stream aborted" });
+        return { ok: false, status: "failed", reason: "llm-failed", date: today };
+      }
+      body = String(text).trim();
+    } catch (error) {
+      audit({ status: "failed", reason: "llm-threw", detail: String(error && error.message ? error.message : error) });
+      return { ok: false, status: "failed", reason: "llm-threw", date: today };
+    }
+
+    const invalid = validateBody(body);
+    if (invalid) {
+      audit({ status: "failed", reason: `invalid-body:${invalid}` });
+      return { ok: false, status: "failed", reason: `invalid-body:${invalid}`, date: today };
+    }
+
+    const gapNote = roll.gap ? str("diaryGapNote", roll.gapDays) : "";
+    // frontmatter 只放「这篇是谁在什么条件下写的」：正文要能独立于记忆库被读懂。
+    // 不写绝对路径（会泄露本机用户名，candidates.js:188-192 同一条纪律），
+    // 只写项目键与身份 id——两者都不是隐私，也都够回答「这声音是谁」。
+    const front = [
+      "---",
+      `date: ${today}`,
+      `project: ${key}`,
+      `source: ${source.kind}`,
+      `persona: ${personaSource}${agentId ? ` (${agentId})` : ""}`,
+      "---"
+    ].join("\n");
+    const header = [front, `# ${today}`, gapNote].filter(Boolean).join("\n\n");
+    let finalText = `${header}\n\n${body}\n`;
+
+    // 同日第二次写（手动按钮最常见）：追加一段「补记」，不覆盖——用户按了两次按钮，
+    // 想要的是多一段，不是把上一段弄丢。整文件仍然一次原子覆盖。
+    let mode = existed ? "append" : "create";
+    if (existed) {
+      let previous = "";
+      try {
+        previous = readFileSync(file, "utf8");
+      } catch {
+        previous = "";
+      }
+      if (previous.trim()) {
+        const stamp = `${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}`;
+        finalText = `${previous.replace(/\s+$/, "")}\n\n## ${str("diaryAddendum", stamp)}\n\n${body}\n`;
+      }
+    }
+
+    try {
+      mkdirSync(root, { recursive: true });
+      writeFileAtomic(file, finalText);
+    } catch (error) {
+      audit({ status: "failed", reason: "workspace-unwritable", detail: String(error && error.message ? error.message : error) });
+      return { ok: false, status: "failed", reason: "workspace-unwritable", date: today };
+    }
+
+    state[key] = { ...entry, projectRoot, lastDate: today, chatId: chatId ?? entry.chatId ?? null, agentId: agentId ?? entry.agentId ?? null };
+    writeState(join(root, ".."), state);
+
+    // 指针行：登记进记忆库，让日记能被检索到。登记不上不算失败——正文已经在盘上、
+    // 已经被用户拥有，那一层不该被一个开关或者一次 dedupe 收走。
+    let pointer = null;
+    if (config?.documentMemoryEnabled === true && typeof service?.registerDocument === "function") {
+      try {
+        const result = await service.registerDocument({
+          path: file,
+          title: str("diaryTitle", today),
+          summary: str("diarySummary", today, body.replace(/\s+/g, " ").slice(0, 160)),
+          tags: ["diary"]
+        });
+        pointer = { action: result?.action ?? "created", id: result?.id ?? null };
+      } catch (error) {
+        degraded = true;
+        pointer = { action: "failed", detail: String(error && error.message ? error.message : error) };
+      }
+    } else {
+      pointer = { action: "skipped", reason: "documentMemoryEnabled-off" };
+    }
+
+    audit({ status: "written", mode, items: collected.items.length, source: source.kind, persona: personaSource, pointer: pointer?.action ?? null });
+    return { ok: true, status: "written", mode, date: today, path: file, pointer, degraded, items: collected.items.length, source: source.kind, persona: personaSource };
+  }
+
+  /**
+   * 状态文件里记过的项目根。
+   *
+   * 启动补写要用它：宿主刚起来时没有任何会话，不知道该补哪个项目——但状态文件里
+   * 记着「上次是哪个项目、哪天写的」，那就是唯一可信的线索。读不到就是空数组。
+   */
+  function knownProjects() {
+    const root = diaryRoot({ memoryDir, configured: config?.diaryDir });
+    let state;
+    try {
+      state = JSON.parse(readFileSync(join(root, "state.json"), "utf8"));
+    } catch {
+      return [];
+    }
+    if (!state || typeof state !== "object" || Array.isArray(state)) return [];
+    const seen = new Set();
+    for (const entry of Object.values(state)) {
+      const p = entry && typeof entry.projectRoot === "string" ? entry.projectRoot.trim() : "";
+      if (p) seen.add(p);
+    }
+    return [...seen];
+  }
+
+  return {
+    compose: (input) => enqueue(() => compose(input)),
+    knownProjects,
+    /** 只读一次账本：面板要回答「今天为什么没有日记」时必须读它，不能靠猜。 */
+    readAudit({ projectRoot, limit = 50 } = {}) {
+      const root = diaryDir({ memoryDir, projectRoot, configured: config?.diaryDir });
+      if (!root) return [];
+      const file = diaryAuditPath(root);
+      let text = "";
+      try {
+        text = readFileSync(file, "utf8");
+      } catch {
+        return [];
+      }
+      const rows = [];
+      for (const line of text.split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          rows.push(JSON.parse(line));
+        } catch {
+          // 坏行跳过（账本纪律：坏行不拖死整份读取）。
+        }
+      }
+      return rows.slice(-limit);
+    }
+  };
+}

package/lib/diary/dir.js

@@ -0,0 +1,59 @@
+/**
+ * 日记的落盘位置。
+ *
+ * 为什么不写进用户绑定的那个项目目录（本次需求的原始想法是 `D:\\QQ对话\\日记\\`）：
+ * 那类目录实测不是 git 仓库、没有 .gitignore，还堆着探针脚本——私密正文摊在那儿，
+ * 误删没有任何回滚面。更要紧的是 mneme 成文的写盘面只有两处（`src/index.js` 的
+ * `memoryDir` 与 `documentDir`），在这里开第三处「往用户任意工作区写」的能力，
+ * 会让「删掉插件的目录就回滚干净」这条性质失效。
+ *
+ * 所以与 candidates / proposals / observations 同构（同一个纪律见
+ * `src/pipeline-observations.js:11-19`）：**项目键分桶、宿在 memoryDir 下、不进仓库**。
+ * 「入库到绑定项目」是另一件事——用户点按钮时导出过去，那是一个主动动作。
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { projectKey } from "../candidates.js";
+
+/** 展开 `~`。candidates.js 里那份是私有的，这里按同一口径抄一份最小实现。 */
+export function expandHome(p) {
+  const s = String(p ?? "");
+  if (s === "~") return homedir();
+  if (s.startsWith("~/") || s.startsWith("~\\")) return join(homedir(), s.slice(2));
+  return s;
+}
+
+/** memoryDir 的基座，与 candidates/proposals/observations 三处同一条回落。 */
+export function memoryBase(memoryDir) {
+  return expandHome(memoryDir && String(memoryDir).trim() ? memoryDir : "~/.dsh/memory");
+}
+
+/**
+ * 日记根：`<memoryDir>/diaries`，或配置里给的目录。
+ *
+ * `diaryDir` 只改**根**，项目键分桶照旧——否则两个项目的日记会混进同一个平面目录，
+ * 而「哪篇属于哪个项目」就只剩 frontmatter 一句话可查。
+ */
+export function diaryRoot({ memoryDir, configured = "" } = {}) {
+  const custom = expandHome(configured && String(configured).trim() ? configured : "");
+  return custom ? custom : join(memoryBase(memoryDir), "diaries");
+}
+
+/** `<root>/<项目键>/`。项目根拿不到时返回 null（调用方必须据此拒绝写，不许退成全局）。 */
+export function diaryDir({ memoryDir, projectRoot, configured = "" } = {}) {
+  const key = projectKey(projectRoot);
+  if (!key) return null;
+  return join(diaryRoot({ memoryDir, configured }), key);
+}
+
+/** 只认 `YYYY-MM-DD.md`：同目录还住着 runs.jsonl，扫最新日期时不能把它算进去。 */
+export const DIARY_FILE_RE = /^\d{4}-\d{2}-\d{2}\.md$/;
+
+export function diaryFilePath(dir, dateLocal) {
+  return join(dir, `${dateLocal}.md`);
+}
+
+/** 审计账本：每条 skip / failed / written 一行，回答「今天为什么没有日记」。 */
+export function diaryAuditPath(dir) {
+  return join(dir, "runs.jsonl");
+}

package/lib/diary/export.js

@@ -0,0 +1,97 @@
+/**
+ * 日记的读侧与「入库」。
+ *
+ * 「入库」是用户点按钮时**主动**把某一篇复制到绑定项目里——不是日记默认就写在那儿。
+ * 这两件事分开的理由写在 `dir.js`：默认写进用户工作区会让「删掉插件目录就回滚干净」
+ * 这条性质失效，而那正是 mneme 现有写盘面的成文契约。
+ *
+ * 复制而不是移动：memoryDir 那一份是主副本（还挂着指针行），项目里那份是给人看的。
+ * 移走会让指针行指向一个已经被搬空的路径，`registerDocument` 下次校验就抛。
+ */
+import { copyFileSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { DIARY_FILE_RE, diaryFilePath } from "./dir.js";
+
+/** 入库目标：`<项目>/diary/`。与项目里其它人类可读产物同层，不埋进点目录。 */
+export const EXPORT_SUBDIR = "diary";
+
+/**
+ * 列出目录里已有的日记，新的在前。
+ *
+ * 读不到目录返回 `[]`（= 还没写过），不抛——面板的空态与「坏了」必须能分开，
+ * 而这里「读不到」的绝大多数情况就是「还没写过第一篇」。
+ */
+export function listDiaries(dir) {
+  if (!dir) return [];
+  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));
+}
+
+/** 读一篇正文。读不到返回 null（面板据此显示「还没有这一篇」而不是一个空框）。 */
+export function readDiary(dir, date) {
+  if (!dir || !/^\d{4}-\d{2}-\d{2}$/.test(String(date ?? ""))) return null;
+  try {
+    return readFileSync(diaryFilePath(dir, date), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 把一篇复制进绑定项目。
+ *
+ * `overwrite:false` 时目标已存在就拒绝——那是**用户项目里**的文件，可能已经被他改过，
+ * 机器无声覆盖比不做更糟。要覆盖必须显式传 `overwrite:true`（面板上是一次确认）。
+ */
+export function exportDiary({ sourceDir, projectRoot, date, overwrite = false } = {}) {
+  if (!sourceDir) return { ok: false, error: "no-source" };
+  if (!projectRoot) return { ok: false, error: "project-unknown" };
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date ?? ""))) return { ok: false, error: "bad-date" };
+  const from = diaryFilePath(sourceDir, date);
+  let st;
+  try {
+    st = statSync(from);
+  } catch {
+    return { ok: false, error: "no-diary", date };
+  }
+  if (!st.isFile() || st.size <= 0) return { ok: false, error: "no-diary", date };
+  const toDir = join(projectRoot, EXPORT_SUBDIR);
+  const to = join(toDir, `${date}.md`);
+  try {
+    mkdirSync(toDir, { recursive: true });
+  } catch (error) {
+    return { ok: false, error: "target-unwritable", detail: String(error && error.message ? error.message : error) };
+  }
+  if (!overwrite) {
+    try {
+      statSync(to);
+      return { ok: false, error: "target-exists", path: to };
+    } catch {
+      // 目标不存在才是可以写的路径。
+    }
+  }
+  try {
+    copyFileSync(from, to);
+  } catch (error) {
+    return { ok: false, error: "copy-failed", detail: String(error && error.message ? error.message : error) };
+  }
+  return { ok: true, date, path: to, bytes: st.size };
+}

package/lib/diary/index.js

@@ -0,0 +1,26 @@
+/**
+ * 日记本（QQ 机器人写日记）。
+ *
+ * 需求原文要的是「让机器人每天写一篇日记，侧栏能把日记入库到绑定的项目里」。
+ * 拆开是三件事，落在三处：
+ *
+ * 1. **写什么** —— `compose.js`：素材 → 一段正文 → 原子落盘 → 指针行。
+ * 2. **什么时候写** —— `auto.js`：本机没有日历调度原语，所以是「跨天惰性判定 +
+ *    启动补写」，不是 cron。判定本身在 `rollover.js`，是纯函数。
+ * 3. **素材从哪来** —— `qq-inbox.js`：只读 QQ 收件箱。这一层是 provider 形状，
+ *    以后接别的来源只需要再写一个同签名模块，compose 不认识 QQ。
+ *
+ * 正文宿在 `<memoryDir>/diaries/<项目键>/YYYY-MM-DD.md`（见 `dir.js` 里为什么不写
+ * 进用户工作区）；记忆库里只有一条 `type="document"` 指针行，复用既有铸造口。
+ */
+export { createDiaryComposer, validateBody, latestDiaryDate, MIN_BODY_CHARS, MAX_MATERIAL_ITEMS } from "./compose.js";
+// 「什么时候写」的纯函数与「素材从哪来」的 provider 形状，都在上面两个文件里。
+export { createDiaryAutoRun, DIARY_MIN_INTERVAL_MS } from "./auto.js";
+export { collectQqInbox, inboxFiles, redactDigits, resolveInboxDir, INBOX_FILE_RE } from "./qq-inbox.js";
+export { collectSessionTranscript, sessionAgentId, MAX_ITEM_CHARS } from "./session-provider.js";
+export { diaryDir, diaryRoot, diaryFilePath, diaryAuditPath, memoryBase, expandHome, DIARY_FILE_RE } from "./dir.js";
+export { localDateString, shouldRollDay, dayGap, MAX_CATCH_UP_DAYS } from "./rollover.js";
+export { listDiaries, readDiary, exportDiary, EXPORT_SUBDIR } from "./export.js";
+// 左侧「ta 的日记」面板读的是**跨桶**清单（它拿不到当前会话的项目），
+// 与上面按 projectRoot 定位单个桶的 dir.js 是两件事。
+export { listDiaryLibrary, readLibraryEntry, isBucketName } from "./library.js";