@modusensus/dsh-mneme 0.9.0 → 0.9.1

package/lib/semantic.js

@@ -28,29 +28,59 @@ import { LocalReranker } from "./reranker.js";
  */
 export async function backfillMissingEmbeddings({
   store, embedder, vectorIndex, logger,
+  // maxTotal: 0 = no cap (drain the whole backlog this run). The default stays
+  // modest so a boot never floods a provider, but the cap is a caller choice
+  // now instead of a hardcoded one — the fixed 500 meant a 4k-row backlog
+  // needed nine restarts to clear, and nothing reported that it had been cut.
   maxTotal = 500, batchSize = 10, rateLimitMs = 200
 }) {
+  const startedAt = new Date().toISOString();
+  // Model-aware selector: rows whose vector came from another model (or
+  // predate per-row provenance) must be re-embedded too, otherwise a model
+  // switch leaves uncomparable vectors in the index forever.
+  const model = embedder.modelHash;
+  const pick = (n) => (typeof store.needsEmbeddingFor === "function"
+    ? store.needsEmbeddingFor(model, n)
+    : store.needsEmbedding(n));
+  const unlimited = !(maxTotal > 0);
   let indexed = 0;
-  for (let done = 0; done < maxTotal;) {
-    const rows = store.needsEmbedding(batchSize);
+  let processed = 0;
+  let failed = 0;
+  for (let done = 0; unlimited || done < maxTotal;) {
+    const rows = pick(batchSize);
     if (!rows.length) break;
     for (const row of rows) {
       try {
         const text = [row.title, row.content].filter(Boolean).join("\n");
         const vector = await embedder.embedSingle(text);
         if (vector?.length) {
-          store.setEmbedding(row.id, vector);
+          store.setEmbedding(row.id, vector, model);
           indexed++;
+        } else {
+          failed++;
         }
-      } catch { /* skip the bad row */ }
+      } catch { failed++; /* skip the bad row, but count it */ }
     }
     done += rows.length;
+    processed += rows.length;
     // Rate limit: space out batches so the provider is not hammered.
-    if (store.needsEmbedding(1).length) await new Promise((r) => setTimeout(r, rateLimitMs));
+    if (pick(1).length) await new Promise((r) => setTimeout(r, rateLimitMs));
   }
-  if (indexed > 0 && embedder.modelHash) vectorIndex.markModel?.(embedder.modelHash, embedder.dimension);
-  logger?.info?.(`[dsh-mneme] auto-reindex backfilled ${indexed} embeddings on boot`);
-  return indexed;
+  if (indexed > 0 && model) vectorIndex.markModel?.(model, embedder.dimension);
+  // stillStale answers "did it actually finish?". The old return value was a
+  // bare indexed count, so a run that hit the cap looked exactly like a run
+  // that drained the backlog.
+  const stillStale = pick(1).length > 0;
+  const finishReason = stillStale ? "capped" : (failed > 0 && indexed === 0 ? "all-failed" : "drained");
+  logger?.info?.(
+    `[dsh-mneme] auto-reindex backfilled ${indexed} embeddings (processed=${processed}, failed=${failed}, finish=${finishReason})`
+  );
+  return {
+    indexed, processed, failed, finishReason, stillStale,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    model: model ?? null
+  };
 }
 
 /**
@@ -74,6 +104,9 @@ export function createSemantic({ store, service, settings, cfg, logger, vectorIn
   // boot 回填首查计时器。搬移前在 index.js 是裸 setTimeout(不参与卸载清理);
   // 纳入 dispose 是修悬挂,不改变启动行为。
   let reindexTimer = null;
+  // Last boot-backfill summary, exposed via backfillStatus() so "did it
+  // finish?" has an answer other than a log line.
+  let lastBackfill = null;
 
   if (lightMode) {
     // Light mode: the whole vector pipeline stays off — no embedder (nothing
@@ -202,12 +235,31 @@ export function createSemantic({ store, service, settings, cfg, logger, vectorIn
           if (tries > 0) reindexTimer = setTimeout(() => attempt(tries - 1), 2000);
           return;
         }
-        if (!store.needsEmbedding(1).length) return; // nothing to backfill
+        const model = embedder.modelHash;
+        const stale = typeof store.hasStaleEmbedding === "function"
+          ? store.hasStaleEmbedding(model)
+          : store.needsEmbedding(1).length > 0;
+        if (!stale) return; // nothing missing and nothing from another model
         // Issue #128: no fingerprint gate here anymore — a matching fingerprint
         // used to return early and permanently orphan rows whose embed failed
         // at write time. See backfillMissingEmbeddings().
-        backfillMissingEmbeddings({ store, embedder, vectorIndex, logger })
+        // Cap and pacing are configuration now (reindexMaxPerBoot /
+        // reindexBatchSize / reindexRateLimitMs) instead of hardcoded 500/10/200.
+        lastBackfill = {
+          state: "running", startedAt: new Date().toISOString(),
+          maxTotal: cfg.reindexMaxPerBoot, batchSize: cfg.reindexBatchSize
+        };
+        backfillMissingEmbeddings({
+          store, embedder, vectorIndex, logger,
+          maxTotal: cfg.reindexMaxPerBoot,
+          batchSize: cfg.reindexBatchSize,
+          rateLimitMs: cfg.reindexRateLimitMs
+        })
+          .then((summary) => {
+            lastBackfill = { ...summary, state: "finished" };
+          })
           .catch((error) => {
+            lastBackfill = { state: "error", error: String(error), startedAt: lastBackfill?.startedAt };
             logger?.warn?.(`[dsh-mneme] auto-reindex failed: ${String(error)}`);
           });
       } catch (error) {
@@ -221,6 +273,10 @@ export function createSemantic({ store, service, settings, cfg, logger, vectorIn
   return {
     embedder,
     reranker,
+    /** Last backfill run: { state, indexed, failed, finishReason, stillStale, ... }. */
+    backfillStatus() {
+      return lastBackfill;
+    },
     dispose() {
       if (embedRetryTimer !== null) { clearTimeout(embedRetryTimer); embedRetryTimer = null; }
       if (reindexTimer !== null) { clearTimeout(reindexTimer); reindexTimer = null; }

package/lib/settings.js

@@ -31,6 +31,67 @@ function parseList(raw) {
   }
 }
 
