@modusensus/dsh-mneme 0.8.6 → 0.8.8

package/src/index.js

@@ -1,20 +1,27 @@
 import { createStore } from "./store.js";
 import { createMirror, TYPE_FILE } from "./mirror.js";
+import { createDocumentIndex } from "./document-index.js";
+import { resolveDocumentDir } from "./document.js";
 import { createService } from "./service.js";
+// #254 写入准入（第一阶段只计量，不拦截）：见 src/write-admission.js 的文件头。
+import { createWriteAdmission } from "./write-admission.js";
 import { createTools } from "./tools.js";
 import { createInjector } from "./inject.js";
+import { createContinuityRescue } from "./continuity.js";
 import { createSummarizer } from "./summarize.js";
 import { createDreamScheduler } from "./dream.js";
 import { createSleepScheduler, runSleep } from "./dream/sleep.js";
 import { createApi } from "./api.js";
 import { createStandaloneApi } from "./api-standalone.js";
+// #275 存储生命周期第一批：无损回收（手动入口，不挂启动路径）。
+import { createMaintenance } from "./maintenance.js";
 import { createSettings } from "./settings.js";
 import { createCommandManager } from "./commands.js";
 import { createEmbedder } from "./embedding.js";
 import { createEmbedderByProvider } from "./local-embedder.js";
 import { LocalReranker } from "./reranker.js";
 import { createVectorIndex } from "./vector-index.js";
-import { Config, applyLightModePreset } from "./config.js";
+import { Config, applyLightModePreset, injectChildEnabled } from "./config.js";
 import { langOf } from "./lang.js";
 import { extractEntities } from "./entities/extractor.js";
 import { mkdirSync } from "node:fs";
