dsh-super-memory

dsh-super-memory（超级记忆）

跨压缩记忆插件：在同一个超长会话里被上下文压缩过几次之后，你早先问过 / 定过的事，模型先看到它，再作为参考结合这次的新条件综合回答——不会当新问题从零重来。

只做同一个会话内、跨压缩这一段。跨会话记忆不在范围内（那是另一类插件的事）。 插件自包含：不依赖任何其他记忆插件，不访问互联网，默认一次模型都不调用。

关于本插件（请先读这两句）

• 本插件由 AI 协助开发与维护，可能存在缺陷。请在重要场景自行验证后再依赖它；发现问题欢迎开 issue 或直接改（见下方「许可」）。
• 它主要面向学习与测试用途，作者不保证持续更新。代码是 MIT 许可，fork、修改、再发布都可以。
• 运行环境需要带 zstd 支持的 Node：插件读会话日志要用 node:zlib 的 zstdDecompressSync，所以 package.json 的 engines 声明了 node >= 22.15。CI 实测 Node 20.20.2 会在加载时直接报语法错（does not provide an export named 'zstdDecompressSync'），Node 24.x 正常，22.x 由 CI 矩阵验证。DSH 本体读会话日志用的是同一个 API，所以下限一致。

1. 这是什么 / 解决什么问题

一句话：上下文压缩会把早先的对话从模型眼前拿走（原文仍在磁盘上），这个插件在被拿走的那一刻把它存到你本机，之后只在相关的时候把那几段递回给模型。

一个真实场景：

1. 同一件事在会话开头被讨论、定过一条结论，之后几轮里又被反复提起、修改，最后定稿。
2. 聊到几百万 token 之后，上下文被自动压缩了两次，那些轮次连同当时的结论一起从窗口里消失。
3. 你说：「按我们之前定下来的做法来吧」。
4. 没有这个插件：模型只能反问「什么做法？」或者猜一个。 有这个插件：本地检索命中那些旧结论，把它作为参考注入——模型看到「此前是 X」，再结合你这次说的新条件回答。

它不做什么：

• 不做跨会话记忆。换一个会话就换一份记忆，互不可见（记忆按「会话所属工作区 + 会话 id」存放）。
• 不能替用户发消息。插件拿到的会话句柄没有 append 能力（实测边界，不是自我限制）——它能做的只有「把资料排进你下一轮的上下文」（见第 4 节），不能凭空让主模型立刻重答，也不会往会话里插一条消息。
• 不改写你的对话、不碰 DSH 的原始会话日志（只读）。
• 不读密钥、不自己连网（要用模型时经 DSH 的模型服务）。

现在还做不到什么（以及为什么）

写这一节是因为：它现在确实做不到"像人一样"地回忆。 下面每条都是实测出来的边界，不是谦虚话。

1. 它只有"被压缩掉"的那部分内容。 会话里还没被压缩的内容本来就在模型眼前，插件不管、也不需要管。实测：本会话 162 条提问里，只有 71 条（43.8%） 曾经落在压缩范围内——其余仍在窗口里。所以用得越久（压缩次数越多），它覆盖的比例越高；刚聊不久时它帮不上什么忙，是正常的。

2. 它按"词"找，不按"意思"找。 你问的用词和当初聊的用词对不上，它就可能找不到。我们试过加本地的语义模型（把内容变成向量再比）：结果并没有更好（在真实语料上还不如按词找），还多占几百 MB 磁盘——所以没上。换成"另一种说法"仍然要靠可选的辅助大模型（第 7 节）。

