@a9i5k4/dsh-auto-memory 2.2.6 → 2.3.0

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

@@ -1,289 +1,382 @@
-# dsh-auto-memory 用户文档
-
-> 无问自忆:记忆不靠你吩咐,该想起的自己浮现;每条都有出处,可查、可改、可删。
-> 适用版本:**2.2.4** · 更新日志见插件内「设置 → 外观 → 查看更新日志」。
-
----
-
-## 目录
-
-1. [安装与入口](#1-安装与入口)
-2. [第一次启动](#2-第一次启动)
-3. [设置页逐组详解](#3-设置页逐组详解)
-   - [自动记忆引擎](#31-自动记忆引擎semantic)
-   - [记忆中枢](#32-记忆中枢memoryhub)
-   - [外观](#33-外观appearance)
-   - [存储](#34-存储storage)
-   - [记忆窗口](#35-记忆窗口injection)
-   - [自动化](#36-自动化automation)
-   - [上下文管理](#37-上下文管理context)
-   - [维护](#38-维护maintenance)
-4. [上下文管理专题](#4-上下文管理专题)
-5. [语义引擎专题](#5-语义引擎专题)
-6. [记忆工具(对话中直接可用)](#6-记忆工具)
-7. [常见问题排查](#7-常见问题排查)
-8. [数据位置与回滚](#8-数据位置与回滚)
-
----
-
-## 1. 安装与入口
-
-- 安装:`pnpm add @a9i5k4/dsh-auto-memory`(或在 DSH 插件市场搜索 dsh-auto-memory)。
-- **装完必须重启 dsh web**:插件的注入面(manifest)在启动时加载;改完 host 代码同理。
-- 浏览器端更新后需**硬刷新**(Ctrl+Shift+R)才会加载新 client.js。
-- 入口:左侧栏底部 **记忆** 按钮 → 记忆面板,含页签 **概览 / 白板 / 语料精修 / 设置**。
-- 面板标题栏:**图钉**(线描图标,与 ⟳ ⤾ ✕ 同画风;点一下钉住后,点桌面其他地方不会自动收起,再点取消;钉住状态会记住)、⤾ 恢复默认位置、⟳ 刷新、✕ 关闭。未钉住时点击面板外或按 Esc 即收起。
-- 面板标题里的版本号与 设置 →「检查更新」显示的都是**当前安装的版本**,与 npm 上的一致(发布时自动同步)。
-- 数据全在本机:`~/.dsh/memory/`(记忆文件)、`~/.dsh/dsh-auto-memory-pre.json`(配置,发布版为 `dsh-auto-memory.json`)。
-
-## 2. 第一次启动
-
-- 首次启动播放**欢迎向导**,每项功能当场可开关;想重看:设置 → 外观 →「重新播放向导」。
-- 向导会提示下载**内置语义模型**(约 130MB,multilingual-e5-small,本地离线运行)。不下载也能用,召回退化为词法排序。
-- 之后随时到 设置 逐组调整。**所有设置改动即时保存**(写配置文件),无需重启;仅"注入面/工具清单"类改动需要重启宿主。
-
----
-
-## 3. 设置页逐组详解
-
-> 左侧分组导航顺序:**自动记忆引擎 → 记忆中枢 → 外观 → 存储 → 记忆窗口 → 自动化 → 上下文管理 → 维护**。
-> 下表默认值即出厂设置;`(重启生效)` 标注的项需要重启 dsh web。
-
-### 3.1 自动记忆引擎(semantic)
-
-| 项 | 默认 | 怎么调 |
-|---|---|---|
-| 总开关(associativeMemoryEnabled) | 开 | 关闭即整插件休眠(不注入、不沉淀),已存记忆保留 |
-| 注入模式(activationEmitMode) | `shadow` | **shadow**=只记录不打扰(最稳,先跑几天看效果);**canary-explicit**=命中可信度高的回忆才显式注入;**active**=全部注入 |
-| 候选方案(candidateScheme) | `balanced` | balanced 3×40 / dense 6×20 / custom;查询越复杂越适合 dense,日常 balanced |
-| 语义引擎模式(semanticEngineMode) | `auto` | auto / lexical / js / python,详见 §5 |
-| 思考链观察(reasoningObserverEnabled) | 开 | 是否把思维链/分支纳入观测面(开源模型为主时建议保持开) |
-| 子会话观测(contextBridgeObserveChildSessions) | 开 | 是否观测子代理会话的事件 |
-| 唤起阈值 | 固定 | 校准值 tauHi 0.45 / tauLo 0.35,只读展示;旁边显示当前发射模式 |
-
-### 3.2 记忆中枢(memoryHub)
-
-记忆中枢把对话蒸馏成三类长期记忆(情景 / 语义 / 程序),**默认关闭**,打开后才开始蒸馏。
-
-| 项 | 默认 | 怎么调 |
-|---|---|---|
-| 记忆中枢总开关(memoryHubEnabled) | 关 | 打开即启用三层记忆蒸馏;关闭保留已有记忆但停止新增 |
-| 情景记忆最小段落数(episodicMinSegments) | 2 | 一段对话至少跨 N 个段落才成一条情景记忆,调大更保守 |
-| 情景记忆保留条数(episodicRetention) | 256 | 上限;超出按时间淘汰 |
-| 程序记忆最小会话数(procedureMinSessions) | 3 | 同一套操作至少出现 N 个会话才固化为"程序" |
-| 程序记忆最小成功数(procedureMinSuccess) | 2 | 至少成功 N 次才算可靠程序 |
-| 纠错上限(procedureCorrectionCap) | 0.3 | 纠正比例超过该值即降权/淘汰该程序 |
-| 高风险需审批(procedureHighRiskApproval) | 开 | 涉及高风险动作的程序在使用前要求确认 |
-| 激活层级(procedureActiveLevel) | checklist | checklist 完整步骤 / excerpt 摘要 / hint 仅提示 |
-
-### 3.3 外观(appearance)
-
-| 项 | 默认 | 说明 |
-|---|---|---|
-| 欢迎向导(welcomeTourEnabled) | 开 | 首启是否自动播放;旁边可「重新播放」「查看更新日志」 |
-| 界面语言(locale) | 跟随系统 | 中文 / English / 跟随系统 |
-| 字号(fontScale) | 标准 | 面板与卡片缩放 |
-| 强调色(accentTheme) | DeepSeek 蓝 | DeepSeek 蓝 / 石墨灰 / 雾紫;日历与状态色保持语义色 |
-| 关系图密度(graphDensity) | 舒展 | 影响工作区关系图的节点间距与显示数量 |
-
-### 3.4 存储(storage)
-
-| 项 | 默认 | 说明 |
-|---|---|---|
-| 用户级记忆目录(userMemoryDir) | `~/.dsh/memory/MEMORY.md` | 跨项目规则 |
-| 项目记忆目录(projectMemoryDir) | `<工作区>/.dsh-memory/` | 项目笔记与每日日志 |
-| 记忆根目录(memoryRoot) | `~/.dsh/memory` | 可点「浏览」换位置 |
-
-### 3.5 记忆窗口(injection)
-
-| 项 | 默认 | 怎么调 |
-|---|---|---|
-| 注入总开关(injectEnabled) | 开 | 关掉即完全不往对话里注入记忆 |
-| 注入预算(injectBudgetChars) | 2400 | 觉得 AI 总被记忆打扰就调小;想不起事就调大 |
-| 注入近期天数(recentDaysInjected) | 1 | 最近 N 天日志参与注入 |
-| 外部记忆预算(externalInjectionChars) | 1400 | 其他 AI 工具(WorkBuddy/Claude Code 等)记忆的注入上限 |
-| 快照最小间隔轮数(snapshotMinGapRounds) | 5 | 同一快照至少间隔 N 轮才重复注入 |
-| 压缩后重注入(snapshotReinjectOnCompact) | 开 | 上下文被压缩后重新注入记忆快照 |
-| prompt 层编辑(promptLayerOverrides) | 空 | 逐层覆盖注入文案;可一键恢复默认 |
-
-### 3.6 自动化(automation)
-
-| 项 | 默认 | 怎么调 |
-|---|---|---|
-| 自动沉淀最小字数(autoConsolidateMinChars) | 240 | 本轮对话短于该长度不触发沉淀 |
-| 自动沉淀开关(autoConsolidate) | 开 | 每轮结束自动评估并写今日日志 |
-| 沉淀冷却(分钟)(autoConsolidateCooldownMinutes) | 30 | 夜间(22:00–08:00)自动翻倍 |
-| 每日沉淀上限(autoConsolidateDailyMax) | 8 | 防止额度被短时间耗尽 |
-| 自动弹窗(autoPopupEnabled) | 开 | 重要状态是否弹面板提示 |
-| 无人值守(unattendedMode) | 关 | 开启后静默一切主动打扰(建议挂机时开) |
-| 无人值守自动接续(unattendedAuto) | 关 | 挂机时水位到阈值即自动接续(无需点确认卡) |
-| 暂离问候(awayMinutes) | 60 | 距上次活动超过 N 分钟后回归时注入一次欢迎;0=关闭 |
-| 时段总结时间(autoSummaryTimes) | 空 | 逗号分隔的 HH:MM 列表,到点跑一次时段总结 |
-| 日界(分钟)(dayBoundaryMinutes) | 450 | 凌晨归前一天的分界线(450=07:30) |
-| 每日反思(reflectEnabled) | 关 | 是否自动生成昨日反思 |
-| 定时固化(consolidateScheduleEnabled/Time/Days) | 开 / 09:30 / 7 | 每天到点读最近 N 天日志发散提炼长期要点 |
-| 定时蒸馏(maintainScheduleEnabled/Time) | 开 / 10:00 | 每天到点把超过 30 天的旧日志蒸馏归档 |
-| 反思风格(reflectStyle) | 由内容决定 | 生活化 / 专业性 / 由内容决定 |
-| 总结/问候默认模型(subagentModel) | 跟随路由默认 | 时段总结、问候、自动沉淀等子代理用的模型;留空即跟随 |
-
-### 3.7 上下文管理(context)
-
-| 项 | 默认 | 怎么调 |
-|---|---|---|
-| 交接白板(handoffEnabled) | 开 | PLAN.md + 四段式账本,注入到动态快照首位 |
-| 白板注入预算(handoffPlanChars) | 1200 | 字符硬截断 |
-| 账本注入预算(handoffLedgerChars) | 800 | 字符硬截断 |
-| 水位窗口覆盖(waterLevelWindowTokens) | 0=自动 | 0 表示自动:优先官方路由容量,其次按当前模型查 settings.yaml。**除非特殊模型,保持 0** |
-| 水位阈值(waterLevelThreshold) | 0.75 | 越阈值即注入交接建议并自动补写账本。**默认 0.75 而非 0.8**:官方自动压缩阈值是 80%,阈值贴着 80% 常被官方先压缩掉,留 5% 余量(1M 窗口约 50K token)才来得及走完交接 |
-| 水位建议注入(waterLevelAdvisory) | 开 | 无人值守时静默 |
-| 越阈值自动写账本(waterLevelAutoHandoff) | 开 | 每会话一次,给 AI 一个骨架,正式账本仍由 AI 写 |
-| **子代理痕迹回收**(subagentGcEnabled) | 开 | 见 §4.5 |
-| **兜底回收保留天数**(subagentGcKeepDays) | 3 | 每天巡检一次,回收超过该天数仍残留的痕迹;0=只靠任务结束即删 |
-
-> 「自动接续」的开关与阈值**不在设置页**,在**记忆面板 → 白板页签**顶部的「自动接续」卡片(见 §4.4)。
-
-### 3.8 维护(maintenance)
-
-| 项 | 说明 |
-|---|---|
-| 版本 / 检查更新 / 立即更新 | 显示当前与最新版本;registry 安装可直接一键更新 |
-| 诊断日志 | `~/.dsh/dsh-auto-memory-pre-diagnose.log`(子代理熔断、跳过、回收等事件都在内) |
-| 交流群 | 反馈问题比 GitHub issue 更快 |
-
----
-
-## 4. 上下文管理专题
-
-### 4.1 水位感知(上下文水位)
-
-记忆面板 → 白板页签顶部显示:**已用 token / 窗口 token · 百分比**,后面标注两个来源:
-
-- **计量**:`官方计量(usage)` = 与聊天框 context ring 同源(token-meter 的 `totalTokens`,即**当前上下文占用**);不可用时降级为启发式估算。
-- **窗口**:`官方路由容量` = 取自会话日志 `request/context` 的 `contextWindow`(最权威);`自动检测: provider/model` = 按**当前会话真实使用的模型**(会话日志 `request/header` 的 provider/model)查 `settings.yaml` 的 `contextWindow`,查不到才回退到 `agent-default-model`(新会话默认模型);`回退默认值` = 前两条都拿不到时的保守值(128K)——看到这个标签说明模型窗口没识别出来,可到设置页手动填 `waterLevelWindowTokens`。
-  > 你在这里看到的模型名是**这个会话正在用的模型**,不是设置里的默认模型;两者不一致时以会话为准(2026-09-08 修正,此前一律显示默认模型)。
-  > 卡片是**按会话**的:切换会话会自动换成该会话的数;该会话还没有实测数据(刚重启、或刚切过来还没发消息)时会标注「本会话尚未测量」,同时先把窗口与模型从该会话日志里推出来。
-
-达到阈值后:AI 收到交接建议,并自动补写一篇骨架账本(正式账本仍由 AI 写)。
-
-> **2.2.4 修复**:此前窗口解析有两条路同时失效(settings.yaml 的 flow 风格 YAML 解析不出、官方 contextWindow 事件只在会话开头出现而旧代码只扫最近 256 条),导致 1M 窗口被当成 128K、水位虚高显示 150%+。现已修复并如实标注来源。
->
-> **比例如实上报**:旧版还把百分比硬截断到 150%,任何超额都显示成同一个数(例如 761,692 / 131,072 真实为 581%,却显示 150%)。现在显示真实百分比,进度条仍按 100% 封顶。注意:宿主代码不会热重载,**升级后必须重启 dsh web**(浏览器再 Ctrl+Shift+R),否则读到的仍是旧窗口解析。
-
-### 4.2 交接白板
-
-- **PLAN.md**:项目全貌快照(项目全貌 / 当前目标 / 关键约定 / 下一步),AI 在有实质变化时重写,旧版自动归档。
-- **四段式交接账本**:任务状态 / 目标 / 已试方案与失败原因 / 进度与下一步,每段 ≤5 行,下一步必须是可直接执行的第一步。
-- 两者都会注入到每轮对话的动态快照首位,是跨窗口续命的核心。
-
-### 4.3 一键接续(手动)
-
-白板页签 →「**一键接续到新会话**」。流程与提示顺序:
-
-1. `刷新仪式:请旧 Agent 更新白板 PLAN 与交接账本…`(旧 Agent 先刷新材料,可在设置页关掉)
-2. `正在构造交接材料(含旧会话转写)…`
-3. `正在创建新会话(沿用旧工作区与模型)…` → `正在沿用旧模型 …` → `✓ 已创建新会话…`
-
-新会话**沿用**旧会话的工作区、模型、思考档位与预设,标题为 `接续 #N · <工作区名>`,首条消息是**分层交接材料**:
-
-| 层 | 内容 |
-|---|---|
-| 第0层 | 指令 + 白板 PLAN.md 节选 |
-| 第1层 | 最新交接账本全文 |
-| 第2层 | 近期线程(最近 20 条 × 700 字,保留角色与工具标记) |
-| 第3层 | 旧会话完整转写文件路径(新会话 AI 可随时 read 回读) |
-
-材料带时间戳,并会提示「白板比账本旧」这类过期风险。
-
-### 4.4 自动接续(免按钮,推荐)
-
-白板页签 →「自动接续」卡片:开关(默认开)+ 阈值(默认 0.75,与水位阈值同步;官方自动压缩阈值是 80%,低于它才有意义)。
-
-- **触发条件**:水位 ≥ 阈值 **且** harness 权威 `running` 位在轮次边界转为 `false`(会话真的空闲了)。长工具调用不会误触发。
-- **确认卡三分支**:点「同意接续」= 立即接续;点「拒绝」= 本轮跳过,同一边界不再提示;**30–40 秒无操作** = 视为挂机,自动接续。
-- 接续前先跑刷新仪式;触发后默认 30 分钟内不重复。
-- 挂机无人值守:设置页 → 自动化 →「无人值守自动接续」打开后,不再弹确认卡,直接接续。
-
-### 4.5 子代理痕迹回收(2.2.4 新增)
-
-**问题**:DSH 会为每个子代理创建一个持久化会话(`~/.dsh/sessions/<工作区>/<裸 uuid>/`)。本插件的自动沉淀 / 时段总结 / 问候 / 蒸馏都会 spawn 一次性子代理,实测全机 686 个子代理会话里 **638 个来自本插件**;积累上千后会拖慢会话列表加载。
-
-**做法**(设置 → 上下文管理):
-
-- **子代理痕迹回收**(默认开):子代理一结束,就把它的会话目录与投影缓存**移动**到 `~/.dsh/subagent-gc-backup/`(只移动不删除,可整体回滚),不影响子代理结果。
-- **兜底回收保留天数**(默认 3):每天巡检一次,回收超过该天数仍残留的痕迹(例如任务异常中断没删掉的);填 0 表示只靠"任务结束即删"。
-- 手动预览/执行:`node tools/subagent-gc.mjs`(预览,不移动任何文件)、`node tools/subagent-gc.mjs --apply`。
-- HTTP 自查:`GET /api/dsh-auto-memory-pre/subagent-gc`(只预览统计),`POST` 同路径即执行回收。
-- 回滚:把 `~/.dsh/subagent-gc-backup/<工作区>/<会话 id>/` 移回 `~/.dsh/sessions/<工作区>/` 即可。
-
-> 清理只针对 `origin=subagent` 且 label 以 `auto-memory-` 开头、mode 为 `one-shot` 的会话;可续聊(continuable)的子代理一律保留。
-
----
-
-## 5. 语义引擎专题
-
-下拉四档(设置 → 自动记忆引擎 →「语义引擎模式」):
-
-- **auto(默认)**:内置 JS 语义就绪即用,否则词法保底——最省心。
-- **lexical**:强制词法(不下载模型也能选)。
-- **js**:内置 JS 引擎(multilingual-e5-small,约 130MB)。选了但没下载会提示「实际生效:词法兜底」,点旁边 **⟳ 检测** 按引导下载。
-- **python**:高级引擎(BGE-M3 int8,约 563MB,本地 Python sidecar),召回质量最高,需要引导式安装(创建 venv + 下载模型)。装不上不影响其他档位。
-
-不确定时:**auto + shadow** 是最稳组合;看到「词法兜底」就说明语义资产没就绪。
-
----
-
-## 6. 记忆工具
-
-AI 在对话中可直接调用(你不需要记,但了解一下有好处):
-
-| 工具 | 作用 |
-|---|---|
-| `memory_log_pre` | 追加今日日志(append-only) |
-| `memory_note_pre` | 项目笔记 / 交接账本 / 白板重写 |
-| `memory_user_pre` | 跨项目长期规则 |
-| `memory_recall_pre` | 跨工作区检索记忆 + 历史会话全文检索 |
-| `memory_read_pre` | 按需读取某天日志 / 反思 / 笔记全文 |
-| `memory_external_pre` | 查看并接入其他 AI 工具的记忆(WorkBuddy/Claude Code/Codex/ZCode 等) |
-| `memory_consolidate_pre` | 做梦式固化:读日志发散提炼长期要点 |
-| `memory_maintain_pre` | 30 天蒸馏:旧日志提炼进笔记,原文归档 |
-| `memory_reflect_pre` | 保存每日反思 |
-| `memory_status_pre` | 查看记忆系统状态 |
-| `calendar_add/list/done/remove_pre` | 日程管理——AI 会主动从对话里提取截止日期并后续提醒 |
-
-自动沉淀:每轮对话结束,插件自动评估并把有长期价值的内容写进日志——**永远不需要说「记一下」**。
-
----
-
-## 7. 常见问题排查
-
-| 现象 | 处理 |
-|---|---|
-| 水位显示 `xxx / 131,072 token · 150%` 之类 | ①先确认**宿主已重启**(host 代码不热重载,只刷新页面没用)②窗口解析已在 2.2.4 修复;若标签仍是「回退默认值」,说明该模型不在 settings.yaml 里,手动填 `waterLevelWindowTokens` ③百分比已不再截断到 150%(旧版任何超额都显示 150%,真实值可能是 581%),进度条仍按 100% 封顶 |
-| 提示「词法兜底 / 未就绪」 | 设置 → 自动记忆引擎 → ⟳ 检测,按引导下载 JS 模型或装 Python |
-| 一键接续报「harness 未提供 remote.session」 | 重启 dsh web(注入面需重启加载);仍不行检查版本 ≥ 2.2.2 |
-| 新会话落到「未分组工作区」/ 没沿用模型与思考档位 | 2.2.4 已修复(create 传 workspaceId、模型取自 request/header);升级后需**重启 dsh web + 硬刷新页面** |
-| 自动接续没触发 | ①开关是否开 ②水位是否到阈值(白板页签看) ③会话是否真的空闲(running 已转 false) ④是否在 30 分钟冷却内 ⑤宿主是否已重启 |
-| 确认卡没等到回复就跑了 | 这是挂机兜底(30–40 秒无操作视为无人值守);不想被带走就点「拒绝」 |
-| 会话列表越用越卡 / 子代理一堆 | 设置 → 上下文管理 →「子代理痕迹回收」保持开;手动清一次:`node tools/subagent-gc.mjs --apply` |
-| 设置页整体消失 | 旧版 bug,升级 2.2.2+ |
-| 侧栏插件按钮消失 | 可能与其它往侧栏注入按钮的插件冲突(如 dsh-mobile 桌面浮层),到插件管理停用嫌疑插件 |
-| 记忆乱码 / 重复 | 写入口有卫生闸门;仍异常可到 存储 分组清理对应文件(先备份) |
-| 想反馈 / 拿日志 | `~/.dsh/dsh-auto-memory-pre-diagnose.log`;QQ 群见 README |
-
----
-
-## 8. 数据位置与回滚
-
-| 内容 | 路径 |
-|---|---|
-| 插件配置 | `~/.dsh/dsh-auto-memory-pre.json`(发布版 `dsh-auto-memory.json`) |
-| 用户级记忆 | `~/.dsh/memory/MEMORY.md` |
-| 工作区记忆 | `~/.dsh/memory/workspaces/<工作区>/`(MEMORY.md、每日日志、handoff/) |
-| 项目内记忆 | `<工作区>/.dsh-memory/` |
-| 白板与账本 | `~/.dsh/memory/workspaces/<工作区>/handoff/`(旧版在 `archive/`) |
-| 子代理痕迹备份 | `~/.dsh/subagent-gc-backup/`(移回 `~/.dsh/sessions/` 即回滚) |
-| 诊断日志 | `~/.dsh/dsh-auto-memory-pre-diagnose.log` |
-
----
-
-*BSD-3-Clause · 仓库:github.com/Aik358/dsh-auto-memory · 更多截图与宣传:README*
+# dsh-auto-memory 用户文档
+
+> 无问自忆：记忆不靠你吩咐，该想起的自己浮现；每条都有出处，可查、可改、可删。
+> 适用版本：**2.2.7+** · 更新日志见插件内「设置 → 外观 → 查看更新日志」。
+> English version: [USER-GUIDE.en.md](./USER-GUIDE.en.md)
+
+---
+
+## 目录
+
+1. [安装与入口](#1-安装与入口)
+2. [第一次启动](#2-第一次启动)
+3. [记忆面板十二页签](#3-记忆面板十二页签)
+4. [设置页逐组详解](#4-设置页逐组详解)
+   - [4.1 自动记忆引擎](#41-自动记忆引擎semantic)
+   - [4.2 记忆中枢](#42-记忆中枢memoryhub)
+   - [4.3 外观](#43-外观appearance)
+   - [4.4 存储](#44-存储storage)
+   - [4.5 记忆窗口](#45-记忆窗口injection)
+   - [4.6 自动化](#46-自动化automation)
+   - [4.7 上下文管理](#47-上下文管理context)
+   - [4.8 维护](#48-维护maintenance)
+5. [检索专题：一次查询走了哪些路](#5-检索专题)
+6. [主动联想专题：记忆怎么自己浮现](#6-主动联想专题)
+7. [证据链与记忆重要性](#7-证据链与记忆重要性)
+8. [上下文管理专题](#8-上下文管理专题)
+9. [记忆中枢专题](#9-记忆中枢专题)
+10. [记忆工具（对话中直接可用）](#10-记忆工具)
+11. [常见问题排查](#11-常见问题排查)
+12. [数据位置与回滚](#12-数据位置与回滚)
+
+---
+
+## 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**：插件的注入面（manifest）在启动时加载；改完 host 代码同理。
+- 浏览器端更新后需**硬刷新**（Ctrl+Shift+R）才会加载新 client.js。
+- pnpm v11 会拦截发布不足 24 小时的新版本（`minimumReleaseAge`）：当天更新请在 `pnpm-workspace.yaml` 设 `minimumReleaseAge: 0`，或直接 pin 版本号。
+- 入口：左侧栏底部 **记忆** 按钮 → 记忆面板。
+- 面板标题栏按钮：**图钉**（线描图标，与 ⟳ ⤾ ✕ 同画风；点一下钉住，点面板外不再自动收起，再点取消；钉住状态会记住）、**⤾** 恢复默认位置、**⟳** 刷新、**✕** 关闭。未钉住时点击面板外或按 Esc 即收起。
+- 面板标题里的版本号与 设置 →「检查更新」显示的都是**当前安装的版本**。
+- 侧栏还有一颗**悬浮钉**（线描快捷入口），可从任何页面快速唤出记忆操作。
+- DSH 0.1.2-rc.1 起 Web UI 有 token 认证闸门（每次重启换新 token，启动日志里 `?token=…` 即访问地址）；本插件的 HTTP 端点仅本机回环可访问，不受闸门影响。
+- 数据全在本机：`~/.dsh/memory/`（记忆文件）、`~/.dsh/dsh-auto-memory-pre.json`（配置，发布版为 `dsh-auto-memory.json`）。
+
+## 2. 第一次启动
+
+- 首次启动自动播放**欢迎向导**，每项功能当场可开关；向导内联了语义引擎的检测、下载与自测，一遍走完。想重看：设置 → 外观 →「重看引导」；更新日志：设置 → 外观 →「查看更新日志」（大版本更新日志带开场动画，点击任意处跳过）。
+- 向导会提示下载**内置语义模型**（约 130MB，multilingual-e5-small，本地离线运行，记忆不出电脑）。不下载也能用，召回退化为词法排序。
+- 之后随时到设置页逐组调整。**设置改动在保存后写配置文件**（右下保存栏，有未保存更改时按钮高亮）；仅「注入面/工具清单/思维链监听」类改动需要重启宿主，其余即时或下一轮生效。
+- 插件内置**公告中心**：发布者推送重大缺陷警报与升级建议，无需等新版发布。
+
+---
+
+## 3. 记忆面板十二页签
+
+> 左侧页签导航：**概览 / 日志 / 唤起回顾 / 记忆中枢 / 存储管理 / 笔记 / 白板 / 反思 / 接续 / 日历 / 检索 / 工作区**（窄面板时收进 › 溢出菜单）。
+
+| 页签 | 内容 |
+|---|---|
+| **概览** | 时段问候、今日工作（按日分组的日志条目数）、昨日反思摘要、工作区总结（跨工作区）、**一键反思**（用最近日志立即生成反思）。暂离超过阈值后回归，这里也是「欢迎回来」的落点 |
+| **日志** | 每日工作日志全文，按日期折叠；自动沉淀的条目实时出现 |
+| **唤起回顾** | 主动联想的**审计台**：每一次唤起决策（envelope）逐条列出——何时、因何触发、注入了什么、结果如何。可打五级评分：**A** 激活正确 / **P** 预取合适 / **S** 应该抑制 / **H** 有害注入 / **E** 内容需编辑；评分进入复核队列，消化为策略提示 |
+| **记忆中枢** | 三层长期记忆：**技能**（含审批队列：晋升/直接激活/弃用/置顶）、**事实**、**经历** 三栏；详见 §9 |
+| **存储管理** | 记忆文件浏览与统计；**扫描脏 token** 一键体检用户级/笔记/日志/反思（GBK 乱码 / 裸 JSON / 超长行 / base64 / 重复块，prion-scan 式四类启发式，**只报位置不含正文**） |
+| **笔记** | 项目长期笔记（MEMORY.md）查看与追加 |
+| **白板** | 交接白板主页：PLAN.md 全貌（含**历史版本**）、**交接账本时间线**、**水位卡**、**自动接续卡**（开关/阈值/确认卡）、**一键接续到新会话**。未启用白板时显示指引 |
+| **反思** | 每日反思列表（结果/教训/下一步） |
+| **接续** | 外部记忆接入（WorkBuddy / CodeBuddy / Claude Code / Codex / 项目约定等）：逐源扫描、逐源导入、逐源移除；**只存路径指针，不复制内容** |
+| **日历** | 07:00–22:00 时间线日视图：AI 从对话里自动提取的截止日期与承诺落在这里；未完成事项会在后续会话持续注入提醒 |
+| **检索** | **全文检索**（即时）+ **智能检索**（AI 把自然语言扩写成关键词、扫全部记忆层、综合成一段带出处的回答） |
+| **工作区** | 记忆关系图：工作区居中、记忆主题为枝、跨工作区共享为虚线；可拖拽缩放，点卡片看详情 |
+
+---
+
+## 4. 设置页逐组详解
+
+> 设置页分组导航顺序：**自动记忆引擎 → 记忆中枢 → 外观 → 存储 → 记忆窗口 → 自动化 → 上下文管理 → 维护**。
+> 下表默认值取自代码出厂设置；标 `(重启生效)` 的项需要重启 dsh web。
+
+### 4.1 自动记忆引擎（semantic）
+
+主动联想的总控区。开启后插件自动观测上下文、做语义检索、并适时把记忆注入对话。
+
+| 项 | 默认 | 怎么调 |
+|---|---|---|
+| 启用自动记忆引擎（associativeMemoryEnabled） | 关 | 总开关。关闭则整个引擎不运行——不检索、不判定、不注入、不生成唤起记录；已存记忆保留。介意 token 消耗或担心动作跑偏可关 |
+| 唤起注入模式（activationEmitMode） | `shadow` | **shadow**=只记录决策不注入（校准用，最稳）；**canary-explicit**=仅明确回忆时注入（推荐日常档）；**active**=所有判定都注入。JS/Python 双轨同源。旁边显示当前发射模式 |
+| 唤起冷却（分钟）（jsDecideCooldownRounds） | 1 | 注入后 N 轮内不再判定，防连续唤起浪费 token；**0=不冷却**（合法值） |
+| 唤起 margin 阈值（jsDecideDeltaExp） | 0.01 | 候选第 1/2 名分差须超过此值才注入（e5 余弦分布紧，默认 0.01；bge-m3 校准值 0.03）。调小=更容易唤起，调大=更保守；0=不过滤 |
+| 唤起候选方案（jsDecideCandidateScheme） | `balanced` | balanced=3 条×40 字符（信息量/token 平衡）；dense=6 条×20 字符（更多候选更广联想）；custom=自定义条数（1-8）与长度 |
+| 唤起注入内容长度（jsDecideExcerptChars） | 40 | Reference 行内容上限。40=关键词级（省 token，细节由模型 `memory_read_pre` 取全文）；可调 20-480 |
+| 检索模式（semanticEngineMode） | `auto` | **auto**=内置语义就绪即用，否则词法保底；**lexical**=仅词法；**js**=内置语义（e5-small，约 130MB）；**python**=高级 Python（BGE-M3 int8，约 563MB）。详见 §5。旁边的 **⟳ 检测** 按钮一键体检环境，缺资产时自动弹安装引导卡 |
+| 思维链监听（reasoningObserverEnabled） | 开 | 把模型思维链纳入实时观测 `(重启生效)`——闭源模型的概括式思维链同样纳入，是「边做边想起」的重要信号源 |
+| 分支会话观测（contextBridgeObserveChildSessions） | 开 | 跨天续接的会话标记为分支后同样纳入观测 |
+| 唤起阈值（校准策略） | 固定 | tauHi 0.45 · tauLo 0.35（只读展示，由校准策略 JSON 权威控制） |
+
+### 4.2 记忆中枢（memoryHub）
+
+三层记忆蒸馏的编排器：**经历（episodic）/ 事实（semantic）/ 技能（procedural）**。
+
+| 项 | 默认 | 怎么调 |
+|---|---|---|
+| 启用记忆中枢（memoryHubEnabled） | **开** | 总开关。开启后三层记忆开始运行；关闭则只保留已有记忆，不再沉淀新内容 |
+| 经历最少对话段数（episodicMinSegments） | 2 | 一次经历至少积累 N 段对话才巩固为记忆；太少噪声多，太多小对话被丢 |
+| 经历保留上限（episodicRetention） | 256 | 超出按时间淘汰最旧 |
+| 技能晋升跨会话数（procedureMinSessions） | 3 | 同一流程至少出现在 N 个独立会话才考虑晋升 |
+| 技能晋升成功次数（procedureMinSuccess） | 2 | 至少成功 N 次才可晋升——一次成功不足以证明可靠 |
+| 技能纠正容忍度（procedureCorrectionCap） | 0.3 | 纠正/错误占总证据比例超过该值即保持候选、不晋升 |
+| 高风险流程需批准（procedureHighRiskApproval） | 开 | SSH/部署/删除等高风险技能晋升需你明确批准，且**永不**因相似度自动执行 |
+| 技能注入形式（procedureActiveLevel） | `checklist` | checklist=完整步骤+完成标准；excerpt=摘要；hint=仅提示。高风险自动降级为 hint |
+
+### 4.3 外观（appearance）
+
+| 项 | 默认 | 说明 |
+|---|---|---|
+| 欢迎向导（welcomeTourEnabled） | 开 | 首启自动播放；旁边可「重看引导」「查看更新日志」 |
+| 界面语言（locale） | 跟随系统 | 中文 / English / 跟随系统 |
+| 界面字号（fontScale） | 标准 | 小/标准/大/特大，记忆面板文字大小，**立即生效，仅本机** |
+| 强调色（accentTheme） | DeepSeek 蓝 | DeepSeek 蓝 / 石墨灰 / 雾紫；日历与状态色保持语义色 |
+| 关系图密度（graphDensity） | 舒展 | 工作区关系图的节点间距与显示数量 |
+
+### 4.4 存储（storage）
+
+| 项 | 默认 | 说明 |
+|---|---|---|
+| 用户记忆目录（userMemoryDir） | `~/.dsh/memory` | 跨项目规则存放处，支持 `~` 开头；需有写权限 |
+| 项目记忆目录（projectMemoryDir） | `.dsh-memory` | 相对各工作区的目录名 |
+| 记忆根目录（memoryRoot） | `~/.dsh/memory/workspaces` | 集中存储：所有工作区记忆统一放这里（每工作区一个子目录），旧版分散记忆自动迁移；可点「浏览」换位置 |
+
+### 4.5 记忆窗口（injection）
+
+静态注入面：每轮对话组装提示词时注入的 `<memory_system>` 块。
+
+| 项 | 默认 | 怎么调 |
+|---|---|---|
+| 注入记忆上下文（injectEnabled） | 开 | 关掉即完全不注入 |
+| 注入预算（字符）（injectBudgetChars） | 1600 | 记忆块总预算，超出截断。觉得 AI 总被记忆打扰就调小，想不起事就调大 |
+| 注入最近日志天数（recentDaysInjected） | 1 | 最近 N 天日志尾部参与注入 |
+| 外部记忆注入预算（externalInjectionChars） | 1400 | 其他 AI 工具记忆的注入上限 |
+| 快照最小间隔（轮）（snapshotMinGapRounds） | 5 | 快照内容变化后至少隔 N 轮才重新注入，防历史膨胀；0=每轮都尝试（仍受内容变化约束） |
+| 压缩后立即重注入快照（snapshotReinjectOnCompact） | 开 | 上下文被压缩/截断后强制立即重注入一次，重建记忆背景 |
+| 自定义记忆注入 prompt（promptLayerOverrides） | 空 | 逐层覆盖注入文案（小众功能），支持 `{date}` `{ws}` `{budget}` `{n}` 占位符；改坏了一键恢复默认 |
+
+### 4.6 自动化（automation）
+
+| 项 | 默认 | 怎么调 |
+|---|---|---|
+| 自动沉淀（autoConsolidate） | 开 | 每轮对话结束由子代理评估：有长期价值的内容按主题写进今日日志——**永远不需要说「记一下」** |
+| 自动沉淀内容门槛（autoConsolidateMinChars） | 240 | 本轮 user+assistant 总字符低于该值视为寒暄跳过 |
+| 自动沉淀间隔/冷却（分钟）（autoConsolidateCooldownMinutes） | 30 | 两次沉淀最短间隔；夜间（22:00–08:00）自动翻倍。注意：填 0 会回退为 30（0 不表示关闭） |
+| 自动沉淀每日额度（autoConsolidateDailyMax） | 8 | 到点后当天不再调用 |
+| 自动弹出记忆窗口（autoPopupEnabled） | 开 | 暂离回归时自动弹出面板并问候；关闭后只能手动打开 |
+| 无人值守模式（unattendedMode） | 关 | 挂机批量任务用：不注入欢迎回来、行为指令、暂离提示、日历提醒——只注入纯事实记忆，token 全给工作 |
+| 夜间/非工作时间自动托管（unattendedAuto） | 关 | 处于时间窗（默认 22:00–08:00，可改 `unattendedAutoHours`）或检测到托管任务时自动进入无人值守 |
+| 暂离阈值（分钟）（awayMinutes） | 60 | 超过视为暂离，回归时欢迎问候；0=关闭暂离检测与问候 |
+| 自动总结时间点（autoSummaryTimes） | 空 | 逗号分隔 HH:MM，到点生成时段总结并弹窗；空=关闭 |
+| 日界（分钟）（dayBoundaryMinutes） | 450 | 凌晨在此之前的活儿归前一天：450=07:30 切日，480=08:00，0=按午夜 |
+| 每日反思（reflectEnabled） | 开 | 昨天有日志时，会话首轮主动呈现昨日反思 |
+| 反思风格（reflectStyle） | 由内容决定 | 生活化 / 专业性 / 由内容决定 |
+| 定时做梦式固化（consolidateScheduleEnabled） | 开 | 每天到点读最近日志发散提炼长期要点，写入笔记/用户级记忆 |
+| 固化触发时间 / 回看天数（consolidateScheduleTime/Days） | 09:30 / 7 | 命中时刻需宿主在线 |
+| 定时 30 天蒸馏（maintainScheduleEnabled） | 开 | 每天到点把超 30 天的旧日志蒸馏进笔记、原文归档；无旧日志零成本跳过 |
+| 蒸馏触发时间（maintainScheduleTime） | 10:00 | 与固化时间错开 |
+| 总结/问候默认模型（subagentModel/Provider） | 跟随路由默认 | 时段总结、问候、沉淀等子代理用的模型；留空跟随 |
+
+### 4.7 上下文管理（context）
+
+| 项 | 默认 | 怎么调 |
+|---|---|---|
+| 交接白板（handoffEnabled） | 关 | **PLAN.md 全貌快照 + 四段式交接账本**：模型在理解全貌/阶段完成时写入，注入动态快照首位，白板页签实时可看，跨窗口续命。建议开启 |
+| 白板注入预算（handoffPlanChars） | 1200 | PLAN.md 注入动态快照的硬截断预算；全文经 `memory_read_pre` 或白板页查看 |
+| 账本注入预算（handoffLedgerChars） | 800 | 最新账本的注入预算；账本内部按四段权重截断（失败原因 .35 ＞ 下一步 .30 ＞ 目标 .20 ＞ 状态 .15，从最低权重段起截） |
+| 水位估计窗口（token）（waterLevelWindowTokens） | 0=自动 | 0 表示自动：优先官方路由容量，其次按当前会话模型查 settings.yaml。**除非特殊模型，保持 0** |
+| 水位建议阈值（waterLevelThreshold） | 0.75 | 越阈即注入交接建议并自动补写账本。**默认 0.75 而非 0.8**：官方自动压缩阈值是 80%，贴着 80% 常被官方抢先压缩，留 5% 余量（1M 窗口约 50K token）才来得及走完交接 |
+| 水位交接建议（waterLevelAdvisory） | 开 | 越阈时在动态快照注入交接建议（写账本/刷新白板/建议开新窗）；无人值守时静默 |
+| 水位自动骨架账本（waterLevelAutoHandoff） | 开 | 越阈时自动写一篇系统骨架账本（每会话一次），防止模型忽视建议时交接材料缺失 |
+| 子代理痕迹回收（subagentGcEnabled） | 开 | 一次性子代理（沉淀/总结/问候/蒸馏）结束后立即把会话痕迹移入 `~/.dsh/subagent-gc-backup/`（只移动不删除，可回滚），防止会话列表越用越卡 |
+| 兜底回收保留天数（subagentGcKeepDays） | 3 | 每天巡检一次，回收超期残留（如异常中断没删的）；0=只靠任务结束即删 |
+
+> 「自动接续」的开关与阈值**不在设置页**，在**记忆面板 → 白板页签**的「自动接续」卡片（见 §8.4）。
+
+### 4.8 维护（maintenance）
+
+| 项 | 说明 |
+|---|---|
+| 插件版本 / 检查更新 | 与 npm registry 比对；registry 安装可一键更新。本地开发链接会显示更新命令 `cd ~/.dsh/profiles/web && pnpm up @a9i5k4/dsh-auto-memory` |
+| 诊断日志 | `~/.dsh/dsh-auto-memory-pre-diagnose.log`（子代理熔断、巩固跳过、回收、唤起降级等事件全在内） |
+| 交流群 | QQ 群反馈，响应比 issue 快（链接见 README） |
+
+---
+
+## 5. 检索专题
+
+一次 `memory_recall_pre`（或面板检索页）背后，召回走的是**多臂融合**管线：
+
+### 5.1 四个检索臂
+
+| 臂 | 做什么 | 特点 |
+|---|---|---|
+| **词法臂** | 关键词包含/BM25 打分 | 零依赖、永远可用；**错误码、变量名这类「L0 里没有的原文细节」靠它命中**；额外保留交接白板命中与全文命中段 |
+| **语义臂** | 向量余弦相似度 | 召回**词法不重合但主题相关**的记忆——查「发布凭证问题」能命中写着「npm ENEEDAUTH」的日志。C2 档=e5-small（JS 内置），C3 档=BGE-M3（Python sidecar）；Python 档同时配备词法臂兜底，语义服务不可用时自动回退，查询永不空转 |
+| **时间臂** | 中文时间表达解析 | 查询含「昨天/前天/上周/上上周/上个月/今年/最近 N 天/N 天前」等表达时，解析出 `[起,止)` 时间范围，**落在该时间段日志里的条目排序软提升**。只提升不硬过滤；**查询不含时间词时零行为变更**（与没有时间臂的版本逐字节一致） |
+| **证据加权** | 记忆被使用的历史 | 每条记忆的六类证据事件（§7）聚合为重要性 importance∈[0,1]，作为语义臂的加权因子；被你纠正过的记忆权重下降 |
+
+### 5.2 融合与返回：L0 分层
+
+- 各臂排名经 **RRF（rank-space 倒数排名融合，k=60）** 合并——只看名次不看绝对分，任何一臂缺席都不扰动其余结果。
+- 查询词先经 **QueryPlan 组装**（窗口 8 段/4096 字符预算、最多 32 个词项）；词项按**权重降序**保留（用户/触发词 1.0 ＞ 近期用户消息 0.8 ＞ 工具结果 0.6 ＞ 思维链 0.5 ＞ 工具调用 0.4 ＞ 助手输出 0.2），超预算时截掉的是低权重词，高权重的关键问句词永不被丢。
+- 默认返回 **L0 摘要列表**：每条约 93 字符（压缩 6.78:1），含 `id`、得分、匹配原因（`词法×N` / `语义×x.xx`）——一次检索只花十分之一的 token。
+- 要看某条原文：把它的 id 传给 `expand="mem_xxx"`（或 `memory_read_pre`），按锚点**字节区间**直接定位原文，精确不串条。
+- 检索范围 `scope`：`all`（默认，含白板语料+跨工作区+外部记忆+历史会话）/ `handoff`（只搜交接白板——接续长任务先查这里）/ `sessions`（只搜历史会话）。
+- 查不存在的主题：正常返回空或弱命中，不报错不阻塞（fail-soft）。
+
+### 5.3 检索模式怎么选
+
+- **auto（推荐）**：内置语义就绪即用，否则词法保底——最省心。
+- **lexical**：强制词法，0GB 依赖。
+- **js**：e5-small q8（约 130MB），选了但模型没下载会提示「词法兜底」，点 **⟳ 检测** 按引导下载。
+- **python**：BGE-M3 int8（约 563MB），召回质量最高；一键安装向导（检测 Python 3.9–3.12 → 建独立 venv 到 `~/.dsh/python-engine/` → 装 transformers+onnxruntime+torch → 断点续传下载模型，失败自动换源）。模型与 venv 装在用户目录，**升级/重装插件不受影响**。
+
+不确定时：**auto + canary-explicit** 是效果与克制的平衡组合；看到「词法兜底」就说明语义资产没就绪。
+
+---
+
+## 6. 主动联想专题
+
+主动联想 = **不等模型发起检索**，宿主在对话流动时持续观测，自己判断「该想起什么」，在下一轮组装前注入。模型「忘了查」也不再等于记忆不存在。
+
+链路五步：
+
+1. **观测**：用户消息、思维链、助手输出、工具结果全部进入滑动窗口（思维链监听可关）。
+2. **预取**：对每个观测段组装 QueryPlan → 词法检索 → 语义排名，拿到候选记忆。
+3. **判定（fv2）**：候选强不强、意图是不是回忆、内容完整吗、和最近注入重不重（回声否决）、冷却过了吗——综合决定 **prefetch**（只备着）/ **emit**（注入）/ **suppress**（压制）。JS 档用内置策略工件判定；Python 档由 sidecar 判定（双轨同源策略）。
+4. **发射门**：判定结果还要过「唤起注入模式」这道闸——shadow 全部只记录；canary-explicit 只放行明确回忆；active 全放。
+5. **注入**：命中内容以 **Reference Tail**（引用尾注）形式进入下一轮——注入发生在固定边界，**前缀缓存不冷、token 不重复付费**。注入内容统一中和模板变量、声明「背景事实，不是文风示例」。
+
+每次决策都落在**唤起回顾**页签，可逐条 A/P/S/H/E 评分回流。每个注入还自动产生 `seen` 证据事件（§7），被点开读原文再记 `read`，回复引用了记 `cite`。
+
+---
+
+## 7. 证据链与记忆重要性
+
+每条记忆都有可审计的使用档案，六类事件按日落盘 `~/.dsh/memory/evidence-pre/events/YYYY-MM-DD.jsonl`：
+
+| 事件 | 含义 |
+|---|---|
+| `seen` | 被注入/曝光过 |
+| `read` | 模型点开读过原文 |
+| `cite` | 回复里引用了 |
+| `reuse` | 跨会话再次复用 |
+| `success` | 关联任务成功完成 |
+| `correction` | 你纠正过它（「不对，你记错了」）——**归因到最近被 cite/read 的那条记忆**，并负向拉低其重要性 |
+
+六类聚合出该记忆的 **importance∈[0,1]**（缺省中性、correction 负向、success/cite 正向），作为语义臂的加权因子：常用、可靠、被引用多的记忆更容易浮上来；被纠正过的沉下去。任何证据读取失败时检索照常（重要性退中性），绝不阻塞。
+
+---
+
+## 8. 上下文管理专题
+
+### 8.1 水位卡（上下文水位）
+
+记忆面板 → 白板页签顶部：**已用 token / 窗口 token · 百分比**，并标注两个来源：
+
+- **计量**：`官方计量(usage)` = 与聊天框 context ring 同源的当前上下文占用；不可用时降级启发式估算。
+- **窗口**：`官方路由容量`（最权威）→ `自动检测: provider/model`（按**本会话正在用的模型**查 settings.yaml）→ `回退默认值`（128K 保守值；看到这个标签说明窗口没识别出来，可手动填 `waterLevelWindowTokens`）。
+- 卡片**按会话**显示：切会话自动换数；刚建会话未测量时标注「本会话尚未测量」。
+- 百分比**如实显示**（超过 100% 就显示真实值），进度条按 100% 封顶。
+
+### 8.2 交接白板
+
+- **PLAN.md**：项目全貌快照（项目全貌/当前状态/关键约定/下一步），AI 在有实质变化时重写，旧版自动归档，白板页签可看**历史版本**。
+- **四段式交接账本**：任务状态 / 目标 / 已试方案与失败原因 / 进度与下一步——下一步必须是可直接执行的第一步。账本按权重截断注入（失败原因最重），保证最值钱的教训永远在注入里。
+
+### 8.3 一键接续（手动）
+
+白板页签 →「**一键接续到新会话**」：
+
+1. `刷新仪式`：先让旧 Agent 把白板 PLAN 与账本刷到最新（可配置关闭；90 秒超时兜底）。
+2. `构造交接材料（含旧会话转写）`。
+3. `创建新会话`（**沿用**旧工作区、模型、思考档位与预设，标题 `接续 #N · <工作区名>`）。
+
+新会话首条消息是**分层交接材料**：
+
+| 层 | 内容 |
+|---|---|
+| 第0层 | 指令 + 白板 PLAN.md 节选（建立全局图景） |
+| 第1层 | 最新交接账本（四段式，含已试方案与失败原因） |
+| 第2层 | 近期线程（最近 20 条 × 700 字，保留角色与工具标记） |
+| 第3层 | 完整转写（文件路径给出，**按需 read**，不整段塞入） |
+
+文案明确「按需取用而非通读」——新会话不需要先读完整个旧会话就能继续干活。
+
+### 8.4 自动接续（免按钮，推荐）
+
+白板页签 →「自动接续」卡：开关（默认开）+ 阈值（默认 0.75，与水位阈值同步）。
+
+- **触发条件**：水位 ≥ 阈值 **且** harness 权威 `running` 位在轮次边界转为 `false`（会话真空闲）。长工具调用不会误触发。
+- **宿主兜底**：达阈值后在宿主侧开倒计时——页面被后台节流、标签页关了、甚至人不在，倒计时一到宿主自己完成「刷新白板/账本 → 建新会话 → 沿用模型与工作区 → 注入交接材料」。
+- **确认卡三分支**：同意=立即接续；拒绝=本轮跳过（同一边界不再提示）；**35 秒无操作**=视为挂机，自动接续。
+- 触发后默认 30 分钟内不重复。
+- 无人值守：设置 → 自动化 →「夜间/非工作时间自动托管」打开后不弹确认卡，直接接续。
+
+### 8.5 子代理痕迹回收
+
+DSH 为每个子代理建持久化会话目录；本插件的沉淀/总结/问候/蒸馏都是一次性子代理，积累上千会拖慢会话列表。回收（默认开）把 `origin=subagent` 且 label 以 `auto-memory-` 开头的一次性会话**移动**到 `~/.dsh/subagent-gc-backup/`（不删除，可整体回滚）；可续聊的子代理一律保留。手动预览/执行：`node tools/subagent-gc.mjs` / `--apply`。
+
+---
+
+## 9. 记忆中枢专题
+
+三层长期记忆（编排器 policyVersion `memory_hub_pre_v1`）：
+
+- **经历（episodic）**：对话流按段累积，攒满 `episodicMinSegments` 段巩固为一条经历，保留最近 256 条。
+- **事实（semantic）**：带主-谓-宾结构的结论（如「DSH 发射档位 · has three modes · …」），含冲突检测（`pendingConflicts`）。
+- **技能（procedural）**：反复出现、反复成功的流程固化为技能，注入时按 `procedureActiveLevel` 给 checklist/摘要/提示；**90 天未用自动归档，重要的可置顶，常用的保持温热**。
+
+晋升门控四关：跨 ≥3 个独立会话出现、成功 ≥2 次、纠正占比 ≤30%、高风险技能需你手动批准（审批队列在记忆中枢页签）。证据（含 success）不足的永远停在候选区。
+
+---
+
+## 10. 记忆工具
+
+AI 在对话中可直接调用（共 14 个，你不需要记）：
+
+| 工具 | 作用 |
+|---|---|
+| `memory_recall_pre` | 检索记忆：本地记忆（全工作区日志/笔记/反思/白板）+ 跨工作区 + 外部记忆 + 历史会话。默认返回 L0 摘要列表；`expand` 展开原文；`scope=handoff/sessions` 直达 |
+| `memory_read_pre` | 按需读取某条记忆/某天日志/反思/笔记全文 |
+| `memory_note_pre` | 写项目笔记 / 交接账本 / 重写白板 PLAN（`kind=plan/handoff`） |
+| `memory_log_pre` | 追加今日日志（append-only） |
+| `memory_user_pre` | 跨项目长期规则读写 |
+| `memory_reflect_pre` | 保存每日反思 |
+| `memory_consolidate_pre` | 做梦式固化：读最近日志发散提炼长期要点 |
+| `memory_maintain_pre` | 30 天蒸馏：旧日志提炼进笔记，原文归档，一字不丢 |
+| `memory_status_pre` | 记忆系统状态总览 |
+| `memory_external_pre` | 外部记忆源管理（扫描/接入/移除其他 AI 工具的记忆） |
+| `calendar_add_pre` / `calendar_list_pre` / `calendar_done_pre` / `calendar_remove_pre` | 日程管理——AI 主动从对话提取截止日期，未完成事项持续提醒 |
+
+三个写入工具（log/note/user）全部过**写入口闸门**：GBK 乱码、口吃退化、连续重复行、外部 AI 人设 JSON、base64 残留一律拒收并给人类可读原因；单次追加 ≤8000 字符、重写 ≤200000 字符、追加与最近约 60 行去重。**凭据/密钥段永远不进提示词。**
+
+---
+
+## 11. 常见问题排查
+
+| 现象 | 处理 |
+|---|---|
+| 语义查询召回为空 | ①看设置页检索模式与 `⟳ 检测`：js/python 资产没就绪会显示「词法兜底」，按引导下载/安装 ②Python 档确认 sidecar 在跑（诊断日志有 sidecar 记录）；2.2.7 起 Python 档带词法臂兜底，语义服务异常自动回退词法，不应再空转 ③auto 档会自动落到可用档位 |
+| 水位显示异常（如 150%） | ①先确认**宿主已重启**（host 代码不热重载）②窗口解析已修复并如实标注来源；百分比不再截断，进度条按 100% 封顶 ③标签是「回退默认值」= 该模型不在 settings.yaml，手动填 `waterLevelWindowTokens` |
+| 自动接续没触发 | ①白板页签卡里开关是否开 ②水位是否到阈值 ③会话是否真空闲（running 已转 false）④是否在 30 分钟冷却内 ⑤宿主是否已重启（宿主兜底依赖新注入面） |
+| 一键接续报「harness 未提供 remote.session」 | 重启 dsh web；仍不行检查插件版本 ≥ 2.2.2 |
+| 设置改了没生效 | 右下保存栏是否有点击（未保存时按钮高亮）；标 `(重启生效)` 的项需重启；浏览器端更新后 Ctrl+Shift+R |
+| 沉淀太频繁/太少 | 调 `autoConsolidateCooldownMinutes`（夜间自动翻倍；填 0 会按 30 处理）与每日额度 |
+| 会话列表越用越卡 | 设置 → 上下文管理 → 子代理痕迹回收保持开；手动清一次 `node tools/subagent-gc.mjs --apply`；备份在 `~/.dsh/subagent-gc-backup/` 可整体回滚 |
+| 唤起回顾里全是 prefetch 不见注入 | 发射门在 shadow 档（只记录）——设成 canary-explicit 或 active；或 margin 阈值调小 |
+| 记忆乱码 / 重复 | 写入口有卫生闸门；存量问题到 存储管理 页签「扫描脏 token」定位（只报位置），按位置手工清理（先备份） |
+| pnpm 安装当天新版被拦 | pnpm v11 `minimumReleaseAge` 拦 24h 内新版：`minimumReleaseAge: 0` 或 pin 版本 |
+| Web UI 打开要 token | DSH 0.1.2-rc.1 起的安全闸门，token 在 `dsh web` 启动日志的 URL 里，重启即换 |
+| 侧栏插件按钮消失 | 可能与其他注入侧栏的插件冲突，到插件管理停用嫌疑插件 |
+| 想反馈 / 拿日志 | `~/.dsh/dsh-auto-memory-pre-diagnose.log`；QQ 群见 README |
+
+---
+
+## 12. 数据位置与回滚
+
+| 内容 | 路径 |
+|---|---|
+| 插件配置 | `~/.dsh/dsh-auto-memory-pre.json`（发布版 `dsh-auto-memory.json`） |
+| 用户级记忆 | `~/.dsh/memory/MEMORY.md` |
+| 工作区记忆 | `~/.dsh/memory/workspaces/<工作区>/`（MEMORY.md、每日日志、handoff/、reflections/、summaries/） |
+| 白板与账本 | `~/.dsh/memory/workspaces/<工作区>/handoff/`（PLAN.md + handoff-*.md） |
+| 记忆中枢三层 | `~/.dsh/memory/hub-pre/`（episodes / facts / procedures .json，原子写） |
+| 证据事件 | `~/.dsh/memory/evidence-pre/events/YYYY-MM-DD.jsonl`（六类，按日） |
+| 语义引擎数据 | `~/.dsh/memory/semantic-pre/`（发射配置 embedding-config.json、决策影子日志、向量缓存） |
+| 语义模型/venv | `~/.dsh/models/js-semantic/`（C2 模型）· `~/.dsh/python-engine/`（C3 venv+模型，升级插件不受影响） |
+| 子代理痕迹备份 | `~/.dsh/subagent-gc-backup/`（移回 `~/.dsh/sessions/` 即回滚） |
+| 诊断日志 | `~/.dsh/dsh-auto-memory-pre-diagnose.log` |
+
+---
+
+*BSD-3-Clause · 仓库：github.com/Aik358/dsh-auto-memory · 更多截图与介绍：[README](../README.zh-CN.md) · English guide: [USER-GUIDE.en.md](./USER-GUIDE.en.md)*