@max-null/dsh-memory 0.9.2 → 0.11.0

package/dist/injection.d.ts

@@ -54,3 +54,33 @@ export declare function renderInjection(records: readonly MemoryRecord[], budget
  * {@link OMITTED_NOTICE_LIMIT} 只列前 N 个。
  */
 export declare function omittedNotice(rendered: InjectionRender): string;
+/** 子项目索引行列出的条数上限（④-B）：超出以 `…` 结尾，防这行本身失控。 */
+export declare const NEIGHBOR_NOTICE_LIMIT = 5;
+/**
+ * 子项目索引行（④-B 2026-09-19）：告诉模型「当前工作区下面还有什么」——它补的是
+ * 「不知道存在」这个检索的结构性盲区，而**不搬运内容**（正文照旧走 memory_search）。
+ *
+ * 与预算诊断行同待遇：**不占注入预算**、自消除（没有子项目记忆时返回空串）。
+ * 只报条数不报 id——这一行的用途是给出**规模与入口**，不是当检索结果用。
+ */
+export declare function neighborNotice(neighbors: ReadonlyArray<{
+    name: string;
+    count: number;
+}>): string;
+/** 索引行列出的主题数上限（① 2026-09-19）：常数级——这行不随库增长。 */
+export declare const INDEX_NOTICE_TOPICS = 5;
+/**
+ * 记忆索引行（① 2026-09-19）：给出「库里还有什么、按什么去搜」。
+ *
+ * 它补的是**检索的结构性盲区**——检索是有意图的动作，不知道某条记忆存在就搜不出它。
+ * 注入行每轮只装得下约 11 条，其余上百条对模型完全不可见；这一行报出**规模与入口**，
+ * 让「不在场」变成「知道存在、需要时去取」。
+ *
+ * 为什么不做成一条常驻记忆（用户最初的设想）：那样它会自己占约 135 字符预算、参与零和
+ * 竞争、可能自己也被挤掉，而且记忆增删后**不会自动更新**（目录与内容不一致且无人察觉）。
+ * 做成系统生成的行则：不占预算、不可能腐化、永远反映当前状态。
+ *
+ * 主题取自各条的 `keywords` 词频——那是记忆写入时被要求「给多角度」的字段，**与检索用的
+ * 是同一套词汇**，所以索引里出现的词就是能搜到的词。同频时按字典序排，保证输出确定。
+ */
+export declare function indexNotice(records: ReadonlyArray<MemoryRecord>): string;

package/dist/injection.js

@@ -30,7 +30,9 @@ export function deriveSummary(content, maxChars) {
 }
 /** 一条注入行的渲染文本（与面板预览完全一致）。 */
 export function injectionLine(record, summaryChars) {
-    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}] ${deriveSummary(record.content, summaryChars)}`;
+    // ④-A：跨工作区召回时带来源标记（`..` / `../..`）；当前工作区不带，保持既有格式
+    const scope = record.scope === undefined ? '' : `@${record.scope}`;
+    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}${scope}] ${deriveSummary(record.content, summaryChars)}`;
 }
 /**
  * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
@@ -75,3 +77,56 @@ export function omittedNotice(rendered) {
     const truncated = rendered.omittedRecords.length > shown.length ? '…' : '';
     return `（另有 ${rendered.omitted} 条常驻因预算未注入：${labels.join('、')}${truncated}）`;
 }
+/** 子项目索引行列出的条数上限（④-B）：超出以 `…` 结尾，防这行本身失控。 */
+export const NEIGHBOR_NOTICE_LIMIT = 5;
+/**
+ * 子项目索引行（④-B 2026-09-19）：告诉模型「当前工作区下面还有什么」——它补的是
+ * 「不知道存在」这个检索的结构性盲区，而**不搬运内容**（正文照旧走 memory_search）。
+ *
+ * 与预算诊断行同待遇：**不占注入预算**、自消除（没有子项目记忆时返回空串）。
+ * 只报条数不报 id——这一行的用途是给出**规模与入口**，不是当检索结果用。
+ */
+export function neighborNotice(neighbors) {
+    if (neighbors.length === 0)
+        return '';
+    const shown = neighbors.slice(0, NEIGHBOR_NOTICE_LIMIT);
+    const labels = shown.map(neighbor => `${neighbor.name}（${neighbor.count} 条）`);
+    const truncated = neighbors.length > shown.length ? '…' : '';
+    return `（本工作区下另有 ${neighbors.length} 个子项目带记忆：${labels.join('、')}${truncated}——用 memory_search 检索）`;
+}
+/** 索引行列出的主题数上限（① 2026-09-19）：常数级——这行不随库增长。 */
+export const INDEX_NOTICE_TOPICS = 5;
+/**
+ * 记忆索引行（① 2026-09-19）：给出「库里还有什么、按什么去搜」。
+ *
+ * 它补的是**检索的结构性盲区**——检索是有意图的动作，不知道某条记忆存在就搜不出它。
+ * 注入行每轮只装得下约 11 条，其余上百条对模型完全不可见；这一行报出**规模与入口**，
+ * 让「不在场」变成「知道存在、需要时去取」。
+ *
+ * 为什么不做成一条常驻记忆（用户最初的设想）：那样它会自己占约 135 字符预算、参与零和
+ * 竞争、可能自己也被挤掉，而且记忆增删后**不会自动更新**（目录与内容不一致且无人察觉）。
+ * 做成系统生成的行则：不占预算、不可能腐化、永远反映当前状态。
+ *
+ * 主题取自各条的 `keywords` 词频——那是记忆写入时被要求「给多角度」的字段，**与检索用的
+ * 是同一套词汇**，所以索引里出现的词就是能搜到的词。同频时按字典序排，保证输出确定。
+ */
+export function indexNotice(records) {
+    const usable = records.filter(record => record.status === 'approved'
+        && record.quarantined !== true
+        && (record.kind ?? 'fact') !== 'prompt');
+    if (usable.length === 0)
+        return '';
+    const counts = new Map();
+    for (const record of usable) {
+        for (const keyword of record.keywords) {
+            counts.set(keyword, (counts.get(keyword) ?? 0) + 1);
+        }
+    }
+    if (counts.size === 0)
+        return '';
+    const topics = [...counts.entries()]
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+        .slice(0, INDEX_NOTICE_TOPICS);
+    const labels = topics.map(([topic, count]) => `${topic}(${count})`);
+    return `（索引：当前可见 ${usable.length} 条记忆，主题集中在 ${labels.join('、')}——用 memory_search 检索）`;
+}