3. "最早 / 第一次 / 上次 / 刚刚"这类话，它现在会认，也会按三类去偏。 0.2.6 起，这类时间指代词会被识别出来；加权只改排序，不改"谁能被注入"（该不该注入只由词法分 + 证据门决定）。 指代词分三类、各配一种时间形状：刚刚 / 刚才 → 越新越高；最早 / 第一次 / 最初 → 越早越高； 之前 / 上次 / 原来 → 中间偏新最高（钟形，波峰贴近当前，两端只是更低、不是归零）。 一条消息里同时命中两类（例如"我们刚刚说的那个最早提过的设想"）→ 这次不做任何时间重排： 这句话真正要的是"两头"（最早一遍 + 刚刚一遍，现在问的是第三遍），而自动检索这条路上没有模型可用， 猜不出来 —— 所以口径是"宁可不用，也不用错"（固定优先级必然选错一边）。 幅度有上限（默认 0.7×–1.35×，可在设置文件里调 timeBoostMin / timeBoostMax 等七个键； both_ends 的"中间凹陷深度"是新增的 timeBothEndsDip，默认 0.2）。 "两头"由点 ✕ 那条路负责：辅助模型判一个"时间意图" （earliest / recent / both_ends / none），选 both_ends 时用两端高、中间低的形状重排； 这个意图只重排、不改资格，也不新增任何模型调用（第 7 节）。 意图从哪来：优先用「改写」那一次调用顺带输出的字段；改写被跳过时（本地已强命中）， 由「分页判读」那一次本来就要发生的调用顺带判——所以"本地强命中、但可能选错"这种点 ✕ 的主场景 也拿得到意图，调用次数一次都不多（回执里 timeIntent.via 会写明来源是 rewrite 还是 pageread）。 但它不会自己想"这题该去哪一段时间翻"。那一步得由模型（也就是跟你对话的那个我）先想清楚，再去用它。

4. 它不能替你想，也不能替你发消息。 它最多把几段原文递到模型眼前。平台限制：插件不能往会话里插一条消息、也不能让模型"立刻重答"——所以点 ✕ 找到的东西会排进你下一轮（第 4 节）。

5. 它不保证找得到，但会明说。 找不到时会直接显示「未搜索到强相关内容」，不会硬凑一段出来。没命中就一分 token 都不花。

5.5 它只能定位到"块"，定位不到"块里哪一轮"。 库里一个块往往装了好几轮问答（按字符数切，目标 900、上限 1500 字符）。所以它给你的是"这几轮里有过这段话"，而不是"第 N 轮说的"。 实测代价：同一次压缩写进去的所有块，时间戳完全相同（真库里 223 块只有 5 个不同的时间值）、也没有轮次字段 → 时间排序只能按块在文件里的前后近似（跨压缩事件是准的，同一次压缩内部是近似的）。 要更细的序，得在入库时给每条块写轮次或块内偏移，那需要重建历史库——本轮没做（代价大于收益）。

5.6 在 Linux/macOS 上，如果工作目录正好在插件目录里，工具结果会被静默跳过。 入库时有一条防自我膨胀的规则：工具结果如果读的是插件自己的源码，就整条丢掉（否则插件会把自己的代码当记忆存起来、越滚越大）。这条规则用当前平台的原生路径语义判断"是不是在插件目录里"。 后果（Windows 上因为盘符天然在外部，遇不到）：在 POSIX 上如果你的 cwd（或被测路径）落在插件目录内部，真实的工作文件也会被判成"插件自己的源码"→ 那条工具结果不入库，而唯一痕迹是诊断日志里的 selfSourceSkipped 计数。 触发条件很窄：把插件仓库本身（或它的子目录）当工作区时才会踩到；正常把项目放在别处不受影响。本轮没改运行时判据（它对真实路径是对的），只记在这里。

6. 一句话定位：它是车，不是门禁卡。 它擅长「你问的事有明确说法、而且被压缩过」；不擅长「你像聊天一样随口问」。后者需要模型先理解你的意思、再决定怎么用它——比如你说"我们最早聊控制面板的时候是怎么定的"，正确开法是「先意识到这是'按时间找最早那条'，再用它去找'控制面板'」；刷一下卡等门自己开，就会失败。

2. 两种检索方式（默认只用第一种）

两条路可以同时存在，但提问时的检索永远是本地的：模型只在「压缩入库扩写」和「你点 ✕」这两个时机被调用，绝不进提问热路径。模型改出来的词也要自己过本地阈值——它没法凭一句话把不相关的内容塞进你的上下文。

3. 三件事怎么工作

几个刻意的取舍：

• 注入块抬头写着「历史只作参考，不作结论」：如果这次的新条件和旧结论冲突，回答要以新条件为准，并明确说「此前是 X，这次因为 Y 改为 Z」，不许静默改口。
• 压缩时不做任何模型提炼：摘要直接用 DSH 生成好的那份，L2 直接抄原文。想省钱的人不该被"入库也要调模型"绑架。
• 原文只在你要的时候才展开：日常注入的是压缩过的一行行结论；要逐字原文请用 history_read 工具（只在用户明确要求时调用）。

