@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/docs/PROMO-PROMPT-3.0.md

@@ -0,0 +1,100 @@
+# dsh-auto-memory 3.0 宣传图 · 单发完整 Prompt
+
+> **用法**：整段粘进生图工具，一次出图。
+> **推荐参数**：`gpt-image-2.5` / quality `high` / size `1536x1024`（16:9 横版）
+> 若要竖版封面用 `1024x1536`，把构图描述里的「left / right」换成「top / bottom」。
+
+---
+
+## Prompt（直接复制）
+
+```
+A polished product banner illustration for a developer tool, 16:9 widescreen, dark cinematic anime aesthetic.
+
+LAYOUT: Split composition. Left 55% is a clean information panel with crisp typography. Right 45% is a full-body anime character with floating holographic elements. A soft vertical light seam separates the two halves.
+
+BACKGROUND: Deep navy-to-near-black gradient, from #12203f at the upper left to #050810 at the lower right. Subtle floating grid of thin cyan lines, faint bokeh particles, and a soft cyan glow behind the character. A few translucent glass panels drift in the background with very low opacity. Clean, premium, technical — not cluttered.
+
+CHARACTER (right side, occupying right 45%, full body from head to knees): A gentle anime girl with long flowing light-blue hair and a small gold star hair clip. Large expressive blue eyes with soft highlights, warm closed-mouth smile, looking slightly toward the viewer. She wears a white blouse with puffy sleeves, a dark navy vest with gold trim and small gold buttons, a large navy bow at the collar with a round blue gemstone brooch, and a navy pleated skirt with a gold chain and gem pendant at the waist. She holds a large open dark-navy hardcover book in both hands; the book's cover is embossed with gold filigree and displays the English text "MEMORY LOG" in clean gold serif capitals. In her raised right hand she holds a dark fountain pen with a gold nib. Around her float 6 to 8 glowing translucent blue glass memory cards, each with a delicate gold corner frame and a small sparkle icon. Soft rim light from the left catches her hair and shoulders; cool cyan bounce light from the cards. Clean crisp line art, cel shading, soft painterly highlights, high detail on hair strands and fabric folds.
+
+LEFT PANEL TOP — main title block:
+Large bold Chinese title text, two lines, white with a subtle cyan glow:
+"无问自忆"
+"记忆不断线"
+Below it, smaller light-blue English subtitle in a clean sans-serif:
+"She remembers, unbidden."
+Below that, one line of small gray-blue Chinese text:
+"跨窗口 · 跨会话 · 跨工具"
+
+LEFT PANEL MIDDLE — a 2x2 grid of four rounded glass capability cards, each with a thin cyan border, a small line-art icon in the upper left, and Chinese text:
+Card 1 icon: a small closed book. Title "自动记忆" in white bold, body text "每轮自动沉淀，寒暄轮跳过" in small gray-blue.
+Card 2 icon: a shield with a checkmark. Title "写入闸门" in white bold, body text "乱码与凭据进不了提示词" in small gray-blue.
+Card 3 icon: a clipboard with a pen. Title "交接账本" in white bold, body text "换窗口不丢上下文" in small gray-blue.
+Card 4 icon: three stacked horizontal layers. Title "三层记忆" in white bold, body text "硬规矩 / 笔记 / 日志" in small gray-blue.
+
+LEFT PANEL LOWER — a dark rounded terminal bar with a thin cyan border, containing monospace text in cyan-green:
+"pnpm add @a9i5k4/dsh-auto-memory@latest"
+To its right, a small rounded pill button with the Chinese text "复制".
+
+LEFT PANEL BOTTOM — a horizontal row of small rounded info chips with thin borders, each containing short Chinese text:
+"17 模型工具"  "49 路由"  "98 配置键"  "12 面板页签"  "零运行时依赖"
+
+TOP RIGHT CORNER — a small glowing version badge, rounded pill shape with a cyan border and cyan text: "v3.0.0"
+
+BOTTOM LEFT CORNER — small gray text: "BSD-3-Clause  ·  Windows / macOS / Linux"
+
+STYLE: Premium dark UI illustration, deep blue and cyan palette with small warm gold accents, glassmorphism, soft glow, high contrast between text and background. Typography must be sharp, correctly spelled, well-kerned, and perfectly legible. All Chinese characters must be accurate and correct. Cinematic lighting, clean composition, professional key visual quality, no watermark, no signature, no border frame.
+```
+
+---
+
+## 出图后必做：文字准确性自检
+
+AI 生图的**中文长文本**仍可能出错（缺笔画、错字、糊字）。逐项核对：
+
+- [ ] 主标题「无问自忆」「记忆不断线」——**这两行最重要**，错一个字就重出
+- [ ] 英文副标题 `She remembers, unbidden.`
+- [ ] 四张卡片标题：自动记忆 / 写入闸门 / 交接账本 / 三层记忆
+- [ ] 卡片小字（错字可接受，糊字不行 —— 小字允许后期覆盖）
+- [ ] 命令 `pnpm add @a9i5k4/dsh-auto-memory@latest`（**必须逐字符对**）
+- [ ] 五个 chip：17 模型工具 / 49 路由 / 98 配置键 / 12 面板页签 / 零运行时依赖
+- [ ] 版本号 `v3.0.0`（不是 0.1.35、不是 3.0.1）
+- [ ] 书封 `MEMORY LOG`
+- [ ] 左下 `BSD-3-Clause`
+
+**修图策略**（按性价比排序）：
+1. **重出**：主标题或命令出错 → 直接重跑，改 prompt 里对应那行
+2. **局部重绘（inpainting）**：只有某一小块错 → 用图生图 + 蒙版只遮那一块
+3. **HTML 后期覆盖**：只有卡片小字或 chip 糊 → 用 HTML 渲染同位置的文字层叠上去（此时 AI 已经画好了光影氛围，只为修字）
+
+---
+
+## 内容依据（写 prompt 时的事实来源）
+
+全部经代码自核，**不要改动这些数字**：
+
+| 项 | 值 |
+|---|---|
+| 版本 | **3.0.0**（2026-09-17 发布） |
+| 模型工具 | **17** |
+| HTTP 路由 | **49** |
+| 配置键 | **98**（60 可写） |
+| 面板页签 | **12** |
+| 运行时依赖 | **0** |
+| 许可 | BSD-3-Clause |
+
+**3.0.0 真正的新东西**（宣传图该讲的）：
+1. **底层重建收官** —— 检索、注入、容量、并发四条底层全部重建
+2. **白板/看板从实验升为出厂形态**（`handoffEnabled` 默认 `true`、`boardMode` 默认 `graph`）
+3. **语义索引永久不就绪的真因修复** —— 累计 22,945 行 `index-not-ready` 降级日志；根因是 Python worker 的同步槽被一次未完成的同步永久占住；修复给出两条「可证已死」接管出口
+4. **多工作区/多会话适配** —— 修掉引擎里 4 处「单槽」变量，同时跑两个会话时不再互相覆盖
+
+---
+
+## 负面提示（若工具支持 negative prompt）
+
+```
+low quality, blurry, blurry text, garbled characters, wrong Chinese characters, misspelled text,
+extra fingers, deformed hands, watermark, signature, logo, border frame, cluttered background,
+neon overload, oversaturated, flat lighting, 3d render, photorealism, western cartoon style
+```

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,12 +35,13 @@
 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)
 
 ---
 
 ## 1. Install & entry points
 
