dsh-instruction-memory 1.0.10 → 1.0.12

package/README.md

@@ -85,6 +85,22 @@ DSH 就会得到第二份空记忆，看起来像"记忆消失"。
 导出的文件一定能被自己导回**——早先写死的 1,000,000 小于满配导出（200 × 6000 = 1.2 M 字符），
 导致满配记忆导出后无法导入。
 
+### 首次运行不写文件（惰性创建）
+
+全新安装、尚无任何记忆时，插件**不会**在宿主启动那一刻创建空的 `memory.json`。
+
+> 这里曾主动物化一份空存储，只为让设置页有个真实路径可显示。但那意味着插件在**进程启动、
+> 零会话、零任务**的状态下执行了一次磁盘写入——这正是行为审计中唯一能被正当称为
+> "没活干还在动"的副作用。现在文件由**第一个真正需要它的动作**创建：一次保存、一次导入，
+> 或设置页读取 `state`（面板打开时就会读）。
+
+在这之前：`storage.path` 仍会显示路径，但 `storage.onDisk` 为 `false`，设置页显示
+「尚未写入磁盘」（该文案本就存在），`state.injection.registered === false`，`pulls === 0`。
+挂载日志相应为 `from=first run (no store on disk yet) onDisk=no`。
+
+**不受影响**：从 `.bak` 恢复、以及从旧位置迁移——这两条分支只有在**磁盘上已有真实数据**时才会走，
+它们仍然会立即写回。
+
 ## 无 Web 服务器时依然生效
 
 `systemPrompt` 是本插件唯一的硬依赖。**Web 服务器不是前置条件**：设置页那部分路由通过
@@ -103,11 +119,27 @@ DSH 就会得到第二份空记忆，看起来像"记忆消失"。
 `info`，过程细节写 `debug`（走宿主的 `ctx.logger`）：
 
 ```
-[instruction-memory] mounted: store=<DSH_HOME>\instruction-memory\memory.json from=memory.json entries=2 enabled=true injected=437 chars
+[instruction-memory] mounted: store=<DSH_HOME>\instruction-memory\memory.json from=memory.json onDisk=yes entries=2 enabled=true section=437 chars (pending assembly) pulls=0
 ```
 
-挂载行含**数据来源**（`memory.json` / `memory.json.bak (main file missing)` / `legacy cwd file (migrated)`
-/ `first run (empty store created)`）、条目数、总开关状态、实际注入字符数，以及读取错误。
+挂载行含**数据来源**（`memory.json` / `memory.json.bak (main file missing)` / `memory.json.bak (main file corrupt)`
+/ `legacy cwd file (migrated)` / `first run (no store on disk yet)`）、**是否已在磁盘上**（`onDisk`）、
+条目数、总开关状态、段落就绪时的字符数，以及 `pulls`。
+
+### 为什么是 `section=… (pending assembly)` 而不是 `injected=…`
+
+**「段落已就绪」≠「已经注入」。** 注入发生在宿主装配提示词时；插件在挂载那一刻**什么都没注入过**，
+打印 `injected=437 chars` 会让人误以为记忆已经进入了某个提示词。这是本插件此前一处会误导排查的措辞。
+
+真正的"到达了提示词"的信号是 **`pulls`**：宿主每次对这段做装配，插件注册的那个 thunk 就被求值一次，
+计数器加一。因此
+
+- `pulls=0` = 已准备、**从未装配**（进程刚起来、或会话空闲）；
+- `pulls=N` = 已被拉进提示词 N 次。
+
+插件看不到会话或轮次，**不会**报告 `sessions=` 之类的数字——那会是编造。它只报告自己能真正观测到的东西。
+`pulls` 同时出现在路由的 `state` 快照里（`injection.pulls`）。每次拉取另有一条 `debug` 行：
+`section pulled into a prompt (pull #N)`。
 
 **这是纯日志，绝不影响注入内容**：同一份存储在"有 logger"和"没有 logger"下渲染出的文本
 **逐字节相同**（`verify.mjs` 有断言锁定这一点）。`debug` 级别由宿主日志级别过滤；