4. 「✕」的完整语义

会话里每条助手回答下面都有一个 ✕（只在这个会话被压缩过之后才出现；没压缩过就没什么可找的）。点它的完整行为是：

1. 立刻在会话窗口里出现一行「xxx（辅助模型）检索中，请稍后…」——不是弹窗，就在对话里；这一行期间没有按钮（结果还没出来，不给操作）。
2. 插件用「你上一个问题」在本会话已压缩的历史里找候选，然后（选了辅助模型时）让模型把你的问法改写成关键词再找一遍，最后让模型判定哪一条是"强相关"。
   • 强相关的定义是「会改变答案的那种」，不是「有点关系」。模型只回一个编号，回 0 = 都不强相关——弱模型有"老好人"倾向，硬挑一条正是最危险的失败模式，所以这一条被明确允许。
   • 同一次改写调用里，模型还会顺带判一个「时间意图」（earliest 最早那次 / recent 最近那次 / both_ends 两头、最早与最近都相关而中间次要 / none 与时间无关）。选 both_ends 时，本地候选会按两端高、中间低的形状重排（默认 1.35× / 1.22× / 1.35×）。这只是排序：不改变"哪几条有资格被注入"，也不额外多花一次调用（就是这一次调用多一个字段）。
     • 本地已强命中、改写被跳过时（下一节第一条），意图改由分页判读那一次（本来就要发生的调用）顺带判出来 —— 提问那一句会和候选清单一起给模型，它回"编号 + 一个意图词"即可。所以"本地字面撞词最多、但可能不是你要的那条"这种点 ✕ 的主场景，也拿得到时间意图了（旧版在这里一次都拿不到：改写整段被跳过，而意图挂在改写上）。判读的调用次数一次都不多，意图词只是同一条回答里多出来的一个词；判读本身仍然只做一件事，提示词里明说"不要为它改变你挑的那一条"。
3. 结果分两种：
   • 有强相关 → 会话里显示「已用 xxx（辅助模型）搜索已压缩的历史：找到相关内容」，并给出两个按钮：
     • 「打开原文」：在右侧栏打开一份逐字摘抄的 Markdown——只有强相关的那几段、只含提问与回答（不含工具调用与思考），纯代码生成、0 token；
     • 「知道了」：把这一行收起来。 同时这段资料被排进你下一轮的注入：你直接继续提问（随口说一句也行）即可，主模型会带着它重新回答。
   • 都不强相关 → 会话里如实显示「未搜索到强相关内容」，不注入任何东西，也不给「打开原文」按钮（没有相关段落就不产出文件）。
4. 必须说清楚的一点：插件不能让主模型"立刻重答"。它没有往会话里发消息的能力，唯一能做的是把资料排进你下一轮的上下文。所以点完 ✕ 之后的效果是——下一次提问时模型带着这段历史回答。界面上的那句话（「资料已备好 —— 直接继续提问即可」）就是这个意思。

另外两个细节：

• 本地检索已经强命中（粗筛最高分 ≥ 阈值 ×1.5）时，会跳过这次查询改写，并如实告诉你「本地已有强命中，这次省掉了「查询改写」那一步（判读照常做了，翻了几页见上），所以结果有可能不是你要的那条 —— 不合适就再点一次或换个问法。」。注意省掉的只是改写：判读（辅助模型逐页挑"哪一条真的回答了你"）照常发生——你点 ✕ 往往正是因为觉得本地找的不对，这句话不会替插件说"我觉得没问题"。分数线为什么是 1.5×（2026-10-08 按新分数尺度重标定：高于实测负样本上界 0.329 与擦边正样本上界 0.417）见文末「设计论证」。
• 检索调用最多等 8 秒（面板可调）。8 秒是上限不是每次都等满；真超时意味着这一次白点了——超时只写诊断日志，不影响你的正常提问。

5. 成本账

单次口径（全部是上限，不是配额）：