-- Install into the DSH web profile directory (`~/.dsh/profiles/web`): `pnpm add @a9i5k4/dsh-auto-memory`, then append `"@a9i5k4/dsh-auto-memory"` to the `dsh.profile.bundles` array in that directory's `package.json` (or one-click from the DSH plugin marketplace).
+- Install into the DSH web profile directory (`~/.dsh/profiles/web`): `pnpm add @a9i5k4/dsh-auto-memory@latest`, then append `"@a9i5k4/dsh-auto-memory"` to the `dsh.profile.bundles` array in that directory's `package.json` (or one-click from the DSH plugin marketplace).
 - **You must restart dsh web after installing**: the injection surface (manifest) loads at startup. Same after changing host code.
 - After a browser-side update, **hard-refresh** (Ctrl+Shift+R) to load the new client.js.
 - pnpm v11 blocks packages published <24h ago (`minimumReleaseAge`): set `minimumReleaseAge: 0` in `pnpm-workspace.yaml` or pin an explicit version for same-day updates.
@@ -185,7 +193,7 @@ The static injection face: the `<memory_system>` block composed into every turn.
 
 | Item | Notes |
 |---|---|
-| Version / check for updates | Compares with the npm registry; registry installs get one-click updates. Local dev links show the update command `cd ~/.dsh/profiles/web && pnpm up @a9i5k4/dsh-auto-memory` |
+| Version / check for updates | Compares with the npm registry; registry installs get one-click updates. Local dev links show the update command `cd ~/.dsh/profiles/web && pnpm up @a9i5k4/dsh-auto-memory@latest` |
 | Diagnostics log | `~/.dsh/dsh-auto-memory-pre-diagnose.log` (subagent circuit-breaking, consolidation skips, GC, recall degradation — all in here) |
 | Community | QQ group feedback — faster than GitHub issues (link in README) |
 
