深鲸记忆 · dsh-memory-doctor
跨会话记忆的管家：用量体检、重复合并、备份恢复、记忆包迁移。本地明文、零依赖、不上传任何数据。
它解决什么
现在大多数记忆插件都在解决「记住」。但用久了真正的问题变成：
- 记忆越写越满（运行时记忆有硬上限），到点就被动归档
- 同一条记了两遍、内容差不多但措辞不同
- 「临时/进度」类内容混进长期记忆，占着预算
- 换电脑、团队协作时，记忆带不走
本插件补的就是这三件事，不改你现有的记忆文件格式（~/.mnemon/runtime/ 下的 MEMORY.md / USER.md），
所以它可以和现有记忆插件共存。
它自己就是热记忆（不是配件）
每轮对话都会把 MEMORY.md（项目/环境记忆）和 USER.md（用户画像）注入 system prompt，
并附带「记忆维护协议」——所以 Agent 真的会记住，而且知道什么时候该写、写去哪、别重复写。
- 注入预算默认 6000 字符，超了截断并提示归档（不会把上下文吃光）
- 记忆是明文 Markdown（
~/.mnemon/runtime/），你自己随时能看、能改、能带走
- Agent 用自带的写文件工具维护记忆，不需要额外工具调用
与别的记忆插件共存 / 替换
本插件默认会自动让位：如果检测到 profile 里装着其他记忆插件，
就不做每轮注入（只提供体检 / 瘦身 / 记忆包），避免两份记忆打架。
- 共存（推荐先这样）：保留对方的注入，本插件只当「记忆管家」——体检、归档、导出；
- 替换：在插件面板停用（不必卸载）对方，重启后本插件自动接管注入（判断只看已启用的 bundles）；
- 强制开关：
MEMORY_DOCTOR_INJECT=0 关、=1 开（优先级最高），或写
~/.mnemon/doctor.json：{ "inject": true } / { "inject": false }。
记忆文件是同一份（~/.mnemon/runtime/MEMORY.md、USER.md），所以替换时内容不用迁移。
功能
- 工作项（0.5.19 起）：把「正在做的事」从聊天记录里拎出来。工单管现在、记忆管以后 —— 工作项只存任务状态（谁发起 / 凭什么做 / 做到哪 / 卡在等谁 / 产出在哪），不存知识结论；结项时填的「教训」自动写入 MEMORY.md。
observe 模式只记录不动手，人确认后才允许执行（对应 superagent 的 observe→auto 思路）。面板新增「工作项」页签；工具 work_item（create/list/update/move/confirm/close）。
| 功能 | 说明 |
|---|
| 写记忆工具 | Agent 可调用 memory 工具：read / append / replace / remove / search / stats / compact；写入经宿主进程、绕开文件沙箱，自动去重、写前备份、到 80% 自动压缩、超上限拒绝 |
| 会话回复存入记忆 | 每条助手回复旁的大脑按钮：预览后一键存入 MEMORY.md / USER.md（自动去重、写前备份、超上限提示） |
| 概览 | 系统状态卡片（记忆引擎 / 运行时记忆 / 归档 / 记忆包）、存储域（根路径+三个子存储）、记忆来源与共存状态、用量（实时曲线 + 历次体检快照，两种口径分开标注）、最近写入 |
| 体检（分级） | 用量百分比、条目数、重复/近重复、低信息量、临时/阶段性条目；只有真需要动作的（超上限、完全重复）才在面板顶部弹黄条，其余只进体检列表，每条可「忽略」（0.5.8） |
| 自动压缩（四层） | 到 80% 自动跑四层管线：L1 无损折叠 → L2 超大条目落盘 → L3 按优先级驱逐 → L4 到摘要线才 LLM 摘要；每层都可恢复、有谱系记录，见下面「压缩」一节 |
| 忽略 | 误报的条目点「忽略」后不再出现在建议里；设置页可一键全部恢复 |
| 瘦身 | 按勾选归档到 archived/（先备份、只移动、不删除，可回滚） |
| 文档（只读） | 浏览 ~/.mnemon/documents/ 里的项目文档（只读，不修改） |
| 对比上次 | 与上一次体检对比：新增 / 移除的记忆条目 |
| 记忆包 | 一键导出 ~/.mnemon/记忆包-日期-xxxx/（含 manifest.json、文档、git 版本），可换机/团队共享/留档 |
压缩（0.5.11 起：四层管线）
MEMORY.md 是整份每轮注入 + 硬上限 10KB，所以它一定会满。旧版是「到 80% 就归档临时条目 + 把长条压成首句」的一刀切；
0.5.11 改成四层依次尝试，每一层都能单独恢复，单层失败只降级、不阻断：
| 层 | 什么时候做 | 做什么 | 怎么恢复 |
|---|
| L1 无损折叠 | 有连续重复行（同一行 ≥3 次）且真能省字节 | 折叠成一行标记 ⟦dsh-fold-N-<行指纹>⟧（带指纹，多条记录不串），不丢信息 | 逆变换.json 的 L1 记录 + 还原折叠() 逐字节还原；层快照 1-折叠.md |
| L2 落盘 | 单条内容 > 4000 字节 | 全文存 落盘/条目-N.md，上下文里留头 480B + 尾 160B + 路径 + SHA256 | 直接读落盘文件；校验压缩() 用 SHA256 校验完整性 |
| L3 软压力 | 70% 只提醒（不改内容）；80% 起驱逐 | 按优先级：临时/进度类 → 可重放指针（已落盘/已归档）→ 超长条目首句化（至少留 3 条） | 被驱逐的进 归档条目.md；整份原文在存档根目录 |
| L4 LLM 摘要 | 前三层压完仍 ≥90%，且调用方注入了摘要器 | 摘要正文上限 = 上限的 15%（预算预留同样 15%），永远保留最新 1 条原文 | 摘要前全量写 摘要前-MEMORY.md；不注入摘要器就跳过（默认不调 LLM） |
每次触发的存档目录 ~/.mnemon/runtime/archived/自动压缩-<时间>/：
MEMORY.md 压缩前全量（整体回滚用）
memories.json 压缩前记忆库
归档条目.md L3 驱逐出去的条目
落盘/条目-N.md L2 落盘全文（带 SHA256）
层快照/0-原始.md … 4-摘要.md 每层跑完的样子
逆变换.json L1 折叠记录 / L2 SHA256 / L3 归档 / L4 摘要
谱系.json 四层各自的状态（ok / noop / 跳过 / 降级）、原因、省下字节
- 入口：
自动压缩({ 文件, 摘要器?, 摘要阈值? })，写记忆/改记忆前自动触发；也可 memory action=compact 手动跑
- 整体回滚：
恢复压缩({ 存档文件名, 确认: true })（会先把当前内容另存 .恢复压缩前.bak）
- 存档完整性：
校验压缩({ 存档文件名 }) → 逐项检查全量存档 / 逆变换 / 落盘 SHA256 / 层快照
- 谱系列表：
压缩谱系()；同时追加一行到 archived/压缩谱系.jsonl（最多保留 200 行）
- L4 默认不跑：插件自己不发 LLM 请求；只有宿主/调用方传入
摘要器 才执行，否则该层记「跳过（未注入摘要器）」并降级
- 任何时候都不删除内容：只做「折叠 / 落盘 / 归档 / 摘要」，原文都能从
archived/ 取回
安装
dsh plugin --profile web add dsh-memory-doctor
- 面板安装需要本机有
pnpm（DSH 的安装器依赖它）
- 没有 pnpm 也行：下载仓库 → 把整个文件夹放进
dsh-home/plugins/ → 重启 DeepWhale Desktop
- 装好后侧栏出现「记忆体检」图标；命令
/memory 可用
面板自检（改 UI 前必跑）
node scripts/panel-check.mjs # 需要全局 playwright；无头打开真实面板，抓渲染报错 + 打印界面文字
2026-11-01 起作为 UI 交付前的硬检查：抓未定义引用/渲染崩溃，避免让用户当第一测试员。
本地安装（开发机）
同源两处都要装，否则重启会被随包载荷覆盖：
bash scripts/install-local.sh
它会把当前仓库的 lib/ + package.json 一起装到随包载荷（Resources/bundled-plugins/dsh-memory-doctor）与用户插件目录（dsh-home/plugins/dsh-memory-doctor），两处各留 .bak-<时间> 备份并校验版本。
⚠️ 桌面端升级（重装 dmg）会换掉载荷 → 升级后重跑一次本脚本即可。
测试
bash tests/run.sh # 106 项：拆条目/体检/瘦身/记忆包/注入/四层压缩/实时曲线（离线，不调 LLM）
使用
- 面板：侧栏「深鲸记忆」图标（大脑图标）→ 概览 / 运行时记忆 / 记忆包 / 归档 / 设置 五个页签
- 命令：
/memory → 一句话看健康度
白屏防护（2026-10-27 起硬性要求）
宿主 web 启动时，任何一个客户端插件激活失败都会让整页显示 "Failed to load plugins"（白屏）。
本插件三层保证自己永远不会触发这件事：
- 客户层加载整体 try/catch：加载期异常 → 降级为空插件（不注册任何槽位），界面照常；
- 错误边界：面板与「存入记忆」按钮都用 React ErrorBoundary 包住，渲染期异常只在那一块显示一句提示；
- apply() 绝不抛错：槽位服务缺失、某个槽位注册失败都只记日志跳过。
发布前自动闸门：npm run preflight（scripts/preflight-client.mjs）模拟宿主加载/激活/渲染，
不通过就发不出去（prepublishOnly 自动执行）；同类闸门也用于其它深鲸插件。
安全
- 只读写
~/.mnemon/；不做删除（归档 + 备份）
- 不联网、不上传；无遥测
未知边界
- 目前瘦身只处理
MEMORY.md（USER.md 是人格画像，建议人工编辑）
- 记忆包导入为追加合并，不与现有条目冲突时才加
更新记录
- 0.5.24：工作项 KPI 补「等评审」—— 自检发现「等评审」不在任何卡片里（四项全 0 但列表有一条等评审，容易误读成没活）。新增
scripts/panel-check.mjs 无头面板自检（抓渲染报错 + 打印界面文字）。
- 0.5.23：面板文案收口（第二次）—— 删掉「没人跑，这不是进度」「为什么它和记忆是上下游而不是竞品」这类内部设计辩解与「工单管现在」的内部框架话；面板只说用户看到什么、该点什么。
- 0.5.22：工作项加
owner（执行者）+ 面板「认领」表单 —— 修一个设计洞：没有 owner 的「进行中」是假进度（点开始≠有人在跑）。列表现在显示「执行者：谁 / 未认领」与最近一条进展；统计加「未认领」；工具 work_item 新增 action=claim、owner 参数。测试 115 → 120 项。
- 0.5.21：修「新建工作项后整块面板降级」—— 客户端 bundle 里引用了宿主侧导出的
阶段中文（未定义），改为优先读接口返回的中文表 + 本地兜底。
- 0.5.20：修面板「新建工作项/结项」点了没反应 —— Electron 不支持
window.prompt（不弹框、直接返回 null），改为面板内联表单（标题/授权/范围/模式，结项带教训输入）。
- 0.5.19：新增工作项账本（
lib/works.js + work_item 工具 + 面板「工作项」页签 + /api/works 等接口）。设计边界：工单管「现在」，记忆管「以后」——工作项不存知识结论，结项时的 lesson 自动写进 MEMORY.md；observe 模式只记录不动手、人工确认后才执行；阶段机 open / working / awaiting-person / awaiting-review / done / stopped / failed，非法迁移拒绝；存储 <记忆家>/work-items.json，原子写 + 每次备份（archived/work-items.*.bak，留 20 份）。测试 106 → 115 项。
- 0.5.18：面板文案与呈现收口 —— 删掉「两种口径不能对比」这类自解释的免责声明，改由区块标题与分隔线表达；迷你折线换成「占用条 + 较上次变化 + 区间」（没有写入时才不会像条死线）；头部状态不再永远写「运行正常」（有问题时显示待处理条数）；「去体检」按钮与实际跳转对齐为「去处理」；版本兜底不再硬编 0.3.0。测试 106 项。
- 0.5.17：合并两条线并修一个口径问题 —— 面板「用量」卡把两种口径拆开标注：「实时（每 2 秒 stat 文件字节，滚动最近 3 分钟）」与「历次体检（每次体检记一个点，最近 N 次）」，并注明二者不能逐点对比；同时带上 0.5.13~0.5.15 的实时曲线、趋势图取值修正，以及 0.5.11 的四层压缩管线。测试 106 项。
- 0.5.11
：自动压缩升级为四层管线（L1 无损折叠 / L2 落盘 / L3 软压力 / L4 摘要），每层可逆、有谱系与层快照，单层失败降级不阻断；新增
压缩谱系/校验压缩/恢复压缩；70% 起软压力提醒；测试 75 → 101 项。
- 0.5.4：写入改为以宿主运行时记忆的
memories.json 为源（md 只是投影）——之前直接改 md，宿主重启会用 memories.json 把改动覆盖回去（USER.md 99% 反复出现就是这个原因）；现在追加/替换/归档/瘦身/恢复都会同步库并重新投影。
- 0.5.0：补上「会话回复存入记忆」——每条助手回复旁的大脑按钮（和宿主记忆系统的位置/交互对齐），预览后存入工作记忆或用户画像；新增
/api/message、/api/save-message；55 项测试。
- 0.4.0：新增
memory 工具（Agent 写记忆不再依赖文件沙箱）；文档页只读浏览；概览新增「与上次体检对比」；注入判断只看已启用的 bundles（停用但不卸载也会自动接管）；51 项测试。
- 0.3.0：面板升级为「仪表盘」结构：系统状态 + 存储域 + 记忆来源 + 用量趋势（历史快照）；运行时记忆改双栏（列表 + 条目详情侧栏）；新增「设置」页（注入开关、路径复制、导出诊断报告、版本与仓库入口）；服务端新增
/api/config、/api/report、诊断与历史快照。
- 0.2.0：面板重做（对齐宿主「记忆系统」的信息架构：状态卡片 + 页签 + 分组 + 搜索筛选 + 批量归档）；新增归档列表与一键恢复；侧栏改名「深鲸记忆」、图标改大脑；服务端补
/api/archive、/api/restore。
