@max-null/dsh-memory 0.10.0 → 0.11.0

package/README.md

@@ -39,8 +39,8 @@ npm install @max-null/dsh-memory
 
 ## 提供的服务与工具
 
-- **服务** `ctx.memory`：`remember` / `list` / `search` / `forget` / `setStatus`
-- **工具**：`memory_save`、`memory_list`、`memory_search`、`memory_confirm`、`memory_forget`、`memory_update`
+- **服务** `ctx.memory`：`remember` / `list` / `search` / `forget` / `setStatus` / `move`
+- **工具**：`memory_save`、`memory_list`、`memory_search`、`memory_confirm`、`memory_forget`、`memory_update`、`memory_move`
 - **注入**：`tool:memory` 指引 section（工具用法 + 常驻注入判据）+ `memory:self` 机制自述 + `memory:recall` 召回 context（global 的 `approved + injected` + 当前会话工作区的 `approved + injected`，带 `[memory:<id>:<namespace>]` 来源标记；摘要化 + 预算截断）
 - **检索**：BM25（CJK 单字 + 2-gram，content 与 keywords 字段分离加权；中文多字查询精度显著优于单字切分）；可选语义融合（见「可选配置」）
 
@@ -55,7 +55,7 @@ npm install @max-null/dsh-memory
 
 两个根都可用 config 覆盖（`globalRoot` / `projectRoot`）。`memory_list` / `memory_search` 不带 `namespace` 过滤时会同时查两层。旧版双重前缀文件名（`memory_project_memory_project_<hash>.json`）在打开时自动迁移为规范名。
 
-## 跨工作区可见性（0.10.0）
+## 跨工作区可见性（0.10.0 / 0.11.0）
 
 project 记忆按**会话工作区**分文件存放，所以「工作区」就是可见性的边界。0.10.0 起补了三个方向——针对的是同一个盲区：**不知道存在**（检索是有意图的动作，搜不出自己不知道存在的东西）。
 
@@ -67,10 +67,14 @@ project 记忆按**会话工作区**分文件存放，所以「工作区」就
 
 三条边界：**写入永远只落当前工作区**（「我在这个项目里记的东西」不该被推理到别处）；但**检索得到的记录就改得动**——`memory_update` / `memory_forget` 同样沿链定位；**注入路径只读当前工作区**（远处的记忆进检索、不进每轮成本）。
 
+**0.11.0 起，「放错了层」有了显式的修正通道**：`memory_move(id, to)` 把一条记忆移到 `global`、`self`（当前工作区）或相对祖先（`..` / `../..`）。它是**例外动作**——默认写入仍然只落当前工作区，只有当你判定「这条其实属于上一层、或上一层的那一支」时才动它。移动**保持 id**、**从源层删除**（不是复制），并报告移动后源层是否仍看得见它：向上移动源层不失明（继承只向上，`global` 人人可见），向下移动则会让源层及其下层从此看不见它。典型用途是**把放高了的记忆降回它真正属于的工作区**——比如只属于某一个生态的规矩躺在 `global` 里、漏进了无关项目。判据与边界见设计文档 §3.2。
+
 后两行**不占注入预算**、自消除（没有内容时整行不出现），且**长度常数级**——不随记忆增长。索引行里的主题取自各条的关键词词频，与检索用的是同一套词汇，所以**索引里出现的词就是能搜到的词**。
 
 **孤儿文件清点**：`node scripts/scan-orphans.mjs [根目录]` 报出「哪些记忆文件当前代码已经打不开」（历史命名遗留：早期无哈希后缀、双重 `memory_project_` 前缀）。**只读，不做任何处置**——旧文件可能含未过隔离检查的内容，处置需人工拍板。
 
+**祖先链诊断与探针**：`node scripts/ancestor-probe.mjs plan [--cwd <会话 cwd>]` 只读地复算该 cwd 的祖先链（哪些层级带记忆文件、引擎会纳入几级），并回答「这个 cwd 上祖先链是否**可观测**」——若以上祖先层都没有记忆文件，祖先链生效与否行为逐字相同，那是个零差异的观测点。要实测检索侧跨链，用 `seed` / `check` / `clean` 在祖先层造一条临时探针再撤销。**前提**：探针只对**没打开过该层**的会话有效——引擎的表打开即缓存，而写路径的新鲜度门（`refreshForWrite`）只比对 global 与当前 cwd，**不含祖先层**，被缓存过的层会用陈旧内存态覆盖掉外部写入。
+
 ## 多实例共存（0.7.1）
 
 两个 DSH 实例（例如 DSH web 与 SSiD 桌面壳）可以同时运行、共用同一个 `DSH_HOME`，**记忆不再互相抹掉**。