@@ -193,15 +200,6 @@ export const apply = (ctx, config) => {
   try {
     store.deleteOldFailures(new Date(Date.now() - 90 * 86400000).toISOString());
   } catch { /* non-fatal */ }
-  // Bug8: enforce llm_audit_logs retention on boot (config.llmAudit.retentionDays,
-  // default 90). Best-effort like the failure prune — the audit trail is
-  // bookkeeping and a failed purge must never block plugin boot.
-  try {
-    if (rawCfg.llmAudit?.enabled !== false) {
-      const retentionMs = Number.isInteger(rawCfg.llmAudit?.retentionDays) ? rawCfg.llmAudit.retentionDays : 90;
-      store.deleteOldLlmAudits(new Date(Date.now() - retentionMs * 86400000).toISOString());
-    }
-  } catch { /* non-fatal */ }
 
   // User-configurable settings (profile, rules, panel mode, standalone API
   // token) share the same SQLite file in dedicated tables, isolated from
@@ -240,10 +238,46 @@ export const apply = (ctx, config) => {
     cfg[objKey] = { ...(cfg[objKey] ?? {}), ...sub };
   }
 
+  // Bug8 的启动期清理放在装配之后：面板把 llmAudit.* 写进 kv、经 nestedFlags 合进
+  // cfg，而写入侧（dream / summarize / 写入准入）读的都是装配后的 cfg——清理若读
+  // rawCfg，面板改了保留期它不认，更糟的是「开不开审计」与写入侧可能取到不同的值
+  // （raw 说关 → 不清理，cfg 说开 → 照写，审计表就无保留期地长）。保留期默认 90 天、
+  // 失败只 warn，与失败表清理同款：账本清理绝不许挡住插件启动。
+  try {
+    if (cfg.llmAudit?.enabled !== false) {
+      const retentionMs = Number.isInteger(cfg.llmAudit?.retentionDays) ? cfg.llmAudit.retentionDays : 90;
+      store.deleteOldLlmAudits(new Date(Date.now() - retentionMs * 86400000).toISOString());
+    }
+  } catch { /* non-fatal */ }
+
   // 记忆语言（memory.language）：本实例逐层传入 inject / summarize / dream /
   // sleep / mirror，多实例（如 agent preset 内挂载）互不影响。
   const mirror = createMirror(memoryDir, langOf(cfg));
-  const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
+
+  // #296 第二批：managed 文档目录。解析与 memoryDir 同一套（空 = 跟随 memoryDir 的
+  // <memoryDir>/documents/，~ 展开，相对路径落在 memoryDir 下）。索引对象总是建：
+  // 闸关时它只承担「清掉陈旧 index.md」这一件事，与 documents.md 在闸关时被镜像删
+  // 掉同一口径。建目录与写索引失败都只 warn，不阻断插件加载（它们是机器产物）。
+  const documentDir = resolveDocumentDir(memoryDir, cfg.documentDir);
+  const documentIndex = createDocumentIndex(documentDir, langOf(cfg));
+  if (cfg.documentMemoryEnabled === true) {
+    const ensured = documentIndex.ensure();
+    if (!ensured.ok) {
+      ctx.logger?.warn?.(`[dsh-mneme] documentDir is not writable: ${documentDir}: ${ensured.error}`);
+    }
+    // 启动即渲染一次：索引不该等到第一次业务写才存在（删掉它之后重启也能自愈）。
+    const synced = documentIndex.sync(store.list({ type: "document", limit: null }));
+    if (!synced.ok) ctx.logger?.warn?.(`[dsh-mneme] document index sync failed: ${synced.error}`);
+  } else {
+    documentIndex.remove();
+  }
+
+  // 写入准入实例：本批次只做计量（决策恒放行、写审计行），所以不需要新开关——它
+  // 不改变任何写入行为，也不新增拦截分支；既有的 llmAudit.enabled 关掉时它同样
+  // 不写（那个开关连审计行的启动期清理一起关掉）。第二阶段把拦截打开时才按仓库
+  // 惯例引入 opt-in 默认关的配置键，届时只改这一个实例的构造与 service 的调用点。
+  const writeAdmission = createWriteAdmission({ store, config: cfg, logger: ctx.logger });
+  const service = createService({ store, mirror, config: cfg, logger: ctx.logger, documentIndex, writeAdmission });
 
   // F-NEW-03: if the mirror sync failed last run (persisted dirty state), retry
   // a safe re-render at boot so a stale mirror converges without needing a
@@ -457,9 +491,37 @@ export const apply = (ctx, config) => {
       thresholdChars: cfg.dreamThresholdChars,
       delayMs: cfg.dreamDelayMs,
       minIntervalMs: (cfg.dreamMinIntervalMinutes ?? 0) * 60000,
+      // Issue #292：连续失败指数退避（opt-in，默认关 = 行为不变）。
+      failureBackoff: cfg.autoDreamFailureBackoff === true,
       logger: ctx.logger,
       semantic: { embedder, vectorIndex },
       lastRunAtSeed: store.lastDreamRunAt("auto"),
+      // Issue #239（第 4 项）镜像到巩固：高峰期不做梦，顺延到最近的高峰结束时刻。
+      peakHours: cfg.dreamPeakHours ?? "",
+      peakMaxDeferMinutes: cfg.dreamPeakMaxDeferMinutes ?? 120,
+      // 跳过时的审计行在这里落地（调度器只拿到 service，拿不到 config 的
+      // llmAudit 开关与巩固模型路由）。口径与 runAuditedLlm 一致：审计关掉就
+      // 不写；写失败只 warn，绝不反噬调度（CONTRIBUTING 的 fail-safe 硬约定）。
+      auditPeakSkip: ({ count, chars }) => {
+        if (cfg?.llmAudit?.enabled === false || typeof service?.saveLlmAudit !== "function") return;
+        const modelId = cfg.dreamProvider && cfg.dreamModel ? `${cfg.dreamProvider}:${cfg.dreamModel}` : "";
+        service.saveLlmAudit({
+          timestamp: new Date().toISOString(),
+          trigger_source: "autoDream",
+          operation_type: "dream_consolidate",
+          model_id: modelId,
+          input_tokens: 0,
+          output_tokens: 0,
+          total_tokens: 0,
+          cost_usd: 0,
+          duration_ms: 0,
+          status: "skipped",
+          error_message: "peak-hours",
+          related_memory_ids: [],
+          // 观测用：跳过时窗口里积了多少（阈值继续累积，不是丢弃）。
+          metadata: JSON.stringify({ count, chars })
+        });
+      },
       onRun: () => (dream ? dream.runDream(ctx, service, cfg) : Promise.resolve({ ok: true, skipped: true }))
     });
     service.setDreamHook(() => dream.maybeSchedule(service));
@@ -526,6 +588,13 @@ export const apply = (ctx, config) => {
     if (cfg.autoInject) disposers.push(createInjector(promptCtx, service, settings, cfg));
   });
 
+  // #249 N3：压缩边缘双落点。触发靠宿主自己落的压缩事件（订阅 + pre-step 追加），
+  // 不需要 systemPrompt / tools 的任何能力，所以不塞进上面的 inject 回调；父／子
+  // 闸门在挂载点判一次，与 inject.js 共用同一个 injectChildEnabled 判据。
+  if (cfg.autoInject && injectChildEnabled(cfg, "continuityRescueEnabled")) {
+    disposers.push(createContinuityRescue(ctx, store));
+  }
+
   ctx.inject(["tools"], (toolsCtx) => {
     disposers.push(createTools(toolsCtx, service, cfg, embedder));
   });
@@ -549,13 +618,19 @@ export const apply = (ctx, config) => {
     disposers.push(api.dispose);
   }
 
