dsh-super-memory
kkwings/dsh-super-memory
Cross-compaction memory for a long session: on compaction it stores what is being dropped, and at question time it injects a few relevant passages (or nothing) so the model can recall what you decided before.
Installer
dsh plugin --profile web add github:kkwings/dsh-super-memoryREADME
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. 这是什么 / 解决什么问题
一句话：上下文压缩会把早先的对话从模型眼前拿走（原文仍在磁盘上），这个插件在被拿走的那一刻把它存到你本机，之后只在相关的时候把那几段递回给模型。
一个真实场景：
- 同一件事在会话开头被讨论、定过一条结论，之后几轮里又被反复提起、修改，最后定稿。
- 聊到几百万 token 之后，上下文被自动压缩了两次，那些轮次连同当时的结论一起从窗口里消失。
- 你说：「按我们之前定下来的做法来吧」。
- 没有这个插件：模型只能反问「什么做法？」或者猜一个。 有这个插件：本地检索命中那些旧结论，把它作为参考注入——模型看到「此前是 X」，再结合你这次说的新条件回答。
它不做什么：
- 不做跨会话记忆。换一个会话就换一份记忆，互不可见（记忆按「会话所属工作区 + 会话 id」存放）。
- 不能替用户发消息。插件拿到的会话句柄没有 append 能力（实测边界，不是自我限制）——它能做的只有「把资料排进你下一轮的上下文」（见第 4 节），不能凭空让主模型立刻重答，也不会往会话里插一条消息。
- 不改写你的对话、不碰 DSH 的原始会话日志（只读）。
- 不读密钥、不自己连网（要用模型时经 DSH 的模型服务）。
现在还做不到什么（以及为什么）
写这一节是因为：它现在确实做不到"像人一样"地回忆。 下面每条都是实测出来的边界，不是谦虚话。
-
它只有"被压缩掉"的那部分内容。 会话里还没被压缩的内容本来就在模型眼前，插件不管、也不需要管。实测：本会话 162 条提问里，只有 71 条（43.8%） 曾经落在压缩范围内——其余仍在窗口里。所以用得越久（压缩次数越多），它覆盖的比例越高；刚聊不久时它帮不上什么忙，是正常的。
-
它按"词"找，不按"意思"找。 你问的用词和当初聊的用词对不上，它就可能找不到。我们试过加本地的语义模型（把内容变成向量再比）：结果并没有更好（在真实语料上还不如按词找），还多占几百 MB 磁盘——所以没上。换成"另一种说法"仍然要靠可选的辅助大模型（第 7 节）。
-
"最早 / 第一次 / 上次 / 刚刚"这类话，它现在会认，也会按三类去偏。 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 节）。
-
它不保证找得到，但会明说。 找不到时会直接显示「未搜索到强相关内容」，不会硬凑一段出来。没命中就一分 token 都不花。
5.5 它只能定位到"块"，定位不到"块里哪一轮"。 库里一个块往往装了好几轮问答（按字符数切，目标 900、上限 1500 字符）。所以它给你的是"这几轮里有过这段话"，而不是"第 N 轮说的"。 实测代价：同一次压缩写进去的所有块，时间戳完全相同（真库里 223 块只有 5 个不同的时间值）、也没有轮次字段 → 时间排序只能按块在文件里的前后近似（跨压缩事件是准的，同一次压缩内部是近似的）。 要更细的序，得在入库时给每条块写轮次或块内偏移，那需要重建历史库——本轮没做（代价大于收益）。
5.6 在 Linux/macOS 上，如果工作目录正好在插件目录里，工具结果会被静默跳过。
入库时有一条防自我膨胀的规则：工具结果如果读的是插件自己的源码，就整条丢掉（否则插件会把自己的代码当记忆存起来、越滚越大）。这条规则用当前平台的原生路径语义判断"是不是在插件目录里"。
后果（Windows 上因为盘符天然在外部，遇不到）：在 POSIX 上如果你的 cwd（或被测路径）落在插件目录内部，真实的工作文件也会被判成"插件自己的源码"→ 那条工具结果不入库，而唯一痕迹是诊断日志里的 selfSourceSkipped 计数。
触发条件很窄：把插件仓库本身（或它的子目录）当工作区时才会踩到；正常把项目放在别处不受影响。本轮没改运行时判据（它对真实路径是对的），只记在这里。
- 一句话定位：它是车，不是门禁卡。 它擅长「你问的事有明确说法、而且被压缩过」；不擅长「你像聊天一样随口问」。后者需要模型先理解你的意思、再决定怎么用它——比如你说"我们最早聊控制面板的时候是怎么定的"，正确开法是「先意识到这是'按时间找最早那条'，再用它去找'控制面板'」；刷一下卡等门自己开，就会失败。
2. 两种检索方式（默认只用第一种）
| ① 本地检索（默认） | ② 大模型辅助检索（可选） | |
|---|---|---|
| 什么时候用 | 每次提问都做 | 只有你在面板 ⑦ 里选了档位才启用 |
| 怎么找 | 本地词法打分：中文字符二元组 + 英文词，标题/关键词/正文分权重（BM25），过阈值才算命中 | ①压缩入库时让模型给每块补几个「你以后可能怎么问这块内容」的短词；②你点 ✕ 时让模型把你的问法改写成关键词，并判定哪一条真的强相关 |
| 花什么 | 0 模型调用、0 token；未命中一分 token 都不花（连注入文本都不产生） | 按次计费，走 DSH 的模型服务；压缩时每批一次调用，点一次 ✕ 一次调用（相同提问 30 天内不重复调用） |
| 延迟 | 提问热路径零延迟 | 压缩时的调用你在等压缩，感觉不到；点 ✕ 时最多等 8 秒（界面会显示「检索中」） |
| 命中率 | 词对得上就命中；「换个说法问」容易漏 | 明显更高（尤其是口语化、同义改写的问法） |
| 怎么切换 | 默认就是它 | 面板 ⑦「使用方式」三选一：不调用大模型（默认） / 调用主模型 / 调用指定模型 |
两条路可以同时存在，但提问时的检索永远是本地的：模型只在「压缩入库扩写」和「你点 ✕」这两个时机被调用，绝不进提问热路径。模型改出来的词也要自己过本地阈值——它没法凭一句话把不相关的内容塞进你的上下文。
3. 三件事怎么工作
| # | 时机 | 做什么 | 成本 |
|---|---|---|---|
| ① | 压缩时 | 把这次被压掉的内容本地入库：一层是 DSH 已经写好的摘要，按小节切开存（短、准、结论级）；另一层是被压掉那段的对话原文（你问的 + 助手答的文字），外加模型读过的文件 / 检索结果原文（read / grep / glob / web_fetch / history_read）。 | 0 模型调用（选了模型档位才会给这些块补关键词） |
| ② | 压缩后 | 注入一份目录级「本会话此前脉络」（话题 — 结论），让新窗口一开场就知道过去聊过哪几大块。挑不出值得留的就一点都不注入。 | ≤ 300 token / 次压缩，自适应，可为 0 |
| ③ | 提问时 | 先在本地比一次关联性，命中才注入参考。 | 命中 ≤ 700 token / 轮（≤2 条、每条 ≤300 字符、每条至少 50 字符才值得注入）；未命中 0 token |
几个刻意的取舍：
- 注入块抬头写着「历史只作参考，不作结论」：如果这次的新条件和旧结论冲突，回答要以新条件为准，并明确说「此前是 X，这次因为 Y 改为 Z」，不许静默改口。
- 压缩时不做任何模型提炼：摘要直接用 DSH 生成好的那份，L2 直接抄原文。想省钱的人不该被"入库也要调模型"绑架。
- 原文只在你要的时候才展开：日常注入的是压缩过的一行行结论；要逐字原文请用
history_read工具（只在用户明确要求时调用）。
4. 「✕」的完整语义
会话里每条助手回答下面都有一个 ✕（只在这个会话被压缩过之后才出现；没压缩过就没什么可找的）。点它的完整行为是：
- 立刻在会话窗口里出现一行「xxx（辅助模型）检索中，请稍后…」——不是弹窗，就在对话里；这一行期间没有按钮（结果还没出来，不给操作）。
- 插件用「你上一个问题」在本会话已压缩的历史里找候选，然后（选了辅助模型时）让模型把你的问法改写成关键词再找一遍，最后让模型判定哪一条是"强相关"。
- 强相关的定义是「会改变答案的那种」，不是「有点关系」。模型只回一个编号，回 0 = 都不强相关——弱模型有"老好人"倾向，硬挑一条正是最危险的失败模式，所以这一条被明确允许。
- 同一次改写调用里，模型还会顺带判一个「时间意图」（
earliest最早那次 /recent最近那次 /both_ends两头、最早与最近都相关而中间次要 /none与时间无关）。选both_ends时，本地候选会按两端高、中间低的形状重排（默认 1.35× / 1.22× / 1.35×）。这只是排序：不改变"哪几条有资格被注入"，也不额外多花一次调用（就是这一次调用多一个字段）。- 本地已强命中、改写被跳过时（下一节第一条），意图改由分页判读那一次（本来就要发生的调用）顺带判出来 —— 提问那一句会和候选清单一起给模型，它回"编号 + 一个意图词"即可。所以"本地字面撞词最多、但可能不是你要的那条"这种点 ✕ 的主场景，也拿得到时间意图了（旧版在这里一次都拿不到：改写整段被跳过，而意图挂在改写上）。判读的调用次数一次都不多，意图词只是同一条回答里多出来的一个词；判读本身仍然只做一件事，提示词里明说"不要为它改变你挑的那一条"。
- 结果分两种：
- 有强相关 → 会话里显示「已用 xxx（辅助模型）搜索已压缩的历史：找到相关内容」，并给出两个按钮：
- 「打开原文」：在右侧栏打开一份逐字摘抄的 Markdown——只有强相关的那几段、只含提问与回答（不含工具调用与思考），纯代码生成、0 token；
- 「知道了」：把这一行收起来。 同时这段资料被排进你下一轮的注入：你直接继续提问（随口说一句也行）即可，主模型会带着它重新回答。
- 都不强相关 → 会话里如实显示「未搜索到强相关内容」，不注入任何东西，也不给「打开原文」按钮（没有相关段落就不产出文件）。
- 有强相关 → 会话里显示「已用 xxx（辅助模型）搜索已压缩的历史：找到相关内容」，并给出两个按钮：
- 必须说清楚的一点：插件不能让主模型"立刻重答"。它没有往会话里发消息的能力，唯一能做的是把资料排进你下一轮的上下文。所以点完 ✕ 之后的效果是——下一次提问时模型带着这段历史回答。界面上的那句话（「资料已备好 —— 直接继续提问即可」）就是这个意思。
另外两个细节：
- 本地检索已经强命中（粗筛最高分 ≥ 阈值 ×1.5）时，会跳过这次查询改写，并如实告诉你「本地已有强命中，这次省掉了「查询改写」那一步（判读照常做了，翻了几页见上），所以结果有可能不是你要的那条 —— 不合适就再点一次或换个问法。」。注意省掉的只是改写：判读（辅助模型逐页挑"哪一条真的回答了你"）照常发生——你点 ✕ 往往正是因为觉得本地找的不对，这句话不会替插件说"我觉得没问题"。分数线为什么是 1.5×（2026-10-08 按新分数尺度重标定：高于实测负样本上界 0.329 与擦边正样本上界 0.417）见文末「设计论证」。
- 检索调用最多等 8 秒（面板可调）。8 秒是上限不是每次都等满；真超时意味着这一次白点了——超时只写诊断日志，不影响你的正常提问。
5. 成本账
单次口径（全部是上限，不是配额）：
| 项 | 数字 |
|---|---|
| 压缩后总览 | ≤ 300 token / 次压缩，可为 0（实测一次：190 token / 8 行 / 747 字符） |
| 单轮注入 | ≤ 700 token、≤ 2 条、每条 ≤ 300 字符（每条下限 50 字符）。700 才真的放得下"两条满额中文块 + 抬头"（2×≈255 + ≈105）；设成 500 时预算会先砍掉第二条 = 实际只注入 1 条 |
| 实测一次注入 | 128 / 167 / 395 / 458 token（视命中几条、正文多长） |
| 入库扩写 | 每块只送前 600 字符、每批 8 块、单次输出上限 240 token（格式不对整批丢弃，保留原词） |
| 查询改写 | 单次输出上限 120 token |
| 每日调用上限 | 默认 0 = 不限（想设就填，到上限停用到次日，面板会显示原因） |
「已删除」的那条闸门：早期版本有一个会话累计注入上限（默认窗口的 2%）。2026-10-07 按实测删掉了它——一天只有 19~21 次辅助调用，整场超长会话的插件总开销约 6 万 token，而主模型累积已用 5.6 亿 token（约 0.01%）。而累计闸门唯一稳定的效果是「命中率莫名其妙下降」：用户不会想到是自己多点了几次 ✕ 把额度花完了，只会觉得这插件后来不灵了。成本控制改由单次口径负责（上面那张表）。
量级表（用于判断"到底贵不贵"）：
| 场景 | 辅助花费 |
|---|---|
| 5 次压缩 + 20 次 ✕（同一会话，估算） | ≈ 3.3 万 token |
| 同一场会话里主模型的累积用量 | 数亿 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 顶替（这是刻意的冗余，不是重复劳动）：
- L0 是压缩包 + 机器格式：提问热路径要现场解多帧 zstd、再解析事件流，太慢——热路径必须以毫秒计。
- L0 里噪声是正文的 3.3 倍：实测工具结果的体量是对话正文的 3.3 倍。直接拿 L0 检索，等于让文件内容、命令输出把真正的对话结论淹没掉。
- 标题与关键词只存在于 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. 可选：模型辅助（默认不调用）
面板 ⑦「使用方式」三选一：
| 档位 | 含义 |
|---|---|
| 不调用大模型（默认） | 纯本地。提问零延迟、零 token；压缩后仍会注入总览与命中的参考。 |
| 调用主模型 | 用你当前会话的主模型补问法、换关键词；成本随主模型走。 |
| 调用指定模型 | 这两处改用你指定的模型（例如主对话用 pro、这里用更便宜的 flash）。 |
- 只在两个时机调用：① 压缩入库时给块补关键词；② 你点 ✕ 时改写查询 + 判定强相关。提问时的检索永远本地。
- ✕ 的「时间意图」不额外花钱：它要么是那一次改写调用里顺带输出的一个字段（
{"点":…, "关键词":[…], "时间意图":"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指到任意目录）里只有这几个小文件：
| 文件 | 内容 |
|---|---|
dsh-super-memory.settings.json | 设置（跨工作区生效，含面板登记的已知工作区列表） |
dsh-super-memory.diag.jsonl | 诊断日志（默认上限 4000 行，超了自动压缩） |
dsh-super-memory.llm-usage.json | 今日调用次数与 token 估算 |
dsh-super-memory.llm-cache.json | 查询改写缓存（30 天、最多 200 条） |
dsh-super-memory.llm.jsonl | 模型调用留痕（只有元数据） |
- 除此之外不写任何地方。
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 节）。
面板怎么用（顶部三句话就够）：
- 它是干什么的：压缩时把被压掉的内容存到你本机，之后只把相关的那几段递回给模型；最多占 700 token/轮，挑不出相关的就一点都不注入。
- 要不要额外调用辅助大模型：在 ⑦ 里三选一（默认不调用）。调用辅助大模型需要你先在 DSH 官方模型接口里接入对应模型；插件不存密钥、不改写你的对话，只读会话日志。
- 平时不用管它——觉得它忘了本应提到过的历史内容，就点回答下面的 ✕ 让它再找一遍。
面板按"插件实际做的三件事"分板块（①②③），后面是 ④ 被保存的压缩内容、⑤ 回收站、⑥ 诊断与路径、⑦ 模型辅助。所有调参项收在顶部右侧的「参数设置」里（默认折叠）：普通用户不展开也完全能用，想抠成本 / 命中率的人展开就能逐项调。所有参数改完即时生效，不需要重启。
常见问题：
- 插件刚重启时点 ✕ 会不会失败？ 一般不会。面板拿不到工作区时，宿主会从会话日志里的 cwd 兜底；只有连 cwd 都读不到（比如这个会话还没被插件见过）才会报「未知工作区」——那时随便发一条消息让它见到本会话，再点一次即可。
- 命中率低怎么办？ 三条路，按性价比排序：① 在 ⑦ 里选「调用指定模型」并挂一个便宜模型（命中率提升最明显）；② 到「参数设置 → 检索参数」把「命中阈值」从 0.28 调低一点（更省 → 更容易命中，代价是可能注入不太相关的内容）；③ 确认「入库」两项都开着（关了就真的没东西可检索）。
- 不想花 token 怎么关？ ⑦ 选「不调用大模型」= 0 模型调用；再想彻底不动上下文，把 ① 的「压缩后注入总览」和 ③ 的「提问时注入记忆」两个开关关掉（入库照旧，已有记忆仍可检索，只是不再注入）。总开关关掉 = 不写入本地、不注入任何内容。
- 记忆在哪儿？ 在你的项目文件夹里（
<工作区>\.dsh-compaction-memory\）。如果那个工作区是 git 仓库，面板 ④ 会检测到并给一个「帮我加忽略规则」按钮——记忆里是对话原文，提交上去就收不回来了。摘抄（点 ✕ 的「打开原文」生成的逐字问答）如果早先被误提交过、已被 git 跟踪，删除后面板会提示你去执行git rm --cached <摘抄目录>（.gitignore对已跟踪文件无效，插件只删工作区里的文件，不会替你动 git 索引）。 - 界面语言？ 面板目前只有中文（插件标题/描述的元数据是中英双语，但设置面板文案没做 i18n）。
10. 开发者：设计与教训
这一轮修掉的真缺陷（都配了会变红的断言）
| 缺陷 | 后果 | 修法 |
|---|---|---|
| 路径穿越写入 | 会话 id 来自请求体，..\..\.. 之类会逃出记忆目录写到任意位置 | 文件名只留安全字符 + 落盘前断言目标仍在 root 之内（双重设防） |
| ✕ 的资料只在第一步可见 | 组装上下文每个 step 都跑一次，清空点写在那里 → 真正作答的那一步看不到它 | 清空点搬到 turn/end，且只在"跨轮"时清 |
| 跨会话串味注入 | 记忆库按工作区放，同工作区里躺着多个会话的块 → 模型说出你根本没说过的事 | /diagnose 的候选只取目标会话的记录，没有 session 字段的旧记录一律不匹配 |
回填 NaN 导致冷启动看不到块 | const added = backfill(...) 而内部是 += await … → added 恒为 NaN → 索引永不刷新 | 去掉错误的 await 链，写出真实计数并在落盘后失效索引 |
outChars 恒 0 | 思考型模型只吐 reasoning 不吐正文 → 留痕里输出量永远是 0，"没输出还是没记账"分不清 | 按分片累加真实长度，并把"思考"与"正文"分开记 |
| 毫秒级陈旧判定 | 用 Date.now() 判断"结果是不是上一轮的"，同一毫秒内发布的新结果被误判成陈旧整块不显示 | 改用发布序号（自增），不做时间比较 |
| Hooks 顺序 / TDZ | ① 提前 return 之前漏掉 hook → 组件卸载，✕ 按钮凭空消失；② onClick 引用了定义在它之后的 const run → 点击抛 TDZ 且被静默吞掉，表现是"点了没反应" | 所有 hook 提到提前 return 之前；run 保持函数声明（提升），并加源码级断言钉死 |
npm test 覆盖不到宿主半边 | lib/host.js 一度被写成 UTF-16 乱码而测试全绿——因为三套脚本只 import 了少数几个模块 | 新增 scripts/host-smoke.mjs：每个文件非空 / 无 BOM / 无 NUL + 逐个 node --check + 宿主入口与关键模块真的能 import + 导出契约在位 |
apply(ctx) 从没被真调用过 | 注册项被注释掉、注册到错的键、apply 中途抛错 —— 整块功能静默消失而四套自检全绿 | host-smoke.mjs 造一个假 ctx 真的 await apply(fakeCtx)，逐条断言"注册了 systemPrompt.context 提供者 / 订阅了 session/event / 注册了面板路由 / 注册了 history_read"，并用"桩调用计数 > 0"证明真的执行到了；再触发一条真实形状的 compaction/summary |
routes.js 的请求链零执行 | HTTP 方法写错、路径字符串写错、写守卫被摘掉都测不出来 | 用合成 req/res 真打 handler：GET /overview 200、未知路径 404、POST 缺来源头 403、只支持 GET 的路径发 POST 落 catch-all 404、带参 /session、/search 200 |
| 面板桩丢弃依赖数组与 cleanup | 桩里 effect 每渲染都跑、cleanup 从不执行 → "effect 依赖写错"在测试里完全不可见；控件绑错键也看不见 | 桩 useEffect/useMemo/useCallback 改为逐项 Object.is 比较依赖（不变不重跑、变了先 cleanup）、useRef 跨渲染复用；新增"控件 ↔ 设置键"绑定断言（8 个控件、种入不同取值） |
load() 不做上下界校验 | 手改设置文件塞 maxRawCharsPerCompaction: 1e21（巨量内存）/ protectRecentDays: 1e15（永远删不掉）被照单全收 | 抽出 INTEGER_BOUNDS 一张表，normalizeSettings（读盘）与 validatePatch（面板提交）共用；单元测试断言 1e21/1e15 读回后被夹到合法上界，并逐字段核对"表 = 面板数字框的 max" |
| 诊断日志含提问明文 | recall 事件写 queryHead（提问前 60 字符明文），而日志在 $DSH_HOME（跨工作区汇聚）→ 提问被另抄一份到工作区之外 | 改为 queryHash（sha256 前 8 位）+ queryChars；host-smoke 断言最后一条 recall 带哈希、与提问哈希一致、且整个文件里没有任何 queryHead |
| GET 产生持久写副作用 | 每次 GET 都把会话 cwd 登记进 knownWorkspaces 并写盘，40 槽被挤爆后用户真实工作区一律 403 | GET 只做内存登记（resolveTarget(..., {persist:false}) 走 resolveReadTarget），持久化只在写操作时发生；容量 40→200 + 最近使用优先 |
| 工具结果入库越界（上限形同虚设） | toolRecords 是"先切后拼"：text.slice(0, maxChars) 之后才拼首行与截断说明 → 落盘长度 = 上限 + 60~70。夹具库实测 22/210 条越界，最大 4068（上限 4000）；上限 200 时落盘 284 | 收口到一个纯函数（clampToolText/toolRecordText）：先净化 → 再按最终长度切；并在 rawRecords 的合并出口再收口一次（两条工具出口都覆盖） |
| 自指噪声（插件源码进 L2） | 读自己源码产生的工具结果正文就是插件代码，"什么词都有"→ 通用吸引子，让任何逐字写在自己源码里的探针提问必然命中 | 入库侧一条窄规则：工具参数里的目标路径落在本插件目录内就不入 L2（selfSourcePath），并在诊断里记 selfSourceSkipped；不排除用户项目里的代码文件 |
| 面板自检把注释当代码 | usedKeys 对整份 client.js 匹配 effective('键')，注释里写过的键也算"面板用到的键" → 统计虚高 1 个假阳性（llmAssistEnabled），且"注释与代码不一致"永远发现不了 | 扫描前先 stripComments（最小词法扫描：保住字符串/模板字面量），键、CSS 类、API 路径、板块编号四处都用剥注释后的源码 |
踩坑经验
- 不要用 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. 变更历史
| 版本 | 关键变化 |
|---|---|
| 0.1.0 | 三件事落地：压缩时入库（L1 摘要 + L2 只留对话文字）、压缩后注入 ≤300 token 总览、提问时本地检索命中才注入。记忆存在会话所属工作区。 |
| 0.1.1 → 0.1.2 | 修「本轮第一个请求看不到召回」：改从 agent/inbox/spliced 事件抓提问（它比运行上下文求值早几毫秒）；新增 stickyRecall（命中块挂住不放，省一次快照追加）。 |
| 0.1.3 → 0.1.6 | 面板按"三件事"重构成板块；④ 拆出「被保存的压缩内容」+「回收站」，会话标题与 DSH 侧栏一致；全局数据目录可用 DSH_SUPER_MEMORY_HOME 搬离系统盘。 |
| 0.2.0 | 审计驱动的安全与正确性修复：路径穿越（连 root 本身也拒绝）、写操作 CSRF 守卫、sessionLogBytes 契约、改设置丢工作区名单、?limit=abc 传播成 slice(0,-NaN)、history_read 回落日志加 64MB 闸、states 加 LRU。新增 scripts/unit.mjs（失败即退出码 1）。 |
| 0.2.1 | 成本口径正式改为「用户选档位 + 单次严格控制」；删除思考强度设置键与继承路径（那是 bug：又慢又贵）；工作区自动识别；新增宿主冒烟守卫 host-smoke.mjs。 |
| 0.2.2 | 辅助成本砍掉一半：工具结果块不再送去扩写（它靠文件名/标题就能检索到，而体量是对话正文的 3.3 倍）、每批 5→8 块、扩写输出上限 300→240；本地已强命中时跳过查询改写（省一次调用，结果不变）；点 ✕ 立刻显示「检索中」、✕ 超时 4s→8s；留痕与用量开始记录 token 估算；修掉陈旧判定的毫秒比较；删除会话累计上限（默认日上限改 0 = 不限）。 |
| 0.2.2 之后（未改版本号） | ① 注入行改为"答优先 / 结论句优先"：以前那一行是"问题 + 截断的正文"，现在先取回答/结论句，回答为空才退回问题开头（lib/recall.js 的 itemText）——用户看到的"想起了什么"从"又念了一遍我的问题"变成"它记得我当时得出的结论"。② spawn 失败不再掀翻宿主：可执行文件不存在走的是异步 error 事件，原来没有监听者 → 未捕获异常直接杀进程（面板点一次「浏览」就能把 DSH 打挂）；现在唯一的子进程出口立刻挂 error、失败只写 reveal-spawn-error 诊断。③ 摘抄跟着删除语义走：/delete、/trash/purge 现在会一并删掉 _readable/excerpts/ 里该会话的逐字摘抄（以前"删干净"是假的，可读原文还躺在磁盘上）。④ 写路径串行化：记忆库的 append 与读-改-写用 withFileLock 串起来，交错不再丢块。⑤ /diagnose 的模型改写限流：同一会话 60 秒最多 6 次（RateLimiter），挡掉"本机任意进程反复 POST 就等于反复花钱"（web server 本身不鉴权）。⑥ outTokensEst：留痕与用量按真实输出分片累加记账（思考型模型只吐 reasoning 时不再恒为 0）。⑦ 本轮的接线层自检与隐私/一致性修复见下一条。 |
| 本轮自检补强 = 接线层自检三件套（0.2.2 之后，未改版本号） | 第三方只读审查点名三处结构性盲区，都补成了"能变红"的断言：① host-smoke.mjs 真的调用 apply(ctx)（以前只 import，从不执行 —— 注册项被注释掉、开关接错键、apply 中途抛错都能四套全绿），断言 systemPrompt.context 提供者 / session/event 订阅 / webServer 路由 / history_read 工具逐条在位，并真触发一条 compaction/summary；② 用合成 req/res 真打一遍 routes.js（请求链此前在 npm test 里零执行）：GET 200 / 未知路径 404 / 写操作缺来源头 403 / 方法分发 / 带参路径 200；③ 桩 React 改为尊重依赖数组并执行 cleanup，另加"控件 ↔ 设置键"绑定断言（8 个控件含开关/数字框/文本框/下拉，种入与默认不同的值再逐项比对 —— 这就是抓"开关接到错的键"的守卫）。另外：load() 与面板 API 共用同一张上下界表（手改设置文件塞 maxRawCharsPerCompaction: 1e21 不再被照单全收）、诊断日志不再写提问明文（改哈希，见第 8 节）、GET 不再产生持久写副作用（已知工作区 40→200，按最近使用淘汰）、harness.mjs 临时目录用完即清（异常路径也清）、titles.js 读侧路径补 safeSessionId、删除摘抄被 git 跟踪时面板追加 git rm --cached 提示。 |
| 本轮（体积/自指/标定/面板自检） | ① 工具结果入库体积收口：toolRecords 的"先切后拼"会让落盘记录 = 上限 + 首行 + 截断说明（实测 4068/上限 4000、上限 200 时 284）；现在把"上限"定义成落盘记录文本长度，收口在纯函数 clampToolText/toolRecordText，并在 rawRecords 合并出口再收口一次（两条工具出口都覆盖）。② 自指噪声不入 L2：读本插件自己目录内文件的工具结果不再入库（窄规则，只看工具参数里的目标路径是否落在插件目录内；不排除代码文件），跳过条数记进诊断 selfSourceSkipped。③ strongHitScore 按新分数尺度重标定：新归一化把同一份样本抬了 2.04×，用两个真实库 592 块 / 154 条历史提问实测（正样本 72 条 min=0.301 中位=0.430；负样本 82 条 max=0.329；擦边正样本 max=0.417），结论是保持 1.5× 并给出两条硬性质（高于负样本上界、高于擦边上界），数据表见文末「设计论证」。④ panel-check.mjs 先剥注释再匹配：usedKeys 不再把注释里的 effective('键') 算进去，报告数字从 41 回到真实的 40（假阳性是 llmAssistEnabled）。⑤ 归一化不随查询长度漂移 + 命中证据门：分母只累加库里出现过（df>0）的 token 的 IDF，粘一段无关长尾不再把相关提问挤下阈值（同一份样本实测 0.210 → 0.983）；分层靠的是证据门（命中 ≥ min(4, 提问去重 token 数) 个不同 token），阈值仍是 0.28。⑥ 两条探针的数字（本轮实测，来源见第 13 节末尾「设计论证」与第 6 节）：注入行改成"答 / 结论句优先"后，问答块的答文本进入注入行的比例 1% → 100%；反过来，无关问题被误注入从 12/12 → 0/12。⑦ 诊断日志的提问头改哈希：recall 事件从 queryHead（前 60 字符明文）改成 queryHash + queryChars（见第 8 节）。 |
| 0.2.6 · 时间指代词两轮改稿 | 第一轮（三类 ↔ 三形状 + 句级窗口）：把指代词分成 near/mid/far 三类，各配一种时间形状（new 单调偏新 / bell 钟形偏新 / old 单调偏旧），窗口从"±60 字符"改成句级（旧口径在真实库 168 条含指代词提问里有 17 条（28%）产出 0 窗口），并确立**"加权只改排序、永不改资格"（时间系数只重排已过证据门 + minScore 的那批；candidates 快照在重排之前固定）；摘掉 这就/这才（实测有 2 条真实提问因此被误判成近指代）。第二轮（本轮）：① 删掉"多类冲突取最左"那条固定优先级 —— 用户那句「我们刚刚说的那个最早提过的设想」同时命中 near 与 far，固定优先级必然选错一边（真正要的是两头**）。新口径：一条消息里命中 ≥2 个不同类 → 判"分不清" → 本次不做任何时间重排（shape = null，与"不含指代词"走同一条路径，逐位不变）；只有恰好一个类时才重排。② 时间形状的判定作用域改成"整条消息"（原先只看第一句含指代词的话 —— 那等于换个地方继续做那条被否决的固定优先级）。③ ✕ 路径把"时间意图"交给辅助模型：在那一次改写调用里顺带输出 时间意图（earliest/recent/both_ends/none），不新增任何调用；旧输出（纯数组 / 无该字段）一律按 none。④ 新增第 4 种形状 both_ends（两端高、中间低）：1 - dip × 4p(1-p)，默认 dip = 0.2 → 位置 0/0.25/0.5/0.75/1 的系数是 1.35 / 1.2525 / 1.22 / 1.2525 / 1.35；新键 timeBothEndsDip 进 DEFAULTS + NUMBER_FIELDS_READONLY（界 [0,1]），面板不暴露（与其余时间形状参数同一条口径）。⑤ 铁律没动：意图只影响 ✕ 内部的候选重排，绝不影响"要不要注入"；found/boosting/资料成员三种意图下逐位一致（有断言）。成本红线（2 条 / 300 字符 / 700 token / minScore 语义 / 证据门）与 ✕ 的调用次数一分未变。 |
| 0.2.7 之后（未改版本号）· 加 CI + 修 Linux 下的一条测试 + 记一条边界 | ① 加了 CI（.github/workflows/ci.yml）：ubuntu-latest / windows-latest × Node 22.x / 24.x，没有任何安装步骤（插件零依赖 ✓ 四套脚本只用 Node 内置模块 ✓）。host-smoke 负责回答"真的装得上、真的调得动"——它按宿主的方式注册插件，然后真的执行一次工具处理函数并断言结果 ✓。② CI 自己抓出两个错：（a） 我最初把 Node 钉在 20 ✗ —— 而仓库的 engines 本来就写着 node >= 22.15 ✓（lib/zstd.js 要 node:zlib 的 zstdDecompressSync ✓ Node 20 没有 ✓ 会在 import 期直接报语法错 ✓）；改成 22.x/24.x 后 Windows 两个 Node 版本都通过 ✓ 这也第一次实测证实了那个下限 ✓。（b） 接着 Ubuntu 两个 Node 版本都挂 ✗（Windows 正常 ✓）：第 30 节的夹具写死了 Windows 盘符 ✓ 而 POSIX 上 E:\... 不是绝对路径 ✓（E: 只是文件名 ✓）→ 被解析进插件目录内部 ✓ → 被"别读自己源码"那条规则整条丢掉 ✓ → 记录数 0 ✓ → 取 [0] 抛 TypeError ✓。夹具改成从插件根用 path.join 推导 ✓ 两平台都落在插件目录之外 ✓；断言一条没放宽 ✓，并把"先判条数再取 [0]"补上（失败时给可读的红 ✓ 而不是 TypeError 截断日志 ✓）。修完 4 个 job 全绿 ✓✓。③ 新记一条已知限制（第 1 节 5.6）：在 POSIX 上，cwd 落在插件目录内部时工具结果会被静默跳过（Windows 遇不到 ✓ 触发条件很窄 ✓ 唯一痕迹是 selfSourceSkipped ✓ 运行时判据未改 ✓ 它对真实路径是对的 ✓）。 |
| 0.2.7 之后（未改版本号）· 清死代码 + 免责声明 | ① 删掉那条"永不执行"的 effect：MissAction 里"新问题到达 → 清结果"依赖 ready.lastQuery，而 ready 只被一个同样只依赖 [sessionId] 的 effect 写一次、全文件无轮询 → 真机从不执行（它的判据函数只在测试桩里被直接调用 = 假绿）。连同只服务于它的两个 ref 与测试钩子一并删除；真正生效的 noteCurrentTurn（新轮 turnTail 挂载时广播清理）保留不动。② 断言随之换成钉真机制，没有为变绿放宽（过程中还修掉两处"把注释/散文当成代码残留"的假红判据）。③ README（中英）顶部新增两条声明：由 AI 协助开发、可能存在缺陷；主要供学习测试、不保证持续更新。 |
| 0.2.7 · ✕ 结果跨轮（真根因）+ 「打开原文」+ 新问题到达即关 + 时间意图盲区 | 用户第三次实测同一个回归，前两次所谓的修好其实只是症状被盖住。① ✕ 的结果为什么每轮都跟着（真根因）：槽位 conversation.chat.turnTail 给的 turn 是 TurnLocation 对象（官方 node.location.turn → renderSlot(..., { turn, seq, openFile })，逐字可证），而代码用 String(stored.turn) === String(turn) 比较 —— 两边都变成 [object Object]，任意两轮恒等 → 每一个轮次的实例都认领同一条结果 → 用户看到“从点 ✕ 之后每一轮后面都跟着它”。修法：turnKeyOf() 归一化（对象取 .turn、数字/字符串原样），并统一“槽位给对象 / 回执给数字”两把尺子。② 兜底分支曾是死代码：missResultFor 第一行原为“拿不到 turn 就无条件返回结果”，于是后面的序号兜底永远不可达、且每个后挂载的实例都会显示旧结果。现在按序号兜底（早于本实例挂载 → 不显示），轮次对得上时仍以轮次为准。③ 「打开原文」其实从没打开过文件：MissTail 解构里漏了 openFile（用了但没解构）→ 它只能展开机器格式原文。已补解构。④ 用户要的行为——新问题一到就关掉上一轮的提示：原先依赖 ready.lastQuery 变化的那个 effect 是死信号（ready 只由同样只依赖 [sessionId] 的 effect 写一次、全文件无轮询 → 真机上一次都不会执行，missActionDecide 只在测试桩里被调用 = 假绿）。现在接到真的会触发的信号上：新轮 turnTail 挂载即广播清理，且只认“确实往后走”（防“点完 ✕ 结果立刻消失”）。⑤ 时间意图不再有盲区：它原先挂在改写那一步，而本地强命中时改写整段被跳过 —— 恰恰是“本地字面撞词最多、可能选错”的点 ✕ 主场景。现在分页判读（本来就要发生的调用）顺带判出来：只在第一页的用户消息里追加一问，PAGE_PICK_MAX_TOKENS 一个字没加；回执 timeIntent.via 写明来源。⑥ 跳过改写时的文案改成说实话：旧文案会让点 ✕ 的用户以为“插件觉得没问题”，现在说清“省掉的是改写那一步，判读照常做了”。⑦ 测试桩的假绿机制一并修掉（这才是同一 bug 复发三次的元凶）：桩原先自己手写组件 props，不经官方 renderEntry 的合并顺序（{...kit, ...injected, ...slotInjected.props, ...ownerProps}）→“宿主 props 到不了组件”这类 bug 在桩里永远绿。现在桩按官方顺序构造，并单独断言“透传”本身。顺带纠正一个错判：inject 的第二个实参是 store.actions（本插件无 store → undefined），不是宿主 props —— 宿主 props 由 renderSlot(key, owner) 经 ownerProps 最后合并，从未丢失，所以 inject: (sessionId) => ({ sessionId }) 本来就是对的（与官方 message-feedback 同槽位写法逐字一致）。⑧ 顺带修好：已发布的 0.2.6 在真实库上有一条既有红（（过召回情形）注入量仍必须守单条上限，召回块 653 字符 > 上限 300 + 头部）—— 现在绿了。 |
| 0.2.5 | 这一轮全是"把该给的信息给全"，不是换机制（换机制的路——本地嵌入、重切块、关键词分级、多路并集——都试过且实测无收益或负收益，见文末「设计论证」）。① 答案的续行终于进得了注入行：L2 是 问：…\n答：…，但只有回答的第一行带 答： 前缀，而旧的 answerTextsOf 只认带前缀的行 → 续行全落进一个"注入行取不到"的池子里。实测铁证：把每块的续行全删掉，注入行逐字不变 70/70；改成一个互补的 qnaSegmentsOf 之后，注入内容 +58.7%（真实库）/ +180.9%（一问一答库），最差的块从 30 字符补到 300。② 纯数字与短标识符不再被丢掉：旧正则要求首字母，252、0.28、stickyRecall、maxCharsPerItem 这些一个都检索不到（三个库 × 12 种门配置实测 0 候选）——而本库最密的锚点恰恰是数字。现在数字/小数/标识符（kebab、snake、camel 会额外拆出结构片段，整串保留）都能匹配，唯一 token +3.4%~6.8%，单次检索 +0.04 ms。③ 长消息不再被自己摊薄：分母改成只累加 IDF 最高的 12 个库内词（标定：不封顶 13 条真实 miss 修 0 条；K=8 全修但长无关误报 4/16→5/16 过冲；K=12 全修且误报一分不涨）。④ 一条消息里的多个话题不再互相挤掉：改用分段检索（每段各自算分母）再按指纹合并——"注入上限是多少 + 按钮不见了"这类消息过去只能命中一个话题，现在两个都进候选。⑤ "最早/第一次/上次"这类时间指代词会被识别并加权（±60 字符窗口当额外一路，1.35×；同分时优先较早的块——但只在出现这类词时，不出现时逐位不变）。⑥ ✕ 时辅助模型先定位"最关键的问题点"再提炼关键词：1000 字长问题的关键词跨度从 979 字符压到 9，不相关的那半段一个词都没进。⑦ 切句不再吞掉真问句：…问题：我们最早聊控制面板的时候是怎么定的？你可以尝试… 以前会把问句粘在引导语后面又被"过短合并"吞掉；现在含问号的片段独立成段、冒号/顿号/分号是引导语边界。⑧ 三条真实用户问题固化成永久回归用例（"第一次聊到控制面板"、"我最早对设置面板要求的原话"、反例"晚饭吃什么"必须 0 注入）。 |
已取消的功能（以及为什么）
| 曾计划 / 曾存在 | 现状 | 理由 |
|---|---|---|
| 每次压缩生成一份"整会话可读 MD" | 已取消（连 0 token 也不做） | 会话窗口本来就能翻到历史——真正的问题是模型记不住，不是你看不到。为此多写一份文件不解决任何问题。保留下来的只有「点 ✕ 时的逐字摘抄」（短、按需、0 token）。 |
| 候选人工挑选界面 | 已取消 | 让用户从 10 条候选里挑一条，等于把检索算法的活派给用户；而且他挑的时候也未必知道哪条"会改变答案"。改成让辅助模型判强相关，判不出来就如实说没有。 |
| 「未命中诊断」界面 | 界面已取消 | "内容没进库 / 在库里没排上来 / 还在被压掉的原文里"是我们的排障信息（诊断日志里本来就有）；用户真正的问题是"这段到底聊没聊过"，而他点 ✕ 时辅助模型会直接回答这个问题。宿主侧的 /diagnose 路由保留给 ✕ 复用。 |
会话累计注入上限（sessionBudgetRatio） | 已删除 | 见第 5 节：它唯一的稳定效果是"命中率莫名下降"，因为用户不会把自己点 ✕ 的消耗归因到额度上。成本改由单次口径负责。 |
思考强度设置键（llmReasoningEffort） | 已删除 | 插件不需要这个概念，也不该继承主对话的（继承会又慢又贵，实测确认是 bug）。要调就去 DSH 官方「设置 → 模型」。 |
入库用 / 检索用两套模型字段（llmIngestProvider、llmIngestModel、llmRecallProvider、llmRecallModel） | 已删除 | 收敛为唯一的一套：llmMode（off / main / custom）+ llmProvider + llmModel——入库扩写与检索改写/重判用的是同一对（面板里只有一个「使用方式」和一对下拉）。旧设置文件里若还有这四个键，load() 会一次性把值搬进 llmProvider/llmModel，save() 再把旧键从盘上删掉（本插件尚无老用户，不保留任何其他兼容分支）。 |
未实现 / 不打算做：跨会话记忆；本地向量检索；把注入内容写回会话（平台没有 append 能力）。
13. 自检脚本
需要 Node ≥ 22.15（原始会话日志是多帧 zstd，用到 zstdDecompressSync；低版本会直接报"不支持 zstd"）。DSH 自带的 node 在 <DSH 安装目录>/resources/runtime/primary-runtime/dependencies/node/bin/node.exe。
⚠️ 这些脚本只存在于源码仓库，不随 npm 包发布。 发布包的
files白名单只有lib与locale（运行时要用的东西），刻意不含scripts/—— 所以从 npm 安装的包 里跑npm test会报"找不到 scripts/unit.mjs"，那是预期行为，不是包坏了： 自检脚本依赖仓库里的源码与测试夹具，只在git clone之后可用。 （要自检请克隆仓库；不要把scripts加回files—— 那会把测试夹具与开发脚本一起 塞进每个用户的 node_modules。）
npm test 会真的报错（退出码非 0），它跑四套：① 单元测试（纯函数 + 历次真实 bug 的回归）、② 面板静态自检（设置键 / CSS 类名 / API 路径 / 板块齐全 / 数字框精度）、③ 面板渲染冒烟（用桩 React 真正渲染面板整棵树，并核对"控件 ↔ 设置键"的绑定）、④ 宿主半边冒烟（每个文件非空无 BOM 无 NUL、逐个 node --check、宿主入口真能加载、导出契约在位，并真的调用一次 apply(ctx) 与合成 req/res 打一遍面板请求链）。
scripts/harness.mjs 与 scripts/selftest.mjs 的退出码同一口径：自检失败 = 1，缺参数 / 日志路径读不到 = 2（并打印用法，不是 TypeError 栈）；不适用的段落打印 SKIP + 原因，不算失败。两个脚本建的临时目录都用完即清（异常路径也清）。
其余脚本用真实会话日志做端到端验证：
测试节奏（2026-10-12 约定，避免白跑最慢那套）：改一处只跑最快且相关的
node scripts/unit.mjs（纯函数、几秒）；改到宿主 / 面板 / 路由再补跑直接相关的那一套 （host-smoke.mjs或panel-check.mjs/panel-render.mjs）；只在交付前才跑全量六套 （含最慢的harness.mjs—— 它要解 11MB 真实日志 + 读真库，且只读真库）。
# 0) 四套自检（不需要会话日志；`npm test` 就是这四条）
node scripts/unit.mjs
node scripts/panel-check.mjs
node scripts/panel-render.mjs
node scripts/host-smoke.mjs
# 1) 纯离线：真实日志跑通「压缩入库 → 检索 → 总览 → 注入样例」+ minScore 标定表
# **有真断言**（入库块数/L1+L2 都在/总览在预算内/命中样例能注入且不超单轮上限/
# 注入行带答案正文/无关提问 0 token），失败退出码 1；日志里没有压缩事件则整段 SKIP。
node scripts/selftest.mjs <session.v4.jsonl.zstd>
# 2) 宿主半边联调：假 cordis ctx + 真实日志，跑通入库/总览/命中/未命中/开关/面板 API/history_read
node scripts/harness.mjs <session.v4.jsonl.zstd> [临时工作区]
# 3) 验收证据导出：库条目统计、总览预览、试检索命中、最近打分日志
node scripts/inspect.mjs "<工作区>" "<一个旧话题>"
# 4) 省钱实测 + 阈值标定：扩写调用 / 输入 token 的 A/B，以及「强命中跳过改写」门槛
node scripts/measure-savings.mjs <session.v4.jsonl.zstd> [--json]
# 5) 时序排障：压缩事件、投影里还剩哪些用户消息、每份运行上下文快照的字符/token
node scripts/compactions.mjs <sessionId> [fromSeq toSeq | --snap | --raw <seq>]
# 6) L2 抽取完整度审核：日志里"应当收进来的文字"vs 插件实际入库字符数
node scripts/shadow-audit.mjs <sessionId> <fromSeq> <toSeq> [插件记账的rawChars]
会话日志位置：$DSH_HOME/sessions/**/session.v4.jsonl.zstd（多帧 zstd，脚本里按帧解码）。
设计论证（不写进界面，只留在这里）
检索打分口径与阈值标定（2026-10-08，两个真实库）
旧口径的缺陷（这是"长提问被系统性惩罚"的根因）：分数 = raw / ideal，而 ideal 是查询里
全部 token 的 IDF 之和 —— 库里根本没出现过的词照样进分母，而且它们 IDF 最高
（df=0 时 idf≈log(1+2n)）。于是"提问里有多少库里没见过的词"直接决定分数高低。
实测（真实库 122 块，同一条相关提问后面粘一段无关长尾）：
| 同一条相关提问 | 原样（15 字符） | +1 段无关长尾（67 字符） | +3 段（169 字符） |
|---|---|---|---|
旧口径 raw/全部 IDF | 1.479（命中） | 0.210（掉出 0.28，漏检） | 0.206（漏检） |
新口径 raw/可匹配 IDF | 1.479 | 0.983（仍命中） | 0.983 |
新口径：分母只累加在这个库里出现过（df>0）的查询 token 的 IDF（"可匹配 IDF 质量"）。
同一查询内分母是常数，所以文档排序完全不变，变的只有"分数与阈值比较"这一层。
但只改归一化不够（这是本次标定最重要的结论）：同一份样本上把候选归一化换成 "可匹配 IDF 质量"后，正样本整体上移、负样本也整体上移，两者仍然重叠，没有任何单一阈值能分开：
| 库 / 口径 | 正样本 top-1（min / 中位 / max） | 正样本 ≥0.28 | 负样本 top-1（min / 中位 / max） | 负样本 ≥0.28 |
|---|---|---|---|---|
| 真实库 122 块 · 旧口径 | 0.059 / 0.123 / 1.479 | 3/8 | 0.000 / 0.074 / 0.255 | 0/26 |
| 真实库 122 块 · 新口径＋证据门 | 0.151 / 0.278 / 1.479 | 4/8 | 0.000 / 0.000 / 0.000 | 0/26 |
| harness 库 350 块 · 旧口径 | 0.064 / 0.330 / 1.549 | 8/16 | 0.000 / 0.081 / 0.239 | 0/24 |
| harness 库 350 块 · 新口径＋证据门 | 0.145 / 0.564 / 1.549 | 10/16 | 0.000 / 0.000 / 0.000 | 0/24 |
（正样本：从诊断日志 hit:true 事件用 queryHash/queryHead 反查会话日志还原明文的真实提问，
加上 harness 夹具里的历史提问，再加 8 条按库内容改写的同主题问句；负样本：24 条与本库无关的日常问题
＋ harness 原有那 2 条。逐条明细与脚本见交接报告。）
所以分开两类的是"命中证据门"，不是阈值：命中 ≥ min(4, 提问去重 token 数) 个不同的查询 token。实测 26 条无关问题的命中 token 数 ≤2（1 个 token 的占多数），而 16 条相关提问 ≥4 （中位 12）—— 这是两个库上唯一能把两类分开的特征。
minScore 因此保持 0.28：新口径下它表示"库能提供的那部分被覆盖了多少"，同一份样本上
把相关提问的召回从 3/8 提到 4/8（harness 库 8/16 → 10/16），而无关问题仍然是 0 条
（由证据门负责）。数据不支持再挪这个数：任何单一阈值都分不开两类（上表），
把阈值降到 0.01 也不会多注入一条无关问题（挡住它们的是证据门）。
两条历史"误注入"探针的真实原因（不是阈值）：harness 里长期报 ✗ 的
"明天北京天气预报怎么样 / 帮我写一首关于春天的五言绝句"，在 harness 库上命中的是
工具 read：scripts/harness.mjs 这块 4 万字符的工具结果 —— 那两条探针字符串逐字写在本文件里，
夹具会话读过本文件、工具结果已入库，所以"用户问的那句话逐字躺在一篇已入库文档里"，
任何词法检索都必然命中（实测命中 8 / 13 个 token，分数 0.89）。在真实库（没有把本文件读进库）
上，同样两条探针是 0.000 / 0.073，不注入。这条诊断现在被钉成断言：harness ③ 段会断言
"库里确实有一条逐字包含它的记录"，哪天入库口径变了，这条断言会红，提醒把它改回"必须为空"。
-
minScore为什么是 0.28：见上面「检索打分口径与阈值标定」。旧标定（真实会话 3.8 MB / 5388 事件 / 2 次压缩）的结论"相关 0.72–1.50 / 不相关 0.00–0.14 分得很开"只在那一份样本上成立； 2026-10-08 在两个真实库上重做后，结论是"阈值分不开、证据门才分得开"，0.28 保持不变作为 可匹配 IDF 质量的操作点。跑几天后可以看诊断日志里hit:false reason=below-threshold的topScore分布，漏召多就往下调。 -
「强命中跳过改写」为什么是 1.5×（2026-10-08 按新分数尺度重标定）：上一轮把归一化从"查询全部 token 的 IDF"改成"库内可匹配的 IDF 质量"，同一份样本上分数整体上移（实测中位抬升 2.04×：正样本中位 0.211 → 0.430），所以旧尺度上的 1.5× 必须用新数据复核。实测口径与结果（两个真实库合计 592 块；154 条真实历史提问，逐字躺在库里的自污染提问已剔除；脚本：把
lib/retrieval.js+lib/zstd.js直接 import 到%TEMP%下的标定脚本，只读日志与记忆库）：样本 条数 top-1 min p25 中位 p75 max 正样本（本地确实可注入， retrieveTwoTier.tier !== 'none'）72 0.301 0.373 0.430 0.507 1.763 负样本（本地不可注入） 82 0.000 0.217 0.254 0.290 0.329 擦边正样本（刚过 minScore）34 0.301 — — — 0.417 分数线 跳过改写 正样本被跳过 负样本被误判 证据不足（matched<4）却被跳过 1.5× = 0.420 38/154（25%） 38/72（53%） 0/82 0 2× = 0.560 15/154（10%） 15/72（21%） 0/82 0 3× = 0.840 6/154（4%） 6/72 0/82 0 结论：保持 1.5×，依据换成新数据下的两条硬性质 —— ① 它高于负样本上界（0.42 > 0.329）： 没有一条"本来找不到"的提问会被跳过改写；② 它高于全部擦边正样本（0.42 > 0.417）： 擦边命中不会被当成强命中。取 2×/3× 只是少跳过几条"本来就找得到"的（多花改写钱）， 换不来任何安全性，所以不动。口径仍是
max(0, minScore, minScore × 1.5)：即使有人把阈值 设成 0 或负数，也不会出现"任何候选都算强命中"（那会让改写永远不触发）。scripts/unit.mjs§11 把上面两个上界（0.329 / 0.417）钉成常量断言：谁把倍率调到 ≤1.17 就会红，提醒他重做标定。
工具结果入库的两条硬规则（2026-10-08）
- 每条工具结果记录 ≤
toolResultMaxChars（默认 4000），落盘记录文本（含【工具 … 的结果 · …】首行与"已截断"说明）的长度上限。修复前是"先切后拼"：text.slice(0, maxChars)+ 首行 + 截断说明， 实测落盘 4068（上限 4000）；上限为 200 时落盘 284。现在收口在一个纯函数 （lib/ingest.js的toolRecordText/clampToolText），并在rawRecords的合并出口再收口一次 （那条出口是唯一绕不过去的入库点；只有"工具结果、没有对话轮"的出口走同一条收口）。 上限被夹在 200–20000（见INTEGER_BOUNDS），面板上那个数字框就是这条硬上限。 - 读本插件自己目录内文件的工具结果不入 L2（窄规则，
selfSourcePath）：判据只看工具参数里的 目标路径（file_path/filePath/path，相对路径按会话 cwd 解析）是否落在插件目录内。 为什么需要它：这类块的正文就是插件源码，对"回忆历史决策"没有价值，却因为"什么词都有"变成 通用吸引子（实测它让任何逐字写在自己源码里的探针提问必然命中）。不排除代码文件本身 —— 用户项目里的.ts/.js照常入库。被跳过的条数记在诊断的selfSourceSkipped（不是静默的）。 - 已存在的历史超大记录：插件不会自动改写或删除用户记忆库。两种取舍留给你决定 ——
① 保留不动（默认、零风险）：它只影响检索噪声与
avgdl，不会让插件出错；想局部清理就用手动删除 （面板单条删除 //delete，进回收站可还原）。② 下次压缩时自动瘦身：可以做，但必须在"用户没有 主动要求"的前提下动他的数据，风险与收益不对等，本轮不做。 （本轮盘点：当前工作区真实库.dsh-compaction-memory/里 122 条记录全是 summary/raw 对话块， 没有任何src=tool记录，最大记录 1500 字符；夹具自检库里有 210 条工具记录，修复前 22 条越界、 最大 4068，修复后不再产生越界记录。）
License
MIT