@a9i5k4/dsh-auto-memory 2.2.2 → 2.2.4

package/docs/S3-TARGET-ARCHITECTURE.md

@@ -0,0 +1,172 @@
+# S3：目标架构 —— 分层契约与拟人化定位
+
+> 写于 2026-09-06。上位：[NEXT-MAJOR-VISION.md](NEXT-MAJOR-VISION.md)（愿景权威）、[S1-SCIENTIFIC-RIGOR.md](S1-SCIENTIFIC-RIGOR.md)、[S2-DEEP-ABSORPTION.md](S2-DEEP-ABSORPTION.md)。
+> 本文回答四个定位问题：①全貌是否应为文件系统架构；②唤起算法是否有更优者；③认知科学分类如何替换；④MemOS / Second Me 与拟人化愿景的关系。
+
+---
+
+## 1. 分层契约
+
+系统自顶向下分为六层，每层职责单一、依赖单向（上层依赖下层，下层不感知上层）。
+
+| # | 层 | 职责 | 现状 | 借鉴来源 |
+|---|---|---|---|---|
+| L1 | **激活决策层** | 观察情境 → 判定 *whether to inject*（是否该打断、注入什么、注入多少） | **已落地且领先** | 原创 |
+| L2 | **上下文分层** | 记忆的 L0/L1/L2 表示 + 固定边界注入 + 前缀缓存纪律 | 部分（注入形态三级，缺 L0/L1 表示与 token 账本） | OpenViking |
+| L3 | **检索三引擎** | C1 BM25 保底 → C2 e5-small q8 → C3 bge-m3，多臂融合 | **已落地**（融合层待修，见 S2 问题 4） | — |
+| L4 | **记忆命名空间** | `dsh://` URI 统一寻址，目录递归检索，先定位分组再下钻 | 部分（文件已分层，缺 URI 与 L0/L1 sidecar） | OpenViking |
+| L5 | **巩固引擎** | 证据 → 观察的周期性综合；矛盾打时间标记而非覆盖 | 弱（有沉淀与蒸馏，缺认识论分层与矛盾语义） | Hindsight |
+| L6 | **元记忆层** | 学习 *how to use* 检索所得，符号化规则库 ADD/MOD/DEL | 无 | MetaMem |
+
+**关键判断**：L1 是本项目唯一的原创层，也是唯一在五个对标项目中**找不到对应物**的层。OpenViking / Hindsight / Mem0 / Zep 全部优化 *what to retrieve*（给定查询下的检索质量）；本项目优化 *whether to inject*（无显式查询时是否该打断）。这一层应保持独立演进，不因借鉴而被稀释。
+
+---
+
+## 2. L4：文件系统架构 —— 采纳，但**只需显式化，不必重构**
+
+### 2.1 现状评估
+
+本项目的存储**天然就是文件系统**：`~/.dsh/memory/MEMORY.md`、`workspaces/{ws}/MEMORY.md`、`YYYY-MM-DD.md`、`reflections/`、`handoff/`。与 OpenViking 的差距不在存储介质，而在三处**未显式化**：
+
+| 缺失项 | 影响 | 改造成本 |
+|---|---|---|
+| **URI 命名空间** | 引用只能靠文件路径字符串；M-CM2 的 provenance 与 M5 cite 缺少稳定标识 | 低（纯约定 + 解析函数） |
+| **L0/L1 sidecar** | 判断相关性必须读全文，无法先便宜筛选 | 中（写入时生成摘要） |
+| **目录级 L0/L1** | 无法在读取前判断某工作区/时段是否值得下钻 | 中 |
+
+### 2.2 采纳方案
+
+```
+dsh://user/prefs/{key}                    用户级规则与偏好
+dsh://ws/{workspace}/notes/{topic}        项目笔记
+dsh://ws/{workspace}/log/{YYYY-MM-DD}     每日日志
+dsh://ws/{workspace}/reflect/{YYYY-MM-DD} 每日反思
+dsh://ws/{workspace}/handoff/{ts}         交接账本（M-CM1）
+dsh://ws/{workspace}/PLAN                 交接白板（M-CM1）
+dsh://ws/{workspace}/skills/{id}          固化技能
+```
+
+配套三条纪律：
+1. **URI 是引用标识，不是存储路径**——物理布局可变，URI 稳定。
+2. **每条记忆的 L0（~100 tok）随写入生成**，L1（~2k）按需生成；L2 为原文。
+3. **检索先定位目录（工作区 / 时段 / 类型），再逐层下钻**，保留浏览轨迹供审计。
+
+**明确不做**：不为对齐而重写存储层。现有 Markdown 文件布局已经正确，只需在其上加寻址与摘要两层。
+
+---
+
+## 3. L5：认知科学分类 —— 从"内容分类"转向"认识论分类"
+
+### 3.1 现行分类（episodic / semantic / procedural）的缺陷
+
+该分类源自 Tulving (1972) 的经典三分，本身并非"饱受批评"，但其为**描述性分类（taxonomy of content）**——回答"记忆是什么"，而非**功能性分类**——不回答"如何存取、如何巩固"。三个工程后果：
+
+1. **边界模糊**：「用户决定采用 PostgreSQL」既可归 semantic（事实）又可归 episodic（事件），分类无法判定。
+2. **不指导存取策略**：三类之间没有不同的读写语义，分类退化为标签。
+3. **不定义转化条件**：episodic → semantic 的迁移条件未形式化，只能靠启发式。
+
+### 3.2 Hindsight 的分类为何更优
+
+Hindsight 的 `world / experience / observation` 是**认识论分类（epistemic classification）**——按**可推导性与可变性**划分，而非按内容：
+
+| 类别 | 认识论地位 | 工程语义 |
+|---|---|---|
+| `world` / `experience` | **证据**（不可推导） | append-only，强写入门禁，永不自动删除 |
+| `observation` | **推断**（可由证据重算） | 允许 consolidation 重写/删除，可重算 |
+
+此分类**直接映射工程策略**：证据只增不改；推断可重算。这是功能性分类的核心价值——分类本身携带了操作语义。
+
+### 3.3 建议：正交三维取代单一三分类
+
+保留存储层分层（用户级/项目/日志/反思，即作用域），在其上叠加两个正交维度：
+
+| 维度 | 取值 | 来源 | 作用 |
+|---|---|---|---|
+| **作用域** scope | `user` / `workspace` / `session` | 已有 | 决定隔离与共享 |
+| **认识论地位** status | `fact`（证据）/ `observation`（推断）/ `directive`（行为指令） | Hindsight | 决定可写性、可删性、可重算性 |
+| **稳定性** stability | `volatile` / `stable` / `superseded` | Hindsight trend + 现有 supersede | 决定注入优先级与蒸馏策略 |
+
+**关于 procedural（技能）**：它不是第三类记忆，而是 `directive`（行为指令）——Hindsight 亦将技能归入 mental model / directive 而非独立记忆类型。**此归并保留本项目的技能固化特色，同时消除分类歧义**：技能 = 由重复成功证据推导出的行为指令，`status=directive`、`stability=stable`，跨会话验证数即其证明强度。
+
+**迁移策略**：三维为**增量元数据**，不改动现有文件布局。先给新写入打标，存量按规则回填（日志→`fact`+`volatile`，项目笔记→`observation`+`stable`，技能→`directive`+`stable`）。
+
+---
+
+## 4. 拟人化愿景：定位与参照
+
+### 4.1 本项目的拟人化是"第二人称"，与 Second Me 根本不同
+
+| | Second Me | 本项目 |
+|---|---|---|
+| 人称 | **第一人称**——AI 成为"你"（数字分身、身份复制） | **第二人称**——AI 是"记得你的同事" |
+| 技术路线 | 参数化（SFT + DPO 把个人知识训进权重） | 外置结构化记忆 + 情境唤起 |
+| 结局 | **已停摆 11 个月**（见 S1 §4） | 活跃 |
+
+**结论**：Second Me 的**愿景**（拟人化身份）成立，失败在**技术路线**（参数化微调不可增量、不可调试、成本收益失衡）。本项目的"她"与之共享愿景动机，但走了相反且正确的技术路线——**不应因 Second Me 失败而否定拟人化方向本身。**
+
+### 4.2 MemOS 对应基础设施愿景，不对应拟人化
+
+MemOS 的隐喻是**操作系统**（记忆作为一等系统资源），属工程治理视角。其对本项目的价值仅在两点：
+- **MemCube 的治理属性**（provenance / 版本 / 过期 / 访问权限）——直接支撑 README「她怎么让你放心」的可审计承诺；
+- **MemScheduler 的生命周期调度**——与稳定性维度（`volatile/stable/superseded`）的自动迁移相关。
+
+**不取**：MemOS 的参数化记忆（LoRA 至今仍为 placeholder，见 S1 §1.2）。
+
+### 4.3 拟人化的三个可工程化维度
+
+README 的叙事（"她"、问候、骑自行车、交接）需有技术支撑才不沦为包装。建议形式化为三维度并各自设可测指标：
+
+| 维度 | 内涵 | 现状 | 可测指标 |
+|---|---|---|---|
+| **连续性** Continuity | 跨窗口 / 跨会话 / 跨工具不断线 | 强（M-CM + 外部继承） | 窗口切换后任务恢复成功率 |
+| **可问责性** Accountability | 每条记忆有出处，可查可改可删 | 强（evidence 链 + 唤起回顾五档） | 唤起决策的可解释覆盖率 |
+| **分寸感** Appropriateness | 知道**何时不该说话** | 中（有 cooldown / user-ignored，未形成学习闭环） | 用户忽略率、误注入率 |
+
+**第三项是最能拉开拟人化差距、且当前最薄弱的一项。** 现有 `user-ignored` drop reason 已记录用户忽略行为，这是**现成的负反馈信号**，可支撑分寸感的学习闭环（见 §5.2）。
+
+---
+
+## 5. L1 唤起算法：横向定位与补强
+
+### 5.1 结论：方向上没有更优者，但缺一个维度
+
+现有对标（OpenViking / Hindsight / Mem0 / Zep / MemOS）**全部为查询驱动的被动检索**，无一家实现"无查询、情境驱动、开口前注入"。本项目的唤起方向在公开项目中无更优替代。
+
+与最接近的学术工作对比——*Generative Agents* (Park et al., 2023) 的 memory stream 采用三维评分：
+
+$$\text{score} = \alpha \cdot \text{recency} + \beta \cdot \text{importance} + \gamma \cdot \text{relevance}$$
+
+对照本项目 `shadow-retrieval-pre.js`：
+
+| 维度 | 本项目 | 差距 |
+|---|---|---|
+| relevance（相关性） | 强（BM25 + 语义 + 短语 + 标题覆盖） | — |
+| recency（新近度） | **弱**——仅 `workspace-log` 计算（S2 问题 3） | 需扩至全记忆层 |
+| **importance（重要性）** | **缺失** | 需新增 |
+
+**importance 是最值得补的一维**：它不随查询变化，是记忆自身的属性（用户显式 pin、跨会话复现次数、被引用次数、是否承载决策），天然适合作为**绝对量**参与门控——恰好可缓解 S2 问题 4 中"分数丧失绝对性"的困境。
+
+### 5.2 补强项（按 ROI）
+
+1. **引入 importance 维度**：`importance = f(pinned, 跨会话复现数, 被引用数, 是否决策)`，作为绝对量参与门控，与相对融合分解耦（呼应 S2 问题 4 解法）。
+2. **负反馈学习闭环**：`user-ignored` / `emitOnSuppress` 等 drop reason 已是标注数据，可驱动门控权重的离线再标定（沿用 M7 的 held-out + 配对 bootstrap 口径）。
+3. **唤起的节律**：人类记忆唤起有间隔效应；现有 `cooldownSegments` 是固定冷却，可考虑按记忆的 stability 动态调整（stable 记忆冷却更长，volatile 更短）。
+
+---
+
+## 6. L6 元记忆层：MetaMem 的接入方式
+
+**定位澄清**：MetaMem **不优化检索本身**，它优化的是"检索结果被如何使用"。对本项目的价值在注入之后，而非检索之前。
+
+**轻量落地**（无需完整训练循环）：
+
+1. 以自然语言规则库形式初始化（可手工撰写 10–20 条，例如「冲突时优先最新」「汇总数值优先用显式结论而非分段累加」）。
+2. 每次唤起后，若发生可观测失败（误注入、用户忽略、证据冲突未处理），触发一次自反思，产出 `ADD / MOD / DEL` 提案。
+3. 用既有 67 条人工金标 held-out 做提案过滤与效果验证——**这与 M7 的评估通路天然复用**，边际成本极低。
+4. 规则库设容量上限（MetaMem 论文指出过度训练会积累冗余规则并损伤泛化，S1 §5 已记录）。
+
+---
+
+## 7. 一句话
+
+**文件系统是骨架（L2/L4），巩固是代谢（L5），元记忆是反射（L6），而唤起决策（L1）是这套系统唯一的"性格"所在——前者都可借鉴，后者只能自己长。**

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