@@ -143,6 +147,9 @@ npm run typecheck   # tsc 严格类型检查
 npm test            # vitest 单测
 npm run build       # 产出 dist/
 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
 ```
 
 ## 依赖（peerDependencies，由宿主提供）

package/dist/engine.d.ts

@@ -178,6 +178,11 @@ export type MemoryChange = {
     operation: 'quarantined';
     id: MemoryId;
     quarantined: boolean;
+} | {
+    operation: 'moved';
+    id: MemoryId;
+    from: string;
+    to: string;
 };
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -364,6 +369,15 @@ export declare class MemoryEngine extends Service {
      * 那时同步缓存已被清空（同 {@link markUsedInner} 的注释）。
      */
     private locateRecord;
+    /**
+     * 写入协调覆盖的存储文件：global + **全部已打开的工作区表** + 本次 cwd。
+     *
+     * 记录（{@link noteStoreStamps}）与比对（{@link refreshForWrite}）必须共用这一个定义——
+     * 两边各写一份正是漂移的来源：在此之前比对侧只列 global + cwd，而 ④-A 把**读**路径扩到了
+     * 祖先链（`projectChain`），于是被缓存过的祖先层「指纹记下了却从不被检查」——外部改动看不见，
+     * 下一次写回把它**整份覆盖**。**读扩到哪，门就得跟着扩到哪。**
+     */
+    private storeScopeFiles;
     /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
     private noteStoreStamps;
     /**
@@ -508,6 +522,34 @@ export declare class MemoryEngine extends Service {
     forget(id: MemoryId, projectCwd?: string): Promise<boolean>;
     /** {@link forget} 的实现体；必须经 `writeScope` 进入。 */
     private forgetInner;
+    /**
+     * 把一条记忆移到另一层（迭代设计 §3.2）。**两个方向共用一个操作**：向上提到祖先层或
+     * `global`，向下把误放高层的降回它真正属于的工作区。
+     *
+     * 原设计（`memory_promote`）只允许向上，理由是「往下或横向会让原本能看见的人失明」。
+     * 但**移动的本意就是改变谁能看见**——那不是副作用，是目的。所以约束从「禁止方向」
+     * 换成「让后果可见」：返回值里的 `sourceStillSees` 就是那个后果。
+     */
+    move(id: MemoryId, to: string, projectCwd?: string): Promise<{
+        id: MemoryId;
+        from: string;
+        to: string;
+        sourceStillSees: boolean;
+    }>;
+    /** {@link move} 的实现体；必须经 `writeScope` 进入。 */
+    private moveInner;
+    /** 按 id 定位记录**并带上它所在的层**（`locateRecord` 只返回表，而移动必须知道来源层）。 */
+    private locateWithKey;
+    /**
+     * 解析 `memory_move` 的目标：`global`、`self` / `.`（当前 cwd），或相对祖先（`..`、`../..`）。
+     *
+     * 用**相对深度**而不是绝对路径，是为了和来源标记 `scope`（`..` / `../..`）说同一套话。
+     * 允许落在**还没有记忆文件**的祖先层——移动是显式动作，在那儿创建文件正是目的，
+     * 不是 `projectChain` 要避免的那种副作用。
+     */
+    private static resolveTarget;
+    /** `ancestor` 是否就是 `node` 本身或它的祖先——用来判断移动后源层是否仍看得见。 */
+    private static isAncestorOrSelf;
     setStatus(id: MemoryId, status: MemoryStatus, projectCwd?: string): Promise<MemoryRecord>;
     /** {@link setStatus} 的实现体；必须经 `writeScope` 进入。 */
     private setStatusInner;

package/dist/engine.js

@@ -508,15 +508,26 @@ export class MemoryEngine extends Service {
         }
         return undefined;
     }
-    /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
-    noteStoreStamps(projectCwd) {
-        const global = this.globalStoreFile();
-        this.storeStamps.set(global, MemoryEngine.fileStamp(global));
+    /**
+     * 写入协调覆盖的存储文件：global + **全部已打开的工作区表** + 本次 cwd。
+     *
+     * 记录（{@link noteStoreStamps}）与比对（{@link refreshForWrite}）必须共用这一个定义——
+     * 两边各写一份正是漂移的来源：在此之前比对侧只列 global + cwd，而 ④-A 把**读**路径扩到了
+     * 祖先链（`projectChain`），于是被缓存过的祖先层「指纹记下了却从不被检查」——外部改动看不见，
+     * 下一次写回把它**整份覆盖**。**读扩到哪，门就得跟着扩到哪。**
+     */
+    storeScopeFiles(projectCwd) {
+        const files = [this.globalStoreFile()];
         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);
+        for (const key of scopes)
+            files.push(this.projectStoreFile(key));
+        return files;
+    }
+    /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
+    noteStoreStamps(projectCwd) {
+        for (const file of this.storeScopeFiles(projectCwd)) {
             this.storeStamps.set(file, MemoryEngine.fileStamp(file));
         }
     }
@@ -529,10 +540,7 @@ export class MemoryEngine extends Service {
             this.noteStoreStamps(projectCwd);
             return;
         }
-        const files = [this.globalStoreFile()];
-        if (projectCwd !== undefined && projectCwd !== '')
-            files.push(this.projectStoreFile(projectCwd));
-        for (const file of files) {
+        for (const file of this.storeScopeFiles(projectCwd)) {
             if (MemoryEngine.fileStamp(file) === this.storeStamps.get(file))
                 continue;
             await this.reload();
@@ -1111,6 +1119,97 @@ export class MemoryEngine extends Service {
         }
         return false;
     }
+    /**
+     * 把一条记忆移到另一层（迭代设计 §3.2）。**两个方向共用一个操作**：向上提到祖先层或
+     * `global`，向下把误放高层的降回它真正属于的工作区。
+     *
+     * 原设计（`memory_promote`）只允许向上，理由是「往下或横向会让原本能看见的人失明」。
+     * 但**移动的本意就是改变谁能看见**——那不是副作用，是目的。所以约束从「禁止方向」
+     * 换成「让后果可见」：返回值里的 `sourceStillSees` 就是那个后果。
+     */
+    async move(id, to, projectCwd) {
+        return this.writeScope(projectCwd, () => this.moveInner(id, to, projectCwd));
+    }
+    /** {@link move} 的实现体；必须经 `writeScope` 进入。 */
+    async moveInner(id, to, projectCwd) {
+        const target = MemoryEngine.resolveTarget(to, projectCwd);
+        const found = await this.locateWithKey(id, projectCwd);
+        if (found === undefined)
+            throw new Error(`cannot move unknown memory '${id}'`);
+        const destination = target.kind === 'global'
+            ? this.requireTable('global')
+            : await this.projectTableFor(target.key);
+        if (destination === undefined)
+            throw new Error('cannot move a project memory without a workspace cwd');
+        if (destination === found.table)
+            throw new Error(`memory '${id}' is already stored in '${to}'`);
+        // 先写目标、再删源：中间态里它同时存在于两处（重复好过丢失），而两次写同处一个
+        // writeScope，外部看不到中间态。
+        await destination.put(id, found.block);
+        await found.table.delete(id);
+        // 继承只向上，而 global 人人可见——所以「移进 global」与「移进自己的某个祖先」都能
+        // 让源层继续看得见它；反过来（global → 某工作区、祖先 → 后代）就是缩小范围。
+        const sourceStillSees = target.kind === 'global'
+            || (found.key !== 'global' && MemoryEngine.isAncestorOrSelf(target.key, found.key));
+        const movedTo = target.kind === 'global' ? 'global' : target.key;
+        this.ctx.emit('memory/changed', { operation: 'moved', id, from: found.key, to: movedTo });
+        return { id, from: found.key, to: movedTo, sourceStillSees };
+    }
+    /** 按 id 定位记录**并带上它所在的层**（`locateRecord` 只返回表，而移动必须知道来源层）。 */
+    async locateWithKey(id, projectCwd) {
+        const global = this.requireTable('global');
+        const globalBlock = global.get(id);
+        if (globalBlock !== undefined)
+            return { key: 'global', table: global, block: globalBlock };
+        for (const { key, table } of await this.projectChainTables(projectCwd)) {
+            const block = table.get(id);
+            if (block !== undefined)
+                return { key, table, block };
+        }
+        return undefined;
+    }
+    /**
+     * 解析 `memory_move` 的目标：`global`、`self` / `.`（当前 cwd），或相对祖先（`..`、`../..`）。
+     *
+     * 用**相对深度**而不是绝对路径，是为了和来源标记 `scope`（`..` / `../..`）说同一套话。
+     * 允许落在**还没有记忆文件**的祖先层——移动是显式动作，在那儿创建文件正是目的，
+     * 不是 `projectChain` 要避免的那种副作用。
+     */
+    static resolveTarget(to, projectCwd) {
+        const raw = to.trim();
+        if (raw === 'global')
+            return { kind: 'global' };
+        if (projectCwd === undefined || projectCwd === '') {
+            throw new Error('moving a memory into a workspace layer needs a session cwd');
+        }
+        if (raw === 'self' || raw === '.')
+            return { kind: 'workspace', key: join(projectCwd) };
+        const parts = raw.split(/[\\/]/).filter(part => part !== '' && part !== '.');
+        if (!parts.every(part => part === '..')) {
+            throw new Error(`unknown move target '${to}' — use 'global', 'self', or a relative ancestor ('..', '../..')`);
+        }
+        let key = join(projectCwd);
+        for (let i = 0; i < parts.length; i++) {
+            const parent = dirname(key);
+            if (parent === key)
+                throw new Error(`move target '${to}' points above the filesystem root`);
+            key = parent;
+        }
+        return { kind: 'workspace', key };
+    }
+    /** `ancestor` 是否就是 `node` 本身或它的祖先——用来判断移动后源层是否仍看得见。 */
+    static isAncestorOrSelf(ancestor, node) {
+        const want = join(ancestor).toLowerCase();
+        let cur = join(node);
+        for (;;) {
+            if (cur.toLowerCase() === want)
+                return true;
+            const parent = dirname(cur);
+            if (parent === cur)
+                return false;
+            cur = parent;
+        }
+    }
     async setStatus(id, status, projectCwd) {
         return this.writeScope(projectCwd, () => this.setStatusInner(id, status, projectCwd));
     }

package/dist/index.js

@@ -109,6 +109,11 @@ const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and pr
     + 'architecture decisions, its pitfalls). '
     + '用一句话选 namespace——**换个项目，这条还成立吗？** 成立 → `global`（偏好、习惯、环境知识）；'
     + '不成立 → `project`（本仓库自己的约定、架构决策、它踩过的坑）。'
+    + 'Record where a conclusion came from, not just the conclusion: the reason it holds, and the situation '
+    + 'that forced it out. A conclusion without its origin is a ruler with no provenance — it looks '
+    + 'self-evident, and self-evident things get applied mechanically. '
+    + '记结论时一并记下**它是怎么来的**——它为什么成立，以及是什么场景把它逼出来的。没有出处的结论像一把'
+    + '没有来历的尺子：看起来天经地义，而天经地义的东西最容易被机械套用。'
     + '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 '
@@ -463,6 +468,31 @@ export async function apply(ctx, config) {
         },
         presentCall: args => present('Forget memory', 'other', args.id),
     }));
+    ctx.tools.register(defineTool({
+        name: 'memory_move',
+        description: 'Move one memory to another layer: `global`, `self` (the current workspace), or a relative ancestor (`..` / `../..`). Use it when a memory sits at the wrong level — a project-specific rule parked in `global` that leaks into unrelated workspaces, or a fact that turned out to hold for sibling projects too. The record keeps its id, and the result reports whether the source layer still sees it. 把一条记忆移到另一层：`global`、`self`（当前工作区）或相对祖先（`..` / `../..`）。用于记忆待错了层——只属于某个项目的规矩躺在 `global` 里、漏进无关工作区，或某条事实其实对兄弟项目也成立。id 保持不变，结果里会报告移动后源层是否仍看得见它。',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Exact memory id from memory_list or memory_search. 要移动的记忆 id。' },
+            to: { type: 'string', required: true, description: 'Target layer: `global`, `self` (current workspace), or a relative ancestor such as `..` / `../..`. 目标层：`global`、`self`（当前工作区），或 `..` / `../..` 这样的相对祖先。' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    from: { type: 'string', required: true, description: '移动前所在的层（`global` 或工作区路径）。' },
+                    to: { type: 'string', required: true, description: '移动后的层。' },
+                    sourceStillSees: { type: 'boolean', required: true, description: '源层移动后是否仍看得见它。为假表示源层及其下层从此看不见这条记忆。' },
+                },
+            },
+            render: (_args, value) => renderJson(value),
+        },
+        execute(args, exec) {
+            return memory.move(args.id, args.to, execProjectCwd(exec));
+        },
+        presentCall: args => present('Move memory', 'other', `${args.id} → ${args.to}`),
+    }));
     ctx.tools.register(defineTool({
         name: 'memory_update',
         description: 'Update the content, keywords or persistent-injection switch of one stored memory (e.g. correcting stale facts). The record keeps its review status; content that looks like a credential quarantines it instead. 修改一条记忆的内容、关键词或常驻注入开关（如修正过时信息）。改动后记忆保持原有审核状态；若新内容命中危险规则则转为隔离。',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.10.0",
+  "version": "0.11.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": {
@@ -24,7 +24,9 @@
     "README.md",
     "LICENSE",
     "docs/shots",
-    "scripts/scan-orphans.mjs"
+    "scripts/scan-orphans.mjs",
+    "scripts/unzstd-frames.mjs",
+    "scripts/ancestor-probe.mjs"
   ],
   "dsh": {
     "bundle": {

package/scripts/ancestor-probe.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+/**
+ * 祖先链探针——验证 dsh-memory「④-A 祖先链」在**运行时**是否生效。
+ *
+ * **为什么需要它**：`test/workspace-chain.spec.ts` 证明的是代码逻辑，证明不了
+ * 「装进 profile、跑在真实会话里」的行为。而运行时验证有个陷阱：`scope` 标记只在
+ * **跨级命中**时出现，得先有一个「带记忆的祖先层」——可这台机器上 `H:\MaxNull\.dsh`
+ * 这类祖先层往往**根本不存在**。于是「在子项目会话里搜父目录记忆」这件事，在祖先链
+ * 失效时表现**逐字相同**（零可观测差异的观测点）。所以要先**把前提造出来**。
+ *
+ * **能回答什么**：
+ *   - `plan`：当前 cwd 的祖先链解析结果——链上有哪些层、每层期望的文件名、哪些真的存在。
+ *     这就是引擎 `projectChain()` 的 `existsSync` 判定，可在会话外独立复算。
+ *   - `seed` / `clean`：造出 / 撤销「祖先层有记忆」这个前提。
+ *   - `check`：探针是否被**跨链记账**——`markUsed` 跨链生效时，`hitCount` 会被写回
+ *     **祖先层自己的文件**（这正是「祖先记录不会被 30 天规则误撤」的机制）。
+ *
+ * **判据怎么算**：
+ *   - 链 = `projectChain()` 的同语义实现：沿 cwd 向上、depth 每步 +1、**只收文件已存在的层**。
+ *     本例内置 djb2 指纹自检（见 `FINGERPRINTS`）——算法漂移时报错退出，而不是**静默算错
+ *     文件名**（路径形式敏感，`H:\a\b` 与 `H:/a/b` 哈希不同，错了不报错，只是找不到）。
+ *   - `check` 看三个数：`records`（该层记录总数）、`hitCount`、`lastUsedAt`。
+ *     `hitCount > 0` 且 `lastUsedAt` 晚于 `createdAt` = 被跨链命中过。
+ *
+ * **哪些情况答不了**：
+ *   - **只对「尚未打开过该层的会话」有效（最要紧的一条）**：引擎的工作区表是**打开一次就
+ *     缓存**的，而写路径的新鲜度门 `refreshForWrite()` 只比对 **global + 当前 cwd** 两个
+ *     文件——**不含祖先层**。于是同一个会话若此前打开过目标层（跑过 `check`、或搜过该层
+ *     的记忆），seed 出的探针**它看不到**；更糟的是该会话下一次对该层的命中记账会把磁盘
+ *     **改写成它的内存态**，探针被直接抹掉。判据：`check` 报「没有探针记录」而文件里躺着的
+ *     是别的记录（往往是上一轮删掉的旧记录，`hitCount` 还在涨），那就是被覆盖了。
+ *     要用探针，就**换一个没打开过该层的会话**，或者重启会话。
+ *   - **答不了「检索是否跨链」**：`memory_search` 是模型工具，脚本调不到。本脚本负责
+ *     「造前提」与「读记账」，中间那一步（在会话里搜 token、看结果有没有 `scope` 字段）
+ *     必须由调用它的会话完成——这是全流程里唯一不能脚本化的一步。
+ *   - **不打开 DSH 存储设施**：只用 `fs` 直接读写那个 JSON 文件，不开句柄、不碰引擎缓存。
+ *     所以它给的是**文件层事实**；引擎内存态是否正确，由 `check` 之后的会话行为体现。
+ *   - **只验「链只向上」的一半**：脚本能算出 cwd 的祖先链，但看不到子目录。
+ *     「父目录会话看不到子目录记忆」要另开会话验（判据：索引行条数不含子目录那些）。
+ *   - 不判断记忆内容质量，不迁移、不合并、不触碰任何**非探针**记录。
+ *
+ * 用法：
+ *   node scripts/ancestor-probe.mjs plan  [--cwd <会话 cwd>]
+ *   node scripts/ancestor-probe.mjs seed  --layer <祖先层绝对路径> [--cwd <会话 cwd>] --apply
+ *   node scripts/ancestor-probe.mjs check --layer <祖先层绝对路径>
+ *   node scripts/ancestor-probe.mjs clean --layer <祖先层绝对路径> --apply
+ *   node scripts/ancestor-probe.mjs --help
+ *
+ * 完整流程（五步）：
+ *   1) plan                            看链；若已有祖先层带记忆 → 直接用它，跳过 2
+ *   2) seed --layer <层> --apply        造探针（打印一个 token）
+ *   3) 在**同一 cwd 的会话里** memory_search 那个 token —— 命中且结果带 `scope` 即检索侧生效
+ *   4) check --layer <层>               读 hitCount：被记账 = 定位侧（markUsed 跨链）生效
+ *   5) clean --layer <层> --apply       撤销前提，恢复原状（空目录一并收回）
+ *
+ * 退出码：0 成功 / 1 前置条件不满足（拒绝执行）/ 2 用法错误 / 3 算法指纹不自检。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const PROBE_MARKER = '[ancestor-chain-probe]'
+
+// djb2 指纹：必须与 src/engine.ts 的 projectBackendName 逐字一致。写成常量表而非注释，
+// 是为了在算法漂移时**报错**——哈希错了不会抛异常，只会静默指向另一个文件。
+const FINGERPRINTS = [
+  ['dsh-memory', 'oy76k6'],
+  ['workstation', '3kjfw6'],
+  ['a', '3t3a'],
+  ['', '45h'], // 空串 = 5381 的 base36，即 djb2 初值
+  ['h:\\X', 'ykhwcb'], // 与 'H:\\x' 同值——顺带验证 toLowerCase 也在算法里
+  ['H:\\x', 'ykhwcb'],
+]
+
+const USAGE = `祖先链探针——验证 dsh-memory「④-A 祖先链」在运行时是否生效。
+
+用法：
+  node scripts/ancestor-probe.mjs plan  [--cwd <会话 cwd>]
+  node scripts/ancestor-probe.mjs seed  --layer <祖先层绝对路径> [--cwd <会话 cwd>] --apply
+  node scripts/ancestor-probe.mjs check --layer <祖先层绝对路径>
+  node scripts/ancestor-probe.mjs clean --layer <祖先层绝对路径> --apply
+  node scripts/ancestor-probe.mjs --help
+
+  --cwd 默认取进程工作目录；脚本通常从仓库目录运行，**它未必等于你的会话 cwd**，
+        所以对不上时务必显式传。
+  seed / clean 必须带 --apply 才真的写盘；不带就是 dry-run（只打印将做什么）。
+
+退出码：0 成功 / 1 前置条件不满足（拒绝执行）/ 2 用法错误 / 3 算法指纹不自检。`
+
+/** 与 engine.ts:484-489 逐字对应（含 toLowerCase、|0 截断、abs 后取 base36）。 */
+function projectBackendName(cwd) {
+  let h = 5381
+  const text = cwd.toLowerCase()
+  for (let i = 0; i < text.length; i++) h = ((h << 5) + h + text.charCodeAt(i)) | 0
+  return `memory_project_${Math.abs(h).toString(36)}`
+}
+
+const projectRootFor = (cwd) => path.join(cwd, '.dsh', 'storages')
+const layerFile = (layer) => path.join(projectRootFor(path.join(layer)), `${projectBackendName(path.join(layer))}.json`)
+
+/** cwd 的全部祖先层（含自身，depth 0 起）——与链无关，plan 用它展示「上面有什么」。 */
+function ancestorLayers(cwd) {
+  const key = path.join(cwd)
+  const out = [{ key, depth: 0 }]
+  let cur = key
+  let depth = 0
+  for (;;) {
+    const parent = path.dirname(cur)
+    if (parent === cur) break // 到盘根
+    cur = parent
+    depth += 1
+    out.push({ key: cur, depth })
+  }
+  return out
+}
+
+/** 引擎 projectChain() 的同语义实现：只收**记忆文件已存在**的层（depth 0 自身始终纳入）。 */
+function projectChain(cwd) {
+  return ancestorLayers(cwd).filter((l) => l.depth === 0 || fs.existsSync(layerFile(l.key)))
+}
+
+function readDoc(file) {
+  if (!fs.existsSync(file)) return undefined
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+function probeRecords(doc) {
+  const blocks = doc?.tables?.blocks
+  if (blocks === undefined) return []
+  return Object.entries(blocks).filter(([, b]) => typeof b.content === 'string' && b.content.includes(PROBE_MARKER))
+}
+
+function selfCheck() {
+  const bad = []
+  for (const [input, expect] of FINGERPRINTS) {
+    const want = `memory_project_${expect}`
+    const got = projectBackendName(input)
+    if (got !== want) bad.push(`${JSON.stringify(input)}: 期望 ${want}，实得 ${got}`)
+  }
+  if (bad.length > 0) {
+    console.error('算法指纹不自检——projectBackendName 与 src/engine.ts 已不一致：')
+    for (const line of bad) console.error(`  ${line}`)
+    console.error('  → 先核对 src/engine.ts 的 projectBackendName，再更新本脚本的 FINGERPRINTS。')
+    process.exit(3)
+  }
+}
+
+function parseArgs(argv) {
+  const out = { command: undefined, apply: false, help: false, cwd: undefined, layer: undefined }
+  const rest = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--apply') out.apply = true
+    else if (a === '--help' || a === '-h') out.help = true
+    else if (a === '--cwd' || a === '--layer') {
+      const v = argv[++i]
+      if (v === undefined || v.startsWith('--')) {
+        console.error(`参数 ${a} 缺值`)
+        process.exit(2)
+      }
+      out[a.slice(2)] = v
+    } else if (a.startsWith('-')) {
+      console.error(`未知参数：${a}\n\n${USAGE}`)
+      process.exit(2)
+    } else rest.push(a)
+  }
+  out.command = rest[0]
+  return out
+}
+
+function cmdPlan(args) {
+  const cwd = path.join(args.cwd ?? process.cwd())
+  const layers = ancestorLayers(cwd)
+  const chain = projectChain(cwd)
+
+  console.log(`cwd = ${cwd}`)
+  if (args.cwd === undefined) {
+    console.log('      （取自进程工作目录；**若它不等于你的会话 cwd，请用 --cwd 重跑**——链是按会话 cwd 算的）')
+  }
+  console.log('\n祖先层（depth 0 = 自身）：')
+  console.log('  depth  存在记忆文件  记录数  路径')
+  for (const l of layers) {
+    const file = layerFile(l.key)
+    const exists = fs.existsSync(file)
+    let count = '-'
+    if (exists) {
+      try {
+        count = String(Object.keys(readDoc(file)?.tables?.blocks ?? {}).length)
+      } catch {
+        count = '解析失败'
+      }
+    }
+    console.log(`  ${String(l.depth).padEnd(6)} ${(exists ? '是' : '否').padEnd(14)} ${count.padEnd(8)} ${l.key}`)
+  }
+
+  const withMemory = chain.filter((l) => l.depth > 0)
+  console.log(`\n引擎会纳入的链：${chain.length} 级（自身 + ${withMemory.length} 个祖先层）`)
+
+  if (withMemory.length > 0) {
+    const nearest = withMemory[0]
+    const scopeText = Array.from({ length: nearest.depth }, () => '..').join('/')
+    console.log(`\n结论：**可以直接验证，不必造探针**——最近的带记忆祖先层是 ${nearest.key}`)
+    console.log(`  在会话里搜该层任一记忆的关键词，结果应带 scope="${scopeText}"。`)
+  } else {
+    const candidate = layers.find((l) => l.depth === 1)
+    if (candidate === undefined) {
+      console.log('\n结论：cwd 已在盘根，**没有祖先层可放探针** → 换一个更深的 cwd 再验。')
+      process.exit(1)
+    }
+    console.log('\n结论：**祖先链在当前 cwd 上是零可观测差异的**——以上祖先层都没有记忆文件，')
+    console.log('      祖先链无论生效与否，行为逐字相同。要观测它，先造一层：')
+    console.log(`\n  node scripts/ancestor-probe.mjs seed --layer "${candidate.key}" --cwd "${cwd}" --apply`)
+  }
+}
+
+function cmdSeed(args) {
+  if (args.layer === undefined) {
+    console.error(`seed 需要 --layer <祖先层绝对路径>\n\n${USAGE}`)
+    process.exit(2)
+  }
+  const cwd = path.join(args.cwd ?? process.cwd())
+  const layer = path.join(args.layer)
+
+  if (layer === cwd) {
+    console.error('拒绝：--layer 等于 cwd 自身。探针必须放在**祖先**层——同层命中证明不了跨链。')
+    process.exit(1)
+  }
+  const layers = ancestorLayers(cwd)
+  if (!layers.some((l) => l.key === layer)) {
+    console.error(`拒绝：${layer} 不是 ${cwd} 的祖先层（链只向上，放子目录无效）。`)
+    process.exit(1)
+  }
+
+  const file = layerFile(layer)
+  const existing = readDoc(file)
+  if (existing !== undefined) {
+    const blocks = existing.tables?.blocks ?? {}
+    const mine = probeRecords(existing)
+    if (mine.length > 0) {
+      console.error(`拒绝：${file} 里已经有探针记录（${mine.length} 条）。先 clean 再 seed。`)
+      process.exit(1)
+    }
+    if (Object.keys(blocks).length > 0) {
+      console.error(`拒绝：${file} 已含 ${Object.keys(blocks).length} 条真实记录，不去动它——`)
+      console.error('      请换一层，或直接用它做验证（plan 会指出这种「祖先层本来就有记忆」的情况）。')
+      process.exit(1)
+    }
+  }
+
+  const token = `aprobe${crypto.randomBytes(4).toString('hex')}`
+  const depth = layers.find((l) => l.key === layer).depth
+  const scope = Array.from({ length: depth }, () => '..').join('/')
+  const now = Date.now()
+  const id = crypto.randomUUID()
+
+  if (!args.apply) {
+    console.log('[dry-run] 将写入（加 --apply 才真的写）：')
+    console.log(`  文件  ${file}`)
+    console.log(`  记录  ${id}`)
+    console.log(`  令牌  ${token}`)
+    console.log(`  层深  depth ${depth}（对应 scope="${scope}"）`)
+    process.exit(0)
+  }
+
+  const doc = existing ?? {
+    unit: { name: projectBackendName(layer), version: 1 },
+    global: null,
+    tables: { blocks: {} },
+  }
+  doc.tables ??= { blocks: {} }
+  doc.tables.blocks ??= {}
+  doc.tables.blocks[id] = {
+    namespace: 'project',
+    status: 'approved',
+    injected: false,
+    content:
+      `${PROBE_MARKER} 临时探针，验证完请删——用 scripts/ancestor-probe.mjs clean 收尾。\n\n` +
+      `由 ancestor-probe.mjs seed 写入祖先层 \`${layer}\`（depth ${depth}），` +
+      `目的是让会话 cwd \`${cwd}\` 拥有一个「带记忆的祖先层」，从而让 ④-A 祖先链可被观测。\n\n` +
+      `检索令牌：${token}`,
+    keywords: [token, '祖先链探针', 'ancestor-chain-probe', '④-A 验证'],
+    createdAt: now,
+    updatedAt: now,
+    hitCount: 0,
+  }
+
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`, 'utf8')
+
+  console.log(`已写入探针 → ${file}`)
+  console.log(`  记录  ${id}`)
+  console.log(`  令牌  ${token}`)
+  console.log(`  层深  depth ${depth}（结果里应出现 scope="${scope}"）`)
+  console.log('\n下一步（脚本做不到，必须由会话完成）：')
+  console.log(`  1) 在同一 cwd 的会话里 memory_search "${token}" —— 命中等且结果带 scope="${scope}" 即检索侧生效`)
+  console.log(`  2) node scripts/ancestor-probe.mjs check --layer "${layer}"`)
+  console.log('\n⚠️ 前提：目标层必须是**本会话此前没有打开过**的层。引擎的表打开即缓存，而写路径的')
+  console.log('   新鲜度门（refreshForWrite）只比对 global + 当前 cwd，不含祖先层——已经被缓存过的')
+  console.log('   层，探针不但搜不到，还会被该会话的内存态覆盖掉。第 1 步搜不到就先换会话。')
+}
+
+function cmdCheck(args) {
+  if (args.layer === undefined) {
+    console.error(`check 需要 --layer <祖先层绝对路径>\n\n${USAGE}`)
+    process.exit(2)
+  }
+  const layer = path.join(args.layer)
+  const file = layerFile(layer)
+  const doc = readDoc(file)
+  if (doc === undefined) {
+    console.error(`该层没有记忆文件：${file}`)
+    process.exit(1)
+  }
+  const blocks = doc.tables?.blocks ?? {}
+  const mine = probeRecords(doc)
+  console.log(`层   ${layer}`)
+  console.log(`文件 ${file}`)
+  console.log(`记录总数 ${Object.keys(blocks).length}，其中探针 ${mine.length} 条`)
+  if (mine.length === 0) {
+    console.log('\n该层没有探针记录。磁盘上现有的记录：')
+    const others = Object.entries(blocks)
+    if (others.length === 0) console.log('  （空表）')
+    for (const [id, b] of others) {
+      console.log(`  ${id}  hitCount=${b.hitCount ?? 0}  keywords=${JSON.stringify((b.keywords ?? []).slice(0, 2))}`)
+    }
+    console.log('\n两种可能：① 这层本来就有真实记忆——用 plan 给出的关键词直接验证即可；')
+    console.log('          ② 探针被运行中会话的内存态覆盖了（该层此前被打开过）——换会话重试。')
+    process.exit(1)
+  }
+  for (const [id, b] of mine) {
+    const used = b.lastUsedAt === undefined ? '从未' : new Date(b.lastUsedAt).toISOString()
+    console.log(`\n探针 ${id}`)
+    console.log(`  hitCount   ${b.hitCount ?? 0}`)
+    console.log(`  createdAt  ${new Date(b.createdAt).toISOString()}`)
+    console.log(`  lastUsedAt ${used}`)
+    if ((b.hitCount ?? 0) > 0 && b.lastUsedAt !== undefined && b.lastUsedAt > b.createdAt) {
+      console.log('  → **被跨链命中并记账了**：markUsed 路径生效，祖先记录不会被 30 天规则误撤。')
+    } else {
+      console.log('  → 还没被记账。若你已经在会话里搜过这个令牌并命中，说明检索侧通了但记账没回写；')
+      console.log('    若根本没搜过，先做 seed 输出里的第 1 步。')
+    }
+  }
+}
+
+function cmdClean(args) {
+  if (args.layer === undefined) {
+    console.error(`clean 需要 --layer <祖先层绝对路径>\n\n${USAGE}`)
+    process.exit(2)
+  }
+  const layer = path.join(args.layer)
+  const file = layerFile(layer)
+  const doc = readDoc(file)
+  if (doc === undefined) {
+    console.error(`该层没有记忆文件，无需清理：${file}`)
+    process.exit(1)
+  }
+  const mine = probeRecords(doc)
+  if (mine.length === 0) {
+    console.error(`拒绝：${file} 里没有探针记录（只有本脚本写的探针才会被删）。`)
+    process.exit(1)
+  }
+
+  const rmDirs = []
+  const storages = projectRootFor(layer)
+  const dshDir = path.join(layer, '.dsh')
+
+  if (!args.apply) {
+    console.log('[dry-run] 将删除（加 --apply 才真的删）：')
+    console.log(`  ${mine.length} 条探针记录，位于 ${file}`)
+    console.log(`  若文件因此变空 → 删文件；若上级目录变空 → 一并收回 ${storages}`)
+    process.exit(0)
+  }
+
+  for (const [id] of mine) delete doc.tables.blocks[id]
+  if (Object.keys(doc.tables.blocks).length === 0) {
+    fs.rmSync(file)
+    console.log(`已删除探针文件 ${file}`)
+    for (const d of [storages, dshDir]) {
+      if (fs.existsSync(d) && fs.readdirSync(d).length === 0) {
+        fs.rmdirSync(d)
+        rmDirs.push(d)
+      }
+    }
+    for (const d of rmDirs) console.log(`已收回空目录 ${d}`)
+  } else {
+    fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`, 'utf8')
+    console.log(`已从 ${file} 删除 ${mine.length} 条探针记录（该层还有 ${Object.keys(doc.tables.blocks).length} 条真实记录，文件保留）`)
+  }
+  console.log('\n若前面观察到索引行条数因探针 +1，下一轮注入应回落到原值——链是实时 existsSync 现算的。')
+}
+
+const args = parseArgs(process.argv.slice(2))
+if (args.help || args.command === undefined) {
+  console.log(USAGE)
+  process.exit(args.help ? 0 : 2)
+}
+selfCheck()
+
+switch (args.command) {
+  case 'plan':
+    cmdPlan(args)
+    break
+  case 'seed':
+    cmdSeed(args)
+    break
+  case 'check':
+    cmdCheck(args)
+    break
+  case 'clean':
+    cmdClean(args)
+    break
+  default:
+    console.error(`未知子命令：${args.command}\n\n${USAGE}`)
+    process.exit(2)
+}

