dsh-instruction-memory 1.0.10 → 1.0.11

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` 级别由宿主日志级别过滤；

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.11",
   "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",