@@ -0,0 +1,283 @@
+# 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。
+- 入口:左侧栏底部 **记忆** 按钮 → 记忆面板,含页签 **概览 / 白板 / 语料精修 / 设置**。
+- 数据全在本机:`~/.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.8 | 越阈值即注入交接建议并自动补写账本 |
+| 水位建议注入(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` = 按当前模型查 `settings.yaml` 的 `contextWindow`;`回退默认值` = 前两条都拿不到时的保守值(128K)——看到这个标签说明模型窗口没识别出来,可到设置页手动填 `waterLevelWindowTokens`。
+
+达到阈值后:AI 收到交接建议,并自动补写一篇骨架账本(正式账本仍由 AI 写)。
+
+> **2.2.4 修复**:此前窗口解析有两条路同时失效(settings.yaml 的 flow 风格 YAML 解析不出、官方 contextWindow 事件只在会话开头出现而旧代码只扫最近 256 条),导致 1M 窗口被当成 128K、水位虚高显示 150%+。现已修复并如实标注来源。
+
+### 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.8)。
+
+- **触发条件**:水位 ≥ 阈值 **且** 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%` 之类 | 2.2.4 已修复(窗口解析两条路都失效);升级后重启 dsh web + 硬刷新。若标签仍显示「回退默认值」,说明该模型不在 settings.yaml 里,手动填 `waterLevelWindowTokens` |
+| 提示「词法兜底 / 未就绪」 | 设置 → 自动记忆引擎 → ⟳ 检测,按引导下载 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*