package/dist/self.js

@@ -3,6 +3,8 @@
  * 0.3.2 起：LLM 每轮知道本环境有记忆机制；不落用户存储，随发版更新，
  * 版本号动态读取 package.json（"只跟随 dsh-memory 组件发版变动"）。
  * 0.9.2：补齐常驻注入机制——`injected` 参数、注入预算上限、预算诊断行的含义。
+ * 0.10.0：修正工具清单（6 → 10，补提示词模板工具）与两层记忆说明——原清单漏了
+ * `prompt_*` 系列，照它读会以为本插件只有记忆工具。
  */
 import { createRequire } from 'node:module';
 export const SELF_VERSION = (() => {
@@ -17,7 +19,8 @@ export const SELF_VERSION = (() => {
     }
 })();
 export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
-    + '你有 6 个记忆工具：memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget。'
+    + '你有 10 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget（`memory_confirm` 仅在用户明确要求放行隔离记录时用）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）。'
+    + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
     + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
     + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
     + '② 用户纠正了你的做法或理解——把正确结论记下来；'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.9.2",
+  "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": {
@@ -23,7 +23,10 @@
     "cordis.patch.yml",
     "README.md",
     "LICENSE",
-    "docs/shots"
+    "docs/shots",
+    "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/scan-orphans.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * 孤儿记忆文件清点（④-C 2026-09-19）——**只读，不做任何处置**。
+ *
+ * 背景：project 记忆的文件名是 `memory_project_<djb2(工作区路径)>.json`，而代码只按这个
+ * 名字去找。历史上换过命名（早期无哈希后缀、有过双重 `memory_project_` 前缀），那些旧文件
+ * 因此**永远不会被打开**——不是「等人放行」，是代码已经不认识这个文件名了。实测
+ * （2026-09-19）全工作区 136 条 project 记忆里有 33 条处于这个状态。
+ *
+ * 本脚本回答一个问题：**哪些文件当前代码打不开**。它不迁移、不删除、不修改任何东西。
+ * 处置（归档 / 选择性导入 / 删除）是一次显式的人工动作，理由见设计文档 §3.4：
+ * 旧文件可能含 0.7.0 之前未过 `detectSensitive` 的内容，自动捞出来等于绕过隔离检查。
+ *
+ * 用法：node scripts/scan-orphans.mjs [根目录]（缺省为当前目录）
+ */
+import { readdirSync, existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** 与 engine.ts 的 projectBackendName 逐字一致：djb2 over 小写路径，36 进制。 */
+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)}`
+}
+
+/** 递归找出所有 `.dsh/storages` 目录；跳过 node_modules / .git，限深防跑飞。 */
+function findStorageDirs(root, depth = 0, out = []) {
+  if (depth > 4) return out
+  let entries = []
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === 'node_modules' || entry.name === '.git') continue
+    const full = join(root, entry.name)
+    if (entry.name === '.dsh') {
+      const storages = join(full, 'storages')
+      if (existsSync(storages)) out.push(storages)
+      continue
+    }
+    findStorageDirs(full, depth + 1, out)
+  }
+  return out
+}
+
+/** 数一个记忆文件里的记录条数；读不出来返回 null（诚实报告「读不了」而不是 0）。 */
+function countRecords(file) {
+  try {
+    const blocks = JSON.parse(readFileSync(file, 'utf8'))?.tables?.blocks ?? {}
+    return Object.values(blocks).filter(block => block && block.content).length
+  } catch {
+    return null
+  }
+}
+
+const root = process.argv[2] ?? process.cwd()
+const storageDirs = findStorageDirs(root)
+
+console.log(`扫描根：${root}`)
+console.log(`发现 ${storageDirs.length} 个 storages 目录\n`)
+
+let orphans = 0
+let orphanRecords = 0
+let healthy = 0
+
+for (const storages of storageDirs) {
+  const workspace = dirname(dirname(storages))
+  const expected = `${projectBackendName(workspace)}.json`
+  let files = []
+  try {
+    files = readdirSync(storages).filter(name => name.startsWith('memory_project') && name.endsWith('.json'))
+  } catch {
+    continue
+  }
+  if (files.length === 0) continue
+
+  const rows = files.map(name => {
+    const file = join(storages, name)
+    return {
+      name,
+      ok: name === expected,
+      count: countRecords(file),
+      size: statSync(file).size,
+      mtime: new Date(statSync(file).mtimeMs).toISOString().slice(0, 10),
+    }
+  })
+  const bad = rows.filter(row => !row.ok)
+  const good = rows.filter(row => row.ok)
+
+  console.log(`── ${workspace}`)
+  console.log(`   期望文件名：${expected}`)
+  for (const row of good) {
+    healthy += 1
+    console.log(`   ✅ ${row.name}  ${row.count ?? '?'} 条  ${row.size}B  ${row.mtime}`)
+  }
+  for (const row of bad) {
+    orphans += 1
+    orphanRecords += row.count ?? 0
+    console.log(`   ⚠️  ${row.name}  ${row.count ?? '?'} 条  ${row.size}B  ${row.mtime}  ← 代码打不开`)
+  }
+  console.log('')
+}
+
+console.log('── 汇总 ──')
+console.log(`能被代码打开：${healthy} 个文件`)
+console.log(`打不开（孤儿）：${orphans} 个文件，共 ${orphanRecords} 条记录`)
+console.log('\n本脚本只清点。处置（归档 / 选择性导入 / 删除）见设计文档 §3.4，需人工拍板后单独执行。')