+  // #275 存储生命周期第一批：无损回收的手动入口。刻意不挂启动路径、不接定时器——
+  // 这一步是不可逆的内容丢弃，只由人显式触发（`dsh-mneme reclaim`）。实例在这里建、
+  // 在 standalone API 上暴露，是为了让 CLI 能在插件进程内跑（VACUUM 要排他锁，跟宿主
+  // 抢锁的那条路走不通）。
+  const maintenance = createMaintenance({ store, config: cfg, logger: ctx.logger });
+
   // Standalone external API (v0.7.12): plain node:http server for ecosystem
   // integrations outside the DSH host. Persisted external_api settings win
   // over the bundle config (enabled/port); the Bearer token lives in the same
   // kv and is auto-generated on first boot by createStandaloneApi. Binding a
   // non-loopback host is the operator's documented responsibility.
   if ((settings.getExternalApi?.()?.enabled ?? cfg.externalApiEnabled) === true) {
-    const standalone = createStandaloneApi({ service, store, config: cfg, logger: ctx.logger, settings });
+    const standalone = createStandaloneApi({ service, store, config: cfg, logger: ctx.logger, settings, maintenance });
     disposers.push(() => standalone.server.close());
     standalone.ready.catch((error) => {
       ctx.logger?.warn?.(`[dsh-mneme] standalone API failed to start: ${String(error)}`);

package/src/inject.js

@@ -3,6 +3,7 @@ import { createHotMemory } from "./hot-memory.js";
 import { STR, langOf } from "./lang.js";
 import { MEMORY_GUIDE_SECTION } from "./guide.js";
 import { adaptiveInjectBudget } from "./search/adaptive.js";
+import { injectChildEnabled } from "./config.js";
 
 // Issue #179：注入预览的数据底座。systemPrompt 渲染是同步回调，面板只能事后
 // 拉取，所以在这里旁路缓存「最近一帧组装」——快照就是本次渲染用过的同一份
@@ -283,12 +284,15 @@ export function createInjector(ctx, service, settings, config) {
     return escapePromptVars(lines.join("\n"));
   }
 
-  // #249 第一批：能力说明的系统提示段。order 150 = 插件指引段的既有惯例
+  // #249 能力说明的系统提示段。order 150 = 插件指引段的既有惯例
   // （ACP 的 ACP_SYSTEM_PROMPT 与 mnemon 的 routing 段都在 150）。文本是常量、
   // 同会话内不随轮次变化，故不影响其后的前缀缓存，也不逐轮复读。宿主若不提供
   // section seam 就静默跳过——#249 §3 的口径是「只用现成 seam，拿不到位的语义
   // 降级处理」：能力说明仍落在工具描述上，不算失败。
-  const guideSection = config.injectGuidanceEnabled === true && typeof ctx.systemPrompt?.section === "function"
+  // 走父／子闸门（#249 第二批）：注入器本身只在 `autoInject` 开时挂载，这里是
+  // 第二道、也是同一个判据的显式落点——两处消费点共用 injectChildEnabled，
+  // 不在各自的地方重写「父关则子不生效」。
+  const guideSection = injectChildEnabled(config, "injectGuidanceEnabled") && typeof ctx.systemPrompt?.section === "function"
     ? ctx.systemPrompt.section({ name: "memory-guide", order: 150, text: MEMORY_GUIDE_SECTION })
     : null;
 

package/src/lang.js

@@ -196,12 +196,23 @@ export const STR = {
 
   // --- mirror.js：镜像文件标签（渲染随实例语言；解析两种语言都认） ----------------
   mirrorLabel: {
-    zh: { type: "类型", importance: "重要性", tags: "标签", updated: "更新时间", source: "来源" },
-    en: { type: "Type", importance: "Importance", tags: "Tags", updated: "Updated", source: "Source" }
+    zh: { type: "类型", importance: "重要性", tags: "标签", updated: "更新时间", source: "来源", scope: "作用域", sensitivity: "敏感度" },
+    en: { type: "Type", importance: "Importance", tags: "Tags", updated: "Updated", source: "Source", scope: "Scope", sensitivity: "Sensitivity" }
   },
   mirrorHeader: {
-    zh: (name) => `# ${name} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`,
-    en: (name) => `# ${name} — dsh-mneme mirror\n\n<!-- Manual edits to this file are merged back into the memory store (human edits win). -->\n\n`
+    zh: (name) => `# ${name} — dsh-mneme 镜像\n\n<!-- 条目标题与正文可编辑，会被合并回记忆库（人工优先）；文件头与条目元数据行由机器维护，改动会在下次同步时被覆盖。 -->\n\n`,
+    en: (name) => `# ${name} — dsh-mneme mirror\n\n<!-- Entry titles and bodies are editable and merged back into the memory store (human edits win); the file header and entry metadata lines are machine-owned and get overwritten on the next sync. -->\n\n`
+  },
+  // document 的镜像只有指针行（#296 第二批）：没有可编辑的正文，手工改动一律被
+  // 下次同步覆盖——所以不能复用上面那句「可编辑、会被合并回记忆库」。
+  mirrorReadonlyHeader: {
+    zh: (name) => `# ${name} — dsh-mneme 只读视图\n\n<!-- 只含指针行：id + 标题 + 摘要首句 + 文件路径，不含正文。正文在路径指向的文件里，批注请写进记忆库；本文件由机器维护，手工改动会在下次同步时被覆盖。 -->\n\n`,
+    en: (name) => `# ${name} — dsh-mneme read-only view\n\n<!-- Pointer rows only: id + title + first sentence of the summary + file path, never the full text. The document itself lives at that path, annotations belong in the memory store, and this file is machine-owned: hand edits are overwritten on the next sync. -->\n\n`
+  },
+  // documentDir 的 index.md（#296 第二批）：整文件机器所有、可从库重建。
+  documentIndexHeader: {
+    zh: () => "# document 索引 — dsh-mneme\n\n<!-- 整文件机器所有，可从记忆库随时重建（所以这里不写生成时间）；要批注请写进记忆库（memory_save）。managed = 文件在 documentDir 内。 -->\n\n",
+    en: () => "# document index — dsh-mneme\n\n<!-- Machine-owned as a whole and rebuildable from the memory store at any time (which is why it carries no generation timestamp). Annotations belong in the memory store (memory_save). managed = the file sits inside documentDir. -->\n\n"
   },
 
   prompts: PROMPTS

package/src/maintenance.js

@@ -0,0 +1,142 @@
+// #275 存储生命周期第一批：无损回收的维护入口。
+//
+// 为什么是「手动入口 + dry-run + receipt」而不是后台任务：这两步都是不可逆的内容
+// 丢弃（历史 run 的输入快照置空、归档行的向量置空），该由人在看得见数字的时候按下
+// （维护者 2026-09-23 拍板：不挂启动自动跑，VACUUM 约 0.8s 说明它就该是个随手跑的
+// 东西）。所以模块里没有任何定时器，挂点只有两个：standalone 数据面的
+// `POST /maintenance/reclaim` 与它上面的 `dsh-mneme reclaim` 子命令。
+//
+// 两项都零价值判断、零条数变化：
+//   A `dream_runs.input` 置空。这一列的含义按 run_type 分叉：auto / sleep 的 run 存的
+//     是当时的记忆库快照，可由记忆库重建；**organize 的 run 存的是 apply 的重放载荷**，
+//     置空会让那次 apply 静默空转并把报告锁死，所以 organize 行不在可清范围内（谓词
+//     在 store.dreamRunInputStats / clearDreamRunInputs 里）。run 的骨架、LLM 决策原文
+//     与 receipt 一律保留，行永不删（拍板 3：裁列同意、删行不同意）。
+//   B 归档行向量置空：检索 SQL 恒带 `archived = 0`，这部分向量按定义不可达。它不是
+//     单程票——取消归档时 service 会重新排队嵌入（archiveMemory 的还原分支）。
+//
+// 报告口径（拍板 2）：收益按 VACUUM 前后体积量，不按列字节估——实际释放来自溢出页与
+// 索引页回收，列文本大小只是上界，所以两个数分开报，不混成一个「省了多少」。
+//
+// 与 #254 的分界（拍板 4）：本入口止体积、不止重复。归档区里同主题堆积是出口问题，
+// 归 #254 的写入准入与后续的整理动作面，这里一条记忆都不碰。
+export const RECLAIM_TRIGGER_SOURCE = "maintenance";
+export const RECLAIM_OPERATION_TYPE = "storage_reclaim";
+// 输入快照的默认保留窗口：7 天内仍可能被离线回放（近期 run 的决策上下文），更早的
+// 重建成本低于留存成本。窗口由调用方显式给，不做成配置键——配置键意味着有个周期性
+// 消费者，而本批次刻意不接周期动作。
+export const DEFAULT_INPUT_RETENTION_DAYS = 7;
+
+/**
+ * 无损回收（#275 第一批）。返回一个函数：同一条代码路径跑 dry-run 与执行，dry-run
+ * 只是不落 UPDATE/VACUUM，所以「报出来的数字」与「执行时的数字」出自同一处统计。
+ *
+ * @param {object} deps
+ * @param {object} deps.store 存储层（dreamRunInputStats / clearDreamRunInputs /
+ *   archivedEmbeddingStats / clearArchivedEmbeddings / storageStats / vacuum / saveLlmAudit）
+ * @param {object} [deps.config] 已解析配置（读 llmAudit.enabled：关掉 audit 时不落 receipt）
+ * @param {object} [deps.logger]
+ * @param {() => number} [deps.now] 时钟注入（测试用）
+ */
+export function createMaintenance({ store, config, logger, now = Date.now } = {}) {
+  const warn = (msg) => {
+    try {
+      logger?.warn?.(msg);
+    } catch { /* 日志故障不能影响回收本身 */ }
+  };
+
+  /** receipt 落到 llm_audit_logs（既有 bookkeeping 表，不触发写钩子）。 */
+  function writeReceipt(report) {
+    if (config?.llmAudit?.enabled === false) return null;
+    try {
+      const row = store.saveLlmAudit({
+        trigger_source: RECLAIM_TRIGGER_SOURCE,
+        operation_type: RECLAIM_OPERATION_TYPE,
+        // 不是模型调用，但该列 NOT NULL——用显式占位串，免得混进按路由分组的花费统计。
+        model_id: "-",
+        status: "success",
+        metadata: {
+          older_than_days: report.olderThanDays,
+          cleared: report.cleared,
+          size_before: report.size.before_bytes,
+          size_after: report.size.after_bytes,
+          vacuum: report.vacuum.ran,
+          duration_ms: report.duration_ms
+        }
+      });
+      return row?.id ?? null;
+    } catch (e) {
+      // 回执失败只 warn：清理已经发生了，不能因为记不上账就当作没发生（也不能反噬）。
+      warn(`[dsh-mneme] storage reclaim receipt failed: ${String(e)}`);
+      return null;
+    }
+  }
+
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.olderThanDays] 输入快照的保留窗口（天）；0 = 清掉全部快照
+   * @param {boolean} [opts.vacuum] 是否在清理后 VACUUM（默认否：它要排他锁，由人决定）
+   * @param {boolean} [opts.dryRun] 默认 true——只报数字，不改一个字节
+   * @returns {object} 报告（dry-run 与执行同形状，执行时多 receipt 字段）
+   */
+  function reclaim({ olderThanDays = DEFAULT_INPUT_RETENTION_DAYS, vacuum = false, dryRun = true } = {}) {
+    const days = Number.isFinite(olderThanDays) && olderThanDays >= 0 ? olderThanDays : DEFAULT_INPUT_RETENTION_DAYS;
+    const cutoff = new Date(now() - days * 86400000).toISOString();
+    const started = now();
+    const before = store.storageStats();
+    const inputs = store.dreamRunInputStats(cutoff);
+    const embeddings = store.archivedEmbeddingStats();
+    const report = {
+      dryRun,
+      olderThanDays: days,
+      cutoff,
+      // planned = 这次会动几行；cleared = 实际动了几行（dry-run 恒 0）
+      planned: { dream_run_inputs: inputs.runs, archived_embeddings: embeddings.rows },
+      // 列文本大小：上界，不是回收量（真实释放看下面的 size 差值）
+      column_bytes: { dream_run_inputs: inputs.bytes, archived_embeddings: embeddings.bytes },
+      cleared: { dream_run_inputs: 0, archived_embeddings: 0 },
+      size: {
+        before_bytes: before.fileBytes,
+        after_bytes: before.fileBytes,
+        // 空闲页就是「现在 VACUUM 能立刻收回来的那部分」，带上它 dry-run 才有个能
+        // 参照的量（真实数字仍然只有做完才知道）
+        freelist_pages: before.freelistCount,
+        freelist_bytes: before.freelistCount * before.pageSize,
+        page_count: before.pageCount
+      },
+      vacuum: { requested: vacuum === true, ran: false, duration_ms: null, error: null },
+      receipt: null,
+      duration_ms: 0
+    };
+    if (dryRun) {
+      report.duration_ms = now() - started;
+      return report;
+    }
+    report.cleared.dream_run_inputs = store.clearDreamRunInputs(cutoff);
+    report.cleared.archived_embeddings = store.clearArchivedEmbeddings();
+    if (report.vacuum.requested) {
+      // VACUUM 失败不能把前面的清理一起吞掉：两个 UPDATE 已经各自提交了，此时抛出去
+      // 就是「数据已经不可逆地清了，但没有任何回执」。所以失败记进报告、回执照写，
+      // 让调用方看到「清了 N 行，VACUUM 没跑成」——锁被别的进程占着（SQLITE_BUSY）是
+      // 最常见的成因，重跑一次 --apply --vacuum 即可（清理是幂等的）。
+      try {
+        const result = store.vacuum();
+        report.vacuum.ran = true;
+        report.vacuum.duration_ms = result.duration_ms;
+      } catch (e) {
+        report.vacuum.error = String(e);
+        warn(`[dsh-mneme] storage reclaim vacuum failed: ${String(e)}`);
+      }
+    }
+    const after = store.storageStats();
+    report.size.after_bytes = after.fileBytes;
+    report.size.freelist_pages = after.freelistCount;
+    report.size.freelist_bytes = after.freelistCount * after.pageSize;
+    report.size.page_count = after.pageCount;
+    report.duration_ms = now() - started;
+    report.receipt = writeReceipt(report);
+    return report;
+  }
+
+  return { reclaim };
+}

package/src/mirror.js

@@ -2,17 +2,37 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "node
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { STR, langOf } from "./lang.js";
+import { PACKAGE_VERSION } from "./version-check.js";
 
 export const TYPE_FILE = {
   preference: "preferences.md",
   project: "projects.md",
   decision: "decisions.md",
   history: "history.md",
-  summary: "summary.md"
+  summary: "summary.md",
+  pitfall: "pitfalls.md",
+  constraint: "constraints.md",
+  rejected_solution: "rejected-solutions.md",
+  pattern: "patterns.md",
+  document: "documents.md"
 };
 
+// 不落镜像的 type。现在是空集：document 由 #296 第二批收进来——第一版排除它的
+// 理由是「镜像块渲染的字段里没有 doc_path，落一个 documents.md 会得到看着完整、
+// 其实找不到文件的视图」，doc_path 进指针行以后这条理由不再成立。这个集合由
+// test/mirror-types.test.js 钉死（TYPES \ TYPE_FILE 必须恰好等于本集合）：将来
+// 新增 type 时必须显式决定它落不落镜像，静默漏掉才是 #278 要修的那种盲区。
+export const MIRROR_EXCLUDED_TYPES = new Set([]);
+
+// 只读视图（#296）：document 的镜像只有指针行（id + 标题 + 摘要首句 + doc_path），
+// 没有可编辑的正文，所以它不参与 readHumanEdits 的人改合并，手工改动一律被下次
+// 同步覆盖；导出/导入也不带它（那两个是 round-trip 通道，见 api.js）。
+export const MIRROR_READONLY_TYPES = new Set(["document"]);
+
 const ESCAPE = /([\\`*_[\]{}()#+.!|>~-])/g;
 const UNESCAPE = new RegExp("\\\\" + ESCAPE.source, "g");
+// 只读视图里摘要首句的字符上限（#296）：够定位就行，长摘要不该把一行撑成一段。
+const POINTER_MAX = 120;
 
 function esc(text) {
   return String(text).replace(ESCAPE, "\\$1");
@@ -22,6 +42,36 @@ function unescape(text) {
   return String(text).replace(UNESCAPE, "$1");
 }
 
+// 元数据标签的唯一来源是 STR.mirrorLabel（lang.js）：渲染按实例语言取，解析两套
+// 都认。下面的正则从那张表现算——旧实现把手写正则与 lang.js 的两处文案分开维护，
+// 加一个字段要改三处，漏改一处那一行就会随 /import 写进 entry 的 content。
+const META_LABELS = [];
+for (const language of Object.keys(STR.mirrorLabel)) META_LABELS.push(...Object.values(STR.mirrorLabel[language]));
+
+function reEsc(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// 元数据行的值必须单行：值里带换行会多出一行，轻则破坏「整段元数据行」的解析契约，
+// 重则伪造出一个条目头（sensitivity 是调用方传入的任意字符串，属信任边界）。
+function oneLine(text) {
+  return String(text).replace(/\s+/g, " ").trim();
+}
+
+// 结构头锚：ID 行紧跟类型行才算条目头（正文里机器格式的 ID 行不会切开块）。
+const ANCHOR_RE = new RegExp(
+  "^- \\*\\*ID\\*\\*: `([^`]+)`\\n- \\*\\*(?:" +
+    [STR.mirrorLabel.zh.type, STR.mirrorLabel.en.type].map(reEsc).join("|") +
+    ")\\*\\*:", "gm"
+);
+// 渲染出的整段元数据行（加字段只需改 lang.js 的 mirrorLabel）。
+const META_RUN_RE = new RegExp(`^(- \\*\\*(?:${META_LABELS.map(reEsc).join("|")})\\*\\*:.*\\n?)+`);
+// 三方合并用的版本令牌（service.syncMirror 比对并发写）。
+const UPDATED_RE = new RegExp(
+  "- \\*\\*(?:" + [STR.mirrorLabel.zh.updated, STR.mirrorLabel.en.updated].map(reEsc).join("|") +
+    ")\\*\\*: ([^\\n]+)"
+);
+
 function renderMemory(m, language = "zh") {
   // last-rendered digest baseline: sha256(title \x00 content). service.js
   // compares the file hash against this to tell "untouched by a human" (machine
@@ -40,6 +90,12 @@ function renderMemory(m, language = "zh") {
   lines.push(`- **${ML.tags}**: ${m.tags.map((t) => `\`${esc(t)}\``).join(" ")}`);
   lines.push(`- **${ML.updated}**: ${m.updated_at}`);
   if (m.source) lines.push(`- **${ML.source}**: ${esc(m.source)}`);
+  // scope / sensitivity 是只读展示字段（#278：sensitivity 的过滤语义另有归属，见
+  // 那条讨论；这里只把值摆出来）。只在真有值时渲染——本机 2843 条里只有 37 条带
+  // scope 标签，无条件渲染会给每条目多添两行空字段。
+  const scopeText = [m.agent_scope, m.workspace_scope].filter(Boolean).map(oneLine).join(" / ");
+  if (scopeText) lines.push(`- **${ML.scope}**: ${scopeText}`);
+  if (m.sensitivity) lines.push(`- **${ML.sensitivity}**: ${oneLine(m.sensitivity)}`);
   lines.push("");
   lines.push(`<!-- mirror-digest: ${digest} -->`);
   lines.push(m.content);
@@ -49,22 +105,76 @@ function renderMemory(m, language = "zh") {
   return lines.join("\n");
 }
 
+/**
+ * 文件头 frontmatter（#278 第一批）。按 type 分文件时一个文件装 N 条，所以
+ * frontmatter 只能落在文件级；条目级元数据仍是块内的 `- **字段**:` 行（见
+ * renderMemory）。
+ *
+ * `covered` / `coverage` 是覆盖范围的自述，必须与这份文本**实际包含的行集**一致：
+ * 磁盘镜像写活跃集（active-only），/export 的文档写全表（all）。说一套写一套比
+ * 没有这个字段更糟——外部工具会照着它聚合条数与标签。
+ *
+ * 键名对齐 OKF v0.2：`type` 是 §4.1 唯一必填键，`tags` 是 §4.1 的推荐键，
+ * `generated.by` / `generated.at` 是 §5.2 的 trust 族。`generated.by` 按 §7 的
+ * actor 约定写 `<producer>/<version>`（所以带版本号）；`generated.at` 按 §5.2 的
+ * 语义只记「内容上次真正变化」，sync 因此只在正文变化时才落盘。v0.2 已用
+ * `generated.at` 取代 v0.1 的 `timestamp`，没有 `updated` 这个顶层键。
+ * `covered` / `coverage` 是 §4.1 允许的 producer 自定义扩展。
+ */
+export function renderFileHeader(type, items, coverage = "active-only") {
+  const tags = [...new Set(items.flatMap((m) => (m.tags ?? []).map(String)))].sort();
+  return [
+    "---",
+    `type: ${type}`,
+    `generated.by: dsh-mneme/${PACKAGE_VERSION}`,
+    `generated.at: ${new Date().toISOString()}`,
+    `covered: ${items.length}`,
+    `coverage: ${coverage}`,
+    `tags: [${tags.map((t) => JSON.stringify(t)).join(", ")}]`,
+    "---",
+    ""
+  ].join("\n");
+}
+
+/**
+ * document 的只读视图一行（#296）：一句话定位 + 文件指针，正文按 doc_path 去读。
+ * 摘要首句按句末标点切，切不出来就整段（超长再按字符数兜底），保证「一行一个
+ * 文档」的形态不被长摘要撑破。
+ */
+function renderPointer(m) {
+  const flat = String(m.content ?? "").replace(/\s+/g, " ").trim();
+  // 句末标点切首句：中文的。！？ 后面通常不跟空格，不能像英文那样要求一个空白
+  // （要求了就一句都切不出来，整段摘要被当成「首句」塞进视图）。英文的 . 仍要求
+  // 后接空白或结尾，免得把 e.g. / v1.2 这类点号当成句末。
+  const first = flat.match(/^.*?(?:[。！？]|[!?]|[.](?=\s|$))|^.*$/s)?.[0] ?? flat;
+  // 按码点切，不按 UTF-16 码元：后者会在 emoji / 代理对中间落刀，落盘成 U+FFFD。
+  const chars = [...first];
+  const summary = chars.length > POINTER_MAX ? `${chars.slice(0, POINTER_MAX).join("")}…` : first;
+  const where = m.doc_path ? ` · \`${oneLine(m.doc_path)}\`` : "";
+  return `- \`${m.id}\` **${oneLine(m.title)}**：${oneLine(summary)}${where}\n`;
+}
+
 /**
  * Render one type's memories into exactly the mirror-file text (header +
  * per-memory blocks, updated_at DESC like sync). sync() writes this to disk;
- * the /export endpoint returns the same text, so an exported markdown is
- * byte-compatible with a mirror file and can be fed straight back through
- * parseHumanEdits → mergeHumanEdits. Unknown type → undefined.
+ * the /export endpoint reuses the same entry blocks for its per-type sections,
+ * so an exported markdown round-trips back through parseHumanEdits →
+ * mergeHumanEdits. Unknown type → undefined.
+ *
+ * `fileHeader: false` 供 /export 用：一个文档只能有一个 frontmatter 块（在文档
+ * 最前，见 api.js 的 /export），所以分节不再各自带文件头。只读 type（#296 的
+ * document）只走磁盘镜像这一条：渲染指针行 + 只读文件头，导出侧不取它。
  */
-export function renderMirrorText(type, memories, language = "zh") {
+export function renderMirrorText(type, memories, language = "zh", { fileHeader = true } = {}) {
   const name = TYPE_FILE[type];
   if (!name) return undefined;
   const items = (memories ?? [])
     .slice()
     .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
-  const header = STR.mirrorHeader[language](name);
-  const body = items.map((m) => renderMemory(m, language)).join("\n");
-  return header + body;
+  const readonly = MIRROR_READONLY_TYPES.has(type);
+  const header = readonly ? STR.mirrorReadonlyHeader[language](name) : STR.mirrorHeader[language](name);
+  const body = items.map((m) => (readonly ? renderPointer(m) : renderMemory(m, language))).join("\n");
+  return (fileHeader ? renderFileHeader(type, items) : "") + header + body;
 }
 
 /**
@@ -91,7 +201,7 @@ export function parseHumanEdits(text) {
   // A body line like "- **ID**: `x`" is not, so it never splits the block
   // or produces a ghost entry.
   // 解析同时接受两种语言的标签：切换语言前渲染的镜像文件仍能合并。
-  const anchors = [...normalized.matchAll(/^- \*\*ID\*\*: `([^`]+)`\n- \*\*(?:类型|Type)\*\*:/gm)];
+  const anchors = [...normalized.matchAll(ANCHOR_RE)];
   let prevEnd = 0;
   for (let i = 0; i < anchors.length; i++) {
     const anchor = anchors[i];
@@ -109,7 +219,7 @@ export function parseHumanEdits(text) {
     let body = normalized
       .slice(blockStart, blockEnd)
       .replace(/^- \*\*ID\*\*: `[^`]+`\n?/, "")
-      .replace(/^(- \*\*(?:类型|重要性|标签|更新时间|来源|Type|Importance|Tags|Updated|Source)\*\*:.*\n?)+/, "")
+      .replace(META_RUN_RE, "")
       .replace(/^<!-- mirror-digest: [a-f0-9]+ -->\n?/m, "");
     const separators = [...body.matchAll(/^---\s*$/gm)];
     const lastSep = separators[separators.length - 1];
@@ -120,7 +230,7 @@ export function parseHumanEdits(text) {
     // render time — the version token for detecting a concurrent store write
     // during a three-way merge of human edits (see service.syncMirror).
     const block = normalized.slice(blockStart, blockEnd);
-    const updatedMatch = block.match(/- \*\*(?:更新时间|Updated)\*\*: ([^\n]+)/);
+    const updatedMatch = block.match(UPDATED_RE);
     const digestMatch = block.match(/<!-- mirror-digest: ([a-f0-9]+) -->/);
     edits.push({
       id: anchor[1],
@@ -136,6 +246,15 @@ export function parseHumanEdits(text) {
   return edits;
 }
 
+/**
+ * 判断「这份文本的内容有没有变」时忽略 generated.at：它每次渲染都是新时间戳，
+ * 带上它就永远判为变化。其余字节必须逐字相同才算没变——镜像的幂等性（同样的库
+ * 渲染两次得到同样的文件）才是可断言的。
+ */
+function stripGeneratedAt(text) {
+  return String(text).replace(/^generated\.at: .*$/m, "");
+}
+
 export function createMirror(dir, language = "zh") {
   mkdirSync(dir, { recursive: true });
 
@@ -150,7 +269,10 @@ export function createMirror(dir, language = "zh") {
    * this wrapper only owns the "read file → text" side.
    */
   function readHumanEdits(type = undefined) {
-    const types = type ? [type] : Object.keys(TYPE_FILE);
+    // 只读 type 不参与人改合并（#296）：它们的文件里没有可编辑的正文，解析出来的
+    // 指针行文本若被当成「人改」写回库，会污染摘要。整类跳过，包括 type 指定的
+    // 那条调用路径。
+    const types = (type ? [type] : Object.keys(TYPE_FILE)).filter((t) => !MIRROR_READONLY_TYPES.has(t));
     const edits = [];
     for (const t of types) {
       const file = filePath(t);
@@ -182,9 +304,19 @@ export function createMirror(dir, language = "zh") {
           // memories do not "resurrect" via readHumanEdits
           rmSync(file, { force: true });
         } else {
-          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径），磁盘镜像
-          // 与导出文本永远同构。
-          writeFileSync(file, renderMirrorText(type, items, language), "utf8");
+          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径）。
+          const text = renderMirrorText(type, items, language);
+          // 内容没变就不落盘。generated.at 每次渲染都新，无脑写会让编辑器、同步盘
+          // 与 git 在每次业务写后看到全部镜像文件「被外部修改」，而内容其实一字未
+          // 变；按 OKF 的语义它只该记内容变化，未变就保留旧值。这也是同步读 9 个
+          // 小文件的代价，比无谓写 9 次盘便宜。
+          let prev = null;
+          try {
+            prev = readFileSync(file, "utf8");
+          } catch { /* 首次写：读不到就是没有旧文件 */ }
+          if (prev === null || stripGeneratedAt(prev) !== stripGeneratedAt(text)) {
+            writeFileSync(file, text, "utf8");
+          }
         }
         results[type] = { ok: true };
       } catch (error) {