「已删除」的那条闸门：早期版本有一个会话累计注入上限（默认窗口的 2%）。2026-10-07 按实测删掉了它——一天只有 19~21 次辅助调用，整场超长会话的插件总开销约 6 万 token，而主模型累积已用 5.6 亿 token（约 0.01%）。而累计闸门唯一稳定的效果是「命中率莫名其妙下降」：用户不会想到是自己多点了几次 ✕ 把额度花完了，只会觉得这插件后来不灵了。成本控制改由单次口径负责（上面那张表）。

量级表（用于判断"到底贵不贵"）：

说明：3.3 万 token 来自 scripts/measure-savings.mjs 在真实会话日志上重放生产代码路径的实测（该脚本会把每次压缩都过一遍入库管线并模拟扩写调用）；"数亿"是主模型侧的累计口径，两者不是同一把尺子的同一段，只用于看数量级。 上表的"实测一次注入 / 一次总览"数字来自 scripts/inspect.mjs 对同一份真实记忆库（122 块：摘要 60 + 原文 62，共 116,747 字符）的试检索输出，可用同一条命令复现。

不想花这钱：面板 ⑦ 选「不调用大模型」即可，插件的核心功能（压缩入库、检索、注入）完全不受影响，只是"换个说法问"更容易漏。

6. 架构与术语

三个层次（术语第一次出现时的解释）：

• L0 = DSH 原生会话日志（$DSH_HOME/sessions/**/session.v4.jsonl.zstd，多帧 zstd 压缩包）。插件只读它，永不写入。
• L1 = 摘要块：压缩时 DSH 已经生成好的摘要文本，按 Markdown 小节切开存下来，短、准、结论级。
• L2 = 对话原文块：从"被压掉的那段"里整理出来的对话文字（你问的 + 助手答的），带标题与关键词，另有读类工具的结果原文。

为什么 L2 不能直接用 L0 顶替（这是刻意的冗余，不是重复劳动）：

1. L0 是压缩包 + 机器格式：提问热路径要现场解多帧 zstd、再解析事件流，太慢——热路径必须以毫秒计。
2. L0 里噪声是正文的 3.3 倍：实测工具结果的体量是对话正文的 3.3 倍。直接拿 L0 检索，等于让文件内容、命令输出把真正的对话结论淹没掉。
3. 标题与关键词只存在于 L2：检索打分靠「标题 + 关键词 + 正文」三种字段加权（标题权重 3、关键词权重 4、正文权重 1）。L0 里没有"这段在讲什么"的标题，也没有"你以后可能怎么问它"的关键词——那两样是入库时现算的。

配套机制（都是为了让"注入"这件事本身不产生额外开销）：

• 命中证据门（2026-10-08 新增，见下面「检索打分口径」）：一条候选要命中 ≥ min(4, 提问去重 token 数) 个不同的查询 token 才算候选。中文按字符 bigram 分词，1–2 个日常词（"今天 / 比较 / 邮件"）在窄领域小库里 IDF 反而高，单靠分数阈值挡不住（实测把阈值降到 0.01 也挡不住）。实测两个真实库：26 条无关问题命中 token 数 ≤2（全部被这道门挡住），相关提问 ≥4（0 误伤）。
• 不做"前几轮兜底"式召回（2026-10-08 收紧）：只有当前这句本身太短（去重 token 数 < 4，典型是"那这个呢""继续"这类指代型短问句）才会把"当前 + 前几轮"拼起来再检索一次。不收紧时，前几轮里那几条真实相关提问会把任何不相关的问题抬过阈值 —— 实测 12/12 条无关问题各注入 256 字符，命中的是前两轮那条提问。
• 指纹去重：每块内容有一个 16 位内容指纹（sha1 前 16 位），同一个块永不重复注入；相似度 ≥0.6 的块也不再塞。
• 同话题冷却：连续两轮话题高度相似（词集 Jaccard ≥0.35）时跳过评分。
• 参考块挂住不放：命中过的参考块在本次压缩窗口内一直显示。撤掉它会让整份运行上下文快照的文本变化，DSH 会再追加一份（实测 1054 字符 ≈ 252 token）——挂着反而更省。
• 总览在窗口内保持稳定：同理，文本不变就不会反复追加快照。

7. 可选：模型辅助（默认不调用）

面板 ⑦「使用方式」三选一：

