@max-null/dsh-memory 0.7.0 → 0.7.1

package/README.md

@@ -55,6 +55,16 @@ npm install @max-null/dsh-memory
 
 两个根都可用 config 覆盖（`globalRoot` / `projectRoot`）。`memory_list` / `memory_search` 不带 `namespace` 过滤时会同时查两层。旧版双重前缀文件名（`memory_project_memory_project_<hash>.json`）在打开时自动迁移为规范名。
 
+## 多实例共存（0.7.1）
+
+两个 DSH 实例（例如 DSH web 与 SSiD 桌面壳）可以同时运行、共用同一个 `DSH_HOME`，**记忆不再互相抹掉**。
+
+DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后端都声明不做跨进程协调（`storage-json`：*writer per process and last-write-wins is correct*；`storage-sqlite`：*cross-process coordination is out of scope*）。插件层的处置是**写前重读**（等价于 update 前先 select）：每次写入在串行区里先比对存储文件指纹（mtime + size），发现磁盘被别的实例动过就先重载再写。代价是磁盘没变时的一次 `statSync`。
+
+残余窗口只剩两个实例在**同一瞬间**写——此时后写者赢；同时写**不同**记忆已不再互相影响。
+
+**未覆盖**：`workspace.json`（工作区登记）由 DSH 自己的 workspace 服务写，插件层够不着，仍会被双实例互相覆盖；根因处置在上游——[discussion #6882](https://github.com/deepseek-ai/deepseek-harness/discussions/6882)。当前防线是轮转快照备份（SSiD 侧 `shell/scripts/backup-storages.mjs` + 计划任务）。
+
 ## 使用流程（写入即生效，人为例外干预）
 
 提示词模板库（0.6.0）：`prompt_search / prompt_get / prompt_list / prompt_add` 四个工具管理**模板库**——
@@ -102,6 +112,8 @@ memory_forget        →  随时删除（删除始终是人的动作）
 
 ## SSID 系列
 
+本插件是 **[SSID（思灵 · Seek Soul in Darkness）](https://github.com/Max-Null/seek-soul-in-darkness)** 全家桶的一员；也可以单独安装到任意 DSH profile——除设置页的记忆面板外不依赖其它同系列插件。
+
 ## 开发
 
 ```bash

package/dist/engine.d.ts

@@ -222,6 +222,10 @@ 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);
@@ -248,7 +252,30 @@ export declare class MemoryEngine extends Service {
      * 命中危险内容规则则隔离：`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）——命中与否都记：
@@ -283,6 +310,8 @@ export declare class MemoryEngine extends Service {
     private tableOf;
     /** 命中标记：写回 lastUsedAt 与命中次数，达标即自动升常驻（2026-09-15）。 */
     private markUsed;
+    /** {@link markUsed} 的实现体；必须经 `writeScope` 进入（`recordUse` 在此之内）。 */
+    private markUsedInner;
     /**
      * 命中记账 + 自动升级（2026-09-15 静默记忆机制）：命中次数达阈值即自动打开常驻
      * 注入——「被反复检索命中」是它值得每轮付费的唯一客观证据。统计性字段不 emit，
@@ -331,6 +360,8 @@ export declare class MemoryEngine extends Service {
      * @returns 被撤下的条数（诊断与日志用）。
      */
     demoteStale(projectCwd?: string, now?: number): Promise<number>;
+    /** {@link demoteStale} 的实现体；必须经 `writeScope` 进入。 */
+    private demoteStaleInner;
     /**
      * 锚点批量校验（2026-09-15）：会话启动时调一次，把失效的条目标成 `stale`。
      *
@@ -343,6 +374,8 @@ export declare class MemoryEngine extends Service {
      * @returns 本次状态发生变化的条数。
      */
     verifyAnchors(probes: AnchorProbes, projectCwd?: string): Promise<number>;
+    /** {@link verifyAnchors} 的实现体；必须经 `writeScope` 进入。 */
+    private verifyAnchorsInner;
     /**
      * 旧数据迁移（2026-09-15 静默记忆机制）：一次性、幂等，会话启动维护时调用。
      *
@@ -363,13 +396,21 @@ export declare class MemoryEngine extends Service {
         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 整理记忆用）。2026-09-15 起：改动**不再**
      * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态；
@@ -379,6 +420,8 @@ export declare class MemoryEngine extends Service {
         content?: string;
         keywords?: string[];
     }, projectCwd?: string): Promise<MemoryRecord>;
+    /** {@link update} 的实现体；必须经 `writeScope` 进入。 */
+    private updateInner;
     /**
      * 预热某工作区的 project 表（异步打开并缓存）。system prompt 的
      * `memory:recall` provider 是同步回调——只读已打开的表；预热让

package/dist/engine.js

@@ -5,7 +5,7 @@
  * is always created `suggested` and becomes effective only through `setStatus`.
  */
 import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { Service } from '@deepseek-ai/cordis';
@@ -170,6 +170,10 @@ export class MemoryEngine extends Service {
     /** backend 只注册一次（registry 重名抛 duplicate；reload 清缓存后不得重复注册）。 */
     registeredProjectBackends = new Set();
     facility;
+    /** 各存储文件上次被我们确认过的指纹；用于识别「另一个实例写过」。 */
+    storeStamps = new Map();
+    /** 写入串行链：「刷新—读—改—写」必须整体互斥，否则并发写会在其间穿插。 */
+    writeChain = Promise.resolve();
     /** 会话启动维护只跑一次的标记（2026-09-15）。 */
     maintenanceDone = false;
     constructor(ctx, config = {}) {
@@ -273,7 +277,87 @@ export class MemoryEngine extends Service {
      * 命中危险内容规则则隔离：`status` 留 `suggested`（天然不注入）**并且**置
      * `quarantined`（不进检索），双保险，等待人工放行或删除。
      */
+    // ── 多实例写入协调（2026-09-17）────────────────────────────────────────
+    //
+    // 另一个 DSH 实例（web 与 SSiD 同时运行）共用同一个 DSH_HOME 时，它写的记忆只落在
+    // 磁盘上；我们的内存态若比磁盘旧，下一次整份覆盖就会把对方的新记忆抹掉。DSH 的
+    // 存储层明确不做跨进程协调（storage-json「writer per process and last-write-wins
+    // is correct」、storage-sqlite「cross-process coordination is out of scope」），
+    // 所以协调放在这里：开写前比对存储文件指纹，变过就重载——等价于「update 前先
+    // select」。残余窗口只剩两个实例真正同时写，而记忆写入是低频操作。
+    /** 文件指纹：mtime + size（size 兜住同一毫秒内的两次写）。 */
+    static fileStamp(file) {
+        try {
+            const stat = statSync(file);
+            return `${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            return 'missing';
+        }
+    }
+    /** 全局记忆的存储文件（JsonStorageBackend 的 unit 文件名 = domain 名）。 */
+    globalStoreFile() {
+        return join(this.config.globalRoot ?? globalRoot(), 'memory.json');
+    }
+    /** 某工作区记忆的存储文件。 */
+    projectStoreFile(projectCwd) {
+        const key = join(projectCwd);
+        return join(this.projectRootFor(key), `${this.projectBackendName(key)}.json`);
+    }
+    /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
+    noteStoreStamps(projectCwd) {
+        const global = this.globalStoreFile();
+        this.storeStamps.set(global, MemoryEngine.fileStamp(global));
+        const scopes = new Set(this.projectTables.keys());
+        if (projectCwd !== undefined && projectCwd !== '')
+            scopes.add(join(projectCwd));
+        for (const key of scopes) {
+            const file = this.projectStoreFile(key);
+            this.storeStamps.set(file, MemoryEngine.fileStamp(file));
+        }
+    }
+    /**
+     * 写前新鲜度门：存储文件被外部改过就重载，避免整份覆盖吃掉对方的写入。
+     * 必须在取表**之前**调用——{@link reload} 重开 facility，此前取到的 table 引用会失效。
+     */
+    async refreshForWrite(projectCwd) {
+        if (this.storeStamps.size === 0) {
+            this.noteStoreStamps(projectCwd);
+            return;
+        }
+        const files = [this.globalStoreFile()];
+        if (projectCwd !== undefined && projectCwd !== '')
+            files.push(this.projectStoreFile(projectCwd));
+        for (const file of files) {
+            if (MemoryEngine.fileStamp(file) === this.storeStamps.get(file))
+                continue;
+            await this.reload();
+            this.noteStoreStamps(projectCwd);
+            return;
+        }
+    }
+    /**
+     * 一次写入的完整作用域：串行化 → 新鲜度门 → 执行 → 记指纹。
+     * 刷新与「读—改—写」必须同处一个互斥区，否则并发写会在两者之间穿插。
+     * @param projectCwd - 本次写入涉及的工作区；无则只覆盖全局存储。
+     * @param run - 实际的读改写；必须在内部重新取表（刷新后旧引用失效）。
+     * @returns `run` 的返回值。
+     */
+    writeScope(projectCwd, run) {
+        const task = this.writeChain.then(async () => {
+            await this.refreshForWrite(projectCwd);
+            const result = await run();
+            this.noteStoreStamps(projectCwd);
+            return result;
+        });
+        this.writeChain = task.then(() => undefined, () => undefined);
+        return task;
+    }
     async remember(input, projectCwd) {
+        return this.writeScope(projectCwd, () => this.rememberInner(input, projectCwd));
+    }
+    /** {@link remember} 的实现体；必须经 `writeScope` 进入（多实例写入协调）。 */
+    async rememberInner(input, projectCwd) {
         const namespace = input.namespace ?? 'global';
         const table = namespace === 'project'
             ? await this.projectTableFor(projectCwd)
@@ -479,13 +563,17 @@ export class MemoryEngine extends Service {
     }
     /** 命中标记：写回 lastUsedAt 与命中次数，达标即自动升常驻（2026-09-15）。 */
     async markUsed(ids, projectCwd) {
+        return this.writeScope(projectCwd, () => this.markUsedInner(ids, projectCwd));
+    }
+    /** {@link markUsed} 的实现体；必须经 `writeScope` 进入（`recordUse` 在此之内）。 */
+    async markUsedInner(ids, projectCwd) {
         if (ids.length === 0)
             return;
         const now = Date.now();
         const global = this.requireTable('global');
-        const project = projectCwd === undefined || projectCwd === ''
-            ? undefined
-            : this.projectTables.get(join(projectCwd));
+        // 取表走异步版：`writeScope` 可能在本次进入前刚 `reload()`（外部实例改过存储），
+        // 那时同步缓存已被清空——继续读缓存会把 project 侧的命中静默漏记。
+        const project = await this.projectTableFor(projectCwd);
         for (const id of ids) {
             const globalBlock = global.get(id);
             if (globalBlock !== undefined) {
@@ -625,6 +713,10 @@ export class MemoryEngine extends Service {
      * @returns 被撤下的条数（诊断与日志用）。
      */
     async demoteStale(projectCwd, now = Date.now()) {
+        return this.writeScope(projectCwd, () => this.demoteStaleInner(projectCwd, now));
+    }
+    /** {@link demoteStale} 的实现体；必须经 `writeScope` 进入。 */
+    async demoteStaleInner(projectCwd, now = Date.now()) {
         const threshold = now - AUTO_DEMOTE_DAYS * 24 * 60 * 60 * 1000;
         const tables = [this.requireTable('global')];
         if (projectCwd !== undefined && projectCwd !== '') {
@@ -664,6 +756,10 @@ export class MemoryEngine extends Service {
      * @returns 本次状态发生变化的条数。
      */
     async verifyAnchors(probes, projectCwd) {
+        return this.writeScope(projectCwd, () => this.verifyAnchorsInner(probes, projectCwd));
+    }
+    /** {@link verifyAnchors} 的实现体；必须经 `writeScope` 进入。 */
+    async verifyAnchorsInner(probes, projectCwd) {
         const tables = [this.requireTable('global')];
         if (projectCwd !== undefined && projectCwd !== '') {
             const project = await this.projectTableFor(projectCwd);
@@ -713,6 +809,10 @@ export class MemoryEngine extends Service {
      * @returns 迁移统计（放行 / 隔离 / 回填计数）。
      */
     async migrateLegacy(projectCwd) {
+        return this.writeScope(projectCwd, () => this.migrateLegacyInner(projectCwd));
+    }
+    /** {@link migrateLegacy} 的实现体；必须经 `writeScope` 进入。 */
+    async migrateLegacyInner(projectCwd) {
         const tables = [this.requireTable('global')];
         if (projectCwd !== undefined && projectCwd !== '') {
             const project = await this.projectTableFor(projectCwd);
@@ -778,6 +878,10 @@ export class MemoryEngine extends Service {
         return stats;
     }
     async forget(id, projectCwd) {
+        return this.writeScope(projectCwd, () => this.forgetInner(id, projectCwd));
+    }
+    /** {@link forget} 的实现体；必须经 `writeScope` 进入。 */
+    async forgetInner(id, projectCwd) {
         if (await this.requireTable('global').delete(id)) {
             this.ctx.emit('memory/changed', { operation: 'forgotten', id });
             return true;
@@ -790,6 +894,10 @@ export class MemoryEngine extends Service {
         return false;
     }
     async setStatus(id, status, projectCwd) {
+        return this.writeScope(projectCwd, () => this.setStatusInner(id, status, projectCwd));
+    }
+    /** {@link setStatus} 的实现体；必须经 `writeScope` 进入。 */
+    async setStatusInner(id, status, projectCwd) {
         const global = this.requireTable('global').get(id);
         if (global !== undefined) {
             const updated = {
@@ -830,6 +938,10 @@ export class MemoryEngine extends Service {
      * 「常驻注入」开关调用（remote.setInjected）。
      */
     async setInjected(id, injected, projectCwd) {
+        return this.writeScope(projectCwd, () => this.setInjectedInner(id, injected, projectCwd));
+    }
+    /** {@link setInjected} 的实现体；必须经 `writeScope` 进入。 */
+    async setInjectedInner(id, injected, projectCwd) {
         const locate = async () => {
             const global = this.requireTable('global').get(id);
             if (global !== undefined)
@@ -872,6 +984,10 @@ export class MemoryEngine extends Service {
      * `injected` 保留原值。若新内容命中危险规则则转为隔离（与写入路径同一判定）。
      */
     async update(id, patch, projectCwd) {
+        return this.writeScope(projectCwd, () => this.updateInner(id, patch, projectCwd));
+    }
+    /** {@link update} 的实现体；必须经 `writeScope` 进入。 */
+    async updateInner(id, patch, projectCwd) {
         const applyPatch = (block) => {
             const normalized = normalizeBlock(block);
             const content = patch.content ?? block.content;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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": {
@@ -22,7 +22,9 @@
     "client.js",
     "cordis.patch.yml",
     "README.md",
-    "LICENSE", "docs/shots"],
+    "LICENSE",
+    "docs/shots"
+  ],
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"