@a9i5k4/dsh-auto-memory 3.0.0 → 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

@@ -41,7 +41,7 @@
 
 ## 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.
@@ -193,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) |
 

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

@@ -41,7 +41,7 @@
 
 ## 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 版本号。
@@ -193,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） |
 

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）
+  不必靠口口相传就能避开已知的雷。
+
+> **约束不落纸，就一定会再被违反一次。**
+
+这句话是本文存在的全部理由。