• 只在两个时机调用：① 压缩入库时给块补关键词；② 你点 ✕ 时改写查询 + 判定强相关。提问时的检索永远本地。
• ✕ 的「时间意图」不额外花钱：它要么是那一次改写调用里顺带输出的一个字段（{"点":…, "关键词":[…], "时间意图":"both_ends"}），要么（改写被跳过时）是分页判读那一次回答里多出来的一个词 —— 两条路都不新增调用，调用次数一次都不多。优先级：改写给了就用改写给的（它是专门为这句话判的），否则用判读顺带给的；回执里的 timeIntent.via 写明来源（rewrite / pageread）。旧格式（纯数组 / 没有该字段 / 判读只回了编号）照旧兼容：一律当 none（= 不重排），不报错、也不重算。
• 只有一个模型选择：llmMode（off / main / custom）+ llmProvider + llmModel。选了「调用指定模型」后，入库与检索都用这一对；这一对为空就按「跟随主模型」处理（不会悄悄退回某个旧字段）。off 不清空你填过的提供方/型号——那是"上次选了什么"的记忆。
• 不指定、也不继承思考强度：插件不给模型传思考强度参数，也不继承主对话的设置——想调就到「设置 → 模型」里对该型号设置。插件里没有这个旋钮。
• 失败一律静默降级：提供方没注册、凭据缺失、限流、超时、输出不是合法 JSON，全部只写诊断日志，插件表现与"没这个功能"完全一致。
• 失败冷却：限流 / 额度类暂停 10 分钟，提供方/凭据类暂停 30 分钟；按路径（入库 / 检索）分别记，互不牵连。
• 超时：入库调用默认 8000ms；✕ 路径默认 8000ms（原为 4000ms，实测思考型模型 4 秒常常只吐思考、正文一个字都没有，那次点击就白费了）。都是上限，模型正常返回就立刻结束。
• 相同输入缓存：同一个提问 + 同一个路由的改写结果缓存 30 天（最多 200 条）。
• 日调用上限：默认 0 = 不限；填了才启用。
• 调用留痕：只记录元数据（时间、路径、成败、耗时、估算 token），写在全局数据目录的 dsh-super-memory.llm.jsonl——不含任何对话内容。

8. 隐私与边界声明

本节逐条列出插件实际用到的主机能力与数据边界，全部可在仓库源码中核对。没有列在这里的能力，插件不会使用。

依赖

