# dsh-session-kit [![](https://img.shields.io/badge/DeepSeek%20Harness->=0.1.5-brightgreen?labelColor=4D6BFE)](https://github.com/deepseek-ai/deepseek-harness) [![](https://badgen.net/npm/dt/dsh-session-kit)](https://www.npmjs.com/package/dsh-session-kit) [English](README.en.md) | 中文 `dsh-session-kit` 是一个 DeepSeek Harness 插件，用于增强会话页的日常管理能力。它不修改 DSH 核心源码，而是通过官方扩展点为会话增加管理菜单、归档会话管理、运行时全局提示、运行时上下文压缩配置、轮次级删除/重新生成、本地记忆管理与召回，以及右侧话题快捷导航。 ## 安装 ### 从 npm 安装（推荐）： ``` dsh plugin --profile web add dsh-session-kit ``` ### 从 github 安装： ``` dsh plugin --profile web add github:ltxlong/dsh-session-kit ```` ## 注意 如果更新了dsh版本0.1.5导致出现会话加载失败报错，比如：历史加载失败 @deepseek-ai/dsh-session-format-v0-to-v1 refuses this format v0 Session， 解决方法是：“会话管理”->“修复会话”-> 点击“修复”按钮即可修复当前会话 ## 示例 image image image image ## 功能概览 ### 会话管理菜单 插件会在会话页头部增加 **会话管理** 按钮，菜单包含： - **删除会话**：会话停止后，经确认删除当前会话；运行中的会话会被保护，不能删除。 - **记忆管理**：可以管理记忆项目、临时记忆、永久记忆、记忆标签。 - **统计调用**：统计当前会话的工具调用，并按工具名显示总数、成功、失败、未完成次数。 - **重新命名**：通过官方 Session API 修改当前会话标题。 - **分叉会话**：在当前轮次允许分叉时，从当前会话创建一个新会话。 - **归档会话**：把当前会话加入工作区归档列表，从侧边栏隐藏。 - **打开目录**：使用系统文件管理器打开当前会话日志目录。 - **导出会话**：调用 DSH Session 日志 的导出能力。 - **全局提示**：配置运行时注入的全局系统提示词，支持开关；保存成功后显示提示，不修改官方代码或配置文件。 - **压缩配置**：仅在运行时覆盖当前压缩引擎，不修改官方或预设配置文件。 - **打开归档**：进入归档会话管理弹窗。 ### 全局提示 **会话管理 → 全局提示** 会打开“全局提示词设置”弹窗： - 支持启用/关闭全局提示； - 支持编辑全局提示词内容； - 保存后会显示保存成功提示； - Host 端通过 `ctx.systemPrompt.section()` 把提示词注册到运行时系统提示词组装中； - 不修改 DSH 官方代码，也不覆盖官方 `system-prompt` 配置； - 插件停用、卸载或未加载后，这段运行时注册会被释放/不再注册，因此不会继续生效。 ### 归档会话管理 归档弹窗用于管理已经归档、也就是从侧边栏隐藏的会话： - 按标题搜索归档会话； - 不恢复会话也能直接在弹窗中预览内容； - 在预览中展示工具调用统计； - 支持分页加载更多预览消息； - 支持把归档会话分叉到新聊天中继续； - 支持恢复归档会话，让它重新出现在会话列表中； - 支持打开归档会话所在文件夹； - 支持确认后删除归档会话。 删除会话时，Windows/macOS 会尽量移动到系统回收站/废纸篓；没有系统回收站集成的平台会直接删除会话目录。正在运行的归档会话不会被删除。 ### 轮次删除与重新生成 插件会在已完成的顶层助手轮次旁，以及部分失败轮次尾部增加操作： - **此轮到后续全删除**：从选中的轮次开始，删除当前轮及其后所有已完成轮次在当前 conversation surface 与后续模型上下文中的内容；不会删除整个 Session。 - **重新生成**：先从选中轮次开始删除后续内容，再把该轮原始用户提问重新加入队列，让模型从该位置重新回答。 安全策略： - 删除并不是直接抹掉 append-only 日志，而是追加持久的 replacement tombstone；tombstone 的 provider/model 为 `dsh-turns-del` / `tombstone`。 - 原始 append-only 事件仍保留在会话日志中；折叠后的 active surface 不再展示被删除范围，后续模型上下文也不再包含这些内容。 - 修改 live session 前会取得 Agent maintenance lease。 - 每个目标轮次都会验证是否仍然对应独立、连续的 surface 区间。如果该轮次已被压缩、与保留历史混合，或与已有删除范围重叠，操作会直接拒绝，而不会猜测处理。 - 成功返回前会执行 `sessions.flush()`。 - 重新生成会在 Agent 正在运行、输入队列有待处理内容、原始用户提问缺失/有歧义/不是纯文本时拒绝执行。 ### 话题快捷导航 每个会话页右侧会显示类似 `chat.deepseek.com` 的 **话题** 导航： - 默认收起为一列扁平线条标记； - 鼠标悬浮或键盘聚焦后展开固定尺寸的可滚动面板； - 用户提问以单行省略标题展示； - 完整标题只通过系统 tooltip 显示； - 滚动会话时自动高亮当前话题； - 点击话题可平滑跳转； - 屏幕宽度较小时自动隐藏。 ### 记忆管理与召回 侧边栏 **记忆** 按钮打开“记忆管理”弹窗。记忆数据全部存储在本地 SQLite 库 `/.dsh-session-kit/memory.sqlite`（WAL 模式），不依赖任何外部服务；核心逻辑位于 `lib/memory.js`。 - **记忆项目（memory_directories）**：记忆按项目归组，内置受保护的 `default` 项目（不可改名/删除）；每个项目可配置自动启用的会话 ID 列表。 - **记忆（memories）**：正文 + 状态（`active` 参与召回 / `inactive` 仅存档）；正文归一化后计算 SHA-256 作为唯一键，天然防止重复写入。 - **记忆标签（memory_tags / memory_tag_links）**：13 个预置标签（用户画像、用户偏好、项目画像、项目架构、项目约束、模块路径、项目场景、模块约束、项目摘要、模块摘要、接口摘要、工作项目、日常生活）+ 自定义标签，均可激活/停用；每条记忆最多挂 12 个标签。 - **会话项目开关（memory_session_directories）**：记录每个会话启用了哪些项目。 - **设置（memory_settings）**：自动蒸馏开关、全部会话启用 default、对话自动匹配项目、蒸馏模型覆盖、分词器版本戳。 - **活动日志（memory_activity_logs）**：记忆相关操作审计，保留 7 天。 #### 写入路径 记忆有三条独立入口，最终写入持久库或进入内存中的临时记忆池： **1. 工具写入（Agent 调用）** — LLM 通过 `memory_add` / `memory_update` 工具写入： - 插件先做同步预校验，随即返回 `{accepted: true}`，实际写库在后台任务队列中 FIFO 执行——工具结果先送达模型，写库失败不会打断对话流，只记录警告与活动日志（可在记忆管理弹窗日志页查看）； - 目标项目按优先级解析：显式指定 > 按名称（不存在则创建）> 会话启用的唯一项目 > 多项目时按正文内容猜测 > 兜底 `default`； - 未显式提供标签时，程序按正文关键词自动归类（8 组中文正则），兜底“工作项目”；标签只接受预置白名单，防止模型杜撰。 **2. UI 手动写入** — 记忆管理弹窗内的创建、编辑、删除、跨项目移动同步执行并记录活动日志；“临时记忆 → 存储”转正操作会把临时条目写入持久库并移出临时池。 **3. 蒸馏写入（自动）** — 每轮对话正常结束（`turn/end` 且原因为 completed）且自动蒸馏开启时触发，按会话串行排队执行： - 提取该轮完整 transcript（用户/助手/工具调用/工具结果）； - 调用当前会话模型（或设置中指定的蒸馏模型覆盖，失败自动回退默认路由）输出固定 JSON：`{"位置":[…],"对象":[…],"内容":"…","踩坑":"…"}`；也接受 `paths` / `symbols` / `content` / `pitfall` 英文 key，标签由程序按正文自动分类，不依赖模型输出； - 涉及代码、路径或接口的内容统一按 JSON 规范存储；位置和对象是字符串数组，内容和踩坑均允许换行，未知字段保留，便于后续扩展与按路径/符号检索； - 蒸馏产物先进**临时记忆池**（内存，不落库）：含有效结构化 JSON 的直接激活，裸文本默认停用、等待人工确认；与持久库或临时池内容重复的自动合并； - 临时记忆带来源会话与轮次元数据，用于召回时的跨会话补偿（见下文）。 #### 召回管线 召回挂载在每轮请求前（`agent/pre-step`），以本轮用户输入为查询自动执行，总预算 30s、最多 20 条。 **预处理** 1. **对话自动匹配项目**：以输入文本对项目名与近期记忆内容评分（≥8 分才启用），新命中的项目自动为当前会话打开开关（每轮至多 3 个），并在注入文本顶部提示； 2. **上下文去重**：已存在于上下文中的记忆不再重复注入（按注入记录的命中 ID 与正文压缩比对双重判定）。 **候选收集** - 主路：FTS5 + BM25。中文分词采用 jieba 词元 ∪ CJK 相邻二元组 ∪ 英数 run，写入派生 token 列；jieba 加载失败自动降级纯二元组； - 兜底：FTS 不可用或无命中时回退子串扫描打分； - 补充：查询词命中自定义标签名的记忆直接入围； - 查询画像：按正则将查询归入六类画像（默认相关/代码定位/场景上下文/约束偏好/用户画像/摘要聚合），各带独立标签权重表； - 候选准入（三选一）：BM25 命中 / 自定义标签命中 / 画像标签命中。 **四段式选拔** 候选按标签划分为底色池（含任一第一档稳定标签：用户偏好、用户画像、项目画像、项目架构、项目约束、模块路径）与普通池，然后四段各自用独立评分矩阵竞争选拔： | 段 | 席位 | 成员 | 评分分量 | |---|---|---|---| | 段1 底色 | 5 | 底色池 | BM25 + 自定义标签 + 画像标签 + 结构分(一档) + 时间衰减 | | 段2 临时 | 5 | 临时记忆池 | BM25 + 自定义标签 + 画像标签 | | 段3 混合 | 5 | 底色剩余 + 普通池 | 全分量（含两档结构分，防标签档位倒挂） | | 段4 兜底 | 5~15 | 普通池剩余 | 除一档结构分外的全分量；席位吸收前三段全部缺口 | 候选充足时总注入恒为 20 条。各分量含义： - **BM25**：FTS 相关性（0~8 分）； - **自定义标签**：查询与自定义标签名的精确/部分匹配（精确 16 分、部分 7 分，封顶 28）； - **画像标签**：按查询画像的标签权重（封顶 4.5）； - **结构分**（与查询无关的身份分）：第一档标签每个 +5 封顶 20（4 个满档），第二档（项目场景、模块约束、项目摘要、模块摘要、接口摘要）每个 +3 封顶 6，两档独立累加； - **时间衰减**（按记忆所属档位分层）：第一档 ≤30 天 1.2 / ≤120 天 0.9 / 更久 0.55 底分（永不归零）；第二档 ≤7 天 1.1 → 底 0.25；非稳定层 >120 天归零。 段2 是**不可见上下文补偿通道**：本会话近期轮次的蒸馏产物因尚未出窗而不入选（避免与对话历史重复），只有跨会话临时记忆、以及本会话中已被上下文压缩吞掉的轮次产出的临时记忆才准入——后者以最后一条压缩事件的序号为边界判定。打包阶段在字符预算内放不下的条目跳过继续（保序），超长记忆截断并标注。 **注入格式** 命中结果组装为一条插件来源的用户消息，插在本轮用户消息之前：编号列表（目录/标签/更新日期 + 正文），头部声明“与用户最新消息冲突时以用户消息为准”。注入同时把命中快照（与正文 1:1）随会话事件持久化，供每轮消息旁的记忆面板跨重启回看。 每条结构化记忆的 `内容/content` 字段注入限制 500 字符；位置、对象、踩坑和未知字段完整保留。（超限截断并提示用记忆工具查全文） #### diff 式剔除 已注入上下文的记忆不会永久占位。每轮正常召回后执行 top-k 语义的 diff 剔除： - **判定**：本轮召回仍命中的记忆保留（上下文前缀稳定，利于提示缓存）；已注入但本轮未进 top-k 的记忆剔除； - **落盘**：通过持久的 surface replacement 实现——部分存活的注入行原地重写为剩余记忆（快照同步裁剪，面板/正文/上下文三者一致）；整条剔除的注入行覆盖为空 tombstone 消息，后续模型上下文不再包含； - **弱输入保护**：短续作（“继续”“好的”）、纯数值/单位/代码片段等弱输入轮召回不可靠，完全不参与剔除判定、不动上下文，防止误剔活跃主题记忆； - **多 step 轮**：step 内召回输入与轮输入不同，同样不做剔除判定。 #### 记忆工具 插件为 Agent 注册 5 个记忆工具： | 工具 | 用途 | 要点 | |---|---|---| | `memory_add` | 新增长期记忆 | 异步后台写入；仅在用户明确要求记住或信息明显需要长期保留时使用 | | `memory_update` | 更新正文/标签/状态/项目 | 异步后台写入 | | `memory_stop` | 停用记忆 | 状态改为 inactive，不参与召回但保留在库 | | `memory_read` | 阅读记忆 | 读取一条记忆的全文 | | `memory_search` | 主动检索记忆库 | 支持从查询解析时间表达（今天/昨天/前天/最近 N 天/本周/上周/本月/上月/具体日期），可按项目/标签/状态过滤，默认 10 条上限 50 | | `conversation_search` | 跨会话搜索历史对话 | 扫描内存会话与持久化会话日志，按行词法打分；默认排除子代理会话 | 同一轮内相同参数的 `memory_search` / `conversation_search` 重复调用会被直接拦截，并提示模型使用上一次结果。 #### 辅助机制 - **FTS 索引生命周期**：分词管线以版本戳记录在设置中；版本变化（如 jieba 可用性切换）或索引行数不一致时，启动后台分批重建（每批 200 行，不阻塞启动，期间召回自动走子串兜底）；项目改名、标签增删改等结构性变更同样触发重建；重建期间的单行写入会挂起并在收尾时统一补齐。 - **活动日志**：覆盖记忆增删改、蒸馏（自动/手动/工具触发）、项目与标签操作、转正等全部动作；失败单独记录原因；保留 7 天，仅在启动时清理一次；异常逃逸的进行中活动超过 6 分钟由兜底扫描按失败落库，避免“进行中”列表永久卡死。 - **召回面板**：每轮消息旁可展开查看该轮上下文真实携带的记忆（按会话日志重放计算，弱输入轮自然继承背景注入），注入快照持久化后重启仍可回看；记忆后续的编辑/删除不影响历史轮显示。 ## 文件结构 - `lib/index.js`：Host 路由、全局提示运行时注册、归档/会话操作、轮次删除与重新生成逻辑。 - `lib/client.js`：Web UI Slot、全局提示弹窗、其他弹窗、话题导航、轮次操作、样式与 locale 字典。 - `lib/memory.js`：本地记忆库（SQLite）、jieba/二元组分词召回、蒸馏与后台索引重建逻辑。 - `cordis.patch.yml`：插件 bundle 插入 patch。 - `README.md` / `README.en.md`：中文与英文说明文档。 ## 注意事项与限制 - 插件不修改 DSH 核心包；全局提示通过运行时 `systemPrompt.section()` 注册，压缩阈值配置也不写入官方或用户 Agent preset 文件，卸载/关闭插件后 DSH 会回到原本的系统提示词与压缩配置。 - 记忆库为本地 SQLite 文件（`/.dsh-session-kit/memory.sqlite`）；删除项目或记忆不可恢复，卸载插件不会自动删除记忆库文件。 - 整个会话删除在会话运行中始终禁用。 - 轮次删除/重新生成采取保守策略；遇到不安全或已压缩的历史会拒绝执行。 - 重新生成只支持重放选中轮次中唯一的纯文本用户提问。 - 即使 active surface 已不再显示被删除内容，原始 append-only 事件仍然保留在会话日志中。 ## License [MIT](LICENSE)