@@ -141,13 +173,21 @@ DNS 重绑定恰好推翻了它**：`evil.com` 解析到 `127.0.0.1` 之后，
 >=0.1.3-alpha.2 <0.1.4 || >=0.1.4-0 <0.1.5-0 || >=0.1.5-alpha.1 <0.1.6-0 || >=0.1.6-alpha.0 <0.1.7-0 || >=0.1.7-alpha.0 <0.2.0-0 || >=0.2.0-0
 ```
 
-**实测范围**：以下 5 个宿主版本已在 **Windows / Node 22** 上逐个真实启动验证（每个版本都确认了
-插件装载、系统提示注入真的进入组装后的提示、插件 HTTP 路由可应答、客户端设置页模块被下发）：
+**验证范围与证据等级**——三者不可混为一谈，下面每一行都标了它到底证明了什么：
+
+| 等级 | 证明什么 | 覆盖 |
+| --- | --- | --- |
+| ① **真实启动** | 在该宿主版本上真的把 DSH 跑起来：插件装载、注入真的进入**组装后的提示**、插件 HTTP 路由可应答、客户端设置页模块被下发（Windows / Node 22） | `0.1.3-alpha.2` · `0.1.5-alpha.1` · `0.1.5-alpha.2` · `0.1.5-rc.1` · `0.1.5-rc.2` |
+| ② **契约核验** | 抓该版本**真实发布的源码**，逐个核验本插件实际用到的每个符号：`systemPrompt.section()`、`assemble()` 是否求值**函数型** `text`、`FILE_REFERENCE=900` / `TOOL_BASH=1000` 仍在（决定 order 950 是否空档）、重名注册是否抛错、`webServer.register()` / `get host()`、`ctx.inject()` / `ctx.effect()`、`dsh.client.inject` 两包在该版本是否存在且声明了 `dsh.client` | 声明范围接住的**全部 12 个已发布版本**（`0.1.3-alpha.2` → `0.1.7-rc.2`） |
+| ③ **真实执行** | 把插件**真的挂载**进该版本的 `@deepseek-ai/cordis`，跑装载 / 路由注册 / 卸载共 9 项断言 | cordis `4.0.2` 与 `4.0.4`（各 9/9） |
+
+此外 `host-range-test.mjs` 的固定矩阵覆盖 `0.1.6-alpha.2` 与 `0.1.7-rc.2`，并会**读取本机实际安装的宿主版本**做实时断言。
+
+**关于 1.0.10 新增的 `ctx.inject`。** 这是新版唯一的硬依赖增量：`inject` 去掉了 `webServer`，设置页路由改为非阻塞的 `ctx.inject(['webServer'], …)` 子 fiber（原因见上）。为此逐个核验了 **cordis 全部 6 个已发布版本**（`4.0.1-rc.1` → `4.0.4`）——**每一个都具备 `ctx.inject`**，因此声明范围内不存在因它而失效的宿主版本。
 
-`0.1.3-alpha.2` · `0.1.5-alpha.1` · `0.1.5-alpha.2` · `0.1.5-rc.1` · `0.1.5-rc.2`
+**关于声明范围是否"超范围承诺"。** 已对全部 **27 个**已发布宿主版本穷举核验：范围内 12 个版本的 API 面**全部齐备，超范围承诺 0 项**。范围外的 15 个版本（`0.0.1-rc.1` → `0.1.2-rc.1`）API 面**同样齐备**，但它们**从未真实启动验证过**，所以下限维持不动、不向外放宽——不把没验证过的东西写进声明。
 
-此外 `0.1.6-alpha.2` 与 `0.1.7-rc.2` 完成了完整的装载与兼容性判定核验（`host-range-test.mjs`
-的固定矩阵覆盖它们，且该脚本会**读取本机实际安装的宿主版本**做实时断言）。
+**一个运维上值得知道的事实。** 早期 DSH 用 caret 范围声明同族依赖（如 `^0.1.5-alpha.2`），范围会随时间"往前漂"：**今天**安装旧版 DSH，npm 在 `includePrerelease` 语义下会把同族子包解析到**当前最新的 `0.1.x`**，而不是当年那份（实测 7/10 个采样版本会漂移，3 个因精确锁定不会）。这不影响本插件的结论——漂移目标同样在已核验范围内——但"今天装出来的树"与"当年装出来的树"可能不同。
 
 **为什么写成分段形式**：node-semver 规定"候选版本带预发布标签时，区间里必须存在同一个
 major.minor.patch 且自身带预发布标签的比较符"。这条规则是**集合级**的——一个 `||` 分支最多
@@ -194,7 +234,8 @@ FAIL  LIVE GUARD: the installed host 0.1.8-rc.1 is admitted by both modes  -> ..
 两次都因为插件市场传入 `includePrerelease: true` 而侥幸放行，但任何标准 semver 判定
 （`npm` / `pnpm` 的依赖解析）都会拒绝。现在 `host-range-test.mjs` 同时具备固定矩阵与实时守卫。
 
-**未验证范围**：macOS / Linux、`headless` 与 `tui` profile、以及上表之外的其他 DSH 版本均未实测。
+**未验证范围**：macOS / Linux、`headless` 与 `tui` profile，以及**除上表等级①那 5 个之外的任何版本的真实启动**，均未实测。
+等级②只证明"该版本里有这些 API"，**不证明端到端可用**。
 
 **同一串范围写在两处**：`dsh.compatibility.dsh`（插件自己的字段）与 `dsh.engines.dsh`（插件市场**实际读取**的位置）。
 市场只读 `engines.dsh` / `dsh.engines.dsh` 以及 `@deepseek-ai/dsh*` 的 `peerDependencies`，并不读 `dsh.compatibility.dsh`。

package/lib/index.js

@@ -437,9 +437,31 @@ export function apply(ctx) {
     migratedFrom: null,
     sectionRegistered: false,
     sectionError: null,
+    /** Whether a store file is actually present on disk (diagnostics + the panel). */
+    storeExists: false,
   }
   let sectionDispose = null
 
+  /**
+   * A first run deliberately writes NOTHING (see readFromDisk step 3). This flag
+   * remembers that the store has not been materialised yet, so the file is
+   * created by the first action that genuinely needs it — a save, or the
+   * settings page asking for `state` — instead of by the bare act of the host
+   * booting with no session and no task.
+   */
+  let needsMaterialize = false
+
+  /**
+   * How many times the host has pulled this section into a prompt, since boot.
+   *
+   * The plugin cannot see sessions or turns; it only knows that the harness
+   * evaluated the thunk it registered. That is still the honest answer to "did
+   * this actually reach a prompt?", and it is the thing the previous log line
+   * could not distinguish: a registered section with pulls=0 has been prepared
+   * but never injected.
+   */
+  let sectionPulls = 0
+
   const describeError = (err) => {
     if (err === null || err === undefined) return '未知错误'
     if (typeof err === 'string') return err
@@ -506,6 +528,21 @@ export function apply(ctx) {
     }
   }
 
+  /**
+   * The thunk handed to the harness.
+   *
+   * It is deliberately NOT `sectionText` itself: wrapping it lets the plugin
+   * count the pulls the host performs (`assembled`), which is the only
+   * first-hand evidence of "this reached a prompt" available on this side of the
+   * API. The returned text is untouched — the render stays byte-identical
+   * (verify.mjs pins that with and without a logger attached).
+   */
+  const assembledSectionText = () => {
+    sectionPulls += 1
+    logDebug('section pulled into a prompt (pull #' + sectionPulls + ')')
+    return sectionText()
+  }
+
   /**
    * Keep the registered section exactly in step with the stored data: present
    * when something must be injected, absent otherwise. An empty memory must
@@ -515,7 +552,7 @@ export function apply(ctx) {
     const wanted = sectionText() !== ''
     if (wanted && sectionDispose === null) {
       try {
-        sectionDispose = systemPrompt.section({ name: SECTION_NAME, order: SECTION_ORDER, text: sectionText })
+        sectionDispose = systemPrompt.section({ name: SECTION_NAME, order: SECTION_ORDER, text: assembledSectionText })
         state.sectionRegistered = true
         state.sectionError = null
         logDebug('prompt section registered: order=' + SECTION_ORDER + ' chars=' + sectionText().length)
@@ -603,6 +640,10 @@ export function apply(ctx) {
       state.storagePath = storePath
       state.storageDisplay = storePath
       state.storageError = null
+      state.storeExists = true
+      // A successful write is the one thing that makes the file real, so it is
+      // also what clears the "not materialised yet" flag set by a first run.
+      needsMaterialize = false
       state.savedAt = Date.now()
       logDebug('store written: ' + storePath + ' bytes=' + text.length
         + ' entries=' + state.data.entries.length
@@ -624,6 +665,7 @@ export function apply(ctx) {
     state.storageDisplay = storePath
     state.storageWarning = null
     state.loadedFrom = null
+    state.storeExists = false
 
     // 1. The canonical location under the harness home.
     try {
@@ -633,6 +675,7 @@ export function apply(ctx) {
         state.data = loaded.data
         state.storageWarning = droppedEntriesMessage(loaded.dropped)
         state.loadedFrom = 'memory.json'
+        state.storeExists = true
       }
       state.storageError = null
       return
@@ -714,10 +757,31 @@ export function apply(ctx) {
       if (err instanceof SyntaxError) state.storageError = '旧位置文件解析失败，已忽略：' + describeError(err)
     }
 
-    // 3. First run: materialise an empty store so the path is real and the
-    //    settings page can show it.
-    await writeToDisk()
-    if (state.loadedFrom === null) state.loadedFrom = 'first run (empty store created)'
+    // 3. First run: there is no store anywhere. Deliberately write NOTHING.
+    //
+    //    This used to materialise an empty memory.json so the settings page had
+    //    a real path to show. That made the plugin perform a disk write at
+    //    process boot — i.e. with no session, no turn and no task — which is the
+    //    one side effect that a behaviour audit can legitimately call "running
+    //    with nothing to do". The file is now created by the first action that
+    //    genuinely needs it: a save, an import, or the settings page reading
+    //    `state` (see ensureStoreMaterialized). Until then the panel shows
+    //    "尚未写入磁盘", a state its UI already renders.
+    needsMaterialize = true
+    state.loadedFrom = 'first run (no store on disk yet)'
+    state.storeExists = false
+  }
+
+  /**
+   * Write the empty store, once, the first time something actually needs the
+   * file to exist. A failed attempt leaves the flag set so the next caller
+   * retries instead of silently pretending the file is there.
+   *
+   * @returns whether a write was performed and succeeded.
+   */
+  const ensureStoreMaterialized = async () => {
+    if (!needsMaterialize) return false
+    return writeToDisk()
   }
 
   /* ---------------- boot ---------------- */
@@ -733,12 +797,17 @@ export function apply(ctx) {
       syncSection()
       // The one always-on line: it answers "is memory mounted, where does it
       // live, and how much is being injected?" without any further digging.
+      // 措辞很重要：`section=` 说的是"这个段落已就绪、若被装配会产出多少字符"，
+      // 而不是"已经注入"。在零会话时打印 `injected=` 会让人误以为记忆已经进入
+      // 了某个提示词。真正的注入证据是 pulls：宿主每拉取一次加一（初始必为 0）。
       const chars = sectionText().length
       logInfo('mounted: store=' + storePath
         + ' from=' + String(state.loadedFrom)
+        + ' onDisk=' + (state.storeExists ? 'yes' : 'no')
         + ' entries=' + state.data.entries.length
         + ' enabled=' + (state.data.enabled === true)
-        + ' injected=' + (chars > 0 ? chars + ' chars' : 'nothing')
+        + ' section=' + (chars > 0 ? chars + ' chars (pending assembly)' : 'nothing to inject')
+        + ' pulls=' + sectionPulls
         + (state.storageError !== null ? ' error=' + state.storageError : ''))
     })
 
@@ -774,12 +843,20 @@ export function apply(ctx) {
         warning: state.storageWarning !== null ? state.storageWarning : state.backupError,
         savedAt: state.savedAt,
         migratedFrom: state.migratedFrom,
+        /** false until the store file has actually been written (see readFromDisk step 3). */
+        onDisk: state.storeExists,
       },
       injection: {
         registered: state.sectionRegistered,
         available: true,
         error: state.sectionError,
         chars: preview.length,
+        /**
+         * How many times the harness has pulled this section into a prompt since
+         * boot. 0 means "prepared, never assembled" — the distinction the old
+         * `injected=` log line could not make.
+         */
+        pulls: sectionPulls,
       },
       preview,
       limits: { minBudget: MIN_BUDGET, maxBudget: MAX_BUDGET, maxEntries: MAX_ENTRIES },
@@ -954,10 +1031,17 @@ export function apply(ctx) {
   const dispatch = async (method, args) => {
     await boot
     switch (method) {
-      case 'state':
+      case 'state': {
+        // The settings page is the first thing that needs a real file on disk —
+        // it displays the absolute path, and the user may then hand-edit it.
+        // A first run writes nothing at boot (readFromDisk step 3), so the
+        // materialisation happens here, on a deliberate user action, instead of
+        // as a side effect of the host merely starting up.
+        await ensureStoreMaterialized()
         // Same envelope as every other method. One response shape means the
         // Client can never again be handed a payload it silently ignores.
         return { ok: true, saved: true, message: null, snapshot: snapshot() }
+      }
       case 'save-entry':
         return saveEntry(args !== null && typeof args === 'object' ? args.entry : null)
       case 'delete-entry':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-instruction-memory",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "User-only instruction memory for DSH: long-term instructions maintained in the settings UI and auto-injected into every conversation — the model has no write access. 指令记忆：只由用户在设置页维护的长期指令，自动注入此后每轮对话；模型没有任何写入口。",
   "license": "MIT",
   "type": "module",