@@ -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,12 +35,13 @@
 10. [记忆工具（对话中直接可用）](#10-记忆工具)
 11. [常见问题排查](#11-常见问题排查)
 12. [数据位置与回滚](#12-数据位置与回滚)
+13. [3.0 底层重建：对你意味着什么](#13-30-底层重建对你意味着什么)
 
 ---
 
 ## 1. 安装与入口
 
-- 安装：在 DSH 的 web profile 目录（`~/.dsh/profiles/web`）执行 `pnpm add @a9i5k4/dsh-auto-memory`，并在同目录 `package.json` 的 `dsh.profile.bundles` 数组里追加 `"@a9i5k4/dsh-auto-memory"`（或在 DSH 插件市场一键安装）。
+- 安装：在 DSH 的 web profile 目录（`~/.dsh/profiles/web`）执行 `pnpm add @a9i5k4/dsh-auto-memory@latest`，并在同目录 `package.json` 的 `dsh.profile.bundles` 数组里追加 `"@a9i5k4/dsh-auto-memory"`（或在 DSH 插件市场一键安装）。
 - **装完必须重启 dsh web**：插件的注入面（manifest）在启动时加载；改完 host 代码同理。
 - 浏览器端更新后需**硬刷新**（Ctrl+Shift+R）才会加载新 client.js。
 - pnpm v11 会拦截发布不足 24 小时的新版本（`minimumReleaseAge`）：当天更新请在 `pnpm-workspace.yaml` 设 `minimumReleaseAge: 0`，或直接 pin 版本号。
@@ -185,7 +193,7 @@
 
 | 项 | 说明 |
 |---|---|
-| 插件版本 / 检查更新 | 与 npm registry 比对；registry 安装可一键更新。本地开发链接会显示更新命令 `cd ~/.dsh/profiles/web && pnpm up @a9i5k4/dsh-auto-memory` |
+| 插件版本 / 检查更新 | 与 npm registry 比对；registry 安装可一键更新。本地开发链接会显示更新命令 `cd ~/.dsh/profiles/web && pnpm up @a9i5k4/dsh-auto-memory@latest` |
 | 诊断日志 | `~/.dsh/dsh-auto-memory-pre-diagnose.log`（子代理熔断、巩固跳过、回收、唤起降级等事件全在内） |
 | 交流群 | QQ 群反馈，响应比 issue 快（链接见 README） |
 
@@ -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/WHITEPAPER.md

@@ -0,0 +1,207 @@
+# dsh-auto-memory 白皮书
+
+> **版本**：3.0.0 · **日期**：2026-09-20 · **许可**：BSD-3-Clause
+>
+> **本文是什么**：一份**约束性文档**。它把「这个插件到底建了什么、它有哪些已知边界」
+> 讲清楚，并把一条**核心不变量**显式成文——因为**约束不落纸，就一定会再被违反一次**。
+>
+> **本文不是什么**：不是宣传材料（宣传看 README），不是 API 文档（看 `FEATURE-INVENTORY.md`），
+> 不是论文（看 `M7-RESEARCH-PAPER.md`）。
+
+---
+
+## 0. 一句话
+
+> **同一份记忆字节，同时喂给三个消费者。任何一处写入，都要同时满足三套约束。**
+
+这是本插件全部工程复杂度的来源，也是历史上绝大多数 bug 的来源。
+
+---
+
+## 1. 核心不变量
+
+### 1.1 三个消费者
+
+记忆在磁盘上是纯 Markdown 明文。但同一份字节被三个**语义不同**的消费方读取：
+
+| # | 消费者 | 怎么读 | 对字节的要求 |
+|---|---|---|---|
+| ① | **注入面** | 每轮自动注入进上下文 | 必须**干净、短、有结构**；乱码与超长行会污染上下文 |
+| ② | **检索面** | 词法 + 语义双路召回 | 必须有**可切分的锚点结构**；锚点被破坏则召回精度下降 |
+| ③ | **语义面** | digest 供语义模型编码 | 必须**可重复生成**；同一输入必须产出同一 digest |
+
+### 1.2 约束
+
+> **一处写入，三处生效。** 写入方必须同时保证：
+> 1. 注入面拿到的字节在**预算内且无污染**；
+> 2. 检索面能按锚点**正确切条**；
+> 3. 语义面的 digest 能**正确失效并重建**。
+
+### 1.3 为什么这条不变量危险
+
+因为它**大多是静默降级**：
+
+- 注入进了一段乱码 → 模型读到噪音，**不报错**；
+- 锚点被写坏 → 召回少了几条，**不报错**；
+- digest 没失效 → 语义召回用了旧向量，**不报错**。
+
+**不爆的时候，完全看不出来。** 这就是为什么必须有一条显式约束 + 一批针对性断言。
+
+---
+
+## 2. 一次真实事故（本不变量的代价）
+
+这是本项目最典型的一类 bug，值得完整记录。
+
+### 2.1 现象
+
+用户在面板「日志」页签看到**乱码**；同时记忆文件侧也出现异常内容。
+
+### 2.2 根因
+
+**两条写入通路，只修了一条。**
+
+- 该插件有**两条互不相干**的写入通路：`procedure`（技能）线与 `fact`（事实）线；
+- 早先的清洗器只接进了 `procedure` 线；
+- `fact` 线的三个入口（`crossFeed` 的 fact 分支 / `factCandidateFromRow` / `hubFlushTick` 的回写）**从来没有过清洗器**；
+- 于是脏数据既进了 `facts.json`，又经回写污染了 `MEMORY.md`。
+
+> **教训**：「修了一条通路」不等于「另一条受保护」。
+> 只修**具名入口**是治标；把清洗**下沉到写原语**才是治本。
+
+### 2.3 处置
+
+- **当时**：在三个已知入口设防，补清洗器 + 新增判据族；
+- **根治（在途）**：把 `sanitizeForWrite` 下沉到写原语（`appendText` / `writeFull`），
+  使**全部写入路径自动受保护**——不再依赖「记得给新通路接上清洗器」；
+- 存量脏数据按**用户拍板**采用 `skip` 并留痕，**不做「清洗后照写」**。
+
+> **为什么不做清洗后照写**：那等于悄悄改数据，并丢失「曾出现脏 fact」这一诊断事实。
+> 本项目纪律是 **fail-soft 必须留痕、不得静默改写**。
+
+---
+
+## 3. 系统的实际形态（截至 3.0.0）
+
+### 3.1 规模（全部经代码自核）
+
+| 项 | 数量 | 说明 |
+|---|---|---|
+| 模型工具 | **17** | 15 个基础 + 2 个条件注册（`memory_expand_pre` / `memory_trace_pre` 仅在 `boardMode=graph` 时注册） |
+| HTTP 路由 | **49** | 全部 loopback-only；插件层外部访问返回 403，宿主层为 401——**两者都是预期行为** |
+| 设置键 | **98** | 其中 **60** 个可在设置页写入 |
+| 面板页签 | **12** | 概览 / 日志 / 唤起回顾 / 记忆中枢 / 存储管理 / 笔记 / 白板 / 反思 / 接续 / 日历 / 检索 / 工作区 |
+| 插槽注册 | **6** | 侧栏入口 / 浮层面板 / 弹窗 / 接续卡 / 设置分区 / 会话页看板 |
+| 运行时依赖 | **0** | 本插件自身不引入任何 npm 运行时依赖 |
+| 浏览器侧 | 单文件 | `lib/client.js`，纯 ESM，**无构建步骤** |
+
+### 3.2 两条线
+
+- **pre 开发线**（本仓）：profile 以 `link:` 挂载 ⇒ **开发树就是活的宿主代码**
+- **REL 发布线**（`_publish_dsh-auto-memory`）：发布时做 `_pre` 后缀擦除与残留闸门
+
+> ⚠️ **「PR merge ≠ 修复落地」的结构性根源**：仓内裸名 `lib/*.js` 是历史遗留的**互引孤岛**
+> （零活引用，唯一例外 `ws-overview-rank.js`），宿主只 import `-pre.js` 版本。
+> **改错副本 = 改了不生效。** 这是本仓最易踩的坑，已写入约束清单。
+
+---
+
+## 4. 已知边界（诚实清单）
+
+### 4.1 特性默认值（★ 3.0.0 起有翻转，旧文档口径已失效）
+
+> **警告**：本表在 3.0.0 有过一次**批量默认值翻转**。任何沿用 3.0 之前口径的文档
+> （包括早期 README 与第三方说明）都会写错。以下数值**经代码自核**
+> （`tools/verify-defaults.mjs` / `tools/verify-experimental.mjs`）。
+
+| 特性 | 键 | **当前默认** | 备注 |
+|---|---|---|---|
+| 交接白板 + 账本 | `handoffEnabled` | **`true`（开）** | ★ 3.0.0 由 `false` **翻转为 `true`** |
+| 白板看板（5 泳道） | `boardMode` | `'graph'` | 默认新版看板 |
+| 水位测量窗口 | `waterLevelWindowTokens` | `0` | `0` = 自动沿用官方窗口容量 |
+| 水位阈值 | `waterLevelThreshold` | `0.75` | — |
+| 水位提示 | `waterLevelAdvisory` | `true` | — |
+| 水位自动写账本 | `waterLevelAutoHandoff` | `true` | — |
+| **自动接续** | `autoContinueEnabled` | **`false`（关）** | 与白板**已解耦**，各自独立 |
+| 自动固化 | `autoConsolidate` | `true` | — |
+| Tier-0 常驻目录 | `tier0CatalogEnabled` | `true` | 预算 400 tok / 占比 25% |
+| 注入总开关 | `injectEnabled` | `true` | 预算 8000 字符 |
+| 记忆中枢 | `memoryHubEnabled` | `true` | — |
+| **机械流程切片** | `hubMechanicalProcedureFeedEnabled` | **`false`（关）** | T10 关停；向导内有标「不推荐」的回退开关 |
+| 主动联想 | `associativeMemoryEnabled` | `false`（关） | 需显式开启 |
+| 无人值守 | `unattendedMode` | `false`（关） | — |
+| 容量上限 | `noteCapacityChars` / `userCapacityChars` | 各 **24000** | 2026-09-18 由 12000 上调 |
+
+**白板默认翻转的理由**（代码注释原文）：README 与用户手册早已对外声称「交接默认开启」，
+而代码默认是关——**文档与实现长期不一致**；且白板/账本是 3.0 的招牌能力，
+出厂关着等于新用户看不到它。
+
+> **这条本身就是「约束不落纸」的又一个样本**：文档写「默认开」、代码写「默认关」，
+> 双方各自都以为自己是权威，一直没人发现。
+
+### 4.2 有测试、无接线
+
+项目内发现**一套协议库三件套**（acceptance / ledger-criteria / state-commit）
+被 smoke 测试养着，但 `index.js` **未引用**。属「有测试、无接线」——
+留作后续整合，当前不影响功能。
+
+### 4.3 两条路由无 UI 消费者
+
+`/subagent-gc` 与 `/activation-inbox-pre`：**能力在、UI 未接**。
+
+### 4.4 前端回归网极薄
+
+146 个测试套件里，**仅 3 个**断言 React 组件行为。
+这意味着**前端改动几乎不受回归保护**——重构前需先补特征化测试。
+（这也是「前端交给社区共创」的前提条件之一，见 `FRONTEND-CO-CREATION.md`。）
+
+### 4.5 授权边界
+
+| 资产 | 许可 | 说明 |
+|---|---|---|
+| 本项目代码 | BSD-3-Clause | — |
+| 角色设定「溟月」 | **CC BY-NC-SA 4.0** | 原作者 **上善无形**；**非商业 + 相同方式共享**，比代码许可更严格 |
+| 参考项目（RhineLabUI 等） | MIT | **仅覆盖其程序代码**，不覆盖 3D 模型 / Blender 工程 / 原片素材 / 游戏品牌 |
+
+> **角色许可与代码许可是两件独立的事，不可合并成一句「本项目采用 XX 许可」。**
+
+---
+
+## 5. 写给后续写入者（约束清单）
+
+任何新增**写入路径**的人（包括 AI 自己）请逐条自查：
+
+- [ ] **三面同时满足**：注入面干净、检索面锚点完好、语义面 digest 正确失效
+- [ ] **走写原语**：不绕过 `appendText` / `writeFull` 的校验与事务
+- [ ] **fail-soft 必须留痕**：禁止静默吞异常（本项目有 `DEGRADE_RING` 降级台账）
+- [ ] **不得静默改写**：脏数据 `skip` 并留痕，不要「清洗后照写」
+- [ ] **改对副本**：`-pre.js` 才是活代码，裸名文件是孤岛
+- [ ] **配置写入唯一出口**：`saveConfigPatch` → `POST /config`
+- [ ] **开关解耦**：单开关不得顺带改变其它功能行为
+- [ ] **新旧并存**：已发布的 3.0.0 有真实用户 ⇒ 必须保留开关回退路径
+
+---
+
+## 6. 本白皮书与其它文档的分工
+
+| 文档 | 回答什么 |
+|---|---|
+| **本文** | 「有哪些**不能违反**的约束、哪些**已知边界**」 |
+| `FEATURE-INVENTORY.md` | 「有哪些功能、住在哪一行」 |
+| `ARCHITECTURE-FOR-ZCODE-20260920.md` | 「代码结构是怎样的」 |
+| `M7-RESEARCH-PAPER.md` | 「为什么这样设计、实验数据如何」 |
+| `FRONTEND-CO-CREATION.md` | 「外部贡献者能改什么、怎么改」 |
+
+---
+
+## 7. 结论
+
+本项目的「完工」有两层含义：
+
+- **功能层面的完工**：功能已稳定，3.0.0 已发布，全量回归 PASS。
+- **认知层面的完工**：**本文** —— 把约束与边界写下来，让后续任何人（含 AI）
+  不必靠口口相传就能避开已知的雷。
+
+> **约束不落纸，就一定会再被违反一次。**
+
+这句话是本文存在的全部理由。

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` 对空转回合是空操作）。