• 没有任何第三方 npm 运行时依赖：package.json 里只有 peerDependencies，没有 dependencies / devDependencies / optionalDependencies。
• peerDependencies 声明的 @deepseek-ai/* 都是 DSH 宿主自身提供的包，由宿主在运行时注入。
• 通过 ctx.inject 拿到的服务：必需 tools、systemPrompt、webServer；可选 llm（拿不到时模型辅助功能自动消失，其余照常工作）。

读什么

• 只读会话日志 $DSH_HOME/sessions/**（多帧 zstd 逐帧解码）：绝不写入、绝不修改、绝不删除。
• 只读会话标题投影缓存 $DSH_HOME/storages/session_projcache/sessions/<会话id>.json（用于在面板里显示与 DSH 侧栏一致的会话标题）。
• 状态查询对会话日志只做 stat 取大小，不读内容。

写什么

• 记忆本体只写会话所属工作区内的记忆目录，默认 <工作区>\.dsh-compaction-memory\：

<workspace>/.dsh-compaction-memory/
  <sessionId>.jsonl                 该会话的压缩记忆（一行一条块）
  _trash/<时间>_<会话>/             回收站（blocks.jsonl + manifest.json）
  _audit.jsonl                      删除 / 还原 / 清空的审计
  _pairs.jsonl                      未命中诊断的人工配对记录（不参与检索）
  _readable/excerpts/*.md           「打开原文」生成的逐字摘抄（只在点 ✕ 时产生）

• 全局数据目录（默认 $DSH_HOME，可用环境变量 DSH_SUPER_MEMORY_HOME 指到任意目录）里只有这几个小文件：

• 除此之外不写任何地方。storeDir 可配置，但含 .. 的配置会被拒绝并回落默认值。
• 会在工作区里写 .gitignore（仅在你自己点按钮时）：面板 ④ 检测到「工作区是 git 仓库、而记忆目录还没被忽略」时会给出「帮我加忽略规则」按钮；点它，插件就往该工作区的 .gitignore 追加一行 storeDir/（文件不存在时顺带创建，并写一行说明注释）。不会自动改写：不点就一个字节都不写。追加动作会记进 _audit.jsonl。
• 读取查询（GET）不产生持久写副作用（2026-10-08 起）：面板打开时发的 /session、/trash、/audit 等只读接口，只会把"当前会话的 cwd"登记进进程内存；设置文件里的「已知工作区」名单只在写操作（删除 / 还原 / 清空 / 改设置 / 加忽略规则）或会话内登记时才落盘。此前每次 GET 都会改写设置文件，而那份名单只有 40 槽 —— 用户的真实工作区被挤出去之后，面板与 ✕ 会一律报"未知工作区"。现在容量提到 200，并按"最近使用"淘汰。

诊断日志里没有提问明文

• dsh-super-memory.diag.jsonl 的 recall 事件只记提问的短哈希与字符数（queryHash = sha256 前 8 位十六进制、queryChars），不含提问文本。自己机器上排障若确实需要明文，可设环境变量 DSM_DIAG_QUERY_PLAINTEXT=1（默认关；开了才会额外写 queryPlain）。
• 披露历史版本：0.2.2 及更早的诊断日志里写的是 queryHead（提问前 60 字符明文）。因为这个文件在 $DSH_HOME（跨工作区汇聚成一个文件），等于把用户问过的话另抄了一份到工作区之外，所以现已改为哈希。旧日志文件里已经写过的那几行明文不会自动消失，要清就自行删除该文件（删掉只影响排障历史，不影响记忆本体）。
• 会话内「✕」用的「上一个问题」是内存里的本地记账（经 /diagnostics 回给面板），不落这个日志文件。

界面语言

• 面板 UI 目前只有中文（locale/zh.json、locale/en.json 里的插件元数据是双语的，但设置面板本身的文案没有做 i18n，README.en.md 也说明了这一点）。

删什么

• 所有删除路径先经 assertInside() 校验——目标必须严格位于记忆目录之内（等于根目录也拒绝，..、绝对路径、符号链接逃逸一律拒绝）。
• 默认走回收站语义：条目移入 _trash/ 可还原，并写审计日志。只有两种情况是永久删除：trashEnabled 显式设为 false 后的删除，以及面板的「清空回收站 / 彻底删除」——两者都写审计。

网络

• 不访问互联网。代码里没有任何对公网地址的请求（无硬编码外部域名 / URL），lib/ 不引入 node:http(s) / net / dns / tls。
• 面板（浏览器半边）里的 fetch 全部指向本机 DSH 的插件接口 /api/dsh-super-memory/*，同源同进程，不产生对外流量。
• 唯一"网外"行为是：你在 ⑦ 里主动选了模型档位之后，插件通过 DSH 的 llm 服务调用你自己配置的模型。

命令执行

• 全仓库只有一处 spawn（lib/routes.js 的 revealInFileManager()），唯一用途是「在系统文件管理器里定位文件」（面板的「浏览」按钮）：Windows 用 explorer.exe /select,，macOS 用 open -R，其它用 xdg-open。
• 该 spawn 不经过 shell，不接受任何来自请求的字符串作为可执行文件名或参数；目标路径由服务端自己用记忆目录根 + 会话 id 拼出，越界工作区直接 403。

凭据

• 不读取、不存储、不转发任何密钥或凭据。仓库内没有 .env 读取、没有 keyring / 凭据存储访问。
• 模型调用一律经由 DSH 的 llm 服务，插件侧只填 provider + model 两个字符串名字；真正的鉴权与密钥由 DSH 掌握。

失败边界

• 任何失败都只写诊断日志，不抛出到宿主、不阻塞对话：检索未命中、模型不可用、输出格式不合要求等全部在内部消化，最坏情况就是不注入参考，回答照常进行。
• 超时、冷却、缓存、日上限四道闸门之外，还有单次输出上限与每批块数上限——模型多说几句的代价不会失控（输出超限或格式不对就整批丢弃，保留原有词频，绝不写坏数据）。

关于 locale/*.json 与"是否需要构建"

• locale/zh.json、locale/en.json 是手写源文件，不是构建产物；随包分发并被 exports 的 ./locale/*.json 导出。
• 本仓库没有构建步骤：不存在 build / prepare / prepublish 之类会产出运行产物的脚本。npm test 只是自检，不产出任何运行产物，也不被运行时依赖。

本节写法说明：以上只写能从本仓库代码与 package.json 核实的事实。若将来新增了本节未列出的能力，请同步更新本节。

9. 安装与使用

环境：DSH 0.1.7-rc.2 / 0.2.0-rc.1 及以上（见 package.json 的 peerDependencies；已在 0.2.0-rc.2 客户端实测）。

安装（三种方式任选）：

# ① 插件市场：搜 dsh-super-memory 直接装（若你的 DSH 版本带市场）
# ② 从本地目录装（<本机插件目录> 换成你 clone / 解压出来的路径）
plugin_manager  action: install_bundle  target: <本机插件目录>
# ③ 从 npm 装（已发布时）
plugin_manager  action: install_bundle  target: dsh-super-memory

装完重启 DSH 客户端：宿主插件代码在进程里缓存，不重启不生效。成功标志：设置里出现「超级记忆」这一节，工具列表里出现 history_read。

卸载：plugin_manager action: remove_bundle target: dsh-super-memory。 卸载不会自动删除工作区里的 .dsh-compaction-memory 与全局目录里的那几个文件，要手动清理（位置见第 8 节）。

面板怎么用（顶部三句话就够）：

1. 它是干什么的：压缩时把被压掉的内容存到你本机，之后只把相关的那几段递回给模型；最多占 700 token/轮，挑不出相关的就一点都不注入。
2. 要不要额外调用辅助大模型：在 ⑦ 里三选一（默认不调用）。调用辅助大模型需要你先在 DSH 官方模型接口里接入对应模型；插件不存密钥、不改写你的对话，只读会话日志。
3. 平时不用管它——觉得它忘了本应提到过的历史内容，就点回答下面的 ✕ 让它再找一遍。

面板按"插件实际做的三件事"分板块（①②③），后面是 ④ 被保存的压缩内容、⑤ 回收站、⑥ 诊断与路径、⑦ 模型辅助。所有调参项收在顶部右侧的「参数设置」里（默认折叠）：普通用户不展开也完全能用，想抠成本 / 命中率的人展开就能逐项调。所有参数改完即时生效，不需要重启。

常见问题：

• 插件刚重启时点 ✕ 会不会失败？ 一般不会。面板拿不到工作区时，宿主会从会话日志里的 cwd 兜底；只有连 cwd 都读不到（比如这个会话还没被插件见过）才会报「未知工作区」——那时随便发一条消息让它见到本会话，再点一次即可。
• 命中率低怎么办？ 三条路，按性价比排序：① 在 ⑦ 里选「调用指定模型」并挂一个便宜模型（命中率提升最明显）；② 到「参数设置 → 检索参数」把「命中阈值」从 0.28 调低一点（更省 → 更容易命中，代价是可能注入不太相关的内容）；③ 确认「入库」两项都开着（关了就真的没东西可检索）。
• 不想花 token 怎么关？ ⑦ 选「不调用大模型」= 0 模型调用；再想彻底不动上下文，把 ① 的「压缩后注入总览」和 ③ 的「提问时注入记忆」两个开关关掉（入库照旧，已有记忆仍可检索，只是不再注入）。总开关关掉 = 不写入本地、不注入任何内容。
• 记忆在哪儿？ 在你的项目文件夹里（<工作区>\.dsh-compaction-memory\）。如果那个工作区是 git 仓库，面板 ④ 会检测到并给一个「帮我加忽略规则」按钮——记忆里是对话原文，提交上去就收不回来了。摘抄（点 ✕ 的「打开原文」生成的逐字问答）如果早先被误提交过、已被 git 跟踪，删除后面板会提示你去执行 git rm --cached <摘抄目录>（.gitignore 对已跟踪文件无效，插件只删工作区里的文件，不会替你动 git 索引）。
• 界面语言？ 面板目前只有中文（插件标题/描述的元数据是中英双语，但设置面板文案没做 i18n）。

10. 开发者：设计与教训

这一轮修掉的真缺陷（都配了会变红的断言）

踩坑经验

• 不要用 PowerShell 做大段文本写入：历史上把 lib/host.js 写成过 UTF-16 + NUL 的乱码（npm test 还全绿）。改文件一律用精确替换工具，改完 node --check。
• 并发编辑会互相覆盖：同一文件被两个进程同时改写时，后写的整份覆盖前一份。多件事要改同一个文件时串行做。
• 桩渲染两大坑：① useRef 必须像真 React 一样跨渲染复用同一个对象（每次新建会让"只在首次渲染记一个值"的组件每帧重置，于是测试里的陈旧判定和真机行为不一致）；② 桩 fetch 要按 URL 分派（宿主就是多个接口），全都回同一个 payload 会让跨接口读取永远读到 undefined。
• hook 槽位下标是数组下标，不是"第几个 useState"：种错槽位（比如把 openLlm 写成 6）会去改另一个状态，断言看着还在、其实形同虚设。
• 注入块必须稳定：任何一节上下文变化都会让 DSH 追加整份运行上下文快照；"撤掉一个块"也要花钱。

11. 为什么插件自管设置（而不是用官方设置表单）

现状：本插件的所有参数由插件自己存（$DSH_HOME/dsh-super-memory.settings.json，见 config.js 的 SettingsStore），界面是自己注册的整页设置板块（client.js 用 ctx.slots.inject('settings.section', …)）。官方 DSH 0.2 提供的是另一条路：插件导出 export const Config = Schema.object({...})，字段要进表单必须标 .volatile()，宿主读 config.<字段>.get()，变更走 ctx.on('loader/volatile-update', …)，值落在当前 profile 的 cordis.patch.yml（分 profile、不分工作区）。下面是一次只读探针的结论，说明为什么不迁移。

• 决定性事实：官方 0.2 的共享表单控件只有「文本框」与「密码框」——没有开关、没有下拉、没有复选框（官方页面里那些开关/下拉都是各插件自己手绘的）。
• 下拉选项不能动态给：schema 要序列化成 JSON 过线，函数会被拒——所以本插件的 provider 下拉（选项来自 ctx.llm.listProviders()）不可能由官方表单生成。
• 官方表单里放不了自定义控件（按钮 / 列表 / 「测试连接」这类），要自定义就只能自己注册页面——也就是我们现在用的 settings.section（那是标准扩展点，不是绕过）。
• 因此迁移只能省下"存储 + 校验 + 重置 + 通知"这四件事，省不到界面本身。而代价是实打实的：
  • 可能多出一个入口（官方表单在插件页，面板在设置里，两边都能改同一件事）；
  • 整段 config 是覆盖而不是深合并，一个键写错可能连带重置别的；
  • 忘标 .volatile() 就静默失效——字段能写进文件，却不进表单、也不通知；
  • 一条未核实的风险：外部插件在解析 @deepseek-ai/* 时，app.asar 内的 0.2.0-rc.2 与 profiles\node_modules 里那份 0.1.7-rc.2 谁生效（见下面的警告）。
• 结论：维持自管设置。 本插件的所有读取点都盯着 SettingsStore，迁移要把它们全部改一遍，而收益只是省掉几百行存储代码——本插件零老用户，不值这个风险。

已采纳的唯一一条：探针里唯一"便宜且明确更好"的建议已经落地——「恢复默认设置」改为逐键重置并保留模型档位（SettingsStore.reset() + RESET_KEEP_FIELDS），不再删掉整个设置文件。原来的实现是 unlinkSync(settingsPath)，用户点一次就把 llmMode/llmProvider/llmModel 一起丢掉（实测踩过）。

⚠️ 给未来维护者的警告：C:\Users\Administrator\.dsh\profiles\node_modules\@deepseek-ai\* 下的 junction 指向的是 0.1.7-rc.2，而桌面实际运行的是 0.2.0-rc.2（在 app.asar 内）。去读那层 junction 会得到过期结论（例如"官方没有这个能力"其实是"旧版的官方没有"）。要判定官方能力，请在 app.asar 里读对应版本，或直接解包 app.asar 后核对。

12. 变更历史