# dsh-auto-memory 用户手册
← 返回 README
> 无问自忆：记忆不靠你吩咐，该想起的自己浮现；每条都有出处，可查、可改、可删。
> 适用版本：**3.0+** · 更新日志见插件内「设置 → 外观 → 查看更新日志」。
> 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-数据位置与回滚)
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**：插件的注入面（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）
静态注入面：每轮对话组装提示词时注入的 `` 块。
| 项 | 默认 | 怎么调 |
|---|---|---|
| 注入记忆上下文（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` |
---
## 13. 3.0 底层重建：对你意味着什么
这一版大部分工作不产生新按钮。它改的是"记忆凭什么被相信"。**你不需要做任何配置**——下面每一条都是默认行为，列出来是为了让你知道边界在哪。
### 13.1 写入更安全：脏正文不再让文件永久失效
以前：一条正文里若出现记忆系统自己的保留标记，写入当场"成功"，但**从下一次写入开始，整个文件都会被拒绝**，且报错不给行号——现场只能自写脚本逐行找。
现在：保留语法检测前移到**写入原语**，含保留标记的正文**当场被拒并给出命中行号**；同时修复了一处既有静默损坏（整理流程会把归档日志自己的标记行内联进笔记，制造幻影锚点）。
> 顺带一提：任何"用反引号/代码块包裹"的规避手法都无效——判定是子串级，必须改写措辞。
### 13.2 写入更稳：Windows 瞬态占用不再丢内容
Windows 下 `rename` 撞上外部文件句柄（杀软扫描、Search 索引、编辑器、宿主刚落盘的句柄）会抛 `EPERM`，属**瞬态**。以前这一层没有退避重试，异常直接上抛，**本次记忆整条丢失**。
现在：`EPERM / EACCES / EBUSY` 走退避重试（`[0, 50, 150, 400, 1000] ms`）；最终仍失败时**保留完整候选快照**（`.dam-failed---<名称>.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)*