+// persona 对象的字段白名单：写入时只挑这些键，未知字段丢弃（设计稿①：字段从简，
+// beta 收到真实反馈再加；provenance 是 v1.5 协作式人格的预留位，v1 不写管道）。
+// 读侧损坏即回空对象——同一容错口径照 parseList（坏值不抛错、面板显示为空可重写）。
+const PERSONA_FIELDS = ["name", "personality", "replyStyle", "enabled", "provenance"];
+
+function parsePersona(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+    const out = {};
+    for (const key of PERSONA_FIELDS) {
+      if (value[key] !== undefined) out[key] = value[key];
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// 多卡模型（v1.2）：存储形为 { default: <卡>, byAgent: { <agentId>: <卡>, … } }。
+// 兼容层：v1 存的是单对象（有 PERSONA_FIELDS 键、无 default/byAgent 键），读侧
+// 判形状——单对象原样落 default 位，旧数据零迁移。byAgent 的键是 agent 身份
+// id（注入时按会话身份寻址，取不到落 default）。default 卡不可删（兜底位）。
+function parsePersonaStore(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return { default: {}, byAgent: {} };
+    }
+    // 新形：含 default 或 byAgent 键 → 按多卡解析
+    if ("default" in value || "byAgent" in value) {
+      const byAgent = {};
+      if (value.byAgent && typeof value.byAgent === "object" && !Array.isArray(value.byAgent)) {
+        for (const [agentId, card] of Object.entries(value.byAgent)) {
+          const parsed = parsePersona(JSON.stringify(card ?? {}));
+          if (Object.keys(parsed).length) byAgent[String(agentId)] = parsed;
+        }
+      }
+      return { default: parsePersona(JSON.stringify(value.default ?? {})), byAgent };
+    }
+    // 旧形：v1 单对象 → 整体作 default（字段白名单在 parsePersona 内裁）
+    return { default: parsePersona(raw), byAgent: {} };
+  } catch {
+    return { default: {}, byAgent: {} };
+  }
+}
+
+function serializePersonaStore(store) {
+  const out = {
+    default: parsePersona(JSON.stringify(store?.default ?? {})),
+    byAgent: {}
+  };
+  if (store?.byAgent && typeof store.byAgent === "object") {
+    for (const [agentId, card] of Object.entries(store.byAgent)) {
+      const parsed = parsePersona(JSON.stringify(card ?? {}));
+      if (Object.keys(parsed).length) out.byAgent[String(agentId)] = parsed;
+    }
+  }
+  return JSON.stringify(out);
+}
+
 // --- feature flags（功能开关）白名单 -----------------------------------------
 // 面板可逐项开关的后端能力。设计约束：
 // 1. 键名与类型必须和 config.js schema 同名同型，这份白名单是唯一校验源