package/scripts/unzstd-frames.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * 多帧 zstd 解压——读 DSH 会话日志的必经一步。
+ *
+ * **为什么需要它**：DSH 的会话日志（`session.v3.jsonl.zstd`）不是单个 zstd 流，而是
+ * **多个独立帧拼接**的结果（一段事件写一帧）。`zlib.zstdDecompressSync()` 只解**第一帧**
+ * 就返回——于是 1.9 MB 的日志读出来只有头一行，看起来像「日志是空的」，极易误判。
+ * Node 的 zstd 绑定没有暴露「解全部帧」的选项，所以只能自己切帧。
+ *
+ * **能回答什么**：把 `*.jsonl.zstd` 还原成完整 jsonl 文本，交给后续分析——事件普查、
+ * 找某次工具调用、统计 token 压力、解剖一个会话到底做了什么。
+ *
+ * **判据怎么算**：zstd 帧的 magic number 是 `28 B5 2F FD`（小端）；扫描它在文件中的
+ * 全部出现位置即为候选帧边界，再逐帧解压。输出行的三个数就是判据：
+ * `frames`（切出几帧）、`ok`（解出几帧）、`failed`（几帧失败）。**failed > 0 说明切帧
+ * 切错了**——多半是压缩数据内部恰好出现了那 4 个字节（magic 扫描法的已知局限）。
+ *
+ * **哪些情况答不了**：
+ * - 逐字节扫描 magic 会有**假阳性**。feral > 0 时真帧通常仍能解出，但**不保证完整**；
+ *   要 100% 可靠需解析 zstd 帧头（`Frame_Header_Descriptor` 的长度字段），本脚本没做到。
+ * - 只做**解压**，不解析 jsonl 语义——事件类型、token 统计属于调用方。
+ * - **明文 jsonl 不需要它**：DSH 从 GUI 导出的会话就是明文（`session.v3.jsonl`），
+ *   直接 `readFileSync` 即可，别绕这一道。
+ *
+ * 用法：
+ *   node scripts/unzstd-frames.mjs <源 .zstd> <目标 .jsonl>
+ *   node scripts/unzstd-frames.mjs --help
+ *
+ * 退出码：0 = 全部帧解出；1 = 有帧失败（结果可能不完整）；2 = 用法错误。
+ */
+import fs from 'node:fs'
+import zlib from 'node:zlib'
+
+const USAGE = `多帧 zstd 解压——读 DSH 会话日志的必经一步。
+
+用法：
+  node scripts/unzstd-frames.mjs <源 .zstd> <目标 .jsonl>
+  node scripts/unzstd-frames.mjs --help
+
+退出码：0 = 全部帧解出；1 = 有帧失败（结果可能不完整）；2 = 用法错误。`
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(USAGE)
+  process.exit(0)
+}
+if (args.length < 2) {
+  console.error(USAGE)
+  process.exit(2)
+}
+const [src, dst] = args
+if (!fs.existsSync(src)) {
+  console.error(`源文件不存在：${src}`)
+  process.exit(2)
+}
+
+const buf = fs.readFileSync(src)
+const MAGIC = [0x28, 0xb5, 0x2f, 0xfd] // zstd frame magic（小端）
+const positions = []
+for (let i = 0; i + 3 < buf.length; i++) {
+  if (buf[i] === MAGIC[0] && buf[i + 1] === MAGIC[1] && buf[i + 2] === MAGIC[2] && buf[i + 3] === MAGIC[3]) {
+    positions.push(i)
+  }
+}
+positions.push(buf.length) // 末帧以文件长度收尾
+
+const parts = []
+let ok = 0
+let failed = 0
+for (let i = 0; i + 1 < positions.length; i++) {
+  const slice = buf.subarray(positions[i], positions[i + 1])
+  try {
+    parts.push(zlib.zstdDecompressSync(slice))
+    ok += 1
+  } catch (error) {
+    // 不在这里尝试 stream 容错：`createZstdDecompress()` 是异步的，在同步块里 end() 之后
+    // 立刻取 chunks 必然拿不到数据。宁可如实报告失败，也不给一个看似成功的空结果。
+    failed += 1
+    console.error(`  帧 ${i}（偏移 ${positions[i]}）解压失败：${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+const out = Buffer.concat(parts)
+fs.writeFileSync(dst, out)
+console.log(`frames=${positions.length - 1} ok=${ok} failed=${failed}`)
+console.log(`输出 ${out.length} 字节 → ${dst}`)
+if (failed > 0) {
+  console.error('⚠️ 有帧未解出，结果可能不完整（magic 扫描法的已知局限，见脚本头部注释）')
+  process.exit(1)
+}