@max-null/dsh-memory 0.6.1 → 0.7.1

package/dist/engine.d.ts

@@ -6,6 +6,9 @@
  */
 import { Service } from '@deepseek-ai/cordis';
 import { type PromptFile } from './prompt-files.ts';
+import type { AnchorProbes, MemoryAnchor } from './anchors.ts';
+import type { MemorySource, SourceStat } from './query-log.ts';
+export type { MemorySource, QueryLogEntry, SourceStat } from './query-log.ts';
 declare const memoryIdBrand: unique symbol;
 /** Opaque identity of one stored memory record. */
 export type MemoryId = string & {
@@ -15,8 +18,9 @@ export type MemoryId = string & {
 export declare function MemoryId(id: string): MemoryId;
 export type MemoryNamespace = 'global' | 'project';
 /**
- * 审核维度（0.3.0）：`suggested` 待审核（模型写入）；`approved` 已人工
- * 审核通过。注入与否由独立维度 `injected` 控制（见 MemoryRecord）。
+ * 审核维度（0.3.0）：`suggested` 未生效；`approved` 已生效。2026-09-15 起写入默认
+ * `approved`（静默机制），`suggested` 主要留给被隔离的记录与人工回退。
+ * 注入与否由独立维度 `injected` 控制（见 MemoryRecord）。
  */
 export type MemoryStatus = 'suggested' | 'approved';
 /**
@@ -46,6 +50,28 @@ export interface MemoryRecord {
     status: MemoryStatus;
     /** 注入维度：true = 每轮全量注入 system prompt（常驻）；false = 仅检索。 */
     injected: boolean;
+    /**
+     * 隔离位（2026-09-15）：命中危险内容规则 → 不进注入、不进检索，等人工放行或删除。
+     * 与 `status` 双保险：隔离记录同时保持 `suggested`，即使某条路径漏了过滤也不会注入。
+     */
+    quarantined: boolean;
+    /** 隔离原因（命中的规则名，诊断与面板展示用）。 */
+    quarantineReason?: string;
+    /** 命中次数（2026-09-15 淘汰机制）：被 memory_search 命中的累计次数。 */
+    hitCount: number;
+    /**
+     * 写入来源（2026-09-15 反例 5）：'agent' = 主模型写入，'human' = 人工写入；
+     * 缺省 = 旧记录（来源未知，不猜测）。影响力统计按它聚合（见 sourceStats）。
+     */
+    source?: MemorySource;
+    /** 注入由信号自动开启（true）还是人工设置（缺省）；只有自动开的会被「长期未命中」自动降级。 */
+    injectedAuto?: boolean;
+    /** 有效性锚点（2026-09-15）：绑定到某个可探测的环境值；值变了即失效。 */
+    anchor?: MemoryAnchor;
+    /** 锚点已失效（由会话启动时的校验写入）；失效不删除，只降权并在检索结果里标注。 */
+    stale?: boolean;
+    /** 失效原因（锚点名 + 声明值 vs 当前值，诊断用）。 */
+    staleReason?: string;
     content: string;
     keywords: string[];
     createdAt: number;
@@ -61,11 +87,20 @@ export interface MemoryWrite {
     content: string;
     namespace?: MemoryNamespace;
     keywords?: string[];
+    /** 写入来源（2026-09-15）；缺省 'agent'（主模型写入）。面板等人工路径传 'human'。 */
+    source?: MemorySource;
+    /**
+     * 有效性锚点（可选，2026-09-15）：把这条记忆绑定到某个可探测的环境值上，值变了即自动
+     * 失效。只用于「随环境变化的事实」（某工具版本下的行为、某环境变量决定的配置）。
+     */
+    anchor?: MemoryAnchor;
 }
 export interface MemoryFilter {
     namespace?: MemoryNamespace;
     status?: MemoryStatus;
     injected?: boolean;
+    /** 隔离过滤（2026-09-15）：缺省排除隔离记录；传 true 只取隔离记录（面板审用）。 */
+    quarantined?: boolean;
     /** 记录类别过滤（0.6.0）；缺省不过滤（工具层显式传 kind='fact' 保持旧行为）。 */
     kind?: MemoryKind;
 }
@@ -73,6 +108,36 @@ export interface MemoryHit {
     record: MemoryRecord;
     score: number;
 }
+/** 反查候选（{@link MemoryEngine.suggestKeywordGaps}）：一条「本应命中」的现存记忆。 */
+export interface KeywordGapCandidate {
+    id: string;
+    /** 正文摘要（{@link GAP_EXCERPT_CHARS} 字符以内）。 */
+    excerpt: string;
+    /** 现有关键词；补写时在其基础上追加。 */
+    keywords: string[];
+    /** 精确词元命中数：> 0 表示「现在重搜就该命中」。 */
+    exact: number;
+    /** 前缀近似命中的查询词元（如 vue3 ↔ vue）。 */
+    relaxed: string[];
+}
+/** 一个空命中查询的反查结果；`candidates` 为空即知识缺口。 */
+export interface KeywordGap {
+    query: string;
+    /** 该查询在日志里空命中的次数。 */
+    count: number;
+    /** 最近一次出现的时间。 */
+    lastAt: number;
+    candidates: KeywordGapCandidate[];
+}
+/** {@link MemoryEngine.suggestKeywordGaps} 的报告（只产出报告，不自动补写）。 */
+export interface KeywordGapReport {
+    /** 查询日志总条数。 */
+    logSize: number;
+    /** 空命中条数（含被 `limit` 截掉的查询）。 */
+    misses: number;
+    /** 逐查询的候选（最多 `limit` 个查询，按最近出现排序）。 */
+    gaps: KeywordGap[];
+}
 /** One durable memory change, emitted after the backend acknowledges the write. */
 export type MemoryChange = {
     operation: 'remembered';
@@ -88,6 +153,10 @@ export type MemoryChange = {
     operation: 'injected';
     id: MemoryId;
     injected: boolean;
+} | {
+    operation: 'quarantined';
+    id: MemoryId;
+    quarantined: boolean;
 };
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -130,6 +199,11 @@ export interface MemoryConfig {
     /** 全局提示词模板根目录（0.6.0）；默认 `$DSH_HOME/prompt-library`。
      *  project 模板随工作区（`<workspace>/.dsh/prompt-library`，与记忆同构）。 */
     promptGlobalRoot?: string;
+    /**
+     * 查询日志文件路径（2026-09-15 §六.6）；默认为全局存储根下的 `query-log.json`
+     * ——即与 `memory.json` **同目录**（`$DSH_HOME/storages/query-log.json`），不落子目录。
+     */
+    queryLogPath?: string;
 }
 /**
  * Cross-session plaintext memory over the storage hub, split by namespace:
@@ -148,6 +222,12 @@ export declare class MemoryEngine extends Service {
     /** backend 只注册一次（registry 重名抛 duplicate；reload 清缓存后不得重复注册）。 */
     private registeredProjectBackends;
     private facility?;
+    /** 各存储文件上次被我们确认过的指纹；用于识别「另一个实例写过」。 */
+    private readonly storeStamps;
+    /** 写入串行链：「刷新—读—改—写」必须整体互斥，否则并发写会在其间穿插。 */
+    private writeChain;
+    /** 会话启动维护只跑一次的标记（2026-09-15）。 */
+    private maintenanceDone;
     constructor(ctx: import('@deepseek-ai/cordis').Context, config?: MemoryConfig);
     protected [Service.init](): Promise<void>;
     /** 打开全局存储域（init 与 reload 共用；backend 复用已注册实例）。 */
@@ -167,10 +247,44 @@ export declare class MemoryEngine extends Service {
      * （JsonStorageBackend 打开时加载一次，无 watch——2026-08-19 实测）。
      */
     reload(): Promise<void>;
-    /** Create one record in `suggested` status — never self-promoting. */
+    /**
+     * Create one record. 低危内容直接 `approved`（静默生效，2026-09-15 静默记忆机制）；
+     * 命中危险内容规则则隔离：`status` 留 `suggested`（天然不注入）**并且**置
+     * `quarantined`（不进检索），双保险，等待人工放行或删除。
+     */
+    /** 文件指纹：mtime + size（size 兜住同一毫秒内的两次写）。 */
+    private static fileStamp;
+    /** 全局记忆的存储文件（JsonStorageBackend 的 unit 文件名 = domain 名）。 */
+    private globalStoreFile;
+    /** 某工作区记忆的存储文件。 */
+    private projectStoreFile;
+    /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
+    private noteStoreStamps;
+    /**
+     * 写前新鲜度门：存储文件被外部改过就重载，避免整份覆盖吃掉对方的写入。
+     * 必须在取表**之前**调用——{@link reload} 重开 facility，此前取到的 table 引用会失效。
+     */
+    private refreshForWrite;
+    /**
+     * 一次写入的完整作用域：串行化 → 新鲜度门 → 执行 → 记指纹。
+     * 刷新与「读—改—写」必须同处一个互斥区，否则并发写会在两者之间穿插。
+     * @param projectCwd - 本次写入涉及的工作区；无则只覆盖全局存储。
+     * @param run - 实际的读改写；必须在内部重新取表（刷新后旧引用失效）。
+     * @returns `run` 的返回值。
+     */
+    private writeScope;
     remember(input: MemoryWrite, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link remember} 的实现体；必须经 `writeScope` 进入（多实例写入协调）。 */
+    private rememberInner;
     list(filter?: MemoryFilter, projectCwd?: string): Promise<MemoryRecord[]>;
+    /**
+     * 关键词检索。每次成功返回的检索都记一条查询日志（⑥ 2026-09-15）——命中与否都记：
+     * 漏检不产生任何事件，只有日志能事后回答「哪些查询本该命中谁」（反例 4）。日志是旁路：
+     * 写失败只记 warn，绝不改变本次检索结果。
+     */
     search(query: string, filter?: MemoryFilter, projectCwd?: string): Promise<MemoryHit[]>;
+    /** 检索打分本体（BM25 + 可选语义融合）；查询日志由 {@link search} 记录。 */
+    private rank;
     /**
      * 语义排序（0.5.2）：查询向量 + 候选向量的余弦相似度，仅在有
      * embeddings 配置时被调用。缺失向量（新增/更新过的记录）在此补生成
@@ -178,25 +292,136 @@ export declare class MemoryEngine extends Service {
      */
     private semanticRanking;
     /** 按已知 id 定位记录所在表（global 优先，其次当前工作区表）。 */
+    /**
+     * 会话启动维护（2026-09-15）：一次扫描做完三件事——旧数据迁移、长期未命中的自动降级、
+     * 锚点批量校验。只跑一次、幂等、**失败不阻断**（记忆可用性优先于维护完成度）。
+     *
+     * 调用点在 `ensureProjectOpen`：它是 async，且每会话首次打开工作区表时必经。
+     * `memory:recall` 的 provider 是**同步**回调，不能在那里 await。
+     *
+     * @param projectCwd - 会话工作区：迁移/降级/校验都连它一起处理。
+     */
+    private runMaintenanceOnce;
+    /**
+     * 锚点探测上下文。`toolNames` 拿不到时返回 `undefined`——**不能给空数组**：那会被判成
+     * 「工具全没了」，让所有 `tool-list` 锚点误失效。
+     */
+    private anchorProbes;
     private tableOf;
-    /** 命中标记：把 lastUsedAt 写回（命中记录不存在时跳过；不 emit 事件——统计性字段）。 */
+    /** 命中标记：写回 lastUsedAt 与命中次数，达标即自动升常驻（2026-09-15）。 */
     private markUsed;
+    /** {@link markUsed} 的实现体；必须经 `writeScope` 进入（`recordUse` 在此之内）。 */
+    private markUsedInner;
+    /**
+     * 命中记账 + 自动升级（2026-09-15 静默记忆机制）：命中次数达阈值即自动打开常驻
+     * 注入——「被反复检索命中」是它值得每轮付费的唯一客观证据。统计性字段不 emit，
+     * 只有真的改变了注入状态才发 `memory/changed`。
+     */
+    private recordUse;
+    /** 查询日志（惰性创建；位置见 {@link queryLogPath}）。 */
+    private queryLogInstance?;
+    private queryLog;
+    /** 查询日志文件路径：与 `memory.json` 同目录（不落子目录）。 */
+    private queryLogPath;
+    /**
+     * 记录一次检索：查询文本（截断到 120 字符）+ 命中条数 + 时间。**失败绝不影响检索**——
+     * 日志是旁路证据，不是检索的一部分。模板库检索不进日志：`prompt_search` 复用同一条
+     * `search` 通道，但模板是文件库、不属于「记忆漏检」的观察面。
+     *
+     * 查询文本是新的明文落盘点，因此先过危险内容硬拦（与写入路径同一套规则）：命中就只记
+     * 规则名、不留原文——凭据不该因为「只是被搜了一下」而进另一个明文文件。
+     */
+    private recordQuery;
+    /**
+     * 影响力统计（⑥ / 反例 5）：按来源聚合「写入量 / 被检索命中数 / 常驻注入数」。
+     * 只算 fact 记录（模板索引不是记忆），隔离记录不计（与 list 的默认口径一致：
+     * 它们不在流通里）。「被人工删除数」暂缺的原因见 `summarizeSources` 的注释。
+     */
+    sourceStats(projectCwd?: string): Promise<SourceStat[]>;
+    /**
+     * 低频反查（⑥，**只产出报告，不自动改写**）：拿「命中 0 的查询」与既有记忆反查，
+     * 给出「本应命中却没命中」的候选，供人工或模型补 keywords。
+     *
+     * 不做自动补写：判断「这条记忆是否真该被那个查询找到」需要 LLM 语义判断，插件只提供
+     * 证据（候选为空即知识缺口——「这类知识你还没有」本身也是有用信息）。调用时机由人
+     * 或模型定，不在检索路径上、不产生每轮成本。
+     *
+     * @param projectCwd - 会话工作区；候选库连工作区记忆一起取。
+     * @param limit - 最多反查几个空命中查询（按最近出现排序）。
+     */
+    suggestKeywordGaps(projectCwd?: string, limit?: number): Promise<KeywordGapReport>;
+    /**
+     * 长期未命中的自动降级（2026-09-15 淘汰机制）：**只撤自动开的常驻注入**——人工开
+     * 的开关不会被时间悄悄关掉（那是人的决定，不是信号的结论）。判定用 lastUsedAt，
+     * 从未命中过则回退 updatedAt。会话启动时调一次即可（见 index.ts 的预热路径）。
+     *
+     * @param projectCwd - 会话工作区；给了就连工作区表一起扫。
+     * @param now - 当前时间（测试注入用）。
+     * @returns 被撤下的条数（诊断与日志用）。
+     */
+    demoteStale(projectCwd?: string, now?: number): Promise<number>;
+    /** {@link demoteStale} 的实现体；必须经 `writeScope` 进入。 */
+    private demoteStaleInner;
+    /**
+     * 锚点批量校验（2026-09-15）：会话启动时调一次，把失效的条目标成 `stale`。
+     *
+     * 失效同时**撤掉常驻注入**——内容可能已经错了，继续每轮注入就是在误导（反例 2 的
+     * 教训）；但**不删除、也不排除检索**，它在结果里带标注，等模型核对后回写。
+     * 探测不到（`undefined`）按「未校验」处理，不动任何状态。
+     *
+     * @param probes - 探测上下文（工具清单 / 自身版本 / env 读取器）。
+     * @param projectCwd - 会话工作区；给了就连工作区表一起校验。
+     * @returns 本次状态发生变化的条数。
+     */
+    verifyAnchors(probes: AnchorProbes, projectCwd?: string): Promise<number>;
+    /** {@link verifyAnchors} 的实现体；必须经 `writeScope` 进入。 */
+    private verifyAnchorsInner;
+    /**
+     * 旧数据迁移（2026-09-15 静默记忆机制）：一次性、幂等，会话启动维护时调用。
+     *
+     * 旧语义里 `suggested` 是「等人工审核」，新语义里它只剩「隔离」与「人工回退」两种含义——
+     * 不迁移的话那些记录会永久卡住：既不注入，也没人去放行。迁移逐条过危险内容检测：
+     * 安全则升 `approved`（写入即生效），命中则标 `quarantined` 进隔离（**必须先检测再放行**：
+     * 历史条目若含密钥，直接放行等于让它开始进注入）。
+     *
+     * 另外把「有 `lastUsedAt` 但无 `hitCount`」的老记录回填 `hitCount = 1`——它们可能早已被
+     * 反复用过，不该从零开始攒两次命中。旧 `injected: true` 且无 `injectedAuto` 的一律不动：
+     * 那是人工决定，不该被自动降级。
+     *
+     * @param projectCwd - 会话工作区；给了就连工作区表一起迁移。
+     * @returns 迁移统计（放行 / 隔离 / 回填计数）。
+     */
+    migrateLegacy(projectCwd?: string): Promise<{
+        approved: number;
+        quarantined: number;
+        counted: number;
+    }>;
+    /** {@link migrateLegacy} 的实现体；必须经 `writeScope` 进入。 */
+    private migrateLegacyInner;
     forget(id: MemoryId, projectCwd?: string): Promise<boolean>;
+    /** {@link forget} 的实现体；必须经 `writeScope` 进入。 */
+    private forgetInner;
     setStatus(id: MemoryId, status: MemoryStatus, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link setStatus} 的实现体；必须经 `writeScope` 进入。 */
+    private setStatusInner;
     /**
      * 注入维度开关（0.3.0）：只改 injected，不动审核状态。供 UI 面板
      * 「常驻注入」开关调用（remote.setInjected）。
      */
     setInjected(id: MemoryId, injected: boolean, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link setInjected} 的实现体；必须经 `writeScope` 进入。 */
+    private setInjectedInner;
     /**
-     * 修改一条记忆的内容/关键词（0.3.1 整理记忆用）。内容被模型改动后
-     * 必须重新人工审核：status 重置为 suggested（自然停止注入——注入仅对
-     * approved 生效）；injected 保留原值（审核通过后注入开关原样恢复）。
+     * 修改一条记忆的内容/关键词（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
+     * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态；
+     * `injected` 保留原值。若新内容命中危险规则则转为隔离（与写入路径同一判定）。
      */
     update(id: MemoryId, patch: {
         content?: string;
         keywords?: string[];
     }, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link update} 的实现体；必须经 `writeScope` 进入。 */
+    private updateInner;
     /**
      * 预热某工作区的 project 表（异步打开并缓存）。system prompt 的
      * `memory:recall` provider 是同步回调——只读已打开的表；预热让
@@ -253,4 +478,3 @@ export declare class MemoryEngine extends Service {
     /** 删除模板：md 文件与索引一并删除；未命中返回 false。 */
     promptRemove(idOrName: string, projectCwd?: string): Promise<boolean>;
 }
-export {};