@max-null/dsh-memory 0.11.0 → 0.12.0

package/README.md

@@ -150,6 +150,7 @@ node scripts/verify-loader.mjs   # 用 Loader 端到端验证插件可加载
 node scripts/scan-orphans.mjs [根目录]       # 清点「当前代码打不开」的记忆文件（只读）
 node scripts/unzstd-frames.mjs <源> <目标>   # 解多帧 zstd（读 DSH 会话日志用）
 node scripts/ancestor-probe.mjs plan [--cwd <cwd>]   # 复算祖先链（只读）；seed/check/clean 验 ④-A
+node scripts/analyze-cooccurrence.mjs        # 关键词共现分析（记忆之间有没有关系网，只读）
 ```
 
 ## 依赖（peerDependencies，由宿主提供）

package/dist/anchors.d.ts

@@ -2,12 +2,13 @@
  * 有效性锚点（2026-09-15 静默记忆机制）：把一条记忆绑定到某个**可探测的环境值**上，
  * 值变了就自动失效——解决「版本特性类记忆随环境升级静默变错」的问题。
  *
- * 第一版只做**进程内可探测**的类型：校验跑在会话启动的路径上，探测必须零 IO。
- * 需要跑子进程才能拿到的（如 PowerShell 版本）留待后续——那要先解决「插件直接
- * spawn 会绕过 DSH 的 shell 沙箱」的合规问题，不能顺手开这个口子。
+ * 探测跑在会话启动的校验路径上，因此**禁止起子进程**（那要先解决「插件直接 spawn 会绕过
+ * DSH 的 shell 沙箱」的合规问题，不能顺手开这个口子）。**文件探测不在此列**：`path-exists`
+ * 只有一次 `existsSync`，与读环境变量同量级。此前这里写的是「探测必须零 IO」，那句话把
+ * 「禁止 spawn」误写成了「禁止一切系统调用」——0.12.0 加 `path-exists` 时改正。
  */
-/** 受控词汇表：写入时只能从这三种里选，不能自创（自创的锚点无法机械校验）。 */
-export type AnchorKind = 'env' | 'tool-list' | 'self-version';
+/** 受控词汇表：写入时只能从这四种里选，不能自创（自创的锚点无法机械校验）。 */
+export type AnchorKind = 'env' | 'tool-list' | 'self-version' | 'path-exists';
 /** 一条记忆声明的锚点。 */
 export interface MemoryAnchor {
     kind: AnchorKind;
@@ -27,6 +28,13 @@ export interface AnchorProbes {
     selfVersion: string;
     /** 环境变量读取器；缺省 `process.env`。 */
     env?: (name: string) => string | undefined;
+    /**
+     * 会话工作区 cwd：`path-exists` 用它把**相对路径**解析成绝对路径（0.12.0）。
+     *
+     * 缺省时相对路径判为「**未校验**」而不是「不存在」——定位不到与文件真的不在是两件事，
+     * 混起来会让所有相对路径锚点在拿不到 cwd 的路径上集体误失效。
+     */
+    workspaceCwd?: string;
 }
 /**
  * 探测某个锚点当前的取值。

package/dist/anchors.js

@@ -2,10 +2,13 @@
  * 有效性锚点（2026-09-15 静默记忆机制）：把一条记忆绑定到某个**可探测的环境值**上，
  * 值变了就自动失效——解决「版本特性类记忆随环境升级静默变错」的问题。
  *
- * 第一版只做**进程内可探测**的类型：校验跑在会话启动的路径上，探测必须零 IO。
- * 需要跑子进程才能拿到的（如 PowerShell 版本）留待后续——那要先解决「插件直接
- * spawn 会绕过 DSH 的 shell 沙箱」的合规问题，不能顺手开这个口子。
+ * 探测跑在会话启动的校验路径上，因此**禁止起子进程**（那要先解决「插件直接 spawn 会绕过
+ * DSH 的 shell 沙箱」的合规问题，不能顺手开这个口子）。**文件探测不在此列**：`path-exists`
+ * 只有一次 `existsSync`，与读环境变量同量级。此前这里写的是「探测必须零 IO」，那句话把
+ * 「禁止 spawn」误写成了「禁止一切系统调用」——0.12.0 加 `path-exists` 时改正。
  */
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
 /**
  * 探测某个锚点当前的取值。
  *
@@ -27,6 +30,16 @@ export function probeAnchor(anchor, probes) {
             return [...probes.toolNames].sort().join(',');
         case 'self-version':
             return probes.selfVersion;
+        case 'path-exists': {
+            if (anchor.name === undefined || anchor.name === '')
+                return undefined;
+            const relative = !isAbsolute(anchor.name);
+            // 相对路径但没有工作区：定位不到 → 未校验（不能判失效）
+            if (relative && (probes.workspaceCwd === undefined || probes.workspaceCwd === ''))
+                return undefined;
+            const target = relative ? resolve(probes.workspaceCwd, anchor.name) : anchor.name;
+            return existsSync(target) ? 'present' : 'absent';
+        }
         default:
             return undefined;
     }

package/dist/engine.d.ts

@@ -114,6 +114,14 @@ export interface MemoryFilter {
     quarantined?: boolean;
     /** 记录类别过滤（0.6.0）；缺省不过滤（工具层显式传 kind='fact' 保持旧行为）。 */
     kind?: MemoryKind;
+    /**
+     * 更新时间下界 / 上界（0.12.0；epoch ms，含端点）。
+     *
+     * **只有 `list` 读这两个字段**——给 `search` 加时间过滤要动候选集（过滤与打分、`markUsed`
+     * 记账的交互：被过滤掉的命中还算不算「用过」），那是另一件要单独论证的事，本版不做。
+     */
+    after?: number;
+    before?: number;
 }
 /** {@link MemoryEngine.update} 的补丁：省略的字段保持原值（`injected` 省略时连 `injectedAuto` 一起保持）。 */
 export interface MemoryPatch {
@@ -184,6 +192,36 @@ export type MemoryChange = {
     from: string;
     to: string;
 };
+/** 体检报告的单条记录：摘要长度与注入行同量级，便于直接念给人听或写进诊断行。 */
+export interface SweepItem {
+    id: string;
+    summary: string;
+}
+/**
+ * 只读体检的产出（{@link MemoryEngine.sweep}）。四类各有明确的消费者，不做「算了没人读」的采样
+ * ——候选与新失效会进注入诊断行（模型每轮可见），久未命中与全量留给按需调用。
+ */
+export interface SweepReport {
+    /** 当前失效的记录，带原因（锚点不符 / 被取代 / 被撤回）。 */
+    stale: Array<SweepItem & {
+        reason: string | undefined;
+    }>;
+    /** 久未被检索命中的**非常驻**记录——常驻的「没被查过」是正常的，它本来就每轮在场。 */
+    longUnused: Array<SweepItem & {
+        lastUsed: number;
+    }>;
+    /** 候选：被反复检索命中但没有被钉成常驻（见 `candidates`）。 */
+    candidates: Array<SweepItem & {
+        hitCount: number;
+    }>;
+    /** 常驻与注入预算的占用：总数 / 实际进注入 / 预算（无限制时不出现）/ 被挤掉几条。 */
+    resident: {
+        total: number;
+        injected: number;
+        budget: number | undefined;
+        omitted: number;
+    };
+}
 declare module '@deepseek-ai/cordis' {
     interface Context {
         memory: MemoryEngine;
@@ -260,6 +298,13 @@ export declare class MemoryEngine extends Service {
     private writeChain;
     /** 会话启动维护只跑一次的标记（2026-09-15）。 */
     private maintenanceDone;
+    /** 最近一次体检的结果（进程内，不落盘）：供注入侧报「本次校验发现的新失效」。 */
+    private lastSweep;
+    /**
+     * 最近一次体检结果（只读）。未跑过时为 `undefined`——注入侧据此决定要不要报那一行，
+     * 它只在真有新失效时出现，稀有所以不构成噪音。
+     */
+    get lastSweepReport(): SweepReport | undefined;
     constructor(ctx: import('@deepseek-ai/cordis').Context, config?: MemoryConfig);
     protected [Service.init](): Promise<void>;
     /** 打开全局存储域（init 与 reload 共用；backend 复用已注册实例）。 */
@@ -363,6 +408,30 @@ export declare class MemoryEngine extends Service {
      * 未打开的层级本轮不计入，影响可忽略（链上祖先在检索路径打开后即缓存）。
      */
     indexCandidates(projectCwd?: string): MemoryRecord[];
+    /**
+     * 只读体检（0.12.0）：把「该退场的」和「钉了却没进来的」摆成一张清单，**不修改任何状态**
+     * ——连时间戳都不写。
+     *
+     * 为什么坚持只读：一只读的工具，最坏情况是报告不准，判断者按错的清单做了坏决定也能追溯；
+     * 一个会改状态的工具，最坏情况是错了都看不见。这决定了它不需要「每日一次」的守卫，也不
+     * 需要定期读者——有人问它就活着，没人问它不产生任何成本（不占预算、不落盘、不写状态）。
+     */
+    sweep(projectCwd?: string, options?: {
+        days?: number;
+        now?: number;
+    }): Promise<SweepReport>;
+    /**
+     * 候选（0.12.0）：被反复检索命中、但没有被钉成常驻的记录。**只提示，不改状态。**
+     *
+     * 筛选条件与原自动升级判据逐条对应（approved、未隔离、未被人工否决、非模板、未常驻）
+     * ——判据没变，变的只是它的作用：从「自动钉住」改为「列出来等一个判断」。`hitCount`
+     * 只增不减，所以候选会一直留着，直到被钉住、被删或记录本身消失——这不是缺陷，是提示
+     * 该有的持续性：它只在被消费之后才消失。
+     *
+     * 与 {@link indexCandidates} 的分工：那个取**全部**记录（供索引行统计规模与主题），
+     * 这个只取满足候选条件的（供体检报告与诊断行）。
+     */
+    candidates(projectCwd?: string): MemoryRecord[];
     /**
      * 按 id 定位记录所在表：global 优先，其次工作区链（自身 → 祖先，由近及远）。
      * **异步版**——写路径必须用它：`writeScope` 可能在本次进入前刚 `reload()`，
@@ -425,6 +494,9 @@ export declare class MemoryEngine extends Service {
     /**
      * 锚点探测上下文。`toolNames` 拿不到时返回 `undefined`——**不能给空数组**：那会被判成
      * 「工具全没了」，让所有 `tool-list` 锚点误失效。
+     *
+     * `workspaceCwd`（0.12.0）供 `path-exists` 把相对路径解析成绝对路径；缺省时相对路径
+     * 判为「未校验」而不是「不存在」。
      */
     private anchorProbes;
     /** 同步版定位：只查**已打开**的表（global + 链上已缓存的工作区表）。 */
@@ -434,9 +506,16 @@ export declare class MemoryEngine extends Service {
     /** {@link markUsed} 的实现体；必须经 `writeScope` 进入（`recordUse` 在此之内）。 */
     private markUsedInner;
     /**
-     * 命中记账 + 自动升级（2026-09-15 静默记忆机制）：命中次数达阈值即自动打开常驻
-     * 注入——「被反复检索命中」是它值得每轮付费的唯一客观证据。统计性字段不 emit，
-     * 只有真的改变了注入状态才发 `memory/changed`。
+     * 命中记账（2026-09-15 静默记忆机制；0.12.0 取消自动升级）。
+     *
+     * 只记 `hitCount` 与 `lastUsedAt`，**不再据此改变注入状态**。原判据是「被反复检索
+     * 命中」= 值得每轮付费的唯一客观证据，但这条证据测错了东西：命中次数度量的是
+     * **它被想起来了**，而常驻的语义是**它不能被忘**——能被检索命中的恰恰是检索已经
+     * 够用的那些，真正该常驻的（想不起来去查的）命中次数永远是 0。达到
+     * {@link CANDIDATE_HITS} 的记录改由 {@link candidates} 列出，进体检报告与诊断行
+     * 提示，改不改由判断者决定（判据详见设计文档 §二事实四）。
+     *
+     * 统计性字段不 emit：本函数现在不改变任何被订阅的状态。
      */
     private recordUse;
     /** 查询日志（惰性创建；位置见 {@link queryLogPath}）。 */
@@ -563,6 +642,33 @@ export declare class MemoryEngine extends Service {
     setInjected(id: MemoryId, injected: boolean, projectCwd?: string): Promise<MemoryRecord>;
     /** {@link setInjected} 的实现体；必须经 `writeScope` 进入。 */
     private setInjectedInner;
+    /**
+     * 语义作废（0.12.0）：把 `targetId` 标成**被 `id` 取代**。
+     *
+     * 与「改内容」的区别：`update` 会让旧内容直接消失，「取代」把痕迹留下来——检索时看到
+     * 「这条已作废，原因是 X」对被主动查的人是信息而不是干扰。`id` 只用来写原因，本身不被
+     * 改动；两条都必须定位得到，否则拒绝（写一个指向不存在记忆的原因没有意义）。
+     *
+     * 下游复用既有的 `stale` 行为：撤常驻、不排除检索、带标注等核对回写。
+     */
+    supersede(id: MemoryId, targetId: MemoryId, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link supersede} 的实现体；必须经 `writeScope` 进入。返回**被标记的那条**。 */
+    private supersedeInner;
+    /**
+     * 撤回（0.12.0）：把本条标成作废并写明原因。**内容保留**——不删除、也不排除检索，
+     * 与锚点失效后「带标注等核对」是同一条路径。
+     */
+    retract(id: MemoryId, reason: string, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link retract} 的实现体；必须经 `writeScope` 进入。 */
+    private retractInner;
+    /**
+     * 标失效的共用落点（0.12.0）：写 `stale` + 原因、撤掉常驻、发 `memory/changed`。
+     *
+     * 与 `verifyAnchorsInner` 的失效分支保持**同一组字段**（不动 `status`、不删内容、不排除
+     * 检索）——「被取代」「被撤回」「锚点不符」在下游是同一种状态，只在 `staleReason` 里区分
+     * 来源。失效是一个维度、多种来源，这是那条判据的落点。
+     */
+    private markStale;
     /**
      * 修改一条记忆的内容/关键词/注入位（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
      * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态。2026-09-18

package/dist/engine.js

@@ -18,26 +18,42 @@ import { parsePromptFile, scanPromptDir, writePromptFile } from "./prompt-files.
 import { detectSensitive } from "./quarantine.js";
 import { SELF_VERSION } from "./self.js";
 import { anchorHolds } from "./anchors.js";
+import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, deriveSummary, renderInjection, } from "./injection.js";
 import { QueryLog, rankGapCandidates, summarizeQueryLog, summarizeSources } from "./query-log.js";
 /** Brand a string as a {@link MemoryId} (compile-time only). */
 export function MemoryId(id) {
     return id;
 }
-/** 自动升常驻所需的命中次数（2026-09-15）：一次偶然命中不足以证明「每轮都值得付费」。 */
-const AUTO_INJECT_HITS = 2;
+/**
+ * 候选提示所需的命中次数（2026-09-15 起是自动升常驻的阈值；0.12.0 改为只提示）。
+ *
+ * 达到它的记录进 {@link MemoryEngine.candidates}，由体检报告与诊断行列出——**不再据此
+ * 改变注入状态**。阈值本身没动：取消自动升之后，它影响的是提示清单的宽度，不再是状态变更。
+ * 一次偶然命中不足以说明任何事，所以起点仍是 2。
+ */
+const CANDIDATE_HITS = 2;
 /**
  * 一次检索里最多把前多少条记为「被使用」（2026-09-15）。
  *
  * 不设上限时，命中计数退化成「和查询有任意字符重叠」：BM25 对常见 2-gram 会给全库打分，
- * 一句「实机验证标记」在本机就能命中 81 条，于是**两次检索把所有 approved 记忆都升成常驻**，
- * 注入预算当场被历史条目占满——「反复被命中才值得每轮付费」这个判据也就失效了。
- * 取前 K 名接近「模型真的会看的那几条」，且与检索返回值解耦（返回值不动）。
+ * 一句「实机验证标记」在本机就能命中 81 条。0.12.0 之前这会让**两次检索把所有 approved
+ * 记忆都升成常驻**、注入预算当场被历史条目占满；取消自动升之后危害降级为「候选清单被灌满
+ * 噪音」，但上限仍然必要——它保证 `hitCount` 度量的是「模型真的会看的那几条」。
+ * 与检索返回值解耦（返回值不动）。
  */
 const HIT_MARK_LIMIT = 5;
 /** 反查候选的正文摘要长度（字符）。 */
 const GAP_EXCERPT_CHARS = 160;
 /** 自动降级的天数阈值（2026-09-15）：与面板的冷数据判定（COLD_DAYS=30）对齐。 */
 const AUTO_DEMOTE_DAYS = 30;
+/**
+ * 体检里「久未命中」的默认天数阈值（0.12.0）。
+ *
+ * 比自动降级的 30 天大得多，因为两者判的不是一类东西：30 天判「自动升上来的常驻是否还有
+ * 价值」，而久未命中的对象**本来就不是常驻**——非常驻的记忆几十天不用是常态，阈值定得太低
+ * 会把正常记录报成待清理。
+ */
+const DEFAULT_SWEEP_DAYS = 90;
 const blockSchema = z.object({
     namespace: z.enum(['global', 'project']),
     status: z.enum(['suggested', 'approved', 'auto', 'suggest']),
@@ -183,6 +199,15 @@ export class MemoryEngine extends Service {
     writeChain = Promise.resolve();
     /** 会话启动维护只跑一次的标记（2026-09-15）。 */
     maintenanceDone = false;
+    /** 最近一次体检的结果（进程内，不落盘）：供注入侧报「本次校验发现的新失效」。 */
+    lastSweep;
+    /**
+     * 最近一次体检结果（只读）。未跑过时为 `undefined`——注入侧据此决定要不要报那一行，
+     * 它只在真有新失效时出现，稀有所以不构成噪音。
+     */
+    get lastSweepReport() {
+        return this.lastSweep;
+    }
     constructor(ctx, config = {}) {
         super(ctx, 'memory');
         this.config = config;
@@ -491,6 +516,78 @@ export class MemoryEngine extends Service {
         }
         return candidates;
     }
+    /**
+     * 只读体检（0.12.0）：把「该退场的」和「钉了却没进来的」摆成一张清单，**不修改任何状态**
+     * ——连时间戳都不写。
+     *
+     * 为什么坚持只读：一只读的工具，最坏情况是报告不准，判断者按错的清单做了坏决定也能追溯；
+     * 一个会改状态的工具，最坏情况是错了都看不见。这决定了它不需要「每日一次」的守卫，也不
+     * 需要定期读者——有人问它就活着，没人问它不产生任何成本（不占预算、不落盘、不写状态）。
+     */
+    async sweep(projectCwd, options) {
+        const now = options?.now ?? Date.now();
+        const days = options?.days ?? DEFAULT_SWEEP_DAYS;
+        const threshold = now - days * 24 * 60 * 60 * 1000;
+        const summaryChars = this.config.summaryChars ?? DEFAULT_SUMMARY_CHARS;
+        const brief = (record) => deriveSummary(record.content, summaryChars);
+        const records = await this.allRecords(undefined, projectCwd);
+        const stale = records
+            .filter(record => record.stale === true)
+            .map(record => ({ id: String(record.id), summary: brief(record), reason: record.staleReason }));
+        // 只看非常驻：常驻的「没被检索过」是正常的（它本来就每轮在场，不需要被查）
+        const longUnused = records
+            .filter(record => record.injected !== true && (record.lastUsedAt ?? record.updatedAt) < threshold)
+            .map(record => ({
+            id: String(record.id),
+            summary: brief(record),
+            lastUsed: record.lastUsedAt ?? record.updatedAt,
+        }));
+        const candidates = this.candidates(projectCwd)
+            .map(record => ({ id: String(record.id), summary: brief(record), hitCount: record.hitCount ?? 0 }));
+        const resident = this.recallRecords(projectCwd);
+        const rendered = renderInjection(resident, this.config.injectionBudget ?? DEFAULT_INJECTION_BUDGET, summaryChars);
+        return {
+            stale,
+            longUnused,
+            candidates,
+            resident: {
+                total: resident.length,
+                injected: rendered.lines.length,
+                // `renderInjection` 用 `null` 表示「预算无限制」，而输出 schema 用「字段缺席」表达
+                // 同一件事（可选字段推导出 `number | undefined`）——在这里归一，避免两套空值语义。
+                budget: rendered.budget ?? undefined,
+                omitted: rendered.omitted,
+            },
+        };
+    }
+    /**
+     * 候选（0.12.0）：被反复检索命中、但没有被钉成常驻的记录。**只提示，不改状态。**
+     *
+     * 筛选条件与原自动升级判据逐条对应（approved、未隔离、未被人工否决、非模板、未常驻）
+     * ——判据没变，变的只是它的作用：从「自动钉住」改为「列出来等一个判断」。`hitCount`
+     * 只增不减，所以候选会一直留着，直到被钉住、被删或记录本身消失——这不是缺陷，是提示
+     * 该有的持续性：它只在被消费之后才消失。
+     *
+     * 与 {@link indexCandidates} 的分工：那个取**全部**记录（供索引行统计规模与主题），
+     * 这个只取满足候选条件的（供体检报告与诊断行）。
+     */
+    candidates(projectCwd) {
+        const picked = (table) => this.recordsOf(table).filter(record => record.status === 'approved'
+            && record.quarantined !== true
+            && record.injected !== true
+            && record.injectedAuto !== false
+            && (record.kind ?? 'fact') !== 'prompt'
+            && (record.hitCount ?? 0) >= CANDIDATE_HITS);
+        const found = picked(this.requireTable('global'));
+        if (projectCwd === undefined || projectCwd === '')
+            return found;
+        for (const { key } of this.projectChain(projectCwd)) {
+            const table = this.projectTables.get(key);
+            if (table !== undefined)
+                found.push(...picked(table));
+        }
+        return found;
+    }
     /**
      * 按 id 定位记录所在表：global 优先，其次工作区链（自身 → 祖先，由近及远）。
      * **异步版**——写路径必须用它：`writeScope` 可能在本次进入前刚 `reload()`，
@@ -612,6 +709,9 @@ export class MemoryEngine extends Service {
         (filter?.quarantined === undefined ? record.quarantined !== true : record.quarantined === filter.quarantined)
             && (filter?.status === undefined || record.status === filter.status)
             && (filter?.injected === undefined || record.injected === filter.injected)
+            // 0.12.0：按更新时间筛——与注入排序、注入行的日期标记同一个依据，不制造第二个「新」的定义
+            && (filter?.after === undefined || record.updatedAt >= filter.after)
+            && (filter?.before === undefined || record.updatedAt <= filter.before)
             && (filter?.kind === undefined || (record.kind ?? 'fact') === filter.kind));
     }
     /**
@@ -739,9 +839,12 @@ export class MemoryEngine extends Service {
             const demoted = await this.demoteStale(projectCwd);
             if (demoted > 0)
                 this.ctx.logger?.info?.(`dsh-memory: 长期未命中，撤下常驻 ${demoted} 条`);
-            const staled = await this.verifyAnchors(this.anchorProbes(), projectCwd);
+            const staled = await this.verifyAnchors(this.anchorProbes(projectCwd), projectCwd);
             if (staled > 0)
                 this.ctx.logger?.info?.(`dsh-memory: 锚点校验更新 ${staled} 条`);
+            // 体检（0.12.0）：只读，产物存进实例字段，供注入侧报「本次校验发现的新失效」。
+            // 它在 try 内——报告没有记忆本身重要，失败由下面的 catch 兜住、不阻断启动。
+            this.lastSweep = await this.sweep(projectCwd);
         }
         catch (error) {
             this.ctx.logger?.warn?.(`dsh-memory: 启动维护失败（不影响使用）：${String(error)}`);
@@ -750,8 +853,11 @@ export class MemoryEngine extends Service {
     /**
      * 锚点探测上下文。`toolNames` 拿不到时返回 `undefined`——**不能给空数组**：那会被判成
      * 「工具全没了」，让所有 `tool-list` 锚点误失效。
+     *
+     * `workspaceCwd`（0.12.0）供 `path-exists` 把相对路径解析成绝对路径；缺省时相对路径
+     * 判为「未校验」而不是「不存在」。
      */
-    anchorProbes() {
+    anchorProbes(workspaceCwd) {
         let toolNames;
         try {
             const tools = this.ctx.get('tools');
@@ -765,7 +871,11 @@ export class MemoryEngine extends Service {
         catch {
             toolNames = undefined;
         }
-        return { ...(toolNames === undefined ? {} : { toolNames }), selfVersion: SELF_VERSION };
+        return {
+            ...(toolNames === undefined ? {} : { toolNames }),
+            selfVersion: SELF_VERSION,
+            ...(workspaceCwd === undefined || workspaceCwd === '' ? {} : { workspaceCwd }),
+        };
     }
     /** 同步版定位：只查**已打开**的表（global + 链上已缓存的工作区表）。 */
     tableOf(id, projectCwd) {
@@ -812,33 +922,24 @@ export class MemoryEngine extends Service {
         }
     }
     /**
-     * 命中记账 + 自动升级（2026-09-15 静默记忆机制）：命中次数达阈值即自动打开常驻
-     * 注入——「被反复检索命中」是它值得每轮付费的唯一客观证据。统计性字段不 emit，
-     * 只有真的改变了注入状态才发 `memory/changed`。
+     * 命中记账（2026-09-15 静默记忆机制；0.12.0 取消自动升级）。
+     *
+     * 只记 `hitCount` 与 `lastUsedAt`，**不再据此改变注入状态**。原判据是「被反复检索
+     * 命中」= 值得每轮付费的唯一客观证据，但这条证据测错了东西：命中次数度量的是
+     * **它被想起来了**，而常驻的语义是**它不能被忘**——能被检索命中的恰恰是检索已经
+     * 够用的那些，真正该常驻的（想不起来去查的）命中次数永远是 0。达到
+     * {@link CANDIDATE_HITS} 的记录改由 {@link candidates} 列出，进体检报告与诊断行
+     * 提示，改不改由判断者决定（判据详见设计文档 §二事实四）。
+     *
+     * 统计性字段不 emit：本函数现在不改变任何被订阅的状态。
      */
     async recordUse(table, id, block, now) {
-        const hitCount = (block.hitCount ?? 0) + 1;
-        const normalized = normalizeBlock(block);
-        // 人工设置过的（injectedAuto === false）双向豁免：既不被降级，也不被升级。
-        // 少了这一条，人手动关掉的记忆会在下次命中时被系统重新打开——用户唯一能
-        // 表达「不要这条常驻」的动作就失效了，而这与降级侧「人工决定优先」不对称。
-        const promote = normalized.status === 'approved'
-            && block.quarantined !== true
-            && block.injectedAuto !== false
-            // 模板永不注入（0.6.0）：prompt 记录连自动升级的资格都没有。少了这一条，
-            // 模板会因「经常被搜到」而升成常驻，把注入预算花在从不该进上下文的东西上。
-            && (block.kind ?? 'fact') !== 'prompt'
-            && !normalized.injected
-            && hitCount >= AUTO_INJECT_HITS;
         const updated = {
             ...block,
-            hitCount,
+            hitCount: (block.hitCount ?? 0) + 1,
             lastUsedAt: now,
-            ...promote ? { injected: true, injectedAuto: true } : {},
         };
         await table.put(id, updated);
-        if (promote)
-            this.ctx.emit('memory/changed', { operation: 'injected', id, injected: true });
     }
     // ── 查询日志与影响力统计（⑥ 2026-09-15）────────────────────────────────
     /** 查询日志（惰性创建；位置见 {@link queryLogPath}）。 */
@@ -1271,6 +1372,64 @@ export class MemoryEngine extends Service {
         this.ctx.emit('memory/changed', { operation: 'injected', id, injected });
         return record;
     }
+    /**
+     * 语义作废（0.12.0）：把 `targetId` 标成**被 `id` 取代**。
+     *
+     * 与「改内容」的区别：`update` 会让旧内容直接消失，「取代」把痕迹留下来——检索时看到
+     * 「这条已作废，原因是 X」对被主动查的人是信息而不是干扰。`id` 只用来写原因，本身不被
+     * 改动；两条都必须定位得到，否则拒绝（写一个指向不存在记忆的原因没有意义）。
+     *
+     * 下游复用既有的 `stale` 行为：撤常驻、不排除检索、带标注等核对回写。
+     */
+    async supersede(id, targetId, projectCwd) {
+        return this.writeScope(projectCwd, () => this.supersedeInner(id, targetId, projectCwd));
+    }
+    /** {@link supersede} 的实现体；必须经 `writeScope` 进入。返回**被标记的那条**。 */
+    async supersedeInner(id, targetId, projectCwd) {
+        if (id === targetId)
+            throw new Error(`cannot supersede a memory with itself ('${id}')`);
+        if (await this.locateRecord(id, projectCwd) === undefined) {
+            throw new Error(`cannot supersede from unknown memory '${id}'`);
+        }
+        const target = await this.locateRecord(targetId, projectCwd);
+        if (target === undefined)
+            throw new Error(`cannot supersede unknown memory '${targetId}'`);
+        return toRecord(targetId, await this.markStale(targetId, target, `被 ${String(id).slice(0, 8)} 取代`));
+    }
+    /**
+     * 撤回（0.12.0）：把本条标成作废并写明原因。**内容保留**——不删除、也不排除检索，
+     * 与锚点失效后「带标注等核对」是同一条路径。
+     */
+    async retract(id, reason, projectCwd) {
+        return this.writeScope(projectCwd, () => this.retractInner(id, reason, projectCwd));
+    }
+    /** {@link retract} 的实现体；必须经 `writeScope` 进入。 */
+    async retractInner(id, reason, projectCwd) {
+        const found = await this.locateRecord(id, projectCwd);
+        if (found === undefined)
+            throw new Error(`cannot retract unknown memory '${id}'`);
+        return toRecord(id, await this.markStale(id, found, `已撤回：${reason}`));
+    }
+    /**
+     * 标失效的共用落点（0.12.0）：写 `stale` + 原因、撤掉常驻、发 `memory/changed`。
+     *
+     * 与 `verifyAnchorsInner` 的失效分支保持**同一组字段**（不动 `status`、不删内容、不排除
+     * 检索）——「被取代」「被撤回」「锚点不符」在下游是同一种状态，只在 `staleReason` 里区分
+     * 来源。失效是一个维度、多种来源，这是那条判据的落点。
+     */
+    async markStale(id, found, reason) {
+        const updated = {
+            ...found.block,
+            stale: true,
+            staleReason: reason,
+            injected: false,
+            injectedAuto: false,
+            updatedAt: Date.now(),
+        };
+        await found.table.put(id, updated);
+        this.ctx.emit('memory/changed', { operation: 'status', id, status: normalizeBlock(updated).status });
+        return updated;
+    }
     /**
      * 修改一条记忆的内容/关键词/注入位（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
      * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态。2026-09-18

package/dist/index.js

@@ -9,12 +9,38 @@ import { MemoryEngine } from "./engine.js";
 import { MemoryGateway } from "./remote.js";
 import { mountMemoryApi } from "./routes.js";
 import { SELF_DESCRIPTION } from "./self.js";
-import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, indexNotice, neighborNotice, omittedNotice, renderInjection } from "./injection.js";
+import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, candidateNotice, indexNotice, neighborNotice, neutralizeBraces, omittedNotice, renderInjection, staleNotice } from "./injection.js";
 export { MemoryEngine } from "./engine.js";
 export { MemoryId } from "./engine.js";
 export { bm25FieldScores, bm25Scores, cosineSimilarity, rrfFuse, tokenize } from "./bm25.js";
 export const name = 'dsh-memory';
 export const inject = ['storage', 'systemPrompt', 'tools', 'webServer', 'webRuntime'];
+/**
+ * 解析时间过滤参数（0.12.0）：`7d` / `30d` 这类相对天数，或 `YYYY-MM-DD` 绝对日期。
+ *
+ * **为什么用字符串而不是数字**：工具参数里目前没有 number 类型的先例（`type: 'number'` 只
+ * 出现在输出 schema），不拿一个未验证的参数类型去赌；字符串也天然容纳 `7d` 这种相对写法。
+ * 解析不出（空串 / 格式不对）一律返回 `undefined` = 不过滤，**不报错**——过滤条件是辅助
+ * 信息，让它把一次查询整体打断得不偿失。
+ *
+ * 绝对日期按**本地时区**解释（`.dsh` 的存储时间戳是 epoch，用户在本地日期里思考），
+ * 相对天数以 `now` 为基准往前推。
+ */
+function parseTimeFilter(input, now) {
+    if (input === undefined)
+        return undefined;
+    const text = input.trim();
+    if (text === '')
+        return undefined;
+    const relative = /^(\d+)d$/.exec(text);
+    if (relative !== null)
+        return now - Number(relative[1]) * 24 * 60 * 60 * 1000;
+    const absolute = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(text);
+    if (absolute !== null) {
+        return new Date(Number(absolute[1]), Number(absolute[2]) - 1, Number(absolute[3])).getTime();
+    }
+    return undefined;
+}
 const RECORD_SCHEMA = {
     type: 'object',
     additionalProperties: false,
@@ -43,6 +69,70 @@ const HIT_SCHEMA = {
         score: { type: 'number', required: true },
     },
 };
+/**
+ * 体检报告的输出（0.12.0）：四类清单一律只读。`summary` 与注入行同量级，直接念给人听
+ * 不失真——这个工具的主要用法就是「你问起时我念给你看」。
+ */
+const SWEEP_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        stale: {
+            type: 'array',
+            required: true,
+            description: '当前失效的记录（锚点不符 / 被取代 / 已撤回），带原因。',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    summary: { type: 'string', required: true },
+                    reason: { type: 'string' },
+                },
+            },
+        },
+        longUnused: {
+            type: 'array',
+            required: true,
+            description: '久未被检索命中的非常驻记录——清理或归档的候选材料。',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    summary: { type: 'string', required: true },
+                    lastUsed: { type: 'number', required: true },
+                },
+            },
+        },
+        candidates: {
+            type: 'array',
+            required: true,
+            description: '被反复检索命中但没有被钉成常驻：要不要钉的待办。',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    summary: { type: 'string', required: true },
+                    hitCount: { type: 'number', required: true },
+                },
+            },
+        },
+        resident: {
+            type: 'object',
+            required: true,
+            additionalProperties: false,
+            description: '常驻与注入预算的占用；`omitted > 0` 表示「钉了却没进来」。',
+            properties: {
+                total: { type: 'number', required: true },
+                injected: { type: 'number', required: true },
+                budget: { type: 'number', description: '生效预算（字符）；无限制时不出现。' },
+                omitted: { type: 'number', required: true },
+            },
+        },
+    },
+};
 /** 模板记录（0.6.0）：不暴露本地文件路径（meta.path 引擎内部使用）。 */
 const PROMPT_RECORD_SCHEMA = {
     type: 'object',
@@ -115,19 +205,24 @@ const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and pr
     + '记结论时一并记下**它是怎么来的**——它为什么成立，以及是什么场景把它逼出来的。没有出处的结论像一把'
     + '没有来历的尺子：看起来天经地义，而天经地义的东西最容易被机械套用。'
     + 'Pass `injected: true` on memory_save / memory_update to pin a memory resident in every turn\'s context: '
-    + 'the same switch the settings panel exposes, exempting the record from both automatic rules (promote on '
-    + 'repeated hits, demote after long idle). Reserve it for rules, standing agreements and judgement criteria '
+    + 'the same switch the settings panel exposes, exempting the record from the remaining automatic rule '
+    + '(demote after long idle; repeated hits no longer promote anything — they only feed the candidate hint). '
+    + 'Reserve it for rules, standing agreements and judgement criteria '
     + '— the kind that must apply even when nobody thinks to search for them; facts, references and case notes '
     + 'stay search-only. '
     + '给 memory_save / memory_update 传 `injected: true` 即把这条钉成每轮常驻——与设置面板是同一个开关，'
-    + '此后不受两条自动规则（反复命中自动开启 / 长期未命中自动撤下）影响。只用于规则、长期约定与判据这类'
+    + '此后不受剩下那条自动规则（长期未命中自动撤下）影响；反复命中已不再自动开启任何东西，只喂候选提示。'
+    + '只用于规则、长期约定与判据这类'
     + '「没人想起来搜也必须生效」的记忆；事实、参考与案例留作按需检索。'
     + 'When earlier context may be relevant, call memory_search to recall it — reviewable memories '
     + '相关历史上下文可用 memory_search 检索；被隔离的记录不进检索。'
     + 'Every memory is plaintext and inspectable with memory_list; memory_forget removes one. '
     + '所有记忆均为明文，可用 memory_list 查看；memory_forget 删除一条。'
     + 'Approved + injected memories of the CURRENT session workspace are every-turn injected too. '
-    + '已审核 + 常驻注入开关打开的工作区记忆也会每轮注入（按当前会话工作区路由）。';
+    + '已审核 + 常驻注入开关打开的工作区记忆也会每轮注入（按当前会话工作区路由）。'
+    + 'When the library grows, call memory_sweep for a read-only health check (stale records with reasons, '
+    + 'long-unused ones, candidates that keep being retrieved without being pinned, and budget usage). '
+    + '库变大之后用 memory_sweep 做只读体检——失效记录（带原因）、久未命中、被反复检索却未常驻的候选、以及预算占用。';
 // 0.5.1：`memory:recall` provider 可经 AssembleContext.agent 拿到当前会话
 // 的 header.cwd——注入 = global + 当前会话工作区的 approved+injected
 // （0.3.4 起工作区记忆就按会话 cwd 路由；provider 是同步回调，只读已
@@ -135,6 +230,8 @@ const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and pr
 // 0.5.2：注入经摘要化 + 预算截断（renderInjection，纯函数）防上下文膨胀。
 // 0.9.0：装不下的条目不再是无声丢弃——末尾追加一行预算诊断（omittedNotice），
 // 报出被挡在外面的 id；它只在有出局时出现，清理干净即消失。
+// 0.11.1：返回值经 neutralizeBraces 中和字面 `{{`——严格插值下它会抛错，让该会话的
+// 全部模型请求一起失败（机制见 injection.ts 的 neutralizeBraces）。
 function recallText(memory, projectCwd, budget, summaryChars) {
     const rendered = renderInjection(memory.recallRecords(projectCwd), budget, summaryChars);
     const parts = [];
@@ -145,6 +242,14 @@ function recallText(memory, projectCwd, budget, summaryChars) {
     const notice = omittedNotice(rendered);
     if (notice !== '')
         parts.push(notice);
+    // 0.12.0：新失效（稀有，出现即值得看一眼）与候选（该不该钉的待办）。
+    // 两者都不占预算；候选必须走到眼前，因为判断者就是读这段上下文的模型自己。
+    const stale = staleNotice(memory.lastSweepReport?.stale ?? []);
+    if (stale !== '')
+        parts.push(stale);
+    const candidates = candidateNotice(memory.candidates(projectCwd));
+    if (candidates !== '')
+        parts.push(candidates);
     // ① 索引行：给出「库里还有什么、按什么去搜」（不占预算、长度常数级）
     const index = indexNotice(memory.indexCandidates(projectCwd));
     if (index !== '')
@@ -153,7 +258,10 @@ function recallText(memory, projectCwd, budget, summaryChars) {
     const neighbors = neighborNotice(memory.neighborsOf(projectCwd));
     if (neighbors !== '')
         parts.push(neighbors);
-    return parts.join('\n');
+    // 中和整个注入副本，而不是在各子行内部：四条子路径（注入行 / 预算诊断 / 索引行 /
+    // 子项目索引）在这里唯一汇合，一处即全覆盖，将来新增子行也不必记得各自中和。
+    // 这四行都承载模型或用户可写的文本——记忆正文、关键词、子项目目录名。
+    return neutralizeBraces(parts.join('\n'));
 }
 /** 从组装上下文取当前 agent 会话的工作区 cwd（AssembleContext.agent 由 dsh-agent 声明合并提供）。 */
 function assemblyProjectCwd(assembly) {
@@ -256,7 +364,7 @@ export async function apply(ctx, config) {
                 additionalProperties: false,
                 description: 'Optional validity anchor: bind this memory to a probeable environment value so it auto-expires when that value changes. Use only for facts that depend on the environment (tool behaviour under a specific version, config decided by an env var). 可选锚点：把记忆绑到可探测的环境值，值变了自动失效。只用于「随环境变化的事实」。',
                 properties: {
-                    kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version'], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version.' },
+                    kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version', 'path-exists'], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version; path-exists = a path that should still exist (`name` = the path, `value` = `present` or `absent`).' },
                     name: { type: 'string', description: 'For kind=env: the variable name.' },
                     value: { type: 'string', required: true, description: 'The value probed at write time.' },
                 },
@@ -282,21 +390,28 @@ export async function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'memory_list',
-        description: 'List every stored memory, optionally filtered by namespace, status, or injected switch. Every memory is plaintext and inspectable. 列出全部记忆，可按 namespace/status/injected 过滤；均为明文可查。',
+        description: 'List every stored memory, optionally filtered by namespace, status, injected switch, or update time. Every memory is plaintext and inspectable. 列出全部记忆，可按 namespace/status/injected/更新时间过滤；均为明文可查。',
         parameters: {
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
             status: { type: 'string', enum: ['suggested', 'approved'], description: 'Restrict to one review status. 限定审核状态（suggested=待审核 / approved=已审核）.' },
             injected: { type: 'boolean', description: 'Restrict by the persistent-injection switch. 按常驻注入开关过滤.' },
+            after: { type: 'string', description: 'Only memories updated at/after this time: `YYYY-MM-DD`, or a relative form like `7d` / `30d`. 只返回此后更新过的记忆（`YYYY-MM-DD`，或相对形式 `7d` / `30d`）.' },
+            before: { type: 'string', description: 'Only memories updated at/before this time (same forms as `after`). 只返回此前更新过的记忆（写法同 after）.' },
         },
         output: {
             schema: { type: 'array', items: RECORD_SCHEMA },
             render: (_args, value) => renderJson(value),
         },
         execute(args, exec) {
+            const now = Date.now();
+            const after = parseTimeFilter(args.after, now);
+            const before = parseTimeFilter(args.before, now);
             return memory.list({
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.status === undefined ? {} : { status: args.status },
                 ...args.injected === undefined ? {} : { injected: args.injected },
+                ...after === undefined ? {} : { after },
+                ...before === undefined ? {} : { before },
             }, execProjectCwd(exec)).then(records => records.map(recordValue));
         },
         presentCall: () => present('List memories', 'read'),
@@ -500,18 +615,28 @@ export async function apply(ctx, config) {
             id: { type: 'string', required: true, description: 'Exact memory id from memory_list. 记忆 id（来自 memory_list）.' },
             content: { type: 'string', description: 'New content; omit to keep current. 新内容；省略则保留现有内容.' },
             keywords: { type: 'array', items: { type: 'string' }, description: 'New keywords; omit to keep current. 新关键词；省略则保留现有.' },
-            injected: { type: 'boolean', description: 'Set or clear the persistent-injection switch; omit to keep the current value. Setting it records a deliberate decision — the memory stops being auto-promoted or auto-demoted. See memory_save for what deserves residency. 设置或清除常驻注入开关；省略则保持原值。给值即视为有意决定——此后不受自动升降影响。何时该常驻见 memory_save。' },
+            supersedes: { type: 'string', description: 'Mark the memory with this id as superseded by the current one (the current record is unchanged; only the other gets the void mark). 把该 id 指向的记忆标成「被本条取代」——本条不变，只写对方的作废标记。与 content / retract 互斥。' },
+            retract: { type: 'string', description: 'Retract this memory: give a reason and it is marked void (content kept, no longer injected, still searchable). 撤回本条：给一个原因即标记作废——内容保留、不再进注入，检索仍可检回。与 content / supersedes 互斥。' },
+            injected: { type: 'boolean', description: 'Set or clear the persistent-injection switch; omit to keep the current value. Setting it records a deliberate decision — the memory stops being auto-demoted (repeated hits no longer promote anything). See memory_save for what deserves residency. 设置或清除常驻注入开关；省略则保持原值。给值即视为有意决定——此后不受自动降级影响（反复命中已不再自动开启任何东西）。何时该常驻见 memory_save。' },
         },
         output: {
             schema: RECORD_SCHEMA,
             render: (_args, value) => renderJson(value),
         },
         execute(args, exec) {
-            return memory.update(args.id, {
+            const cwd = execProjectCwd(exec);
+            const id = args.id;
+            // 三种动作互斥，按 retract > supersedes > update 的次序取第一个（与工具描述一致）：
+            // 前两个是「标状态」，第三个才是「改内容」。同时给多个时以更重的动作为准。
+            if (args.retract !== undefined)
+                return memory.retract(id, args.retract, cwd).then(recordValue);
+            if (args.supersedes !== undefined)
+                return memory.supersede(id, args.supersedes, cwd).then(recordValue);
+            return memory.update(id, {
                 ...args.content === undefined ? {} : { content: args.content },
                 ...args.keywords === undefined ? {} : { keywords: args.keywords },
                 ...args.injected === undefined ? {} : { injected: args.injected },
-            }, execProjectCwd(exec)).then(recordValue);
+            }, cwd).then(recordValue);
         },
         presentCall: args => present('Update memory', 'other', args.id),
     }));
@@ -530,4 +655,17 @@ export async function apply(ctx, config) {
         },
         presentCall: args => present('Confirm memory', 'other', args.id),
     }));
+    ctx.tools.register(defineTool({
+        name: 'memory_sweep',
+        description: 'Read-only health check: lists stale memories (with the reason), long-unused non-resident ones, candidates that keep being retrieved without being pinned, and how much of the injection budget the resident set takes. Changes nothing. 只读体检：列出失效的记忆（带原因）、久未被检索命中的非常驻记录、被反复检索却未常驻的候选，以及常驻占用了多少注入预算。不修改任何状态——最坏情况是报告不准，而不是误改内容。',
+        parameters: {},
+        output: {
+            schema: SWEEP_SCHEMA,
+            render: (_args, value) => renderJson(value),
+        },
+        execute(_args, exec) {
+            return memory.sweep(execProjectCwd(exec));
+        },
+        presentCall: () => present('Sweep memory', 'other', 'read-only'),
+    }));
 }

package/dist/injection.d.ts

@@ -18,7 +18,28 @@ export declare const OMITTED_SUMMARY_CHARS = 24;
  * 空内容/空首行回退为去掉换行后的前 maxChars（保证 any 内容有摘要）。
  */
 export declare function deriveSummary(content: string, maxChars: number): string;
+/**
+ * 中和注入副本里的字面 `{{`。DSH 的系统提示词走**严格插值**：section/context 的
+ * 文本里出现 `{{name}}` 会当场抛错（未注册 → `unknown`；名字不合
+ * `/^[a-z][a-z0-9_]*$/` → `malformed`），而组装发生在模型调用之前——该会话的
+ * 全部模型请求一起失败，模型无从自救（它改不了自己的记忆）。
+ *
+ * 循环替换直至稳定：单遍 `replaceAll` 处理不了 3 连以上左花括号——`{{{{a}}}}`
+ * 单遍得 `{ {{ {a}}}}`，仍含 `{{`。实测 1..1000 连最多 2 轮收敛。
+ *
+ * 只施加于**注入副本**：存储与面板预览都保留原文。记忆是给人看的审计窗口，
+ * 显示被改写过的内容会让人以为记忆本身被改过。
+ */
+export declare function neutralizeBraces(text: string): string;
 /** 一条注入行的渲染文本（与面板预览完全一致）。 */
+/**
+ * 日期标记（0.12.0）：`YYYY-MM-DD`，按**本地时区**取，输入是 epoch ms。
+ *
+ * 用绝对日期而不是「18 天前」：相对时间每轮都在变，会把一个稳定的注入副本变成每轮漂移的
+ * 文本——`memory:recall` 本来就是动态 context，但不必要的漂移仍应避免。**减少变化的维度
+ * 是廉价的稳定性。**
+ */
+export declare function formatDay(at: number): string;
 export declare function injectionLine(record: MemoryRecord, summaryChars: number): string;
 export interface InjectionRender {
     /** 实际注入行（已按预算截断、按更新时间降序）。 */
@@ -41,9 +62,12 @@ export interface InjectionRender {
     chars: number;
 }
 /**
- * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
- * updatedAt——最近使用/更新的记忆最先），逐条累加开销直到预算用尽；
- * 预算为 null 或非正数时全量注入（不过滤）。
+ * 由候选记录渲染注入行：按**更新时间**降序（最近更新的最先），逐条累加开销直到预算
+ * 用尽；预算为 null 或非正数时全量注入（不过滤）。
+ *
+ * 0.12.0 起不再看 `lastUsedAt`：那是**检索**留下的痕迹，而检索是「需要时才用」的行为
+ * ——拿它决定「谁每轮在场」，等于让「查得多的」挤掉「钉得牢的」，而且一次 `memory_search`
+ * 会当场改变下一轮的注入内容（`markUsed` 就在检索路径上）。排序只该由内容本身的变更驱动。
  */
 export declare function renderInjection(records: readonly MemoryRecord[], budget: number | null, summaryChars: number): InjectionRender;
 /**
@@ -54,6 +78,31 @@ export declare function renderInjection(records: readonly MemoryRecord[], budget
  * {@link OMITTED_NOTICE_LIMIT} 只列前 N 个。
  */
 export declare function omittedNotice(rendered: InjectionRender): string;
+/** 注入侧报「新失效」的条数上限——在稀有与有用之间取舍，只报几条就够指向问题。 */
+export declare const STALE_NOTICE_LIMIT = 3;
+/** 候选提示列出的条数上限。 */
+export declare const CANDIDATE_NOTICE_LIMIT = 3;
+/** 候选提示里每条摘要的长度：比注入行更短，这一行本身不该占太多。 */
+export declare const CANDIDATE_SUMMARY_CHARS = 24;
+/**
+ * 新失效提示行（0.12.0）：报「本次启动校验发现几条记忆失效」。
+ *
+ * **它稀有，所以不构成噪音**：一条记忆失效意味着「照它行动会出错」，值得每轮看见，直到被
+ * 核对回写或删除。与 {@link omittedNotice} 一样**不占注入预算**（调用方追加在注入行之后）。
+ */
+export declare function staleNotice(stale: ReadonlyArray<{
+    summary: string;
+}>): string;
+/**
+ * 候选提示行（0.12.0）：报「有几条被反复检索命中、但没有被钉成常驻」。
+ *
+ * **判断者是模型自己**——一份不会主动去调的体检报告等于不存在，所以候选必须自己走到它眼前。
+ * `hitCount` 只增不减，候选会一直留着直到被消费（钉住或删掉）：这不是缺陷，是提示该有的
+ * 持续性。**不占注入预算**。
+ */
+export declare function candidateNotice(candidates: ReadonlyArray<{
+    content: string;
+}>): string;
 /** 子项目索引行列出的条数上限（④-B）：超出以 `…` 结尾，防这行本身失控。 */
 export declare const NEIGHBOR_NOTICE_LIMIT = 5;
 /**

package/dist/injection.js

@@ -28,19 +28,53 @@ export function deriveSummary(content, maxChars) {
         return content;
     return collapsed.length <= maxChars ? collapsed : `${collapsed.slice(0, maxChars)}…`;
 }
+/**
+ * 中和注入副本里的字面 `{{`。DSH 的系统提示词走**严格插值**：section/context 的
+ * 文本里出现 `{{name}}` 会当场抛错（未注册 → `unknown`；名字不合
+ * `/^[a-z][a-z0-9_]*$/` → `malformed`），而组装发生在模型调用之前——该会话的
+ * 全部模型请求一起失败，模型无从自救（它改不了自己的记忆）。
+ *
+ * 循环替换直至稳定：单遍 `replaceAll` 处理不了 3 连以上左花括号——`{{{{a}}}}`
+ * 单遍得 `{ {{ {a}}}}`，仍含 `{{`。实测 1..1000 连最多 2 轮收敛。
+ *
+ * 只施加于**注入副本**：存储与面板预览都保留原文。记忆是给人看的审计窗口，
+ * 显示被改写过的内容会让人以为记忆本身被改过。
+ */
+export function neutralizeBraces(text) {
+    let result = text;
+    while (result.includes('{{'))
+        result = result.replaceAll('{{', '{ {');
+    return result;
+}
 /** 一条注入行的渲染文本（与面板预览完全一致）。 */
+/**
+ * 日期标记（0.12.0）：`YYYY-MM-DD`，按**本地时区**取，输入是 epoch ms。
+ *
+ * 用绝对日期而不是「18 天前」：相对时间每轮都在变，会把一个稳定的注入副本变成每轮漂移的
+ * 文本——`memory:recall` 本来就是动态 context，但不必要的漂移仍应避免。**减少变化的维度
+ * 是廉价的稳定性。**
+ */
+export function formatDay(at) {
+    const date = new Date(at);
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
 export function injectionLine(record, summaryChars) {
     // ④-A：跨工作区召回时带来源标记（`..` / `../..`）；当前工作区不带，保持既有格式
     const scope = record.scope === undefined ? '' : `@${record.scope}`;
-    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}${scope}] ${deriveSummary(record.content, summaryChars)}`;
+    // 0.12.0：日期固定在 scope 之前——日期是数字、scope 是点号，顺序固定即无歧义。
+    // 「这条是什么时候记的」直接决定要不要先核对再照它做，尤其对随环境失效的那类记忆。
+    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}@${formatDay(record.updatedAt)}${scope}] ${deriveSummary(record.content, summaryChars)}`;
 }
 /**
- * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
- * updatedAt——最近使用/更新的记忆最先），逐条累加开销直到预算用尽；
- * 预算为 null 或非正数时全量注入（不过滤）。
+ * 由候选记录渲染注入行：按**更新时间**降序（最近更新的最先），逐条累加开销直到预算
+ * 用尽；预算为 null 或非正数时全量注入（不过滤）。
+ *
+ * 0.12.0 起不再看 `lastUsedAt`：那是**检索**留下的痕迹，而检索是「需要时才用」的行为
+ * ——拿它决定「谁每轮在场」，等于让「查得多的」挤掉「钉得牢的」，而且一次 `memory_search`
+ * 会当场改变下一轮的注入内容（`markUsed` 就在检索路径上）。排序只该由内容本身的变更驱动。
  */
 export function renderInjection(records, budget, summaryChars) {
-    const ordered = [...records].sort((left, right) => (right.lastUsedAt ?? right.updatedAt) - (left.lastUsedAt ?? left.updatedAt));
+    const ordered = [...records].sort((left, right) => right.updatedAt - left.updatedAt);
     const lines = [];
     const omittedRecords = [];
     let chars = 0;
@@ -77,6 +111,40 @@ export function omittedNotice(rendered) {
     const truncated = rendered.omittedRecords.length > shown.length ? '…' : '';
     return `（另有 ${rendered.omitted} 条常驻因预算未注入：${labels.join('、')}${truncated}）`;
 }
+/** 注入侧报「新失效」的条数上限——在稀有与有用之间取舍，只报几条就够指向问题。 */
+export const STALE_NOTICE_LIMIT = 3;
+/** 候选提示列出的条数上限。 */
+export const CANDIDATE_NOTICE_LIMIT = 3;
+/** 候选提示里每条摘要的长度：比注入行更短，这一行本身不该占太多。 */
+export const CANDIDATE_SUMMARY_CHARS = 24;
+/**
+ * 新失效提示行（0.12.0）：报「本次启动校验发现几条记忆失效」。
+ *
+ * **它稀有，所以不构成噪音**：一条记忆失效意味着「照它行动会出错」，值得每轮看见，直到被
+ * 核对回写或删除。与 {@link omittedNotice} 一样**不占注入预算**（调用方追加在注入行之后）。
+ */
+export function staleNotice(stale) {
+    if (stale.length === 0)
+        return '';
+    const shown = stale.slice(0, STALE_NOTICE_LIMIT);
+    const truncated = stale.length > shown.length ? '…' : '';
+    return `（本次校验发现 ${stale.length} 条记忆失效：${shown.map(item => item.summary).join('、')}${truncated}）`;
+}
+/**
+ * 候选提示行（0.12.0）：报「有几条被反复检索命中、但没有被钉成常驻」。
+ *
+ * **判断者是模型自己**——一份不会主动去调的体检报告等于不存在，所以候选必须自己走到它眼前。
+ * `hitCount` 只增不减，候选会一直留着直到被消费（钉住或删掉）：这不是缺陷，是提示该有的
+ * 持续性。**不占注入预算**。
+ */
+export function candidateNotice(candidates) {
+    if (candidates.length === 0)
+        return '';
+    const shown = candidates.slice(0, CANDIDATE_NOTICE_LIMIT);
+    const labels = shown.map(record => deriveSummary(record.content, CANDIDATE_SUMMARY_CHARS));
+    const truncated = candidates.length > shown.length ? '…' : '';
+    return `（另有 ${candidates.length} 条被反复检索但未常驻：${labels.join('、')}${truncated}）`;
+}
 /** 子项目索引行列出的条数上限（④-B）：超出以 `…` 结尾，防这行本身失控。 */
 export const NEIGHBOR_NOTICE_LIMIT = 5;
 /**

package/dist/self.js

@@ -5,6 +5,8 @@
  * 0.9.2：补齐常驻注入机制——`injected` 参数、注入预算上限、预算诊断行的含义。
  * 0.10.0：修正工具清单（6 → 10，补提示词模板工具）与两层记忆说明——原清单漏了
  * `prompt_*` 系列，照它读会以为本插件只有记忆工具。
+ * 0.12.0：工具清单 10 → 11（补 `memory_sweep`）；删掉「命中累计 2 次自动开启常驻」
+ * （该规则已取消，命中只喂候选提示）；注入取舍依据由「最近使用」改为「最近更新」。
  */
 import { createRequire } from 'node:module';
 export const SELF_VERSION = (() => {
@@ -19,7 +21,7 @@ export const SELF_VERSION = (() => {
     }
 })();
 export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
-    + '你有 10 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget（`memory_confirm` 仅在用户明确要求放行隔离记录时用）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）。'
+    + '你有 11 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget / memory_sweep（`memory_confirm` 仅在用户明确要求放行隔离记录时用；`memory_sweep` 是只读体检——失效清单、久未命中、候选与预算占用，不修改任何状态）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）。'
     + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
     + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
     + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
@@ -30,9 +32,9 @@ export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话
     + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确。'
     + '写入即生效（`approved`），人工只在例外时介入；命中密钥/凭据规则的写入会被隔离（不进注入与检索）。'
     + '**常驻注入**：每轮注入「global + 当前会话工作区」里 approved 且开着常驻开关的记忆单行摘要（形如 `- [memory:id:namespace] 摘要`）；全文要靠 memory_search 取。'
-    + '开关有两条自动规则：命中累计 2 次自动开启、30 天未命中自动撤下；**给 memory_save / memory_update 传 `injected` 即显式接管**，此后这两条都不再适用。'
+    + '开关只有一条自动规则：**自动升上来的**常驻在 30 天未命中后撤下；命中次数不再自动改变注入状态（它只喂体检报告的候选提示）。**给 memory_save / memory_update 传 `injected` 即显式接管**，此后这条规则也不再适用。'
     + '**钉的判据是「失效可察觉性」**：这条记忆若没被想起来，你会不会根本意识不到自己漏了它？会 → 钉常驻（规则 / 委托 / 判据）；不会 → 留检索（事实 / 参考 / 案例）。'
-    + '**注入有预算**（默认 1500 字符，约装 11 条），装不下的整条丢弃、按最近使用优先取舍——所以「钉了常驻」只等于「有资格排队」。'
+    + '**注入有预算**（默认 1500 字符，约装 11 条），装不下的整条丢弃、按**最近更新**优先取舍（不是最近被检索——检索是「需要时才用」的行为，拿它决定「谁每轮在场」会让查得多的挤掉钉得牢的）——所以「钉了常驻」只等于「有资格排队」。'
     + '装不下时注入末尾会出现一行 `（另有 N 条常驻因预算未注入：…短摘要…）`——**那是「有常驻记忆并不在场」的唯一信号**，看到它就该逐条评估撤下。'
     + '发现某条记忆与实际不符时用 memory_update 修正（保持生效）；确认没用的用 memory_forget。'
     + '（English: dsh-memory provides cross-session memory. Writes take effect immediately; save durable preferences, corrections and reusable conclusions — not transient state, guesses, or facts readable from the repo (record where to look instead). Always add multi-angle keywords. Pass `injected: true` to keep one resident every turn — reserve that for rules and standing agreements; facts stay search-only. Resident injection runs on a budget, so a pinned memory is only queued, never guaranteed to be in context.)';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {
@@ -26,7 +26,8 @@
     "docs/shots",
     "scripts/scan-orphans.mjs",
     "scripts/unzstd-frames.mjs",
-    "scripts/ancestor-probe.mjs"
+    "scripts/ancestor-probe.mjs",
+    "scripts/analyze-cooccurrence.mjs"
   ],
   "dsh": {
     "bundle": {
@@ -58,6 +59,7 @@
     "build": "tsc -p tsconfig.json && node build-client.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
+    "mutate:check": "node scripts/mutate-check.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {

package/scripts/analyze-cooccurrence.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * 关键词共现分析——回答「记忆之间有没有关系网」。
+ *
+ * **为什么需要它**：记忆系统有两个方向可选——「报规模与主题」（我们现在的做法）与
+ * 「给记忆建关系」（图 / 相关推荐）。选哪个不该靠直觉，而该看数据里到底有没有关系。
+ * 本脚本就是量这件事的：把两条记忆共享的关键词个数当关联强度，统计多少对有关联、
+ * 它们连成几个簇、多少条是孤立点。
+ *
+ * **能回答什么**：
+ * - 孤立点占比——**关系维度值不值得做**的第一判据。孤立率高（比如 >50%）说明记忆
+ *   本质是「一条条独立事实」，图与相关推荐都没有数据支撑。
+ * - 簇的规模与主题——若确实成簇，簇内高频词就是「成片的主题」，比全局词频 top-N 更聚焦。
+ * - 阈值敏感度——共享 1 个词 vs 2 个词的对数比，决定「关联」的门槛该定在哪。
+ *
+ * **判据怎么算**：
+ * - 只统计 approved、非隔离、非模板（`kind !== 'prompt'`）的记录——与 `indexNotice` /
+ *   `recallRecords` 的候选口径一致，否则会把不该参与的东西算进来。
+ * - 关联门槛默认「共享 ≥2 个关键词」。**不要降到 1**：实测共享 1 个的有 273 对、
+ *   共享 ≥2 的只有 38 对（7 倍差），降到 1 等于把「都含 dsh」也算成关联。
+ * - 连通分量用洪水填充；**孤立点 = 自己成一个分量的记录**。
+ *
+ * **哪些情况答不了**：
+ * - 只做**词面**共现，不理解语义：「pnpm」与「包管理器」不共享词就是孤立点，哪怕它们
+ *   讲的是同一件事。跨过这一层需要语义检索（见 `docs/决策/2026-09-18-语义检索通道启用判据.md`）。
+ * - 结论只在「关键词是多角度的」这个前提下成立：若写入时关键词给得敷衍（比如都只给一个
+ *   项目名），脚本会报出虚高的关联。
+ * - **只读**：不写任何存储文件，可随时重跑。
+ *
+ * 用法：
+ *   node scripts/analyze-cooccurrence.mjs [--workspace <路径>] [--min-shared N] [--top N] [--help]
+ *
+ * 退出码：0 = 正常；2 = 用法错误。
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const USAGE = `关键词共现分析——回答「记忆之间有没有关系网」。
+
+用法：
+  node scripts/analyze-cooccurrence.mjs [--workspace <路径>] [--min-shared N] [--top N] [--help]
+
+  --workspace P   工作区根（默认从 cwd 起向上找第一个含 .dsh/storages 的目录）
+  --min-shared N  关联门槛：共享几个关键词才算有关联（默认 2，不建议降到 1）
+  --top N         展示最大的几个簇（默认 5）
+
+只读，不写任何文件。
+退出码：0 = 正常；2 = 用法错误。`
+
+const argv = process.argv.slice(2)
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(USAGE)
+  process.exit(0)
+}
+const readString = (name) => {
+  const index = argv.indexOf(name)
+  return index === -1 ? undefined : argv[index + 1]
+}
+const readNumber = (name, fallback) => {
+  const raw = readString(name)
+  if (raw === undefined) return fallback
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value < 0) {
+    console.error(`${name} 需要一个非负整数，收到：${raw}`)
+    process.exit(2)
+  }
+  return value
+}
+const MIN_SHARED = readNumber('--min-shared', 2)
+const TOP = readNumber('--top', 5)
+
+/** 从 cwd 起向上找第一个含 `.dsh/storages` 的目录——工作区根通常就是它。 */
+function findWorkspace(start) {
+  let current = start
+  for (;;) {
+    if (existsSync(join(current, '.dsh', 'storages'))) return current
+    const parent = dirname(current)
+    if (parent === current) return start
+    current = parent
+  }
+}
+
+const workspace = readString('--workspace') ?? findWorkspace(process.cwd())
+const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+
+/**
+ * 两个存储：`project` 在工作区下（随 git 分享），`global` 在 DSH_HOME 下。
+ * project 的文件名带 cwd 哈希后缀，所以扫目录而不是拼固定名；双重前缀的历史残骸
+ * （`memory_project_memory_project_*`）不是当前代码认得的名字，排除掉。
+ */
+const sources = []
+const projectStorages = join(workspace, '.dsh', 'storages')
+let projectNames = []
+try {
+  projectNames = readdirSync(projectStorages)
+} catch {
+  projectNames = [] // 工作区没有 project 存储：只分析 global
+}
+for (const name of projectNames) {
+  if (!name.startsWith('memory_project') || !name.endsWith('.json')) continue
+  if (name.startsWith('memory_project_memory_project')) continue
+  sources.push(['project', join(projectStorages, name)])
+}
+sources.push(['global', join(dshHome, 'storages', 'memory.json')])
+
+console.log(`工作区：${workspace}`)
+console.log(`DSH_HOME：${dshHome}\n`)
+
+const records = []
+for (const [namespace, file] of sources) {
+  let doc
+  try {
+    doc = JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    continue // 存储不存在或读不动：跳过，不报错
+  }
+  for (const [id, block] of Object.entries(doc.tables?.blocks ?? {})) {
+    if (block === null || typeof block !== 'object' || typeof block.content !== 'string') continue
+    if (block.quarantined === true) continue
+    if ((block.status ?? 'approved') !== 'approved') continue
+    if ((block.kind ?? 'fact') === 'prompt') continue
+    records.push({
+      id: String(id),
+      namespace,
+      keywords: new Set((block.keywords ?? []).map(keyword => String(keyword).toLowerCase())),
+      title: block.content.split('\n')[0].slice(0, 46),
+    })
+  }
+}
+
+if (records.length === 0) {
+  console.log('没有可分析的记忆（未找到 project / global 存储，或库里没有 approved 记录）。')
+  process.exit(0)
+}
+
+console.log(`候选记忆：${records.length} 条（approved、非隔离、非模板）`)
+const sizes = records.map(record => record.keywords.size)
+console.log(`关键词密度：平均 ${(sizes.reduce((a, b) => a + b, 0) / sizes.length).toFixed(1)} / 最少 ${Math.min(...sizes)} / 最多 ${Math.max(...sizes)}`)
+console.log(`关联门槛：共享 ≥${MIN_SHARED} 个关键词\n`)
+
+const histogram = new Map()
+const adjacency = new Map()
+const link = (a, b) => {
+  if (!adjacency.has(a)) adjacency.set(a, new Set())
+  if (!adjacency.has(b)) adjacency.set(b, new Set())
+  adjacency.get(a).add(b)
+  adjacency.get(b).add(a)
+}
+for (let i = 0; i < records.length; i += 1) {
+  for (let j = i + 1; j < records.length; j += 1) {
+    let shared = 0
+    for (const keyword of records[i].keywords) if (records[j].keywords.has(keyword)) shared += 1
+    if (shared === 0) continue
+    histogram.set(shared, (histogram.get(shared) ?? 0) + 1)
+    if (shared >= MIN_SHARED) link(records[i].id, records[j].id)
+  }
+}
+
+console.log('共享关键词个数的分布（对数）：')
+for (const [shared, count] of [...histogram.entries()].sort((a, b) => a[0] - b[0])) {
+  const noise = shared === 1 ? '   ← 噪声级，通常不计入关联' : ''
+  console.log(`  ${String(shared).padStart(2)} 个 → ${String(count).padStart(4)} 对${noise}`)
+}
+
+const seen = new Set()
+const clusters = []
+for (const record of records) {
+  if (seen.has(record.id)) continue
+  const stack = [record.id]
+  const component = []
+  seen.add(record.id)
+  while (stack.length > 0) {
+    const current = stack.pop()
+    component.push(current)
+    for (const neighbor of adjacency.get(current) ?? []) {
+      if (!seen.has(neighbor)) {
+        seen.add(neighbor)
+        stack.push(neighbor)
+      }
+    }
+  }
+  clusters.push(component)
+}
+clusters.sort((a, b) => b.length - a.length)
+const isolated = clusters.filter(cluster => cluster.length === 1).length
+
+console.log(`\n连通分量：${clusters.length} 个`)
+console.log(`  规模：${clusters.map(cluster => cluster.length).slice(0, 12).join(' / ')}${clusters.length > 12 ? ' …' : ''}`)
+console.log(`  孤立点：${isolated} 个（${((isolated / records.length) * 100).toFixed(0)}%）  |  参与成簇：${records.length - isolated} 个`)
+
+const byId = new Map(records.map(record => [record.id, record]))
+console.log(`\n最大的 ${TOP} 个簇（簇内高频词 = 成片的主题）：`)
+let shown = 0
+for (const component of clusters) {
+  if (component.length === 1 || shown >= TOP) break
+  shown += 1
+  const frequency = new Map()
+  for (const id of component) {
+    for (const keyword of byId.get(id).keywords) frequency.set(keyword, (frequency.get(keyword) ?? 0) + 1)
+  }
+  const top = [...frequency.entries()]
+    .filter(([, count]) => count >= 2)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 6)
+  console.log(`\n  ● ${component.length} 条：${top.map(([keyword, count]) => `${keyword}(${count})`).join('、') || '(无重复词)'}`)
+  for (const id of component.slice(0, 5)) console.log(`      · ${byId.get(id).title}`)
+  if (component.length > 5) console.log(`      … 另 ${component.length - 5} 条`)
+}