@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.0

package/docs/USER-GUIDE.en.md

@@ -1,7 +1,14 @@
 # dsh-auto-memory User Guide
 
+<p align="center">
+  <a href="./USER-GUIDE.zh-CN.md"><img alt="中文" src="https://img.shields.io/badge/%E4%B8%AD%E6%96%87-switch-lightgrey?style=for-the-badge"></a>
+  <a href="./USER-GUIDE.en.md"><img alt="English" src="https://img.shields.io/badge/English-current-blue?style=for-the-badge"></a>
+</p>
+
+<p align="center"><a href="../README.md">← Back to README</a></p>
+
 > She remembers, unbidden: memory never waits for your command — the right memory surfaces on its own; every entry has provenance — checkable, editable, deletable.
-> Applies to version **2.2.7+** · Changelog: in-plugin **Settings → Appearance → View changelog**.
+> Applies to version **3.0+** · Changelog: in-plugin **Settings → Appearance → View changelog**.
 > 中文版：[USER-GUIDE.zh-CN.md](./USER-GUIDE.zh-CN.md)
 
 ---
@@ -28,6 +35,7 @@
 10. [Memory tools (available in conversation)](#10-memory-tools)
 11. [Troubleshooting](#11-troubleshooting)
 12. [Data locations & rollback](#12-data-locations--rollback)
+13. [The 3.0 rebuild: what it means for you](#13-the-30-rebuild-what-it-means-for-you)
 
 ---
 
@@ -379,4 +387,51 @@ All three write tools (log/note/user) pass the **write gate**: GBK mojibake, stu
 
 ---
 
+## 13. The 3.0 rebuild: what it means for you
+
+Most of this release adds no new buttons. It changes *what makes a memory trustworthy*. **You don't need to configure anything** — everything below is default behaviour, listed so you know exactly where the boundaries are.
+
+### 13.1 Safer writes: one bad line no longer bricks the file
+
+Before: if a record's body happened to contain the memory system's own reserved marker, the write reported **success** — but from the *next* write onward the **entire file was refused**, with an error carrying no line number. The only way to locate it was to script a line-by-line scan.
+
+Now: reserved-syntax detection moved into the **write primitives**. A body carrying a reserved marker is refused **on the spot, with the offending line number**; a pre-existing silent corruption is fixed too (the compaction path used to inline archived logs' own marker lines into the note, minting phantom anchors).
+
+> Worth knowing: wrapping the text in backticks or a code fence does **not** help — the check is substring-level, so the wording itself has to change.
+
+### 13.2 Steadier writes: transient Windows contention no longer eats content
+
+On Windows, `rename` hitting an external file handle (antivirus scan, Search indexer, an editor, a handle the host just wrote) throws `EPERM` — a **transient** condition. That layer previously had no backoff: the exception propagated and **the whole record was lost**.
+
+Now: `EPERM / EACCES / EBUSY` retry with backoff (`[0, 50, 150, 400, 1000] ms`); if it still fails, the **full candidate snapshot is preserved** (`.dam-failed-<ts>-<nonce>-<name>.tmp`, exposed as `recoveryPath` in the error) so you can recover it by hand — already-rendered content is never destroyed. Write tools also report **`isError` truthfully**, so a failure no longer masquerades as "the call succeeded, but the body contains a failure sentence".
+
+### 13.3 Workspaces and sessions stop starving each other
+
+This is the most important fix of the release. **Symptom**: with two workspaces or two sessions open, "nothing can inject any more" — not a compute problem (the worker measured idle), but four single-slot states overwriting each other:
+
+| Overwritten state | Consequence |
+|---|---|
+| Recall-decision projection | A's projection clobbered by B ⇒ A later reads B's ⇒ **the identity gate sees a session mismatch ⇒ A never descends to tier-1 retrieval** |
+| Index-version cache | Two workspaces evict each other ⇒ a guaranteed recompute every time (amplifying the "index never becomes ready" problem below) |
+| Index-degradation state | The reader checked only a 10-minute window, not the session ⇒ **false cross-session degradation** |
+| Last-query record | Unconditional overwrite ⇒ the reader falls back to `triggerText`, a semantic downgrade |
+
+Now: all four are sharded **by session / workspace**, in bounded containers (`size > 32` eviction). **The decision predicate is unchanged** — sharding adds one key dimension and changes no rule; compatibility projections are retained so older readers never receive `undefined`.
+
+**In plain terms**: clicking into another workspace used to disturb the recall of the session that was actually running. It no longer does. This is the one you can feel directly.
+
+### 13.4 Three more (default behaviour, nothing to configure)
+
+- **Mutually exclusive engine identities**: the built-in JS semantic tier and the advanced Python tier are **two interchangeable implementations** — whichever you pick is the one that runs. No shadowing, no cross-triggering, and neither is a prerequisite for the other.
+- **True incremental embedding**: only changed records get re-embedded, with reuse ordering, instead of recomputing the whole store.
+- **Bounded rerank window**: if you enable a rerank tier, the clock starts at enqueue, 60s expiry with no renewal, LRU ≤16, yields when busy — background work never slows the live conversation.
+
+### 13.5 How to confirm it's really in effect
+
+- **No new settings.** The eight groups in §4 are unchanged.
+- Write-failure tell-tales: check `isError` and `recoveryPath` in the tool result; a `.dam-failed-*.tmp` file in the directory means a final-state failure occurred and the file *is* the forensic snapshot — safe to delete once confirmed.
+- Regression evidence: the matching suites live under `tests/smoke/`, including mutation demos that revert each mechanism to its old behaviour and must go genuinely red.
+
+---
+
 *BSD-3-Clause · Repo: github.com/Aik358/dsh-auto-memory · Screenshots & story: [README](../README.md) · 中文文档：[USER-GUIDE.zh-CN.md](./USER-GUIDE.zh-CN.md)*

package/docs/USER-GUIDE.zh-CN.md

@@ -1,7 +1,14 @@
-# dsh-auto-memory 用户文档
+# dsh-auto-memory 用户手册
+
+<p align="center">
+  <a href="./USER-GUIDE.zh-CN.md"><img alt="中文" src="https://img.shields.io/badge/%E4%B8%AD%E6%96%87-%E5%BD%93%E5%89%8D-blue?style=for-the-badge"></a>
+  <a href="./USER-GUIDE.en.md"><img alt="English" src="https://img.shields.io/badge/English-switch-lightgrey?style=for-the-badge"></a>
+</p>
+
+<p align="center"><a href="../README.zh-CN.md">← 返回 README</a></p>
 
 > 无问自忆：记忆不靠你吩咐，该想起的自己浮现；每条都有出处，可查、可改、可删。
-> 适用版本：**2.2.7+** · 更新日志见插件内「设置 → 外观 → 查看更新日志」。
+> 适用版本：**3.0+** · 更新日志见插件内「设置 → 外观 → 查看更新日志」。
 > English version: [USER-GUIDE.en.md](./USER-GUIDE.en.md)
 
 ---
@@ -28,6 +35,7 @@
 10. [记忆工具（对话中直接可用）](#10-记忆工具)
 11. [常见问题排查](#11-常见问题排查)
 12. [数据位置与回滚](#12-数据位置与回滚)
+13. [3.0 底层重建：对你意味着什么](#13-30-底层重建对你意味着什么)
 
 ---
 
@@ -379,4 +387,51 @@ AI 在对话中可直接调用（共 14 个，你不需要记）：
 
 ---
 
+## 13. 3.0 底层重建：对你意味着什么
+
+这一版大部分工作不产生新按钮。它改的是"记忆凭什么被相信"。**你不需要做任何配置**——下面每一条都是默认行为，列出来是为了让你知道边界在哪。
+
+### 13.1 写入更安全：脏正文不再让文件永久失效
+
+以前：一条正文里若出现记忆系统自己的保留标记，写入当场"成功"，但**从下一次写入开始，整个文件都会被拒绝**，且报错不给行号——现场只能自写脚本逐行找。
+
+现在：保留语法检测前移到**写入原语**，含保留标记的正文**当场被拒并给出命中行号**；同时修复了一处既有静默损坏（整理流程会把归档日志自己的标记行内联进笔记，制造幻影锚点）。
+
+> 顺带一提：任何"用反引号/代码块包裹"的规避手法都无效——判定是子串级，必须改写措辞。
+
+### 13.2 写入更稳：Windows 瞬态占用不再丢内容
+
+Windows 下 `rename` 撞上外部文件句柄（杀软扫描、Search 索引、编辑器、宿主刚落盘的句柄）会抛 `EPERM`，属**瞬态**。以前这一层没有退避重试，异常直接上抛，**本次记忆整条丢失**。
+
+现在：`EPERM / EACCES / EBUSY` 走退避重试（`[0, 50, 150, 400, 1000] ms`）；最终仍失败时**保留完整候选快照**（`.dam-failed-<ts>-<nonce>-<名称>.tmp`，错误里带 `recoveryPath`）供人工找回，不再把已渲染好的内容销毁。写工具也会**如实置 `isError`**——失败不再伪装成"调用成功但正文里带一句提示"。
+
+### 13.3 多工作区 / 多会话不再互相饿死
+
+这是本轮最重要的一条。**症状**：同时开两个工作区或两个会话时，「谁也没法注入」——不是算力不够（实测 worker 在闲着），而是四处"单槽"状态被交替覆盖：
+
+| 被覆盖的状态 | 后果 |
+|---|---|
+| 唤起判据投影 | A 投递后被 B 覆盖 ⇒ A 后续取到 B 的投影 ⇒ **身份门判 session 不匹配 ⇒ A 永远不下探二级检索** |
+| 索引版本缓存 | 两工作区互相踢缓存 ⇒ 每次必然重算（放大下面的"索引迟迟不就绪"） |
+| 索引降级状态 | 读方原本只判 10 分钟时间窗、不判会话 ⇒ **跨会话假降级** |
+| 上次检索记录 | 无条件覆盖 ⇒ 读取侧退回 `triggerText`，语义降级 |
+
+现在：四处全部按**会话 / 工作区**分片，容器有界（`size > 32` 淘汰）。**判定口径一字未改**——分片只增加一个维度，不改判据；同时保留兼容投影，老读取方不会拿到空值。
+
+**说白了**：以前"你点进另一个工作区"会顺带影响正在跑的那个会话的召回；现在不会了。这是你能直接感知的修复。
+
+### 13.4 其他三条（默认行为，无需配置）
+
+- **引擎身份互斥**：JS 内置语义与 Python 进阶语义是**两套可互换的独立实现**，选了哪个就是哪个——不互相顶替、不互相联动，也不存在"装了一个才能用另一个"。
+- **真增量嵌入**：只对变化的记录重新嵌入并复用顺序，而不是整库重算。
+- **精排有界窗口**：若开启精排档位，入队起算 60s 到期不续命、LRU ≤16、忙碌时让路——后台重活不拖慢当前对话。
+
+### 13.5 怎么确认这些真的在生效
+
+- 配置项与开关位置：**没有新增**。§4 的八组设置照旧。
+- 写入失败的可判据：工具结果里看 `isError` 与 `recoveryPath`；目录里若出现 `.dam-failed-*.tmp`，说明有过一次终态失败，文件即取证快照，确认后可删。
+- 回归证据：本仓库 `tests/smoke/` 下有对应套件（含"把机制改回旧行为"的变异演示）。
+
+---
+
 *BSD-3-Clause · 仓库：github.com/Aik358/dsh-auto-memory · 更多截图与介绍：[README](../README.zh-CN.md) · English guide: [USER-GUIDE.en.md](./USER-GUIDE.en.md)*

package/docs/internal/ACCEPT-35-LIVE.md

@@ -0,0 +1,143 @@
+# #35 真机验收方案（停旧回合 → 仪式 → 真判据 → 新窗口）
+
+> 目标：把 #35 的修复从**夹具级**（`smoke-test-autocont-host-pre.mjs` 95 断言）升级为**真机级**。
+> 本文件给**新会话**执行；执行者不需要读原对话。改配置前先备份（用户级硬规则）。
+
+## 0. 为什么必须换一个会话做
+
+- 验收的**核心那一档**要求在「回合正在运行时点同意」——那会**终止当前回合**。
+  拿重要对话当靶子会打断它，所以：**另开一个新会话当"旧会话"被接续**，本对话不受影响。
+- 新会话要够长、有实质内容（交接材料才有东西可带）；空会话测不出材料质量。
+
+## 1. 前置条件（**2026-09-14 解耦后已更新：只需开一个开关**）
+
+> 历史注记：解耦前 `handoffEnabled=false` 会让 `checkWaterLevel` 提前返回 → `waterLevelModelKnown` 不写 → fail-closed 闸永不 arm，所以当时**必须同时开两个开关**。那处耦合已切除（`lib/index.js` 的 `checkWaterLevel` 早退、`armAutoContinue` 早退、`autoContinueState.enabled` 二次与运算、`buildContinueCarry` 的 `handoff disabled` 早退，共 4 处）。
+
+这台机器的现行配置（`~/.dsh/dsh-auto-memory-pre.json`）：
+
+| 键 | 现值 | 现在的要求 |
+|---|---|---|
+| `autoContinueEnabled` | **false** | **必须临时改 true**——它是接续的唯一资格开关 |
+| `handoffEnabled` | false | **可保持 false**，此时走「最小转写载体」；也可改 true 走完整两层载体（见步骤 1 的 A/B 跑法） |
+| `autoContinueThreshold` | 0.75 | 正常会话很难自然达阈值，验收要临时降 |
+
+**结论：只开 `autoContinueEnabled` 即可跑验收。** 而且**建议第一轮就保持白板关闭**——那条路径是这次解耦才第一次可用的（此前直接 hard-fail），顺带把解耦也验了。
+
+## 2. 步骤
+
+### 步骤 0 · 备份（必做）
+```pwsh
+Copy-Item "$env:USERPROFILE\.dsh\dsh-auto-memory-pre.json" "$env:USERPROFILE\.dsh\dsh-auto-memory-pre.json.bak-accept35" -Force
+```
+
+### 步骤 1 · 临时开开关 + 降阈值（**A/B 两轮**）
+
+**A 轮（先跑，白板关闭 —— 验解耦后的最小载体）**：
+```json
+"autoContinueEnabled": true,
+"autoContinueThreshold": 0.05
+```
+保持 `handoffEnabled: false` 不动。此轮新会话应拿到**转写包 + 近期线程**，且材料里带一句自述「未启用白板/账本」；仪式步骤会被**跳过**（日志 `reason:'handoff-disabled'`），这是**预期**，不是失败。
+
+**B 轮（A 通过后再跑，白板打开 —— 验完整两层载体）**：
+再把 `"handoffEnabled": true` 打开，重跑一次，观察步骤 ②③ 的仪式链路。
+
+> 为什么降的是 `autoContinueThreshold` 而不是 `waterLevelWindowTokens`：改窗口会让**水位测量本身**失真，连带 advisory 与自动账本写入都变形；降阈值只动"什么时候弹卡"。
+> 每轮改完**重启 dsh web**（注入面与开关在启动时读）。**注意冷却**：`autoContinueCooldownMinutes=30`，触发过一次后 30 分钟内不再弹——两轮之间要么等，要么把冷却临时调小。
+
+### 步骤 2 · 造场景
+在**新会话**里正常跑一两轮（有工具调用、有实质产出）。
+- 注意：**首轮 pre-step 拿不到模型信息**（`request/header` 还没写），按 #33 的 fail-closed 设计，首轮的按比例 arm 会被拦，**推迟到该轮 turn-stopping**。所以卡片应在**第一轮结束后**出现，而不是开局。
+- 若 10 分钟不弹卡：先查日志有没有 `auto-continue armed`，没有就回头查开关与 `modelKnown`（见 §4 排查）。
+
+### 步骤 3 · 点「同意接续」并采日志
+两种点法，验证深度不同——**建议先 A 后 B**：
+
+- **A 档（先做，安全）**：**空闲时点**。验通 ①→④ 全链路与节拍；`cancel` 对空转回合是空操作。
+- **B 档（核心，代价已知）**：**让一个回合跑着（多步工具调用/长输出），在运行中点同意**。这才是 issue 原现场，也是唯一能验「回合活跃时不再并行」的做法。**代价：该回合会被终止，未完成的回答落 `interrupted`。**
+
+采集（改完配置重启后）：
+```pwsh
+Get-Content "$env:USERPROFILE\.dsh\dsh-auto-memory-pre-diagnose.log" -Tail 200 |
+  Select-String 'auto-continue|ritual|prev-session|stopped|waited'
+```
+
+## 3. 判据（缺一不算过；第 3 条仅 B 轮适用，A 轮看 3′）
+
+| # | 期望日志 | 含义 |
+|---|---|---|
+| 1 | `auto-continue armed: … awaitIdle=true …` | 闸放行了（能验到这条本身就说明 #33 的 fail-closed 没误杀） |
+| 2 | **`auto-continue: stopped old turn sid=…`** | **① 新链路真的执行了**；若旧回合在跑，旧窗口应显示被打断 |
+| 3 | **`host refresh ritual: … waited=updated`**（**仅 B 轮／白板开时适用**） | **②③ 因果闭合判据通过**（若显示 `waited=stamp-fallback` → 说明 `sc.inspect` 不可用、退到弱判据，**要当作半通过并单独记**） |
+| 3′ | **A 轮（白板关）替代判据**：日志出现仪式的 `reason:'handoff-disabled'`（仪式按设计被跳过），**且**新会话交接材料里出现「未启用白板/账本」自述、**不含**磁盘上真实存在的 PLAN/账本正文 | 解耦生效：白板关 ≠ 不能接续；且降级是**显式**的，不是静默丢弃 |
+| 4 | `prev-session pack built` → `auto-continue host-executed: … stopped=ok` | ④ 新会话建立；`stopped=ok` 与判据 2 互相印证 |
+
+**反向断言（同样重要）**：
+- 若 ④ 出现但**没有** 2 → 停旧回合没生效（或旧会话无 id，`stopped=no-old-session`），必须记下来；
+- 若旧回合被打断后**新会话没建起来** → 交接失败，比"并行"更糟，立即回滚并报告。
+
+## 4. 排查（卡片不弹时按序查）
+
+1. 开关是否真的生效：`GET /api/dsh-auto-memory-pre/auto-continue-state`（或设置页）看 `enabled`；
+2. 日志有没有 `consolidate skip:` / `auto-continue` 任何一行；
+3. `modelKnown` 是否为真：首轮必为假（设计如此），只在**轮末**才可能 arm；
+4. 冷却：`autoContinueCooldownMinutes=30`，触发过一次后 30 分钟内不再弹——**验收期间只点一次**，要点第二次就先把它调小。
+
+## 5. 回滚（验完必做）
+
+```pwsh
+Copy-Item "$env:USERPROFILE\.dsh\dsh-auto-memory-pre.json.bak-accept35" "$env:USERPROFILE\.dsh\dsh-auto-memory-pre.json" -Force
+```
+然后重启 dsh web。**除非用户明确要求长期开启**，否则恢复成 `handoffEnabled=false` / `autoContinueEnabled=false` / `autoContinueThreshold=0.75`。
+
+> 待用户裁定（会写进交接账本）：这两个开关**日常要不要开**。若长期关着，则 #35 与 #31 第二半这两笔修复在水位/接续/白板面上**处于不生效状态**——修了但不在线。
+
+## 6. 纪律
+
+- 改配置**必须先备份**（用户级硬规则）；只改目标键，别整篇重写。
+- **不要**按进程名杀进程（曾误杀 harness）；要停就用精确 PID + `taskkill /PID <pid> /T /F`。
+- 不要拿主对话当接续靶子。
+- 验收结论无论通过与否都要落一笔到当日日志；失败要附原始日志片段，不要只写"没通过"。
+
+## 7. 真机验收结果（2026-09-14 17:37–17:41，Run 1）
+
+> 现场：旧会话 `session-d2c13583`（128 msgs）→ 新会话 `session-b8f093e4`。**在飞配置为 `handoffEnabled=true`**（非本文档 §2 设想的 A 轮），故本次实为 **B 轮**（完整两层载体）；**A 轮（白板关）仍未验**。
+> 验收人操作：用户在新窗口点「同意接续」（`decideAutoContinue('agree')`）。
+
+### 判据结果
+
+| # | 结果 | 证据 |
+|---|---|---|
+| 1 | **PASS** | `09:36:52.739Z auto-continue armed: sid=session-d2c13583… ratio=0.07 awaitIdle=true` |
+| 2 | **PASS** | `09:37:37.776Z auto-continue: stopped old turn sid=session-d2c13583…`；旧会话 `turn/end reason.kind=aborted/user` |
+| 3 | **FAIL（原因已查清，非逻辑缺陷）** | `09:39:08.082Z host refresh ritual: timeout, continuing with current material` → `lastOk.refreshRitual='timeout'` |
+| 4 | **PASS** | `09:39:08.106Z prev-session pack built … contSeq=22` → `09:39:08.247Z auto-continue host-executed: new session session-b8f093e4… ritual=timeout stopped=ok` |
+
+**反向断言**：④ 出现且 ② 同时出现 → 停旧回合生效；新会话成功建立（侧栏标题 `接续 #22 · dsh-auto-memory`，工作区/模型/权限 `deepseek-v4.1-flash` + `danger-full-access` 均继承）→ 无"比并行更糟"的交接失败。
+
+### 判据 3 超时的根因（已用旧会话原始事件流取证）
+
+不是判据写错，是**上游 API 故障把仪式推后到轮询窗之外**：
+
+1. `09:37:37.778Z` 仪式以 `mode:'queue'` 投给旧会话，**立刻**落为 `seq=244 user/message`，`turn=3` 同步启动 → 投递链路本身正常。
+2. `turn=3` 全窗没有一次成功的 assistant 产出：`llm/retry` 连续 5 次（`09:37:45`→`09:38:38`，61s），
+   `09:38:38.450Z turn/end reason.kind=error`，错误为 **`502: {"message":"上游拒绝请求","type":"upstream_bad_request"}`**。
+3. 90s 轮询窗（`autoContinueRefreshTimeoutSeconds`）到点 → 报 `timeout`，宿主按 fail-soft 继续接续。
+4. **仪式随后真的执行了**：用户后续「继续」推动 `turn=6`，`09:41:01.529Z`（seq 291–295）模型连调两次
+   `memory_note_pre`（`kind=plan` + `kind=handoff`）→ `PLAN.md` 与 `handoff-20260914-174101.md` 的 mtime 正是 `17:41:01`。
+
+结论：**因果闭合判据的实质成立**（事件数增长且出现 seq>239 的 `assistant/message` + `tool/call`），只是发生在 90s 窗之后（+114s）。**记为半通过**，按本文档 §3 的口径单独记录；若要让它真通过，应提高 `autoContinueRefreshTimeoutSeconds`（当前上限 600）。
+
+### 本轮新发现的真实风险：新会话会被立刻再次 arm（链式接续）
+
+- `09:42:49.340Z auto-continue armed: sid=session-b8f093e4…`（**即刚建出来的新会话**）→ 若无人干预，约 35s 后会再次掐掉新会话并再建一个。
+- 机制：`markContinuedSession(oldSid, newId)` 只给**旧**会话上闩（`isContinuedSession` 检查的是旧 sid）；新会话是全新身份，不受闩保护。而新会话首题就是超大交接包，`ratio` 开局即 ≈0.053。
+- 本次是阈值降到 `0.05` 的**验收态放大**了它；生产阈值 `0.75` 下新会话开局不可能越线，故**当前不判定为缺陷**，但值得在 3.1 决策：新会话是否也应有一段"免接续蜜月期"。
+- **已处置**：`POST /auto-continue-decide {action:'reject'}` 已拆引信（`rejectedEdgeAt=1789378969340`），armed 清空。
+
+### 收尾状态
+
+- 配置已按 §5 回滚：`autoContinueEnabled=false` / `autoContinueThreshold=0.75` / `autoContinueCooldownMinutes=30`（`handoffEnabled` 保持 `true`，与备份一致）。sha `3DEE4041F3E9`。
+- 回滚已**热生效**（`GET /api/dsh-auto-memory-pre/config` 内部会 `loadConfig()` 覆盖内存态；无需重启即生效，实测 `enabled:false`）——这与本文档 §2"每轮改完重启 dsh web"的旧说法不同，**热重载可用**。
+- 验收态快照留存：`~/.dsh/dsh-auto-memory-pre.json.bak-accept35-run1-evidence`。
+- **未验**：A 轮（`handoffEnabled=false`，判据 3′）、B 档"回合运行中点同意"（本次点同意时旧回合已自行 abort，`cancel` 对空转回合是空操作）。

package/docs/internal/ACCEPTANCE-20260914.md

@@ -0,0 +1,90 @@
+# 验收报告 · ZCode 交班对账
+
+> 验收时间：2026-09-14 02:2x–02:5x（本地）｜验收方：DSH 主对话（**只做取证与复核，未改任何产品代码**）
+> 验收对象：ZCode 交付的三任务 + 10 项追加需求 + 交班材料（对账单见对话与 `TODO-BACKLOG.md`）
+> 口径：**能独立复核的写实测值；不能复核的明确标注"不可独立复核"**，不用转述充证据。
+
+## 一、基线复核（实测）
+
+| 项 | 报告值 | 实测（命令/位置） | 判定 |
+| --- | --- | --- | --- |
+| npm latest | 2.5.2 | `npm view @a9i5k4/dsh-auto-memory version --registry=https://registry.npmjs.org` → `2.5.2`；`dist-tags.latest=2.5.2` | ✅ |
+| GitHub main = tag | `55c3deb` | REL 线 `D:\dsh_debug\_publish_dsh-auto-memory` HEAD = `55c3deb`，tag `v2.5.0/v2.5.1/v2.5.2` 齐 | ✅ |
+| REL 工作树 | （未提） | 唯一未跟踪 = `.github/cloud/qq-webhook/index.zip`（发版纪律要求排除构建产物，正常） | ✅ |
+| pre 线 HEAD | `747aa68` | **实测 `1c06c46`** —— 多出 4 个提交，全是 `docs/`：官方 discussion #5732 评论稿 3 版 + dshapi 中转反馈稿（**非 ZCode 线，是本机 DSH 会话产出**） | ⚠️ 偏差，已更正 |
+| 冒烟套件 | 71 全绿 | 首次全量 **70/71**（`m73` 假红，见三）→ 夹具加固后 **71/71 全绿**，125s | ✅（修复后） |
+| 静态检查 | — | `node --check lib/index.js`、`lib/client.js` 均 0；两文件首三字节非 `EF BB BF` | ✅ |
+
+## 二、10 项追加需求逐项取证（全部落到源码/文件，可独立复核）
+
+| # | 需求 | 取证点 | 判定 |
+| --- | --- | --- | --- |
+| 1 | PR #29 合并移植 | `lib/index.js:47` import `decodeZstdFramesHead`；调用点 `:1626`（巡检扫描）、`:1927`（`waterWindowForSession` 同防） | ✅ |
+| 2 | procedure 链路审计 + 缺口记录 | 结论落在 `TODO-BACKLOG.md` §A 末条（数据层从未产出 active procedure、`renderChecklist` 无子代理出口、`memory_recall` 无 procedures scope）——**没有独立审计文件** | ⚠️ 审计在、未单独成文 |
+| 3 | 白板整合预研 + 看板化评估 | `WB-GRAPH-RESEARCH-BRIEF.md`(7.7KB) / `-LOCAL.md`(21.2KB) / `-EXTERNAL.md`(33.2KB) / `WB-GRAPH-INTEGRATION-PLAN.md`(39.1KB)，四份齐 | ✅ |
+| 4 | 云函数定时自触发 | `.github/cloud/qq-webhook/index.js:366-368` timer 分支；`triggerName=digest_dispatch`；`TIMER_MIN_GAP_HOURS=10` 防重 | ✅ |
+| 5 | @ 答疑限额 env 化 | `index.js:47-50` `AI_MAX_PER_HOUR`（0/缺省=不限）/`AI_QUOTA_HOURS`（默认 1h）；配额落 gist | ✅ |
+| 6 | 日报去重（prompt + 确定性双层） | `group-digest.mjs:91-93` 30 分钟 schedule 去重；`:400` prompt 规则「不得新增重复条目」；`:417` 解析失败兜底按标题前 8 字去重 | ✅ |
+| 7 | 未解决事项跨期跟踪 + 自动销账 | `group-digest.mjs:327-331`（open/resolved/stale，14 天归档）、`:400` `resolved_titles` 规则、`:234` 日报渲染「✅ 已解决并移出」 | ✅ |
+| 8 | 反馈文件钉死 | 提交 `9f594db`「反馈文件钉死文件名（修复第一个文件换人/清空即删文件）」，code 侧仍在 | ✅ |
+| 9 | 思维链截断修复 | `index.js:232-249` `max_tokens: 1600` + 三层过滤（`reasoning_content` → `</think>` 切段 → 行首思考特征词剥除） | ✅ |
+| 10 | mention id 变更失聪修复 | `index.js:308-310` 学习改为**取最新见到的 mention** 为准；`:479` diag 暴露 `mentionLearned` | ✅ |
+
+另：源码 `VERSION = 'webhook-gist-20260913n'`（`index.js:56`）——与"线上 n 版"的自述一致。
+
+## 三、本轮发现并修复的问题（1 项真问题 + 1 条教训）
+
+**① `smoke-test-m73-pre.mjs` 负载敏感假红（真问题，已修）**
+
+- 现象：全量连跑 FAIL；单跑第 1 次也 FAIL，第 2 次绿 → 非确定。失败点在 N8「模型缺失 → enabled/ready」：`h.frame.payload` 为 undefined 抛 `TypeError`。
+- 根因：夹具 `requestTimeoutMs: 8000`，连跑时 python worker 冷启动超过窗口 → `health()` 返回**无 frame** 的失败响应（属夹具鲁棒性，不是产品缺陷）。
+- 修法：新增 `healthReady(c, attempts=8, gapMs=400)` 有界轮询，**只对"无 frame"重试**；9 处 `c.health()` 全部改走它。断言（`embedding.enabled/ready/error`）一字未改 —— worker 真起不来时轮询耗尽、拿最后一个无 frame 响应、断言照常失败，**不掩蔽真故障**。
+- 验证：单跑 3/3 绿（`pass=59 fail=0`）；全量 71/71 绿。
+
+**② 教训（写进本项目纪律）**：`replace_all` 会命中**同一次编辑新加入的代码块** —— 本次把辅助函数内部的 `c.health()` 也替换成了 `healthReady(c)`，造成自递归、3 连红。替换后必须核对命中计数（预期 9 实得 10 即报警）并 `node --check`。
+
+## 四、不可独立复核项（如实标注，不作为验收结论）
+
+- **线上云函数部署版本**：函数 URL 与 `ROUTE_TOKEN` 不在仓库（符合凭据纪律），只能由用户/群内实测确认；本报告只证明**源码 = n 版**。
+- **群内实战验证（"没毛病了"）**：外部证据，仓库侧无法复核。
+- **两个外部时间点**：今早 11:40 定时触发器首跑、下期日报应把「工作区切换问题」按 v2.5.2 自动销账 —— 时间未到（现 2026-09-14 02:5x），不可验。
+
+## 五、结论
+
+1. **ZCode 三问三答的 ①发版 ②`?report=N` 排查 ③群反馈调研**：仓库侧证据充分，成立；本机 DSH 侧对 71 套件的独立复跑同样通过（修复夹具后）。
+2. **10 项追加需求**：9 项源码取证完全成立；第 2 项（procedure 审计）结论存在但未单独成文。
+3. **报告偏差 2 处**（均已修正到文档）：
+   - `pre` 线 HEAD 不是 `747aa68` 而是 `1c06c46`（+4 个 docs 提交，与本机 DSH 会话的 harness bug 上报有关）。
+   - 白板 `PLAN.md` 当时写着"下一版深改三点仍未动"，**与事实相反**（水位口径 / 接续序号 / 流程外包三项已于 v2.5.0 落地并发布）——白板已重写。
+4. **真正剩余的待办**只分三类：①**阻塞在用户的决策**（大排期 6 拍板点 + 3 样输入；procedure 机制整体重构）②**待外部时间点**（定时班首跑、下期日报销账）③**可排期的存量项**（`TODO-BACKLOG` §C 冷启动 5 项 / §D 分发门面 / §E 文档体系 —— 已复核仍成立，但非当前焦点）。
+
+---
+
+### 附：本机"会话语义检索"不可用的根因与处置（2026-09-14 追查，已实施待重启生效）
+
+**现象**：`memory_recall(scope='sessions')` 报 `session search is disabled: this deployment configures the session-query index with openAt "never"`。
+
+**根因（逐层取证；不是"没装"，是"从没打开"）**：
+
+1. 抛错点在 `@deepseek-ai/dsh-session-query-sqlite/lib/index.js:594-595`：`openAt === 'never'` 时在任何 SQLite 动作之前直接抛 `SESSION_QUERY_SEARCH_DISABLED`。
+2. `never` 是**随包默认**，写在 `@deepseek-ai/dsh-base/cordis.patch.yml:121-133`（该行注释原文：「Full-text session search is **opt-in**. `openAt: never` …」），配置为 `path: ':memory:'` + `openAt: never`。
+3. 同一段注释**给出了开启方式**：「Deployments enabling content search override `openAt` to `first-search` or `startup` in a later patch layer (**profile cordis.patch.yml** or a `--patch` overlay), typically with a durable `path`。」
+4. 本机用户层 `~/.dsh/profiles/web/cordis.patch.yml`（最后应用）原只有 3 条 `disabled: true`，**从未覆盖过这一行** → 检索一直是关的。**更正**：先前报告写「值来自 launcher 默认、属 DSH 侧改动」不准确 —— 值是 dsh-base bundle 的随包默认，而覆盖层正是**用户可改**的 profile patch。
+5. 插件侧无额外开关：`lib/index.js:1804-1807` 直接调 `sq.searchSessions(...)`，没有自己的门闸 —— 唯一阻塞就是上面这一行。
+
+**处置（已落盘）**：在 `~/.dsh/profiles/web/cordis.patch.yml` 追加 id 定向覆盖（原件已备份为同目录 `cordis.patch.yml.bak-20260914-search`）：
+
+```yaml
+- id: session-query-sqlite
+  config:
+    path: 'C:/Users/JH Z/.dsh/profiles/web/session-query.db'
+    openAt: first-search
+```
+
+关键约束：patch 对目标行是**整块 `config` 替换而非合并** → `path` 必须一并重述（`path` 是 `z.string().required()`，省略即配置非法）；`path` 取 **profile 私有**路径，避免与其它 profile/进程争用同一索引文件（该索引每路径单进程持有）。
+
+**校验证据（不启动宿主，`dsh --profile web --dump-config`）**：退出码 0；合成结果该行 `name` 仍由 base 层给出、仅 `config` 被替换；全树 `openAt` **只出现 1 次** = `first-search`；`- id: session-query-sqlite` 恰 1 条（无重复行）；后端为 **`node:sqlite`（Node v24.18.0 内置，`require('node:sqlite')` 实测可用，不需原生模块）**；目标目录尚无 db 文件（首次检索时创建，属预期）；文件首 3 字节非 `EF BB BF`。
+
+**生效条件**：宿主只在启动时读该文件 → **需用户自行重启 dsh web**；重启后首次检索即建索引（`first-search`）。副作用：Web 侧边栏搜索从"只匹配标题/工作区名"升级为内容检索。
+
+**与它无关但一直可用**：插件的跨工作区记忆检索（日志/笔记/反思）与 `handoff/` 分层转写材料 —— 本次验收全程用的是后者。