@@ -146,7 +207,18 @@ const FEATURE_FLAG_BOOLEANS = [
   // 决定是否注册座位（会话头图标 / 浮层 / 右栏 / 对话行卡片），服务端只负责把
   // 这个键稳定暴露出来——键若不在 effective 里，客户端静默少键、一个座位都不注册。
   // 默认关（beta、opt-in）；顶层扁平键，因此不需要 NESTED_FLAG_PATHS 条目。
-  "actionPipelineEnabled"
+  "actionPipelineEnabled",
+  // v0.9.0 第二批：M.O. 执行记账（`/mo-run` 开窗 → 窗口内命令被记成一条 run）。
+  // 与上面那个键分开：那个管「看图的座位」，这个管「往账本里写」。默认关（beta、
+  // opt-in），顶层扁平键，不需要 NESTED_FLAG_PATHS 条目。
+  "actionRunEnabled",
+  // 人格定义页（beta）：注入器渲染人格段的顶层总闸（双闸门的 config 半边；对象内
+  // 的 persona.enabled 是 per-agent 半边，存 user_settings 的 "persona" 键，见
+  // getPersona/setPersona）。默认关（beta、opt-in，老用户行为逐字节不变）；不进
+  // LIGHT_MODE_OFF——人格段是用户自写的一小段轻量常驻文本，不引入任何重型后台
+  // 路径，轻量档用户显式勾选仍然赢（同 actionPipelineEnabled 的定性）。顶层扁平
+  // 键，不需要 NESTED_FLAG_PATHS 条目。
+  "personaEnabled"
 ];
 // 整数开关的闭区间，与 config.js 里 z.natural().min().max() 对齐。
 const FEATURE_FLAG_INT_RANGES = {
@@ -403,6 +475,65 @@ export function createSettings(db) {
       setSetting("rules", JSON.stringify(list));
     },
 
+    /**
+     * Agent persona (name / personality / replyStyle + enabled gate), stored as
+     * one JSON key. v1.2 多卡：存储形 { default, byAgent }，旧 v1 单对象读作
+     * default 兼容。getPersona 返回全量多卡形（面板用）；getPersonaFor 按 agent
+     * 身份取卡（注入用），身份缺失/无卡/卡 enabled=false 均落 default。
+     */
+    getPersona() {
+      return parsePersonaStore(getSetting("persona") ?? "{}");
+    },
+    setPersona(input) {
+      // 双形兼容：单对象形 = 只更新 default、byAgent 保留（旧面板/旧调用方合并语义）；
+      // 多卡形 = 全量替换。坏体（非对象）在此不落库不抛错，保值由调用方守卫。
+      if (typeof input !== "object" || input === null || Array.isArray(input)) return;
+      if ("default" in input || "byAgent" in input) {
+        setSetting("persona", serializePersonaStore(input));
+        return;
+      }
+      const current = parsePersonaStore(getSetting("persona") ?? "{}");
+      current.default = parsePersona(JSON.stringify(input));
+      setSetting("persona", serializePersonaStore(current));
+    },
+    /** Per-agent lookup for the injector: id card → default fallback. */
+    getPersonaFor(agentId) {
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+      if (id) {
+        const card = store.byAgent[id];
+        if (card && card.enabled === true) return card;
+      }
+      return store.default;
+    },
+    /** Replace one byAgent card wholesale (panel save); default 不可经此改。 */
+    setPersonaFor(agentId, card) {
+      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+      if (!id || id === "default") return false;
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      const clean = parsePersona(JSON.stringify(
+        typeof card === "object" && card !== null && !Array.isArray(card) ? card : {}
+      ));
+      if (Object.keys(clean).length) store.byAgent[id] = clean;
+      else delete store.byAgent[id];
+      setSetting("persona", serializePersonaStore(store));
+      return true;
+    },
+    /** byAgent 键列表（面板卡列表用，default 不在其中）。 */
+    listPersonas() {
+      return Object.keys(parsePersonaStore(getSetting("persona") ?? "{}").byAgent);
+    },
+    /** 删一张 byAgent 卡；default 不可删（返回 false）。 */
+    removePersona(agentId) {
+      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+      if (!id || id === "default") return false;
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      if (!(id in store.byAgent)) return false;
+      delete store.byAgent[id];
+      setSetting("persona", serializePersonaStore(store));
+      return true;
+    },
+
     /** All custom commands, sorted by name. */
     listCommands() {
       const rows = db.prepare("SELECT * FROM custom_commands ORDER BY name ASC").all();

package/lib/store.js

@@ -835,6 +835,15 @@ export function createStore(path) {
   // 老库打开时 SCHEMA 的 CREATE TABLE 对既有表不生效，列还不存在，把索引写进 SCHEMA
   // 会直接报 no such column（与下方 llm_audit_logs.session_key 同理）。
   addColumn("memories", "content_hash", "ALTER TABLE memories ADD COLUMN content_hash TEXT");
+  // 每条向量的出身（行级 model hash，如 `qwen3.7-text-embedding-flash#17a6a0b1`）。
+  // 为什么必须行级：vector_meta 只有一个 model_hash，它记的是「最后一次成功写入
+  // 的模型」，换模型时被整表覆盖——于是上一代模型产出的向量在元数据上看起来完全
+  // 合规，实际与新模型的查询向量不可比。没有这一列，「这条向量是不是当前模型产
+  // 的」就无从判断（content_hash 是内容归一化哈希，与向量模型无关；dimension 在
+  // 同为 1024 维的模型间也区分不出来）。
+  // 存量行的值是 NULL，且**不推断**：按 updated_at 猜出的模型名会变成日后审计信
+  // 以为真的证据。NULL 一律读作「出身未知」，等价的补法是重算，不是猜。
+  addColumn("memories", "embedding_model", "ALTER TABLE memories ADD COLUMN embedding_model TEXT");
   // issue #24 块2（权重演化）：entity_relations 加 weight + source。存量关系
   // 行缺列 → 默认 manual 1.0（最保守：既有语义不因迁移而变弱）。
   addColumn("entity_relations", "weight", "ALTER TABLE entity_relations ADD COLUMN weight REAL NOT NULL DEFAULT 1.0");
@@ -1606,10 +1615,24 @@ export function createStore(path) {
     return rows.map((row) => row.content ?? "");
   }
 
-  /** Set (or clear with null) the embedding vector of a memory. */
-  function setEmbedding(id, vector) {
+  /** Set (or clear with null) the embedding vector of a memory.
+   *  `modelHash` records which model produced THIS vector (see the
+   *  embedding_model migration note). Clearing the vector clears the
+   *  provenance with it, so a NULL vector is never paired with a stale model
+   *  name; omitting modelHash leaves the column untouched (callers that
+   *  predate the column still work, their rows simply read as unknown). */
+  function setEmbedding(id, vector, modelHash) {
     const json = Array.isArray(vector) && vector.length ? JSON.stringify(vector) : null;
-    db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(json, id);
+    if (json) {
+      if (modelHash !== undefined) {
+        db.prepare("UPDATE memories SET embedding = ?, embedding_model = ? WHERE id = ?")
+          .run(json, modelHash === null ? null : String(modelHash), id);
+      } else {
+        db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(json, id);
+      }
+    } else {
+      db.prepare("UPDATE memories SET embedding = NULL, embedding_model = NULL WHERE id = ?").run(id);
+    }
     // Issue #202：单一写入口即单一失效点——重写缓存条目（向量在手上不必重解析），
     // 清空则移除，删除过的 id 不会被下一次 searchVector 的 id 集合选中。
     if (json) {
@@ -1662,6 +1685,54 @@ export function createStore(path) {
     ).all(limit);
   }
 
+  /**
+   * Rows whose vector is missing OR was produced by a different model than
+   * `modelHash` — the selector the backfill should use whenever the caller
+   * knows which model the vectors are supposed to come from.
+   *
+   * Why `needsEmbedding` alone is not enough: it only matches empty vectors,
+   * so after a model switch every vector written by the previous model stays
+   * eligible for "has a vector" forever, while its similarity to the current
+   * query embedding is meaningless. Those rows keep inflating the status
+   * card's coverage while semantic recall silently degrades.
+   *
+   * `embedding_model IS NULL` counts as stale on purpose: NULL means "written
+   * before per-row provenance existed, producing model unknown", and an
+   * unknown origin cannot be proven to match. Those rows get re-embedded
+   * rather than assumed correct.
+   *
+   * When `modelHash` is falsy (embedder unconfigured / no fingerprint yet)
+   * this degrades to the plain missing-only selector instead of re-embedding
+   * the whole table against nothing.
+   */
+  function needsEmbeddingFor(modelHash, limit = 50) {
+    if (!modelHash) return needsEmbedding(limit);
+    return db.prepare(
+      `SELECT id, title, content, embedding_model FROM memories
+       WHERE ((embedding IS NULL OR embedding = '')
+              OR embedding_model IS NULL
+              OR embedding_model != ?)
+         AND forgotten = 0 AND archived = 0
+       ORDER BY updated_at DESC LIMIT ?`
+    ).all(String(modelHash), limit);
+  }
+
+  /** True when any active row would be picked by needsEmbeddingFor(). */
+  function hasStaleEmbedding(modelHash) {
+    return needsEmbeddingFor(modelHash, 1).length > 0;
+  }
+
+  /** Per-model provenance counts over active rows ('' = unknown origin). */
+  function embeddingModelBreakdown() {
+    return db.prepare(
+      `SELECT COALESCE(embedding_model, '') AS model, count(*) AS c
+         FROM memories
+        WHERE embedding IS NOT NULL AND embedding != ''
+          AND forgotten = 0 AND archived = 0
+        GROUP BY COALESCE(embedding_model, '')`
+    ).all();
+  }
+
   function search(query, { limit = 20, includeArchived = false } = {}) {
     const q = String(query).trim();
     if (!q) return [];
@@ -3159,6 +3230,9 @@ export function createStore(path) {
     getParsedEmbedding,
     embeddedCount,
     needsEmbedding,
+    needsEmbeddingFor,
+    hasStaleEmbedding,
+    embeddingModelBreakdown,
     searchVector,
     saveDreamRun,
     lastDreamRunAt,

package/lib/summarize.js

@@ -514,8 +514,7 @@ export function createSummarizer(ctx, service, config, deps = {}) {
   const clearTimer = typeof deps.clearTimeoutFn === "function" ? deps.clearTimeoutFn : clearTimeout;
 
   // v0.9.0（M.O. 项目记忆）：蒸馏写入也要盖作用域章。此前只有 memory_save 那条工具
-  // 路径盖章（tools.js 的 memory_save 里 resolveSessionScope 到 workspaceLabel 那一段，
-  // 2026-10-13 在 :173-193），而机器提炼是写入量的绝大多数——于是「项目记忆」
+  // 路径盖章（tools.js 的 resolveSessionScope 盖章块，2026-10-14 在 :174-181），而机器提炼是写入量的绝大多数——于是「项目记忆」
   // 在库里根本不存在（全库带 scope 的行不足 3%，且带 scope 的全部来自工具路径）。
   // 这里不另造口径：同一把解析器（scope.js 的 createScopeResolver，2026-10-13 在 :24）、同一把闸门
   // （config.scopeEnabled === true）、同一对列（*_scope + *_scope_source='auto'），
@@ -888,7 +887,7 @@ export function createSummarizer(ctx, service, config, deps = {}) {
       // v0.9.0（M.O. 项目记忆）：一次窗口解析一次——同一蒸馏窗口里所有条目同属一个
       // 工作区、一个 agent 身份，逐条解析是白花钱。解析不到就落 NULL（NULL = 未标注 =
       // 全局可见），且解析器绝不抛错（scope.js 的硬约束：记忆写入不该被作用域拖挂）。
-      // 闸门与 tools.js 的 autoStamping（2026-10-13 在 :180）同一把：关着就一个字段都不加，老行为不变。
+      // 闸门与 tools.js 的 autoStamping（2026-10-14 在 :175）同一把：关着就一个字段都不加，老行为不变。
       const writeScope = config?.scopeEnabled === true
         ? resolveSessionScope({ agent: { session } })
         : null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
-  "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 9 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.9.0",
+  "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 10 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
+  "version": "0.9.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -64,7 +64,7 @@
     "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6 <0.2.0 || >=0.1.5-rc.0 <0.3.0 || >=0.2.0-rc.0 <0.3.0",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@huggingface/transformers": ">=4.2.0 <5",
-    "dsh-better-sidebar": "^0.18.0"
+    "dsh-better-sidebar": ">=0.18.0 <1"
   },
   "peerDependenciesMeta": {
     "dsh-better-sidebar": {

package/scripts/changelog-prep.mjs

@@ -14,23 +14,78 @@ export function detectEol(text) {
 }
 
 /**
- * 在 `# Changelog` 标题之后插入 `## [version] - date` 占位节（幂等：已含该版本则不改）。
+ * 只剥掉整段两端的空行，保留每行自己的缩进（正文原样搬走的前提）。
+ * 重新拼回时用原文的行尾：CRLF 的 CHANGELOG 若在这里退化成 LF，整份文件就成了混合行尾。
+ */
+function stripBlankEdges(text, eol) {
+  const lines = text.split(/\r?\n/);
+  let from = 0;
+  let to = lines.length;
+  while (from < to && lines[from].trim() === "") from += 1;
+  while (to > from && lines[to - 1].trim() === "") to -= 1;
+  return lines.slice(from, to).join(eol);
+}
+
+/**
+ * 插入 `## [version] - date` 节（幂等：已含该版本则不改）。
+ *
+ * **两个位置约定，都是被真实发版逼出来的**：
+ *
+ * 1. 新版本节排在 `## [Unreleased]` **下面**，不是 `# Changelog` 下面。Keep a Changelog
+ *    的约定是未发布区永远在最上；插反了会写出「[0.9.1] 在 [Unreleased] 之上」的顺序颠倒。
+ *    v0.9.0 那次就是靠事后一笔人工提交（77df0fb）掰回来的——机器算得对的事不该留给人补。
+ *
+ * 2. `[Unreleased]` 里攒着的条目**整段搬进新版本节**，Unreleased 留空。原先只插一个
+ *    「🐛 修复 / （待填）」空占位，攒着的条目原地不动，于是发版后文件里同时存在
+ *    「新版本节是空的」和「旧条目还挂在 Unreleased 名下」——搬运这一步照样是人工补的
+ *    （同一个 77df0fb）。搬的是位置不是内容：原样移动、一个字不改，所以「新版本节里
+ *    该写什么」这个判断仍然只由往 Unreleased 里写条目的人做。
  *
  * 返回 `{ok:false, reason}` 而不是静默返回原文——调用方必须能区分「没什么可做」与
  * 「该做但没做成」，后者要报错退出。`reason` 取值：`already-present` / `header-not-found`。
+ * 成功时带两个字段，**必须分开用**：
+ * - `movedContent`：是否真的从 [Unreleased] 搬了非空正文（决定「搬了」还是「插了空占位」）；
+ * - `moved`：其中以 `- ` 开头的条目数，只用于把日志说得更具体。
+ * 用 `moved` 当「有没有搬」的判据是错的：正文非空但一条 `-` 都没有（例如全是正文段落或
+ * 缩进代码块）时 `moved` 是 0，日志会说「[Unreleased] 本来是空的」——而它是非空的。
  *
  * @param {string} text CHANGELOG 全文
  * @param {string} version 如 "0.8.13"
  * @param {string} date 如 "2026-10-03"
- * @returns {{ok: true, text: string} | {ok: false, reason: "already-present" | "header-not-found"}}
+ * @returns {{ok: true, text: string, moved: number, movedContent: boolean} | {ok: false, reason: "already-present" | "header-not-found"}}
  */
 export function insertReleaseSection(text, version, date) {
   if (text.includes(`## [${version}]`)) return { ok: false, reason: "already-present" };
   const eol = detectEol(text);
-  const head = `## [${version}] - ${date}${eol}${eol}## 🐛 修复${eol}${eol}- （待填）${eol}${eol}`;
-  // BOM 可选：带 BOM 的检出上 `^#` 同样匹配不到，属于同一类「形状变了就静默失败」。
-  // 行尾 `\r?\n` 两种都吃——这就是本模块存在的首要理由。
-  const out = text.replace(/^(\uFEFF?# Changelog\r?\n\r?\n)/, `$1${head}`);
+  const placeholder = `## 🐛 修复${eol}${eol}- （待填）${eol}`;
+
+  const m = /^## \[Unreleased\][^\r\n]*\r?\n/m.exec(text);
+  if (m) {
+    const start = m.index + m[0].length;
+    const rest = text.slice(start);
+    const nextRel = rest.search(/^## \[/m);
+    const body = nextRel === -1 ? rest : rest.slice(0, nextRel);
+    const tail = nextRel === -1 ? "" : rest.slice(nextRel);
+    // 只剥节边界上的空行，**不 trim 正文**：正文首行若是缩进代码块（Markdown 的四空格），
+    // trim 会把前导空格吃掉，代码块降级成普通段落——那就不是「原样搬」了。
+    const pending = stripBlankEdges(body, eol);
+    const head = `## [${version}] - ${date}${eol}${eol}`;
+
+    // Unreleased 里攒着东西：整段搬进新版本节，Unreleased 留空。
+    // 搬的是位置不是内容——原样移动，一个字不改。这样「新版本节里有什么」这个判断
+    // 仍然只由往 Unreleased 里写条目的人做，脚本只负责把攒好的东西挪对地方。
+    if (pending) {
+      const moved = pending.split(/\r?\n/).filter((l) => l.startsWith("- ")).length;
+      return { ok: true, moved, movedContent: true, text: text.slice(0, start) + eol + head + pending + eol + eol + tail };
+    }
+
+    // Unreleased 是空的：插占位节，等人写内容。
+    return { ok: true, moved: 0, movedContent: false, text: text.slice(0, start) + eol + head + placeholder + eol + tail };
+  }
+
+  // 没有 [Unreleased] 的旧文件：退回标题之后。BOM 可选——带 BOM 的检出上 `^#` 同样匹配不到。
+  const section = `## [${version}] - ${date}${eol}${eol}${placeholder}${eol}`;
+  const out = text.replace(/^(\uFEFF?# Changelog\r?\n\r?\n)/, "$1" + section);
   if (out === text) return { ok: false, reason: "header-not-found" };
-  return { ok: true, text: out };
+  return { ok: true, moved: 0, movedContent: false, text: out };
 }

package/scripts/check-sync.js

@@ -1,11 +1,13 @@
-// 发布前校验 src/ 与 lib/ 一致性。
+// 断言 src/ 与 lib/ 一致——发布前的平价闸门。
 //
-// npm 包实际加载 lib/（package main → lib/index.js），而 root 层 `npm publish`
-// 不触发 dsh-mneme/ 的 prepack → sync 同步。历史教训：PR #60 只改了 src 忘了同步
-// lib，v0.7.8 发出去的 npm 包跑的还是旧代码（issue #65）。此脚本让这类漂移在发布时
-// 直接 fail，而不是带着旧产物上线。
+// npm 包实际加载 lib/（package main → lib/index.js）。历史教训：PR #60 只改了 src
+// 忘了同步 lib，v0.7.8 发出去的 npm 包跑的还是旧代码，用户侧静默失效（issue #65）。
 //
-// 用法：node scripts/check-sync.js （root package.json 的 prepack 钩子自动调用）
+// 注意这里**只校验、不同步**：prepack 钩子跑的是 `npm run sync`（把 src 覆盖到
+// lib），同步后必然一致，所以它永远不会因漂移失败。真正的闸门是这道脚本，跑在
+// CI 每个 PR 与 release.yml 的 test job 里——让漂移在合并前就红，而不是等到发布。
+//
+// 用法：node scripts/check-sync.js （CI 与 release.yml 调用，非 prepack）
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";