dsh-session-mgr

dsh-session-mgr（会话管理）

DeepSeek Harness Web 会话语管理外挂

在设置页直接对「会话」与「已归档会话」进行移动、归档、恢复、备份与删除，并可跨工作区操作。

English · ·

---

目录

• 功能
• 截图
• 环境需求
• 安装
• 使用
• HTTP API
• 原理
• 安全机制
• 开发
• 授权

---

功能

支持单条与批量操作（移动 / 归档 / 恢复 / 备份 / 删除选中）。

跨机器可携

会话通过 header 的 cwd 关联工作区，而 cwd 是每台机器专属的绝对路径——直接复制文件夹到另一台机器会因路径不存在而无法继续。因此：

1. 在 A 机：对会话点「备份」，得到可携式包；
2. 把该包复制到 B 机；
3. 在 B 机：「汇入」该包并选择会话应归属的工作区/文件夹——汇入会把 cwd 重设为 B 机的路径（会话内容不变），会话即可在 B 机无缝继续。

工作区 = 文件夹，会通过 header 的 cwd 关联，而 cwd 是每台机器专属的绝对路径。因此 A 机备份的会话要搬到 B 机继续，需要用「汇入」把 cwd 重设为 B 机上存在的路径。

包的 DSH 版本比本机新时： 包里可能出现本机词表不认识的事件类型。汇入会用本机 harness 自己的事件词表逐条比对，把这类事件补上 ignorable: true（可安全跳过）后才安装——只重压含该事件的那一帧，header 帧与其他帧保持原字节与校验和，事件数量、顺序与序号都不变，界面会提示跳过了哪些类型。否则会出现「汇入成功，但打开会话报 failed to observe session … not marked ignorable」。

截图

会话管理页

弹窗

环境需求

• DeepSeek Harness 的 web profile（dsh web）
• Node.js ^22.19.0 || >=24.0.0（Harness 运行时）

安装

方法一：从 npm 安装（推荐）

# 1. 从 npm registry 安装到你的 web profile。
dsh plugin --profile web add dsh-session-mgr

# 2. 在 web profile 的 package.json 中，把 "dsh-session-mgr" 加入 dsh.profile.bundles
#    （与其他插件条目并列）。

# 3. 重新启动 web 服务器使外挂生效。
dsh web

也可以用 npm install dsh-session-mgr，或指定版本 dsh-session-mgr@0.6.7。

方法二：从本仓库安装

# 克隆/下载本仓库，把 <path> 换成 dsh-session-mgr 文件夹的绝对路径。
dsh plugin --profile web add "file:<path>\dsh-session-mgr"

# 之后同样把 "dsh-session-mgr" 加入 dsh.profile.bundles，再重启 dsh web。

方法三：手动安装

把本包放进 profile 的 node_modules（例如 pnpm add file:... 或 symlink）， 再把 "dsh-session-mgr" 加入 profile package.json 的 dsh.profile.bundles，然后重启。

使用

1. 打开「设置 → 会话管理」。

2. 所有会话按当前工作区分组；已归档的会话带有徽章标记。

3. 使用每行的按钮，或勾选复选框后使用工具栏批量操作：

   • 移动选中… → 选择目标工作区（或输入任意已存在文件夹，使其成为「未分组」）。
   • 归档选中… → 从侧栏隐藏（保留原位置）。
   • 恢复选中… → 取消归档，回到原位置。
   • 备份选中… → 把每个会话汇出为可携式压缩档（含 manifest.json、完整日志与全部附件的 <id>.zip / .tar.gz）到指定文件夹。
   • 汇入… → 把另一台机器的可携式包安装到所选的会话所在工作区/文件夹（在 B 机执行）。
   • 删除选中…（红色）→ 红色警告弹窗要求再次确认后才会真正删除。

4. 打开会话时，标题栏还有「移动到工作区」按钮，可一键移动当前会话。

5. 工具栏的 简体/繁體 切换（只有当 Harness 语言设为中文时才显示）用于切换中文简繁。

HTTP API

宿主端在 /dsh-session-mgr/* 下提供小型 JSON API（均为 POST）：

targetPath 接受真实路径或已注册的工作区 ID。backup（format: "zip" 用于 Windows，"targz" 用于 Linux）产生一个可携式压缩档（<sessionId>.zip / <sessionId>.tar.gz）；import 在本机读取该档案并安装（把 cwd 重设为 targetPath）。unknownEvents 是本次汇入因本机不认识而被标记为可跳过的 { type, count } 列表，通常为空数组。

原理

DSH 的「工作区」本质上是文件夹：会话通过 session header 的 cwd 归属到工作区。 「移动」＝

1. 把会话存档文件夹从 <sessions>/<旧cwd编码>/<id> 移到 <sessions>/<新cwd编码>/<id>；
2. 重写 JSONL 存档第一行（zstd 的第一个 frame）的 cwd；
3. 同步更新内存中的 workspace registry（header 索引 + 会话归账），侧栏立即重新分组——无需重启。

「归档/恢复」使用 registry 的全域归档集合；归档的会话保留 sessionIds 席位， 因此恢复后会回到原来的位置。

安全机制

• 运行中的会话不可移动／归档／备份／删除（通过 agents 服务判断）。
• 已打开（live）但闲置的会话在移动／删除前会先从内存卸载，下次打开读取新 header。
• 目标位置已存在同名文件／文件夹时拒绝并报错（不会静默覆盖）。
• 跨磁盘（EXDEV）移动时自动改为复制＋删除来源。
• 删除需要二次确认且不可恢复——建议先备份。

开发

lib/host.js 中的纯函数（路径编码、zstd frame 扫描、header 重写、文件夹搬移）可独立测试：

node scripts/test-i18n.mjs           # 三语键值与错误码一致性（机械式自我检查）
node scripts/test-session-ops.mjs    # 会话操作接缝（世代回退、cache 重绑/清理）
node scripts/test-move.mjs           # 合成数据测试
node scripts/test-real.mjs           # 用真实存档的「副本」测试

test-real.mjs 需要传入一个真实会话目录作为参数（或设置 DSH_REAL_SAMPLE）：

node scripts/test-real.mjs "C:\path\to\<session-id>\"

实机测试需要一个运行中的 harness（预设 http://127.0.0.1:3080/dsh-session-mgr；桌面版 App 的端口不同，请把它自己的位址当作第一个参数传入，例如 http://127.0.0.1:19387/dsh-session-mgr）。它们会在 DSH_HOME 下建立临时会话并在结束时清理：

node scripts/test-session-ops-live.mjs         # 移动 / 归档 / 恢复 / 备份 / 删除 整轮（含旧世代会话与 cache 回收）
node scripts/test-import-live.mjs              # 汇入：容器与世代正规化、附件还原
node scripts/test-import-rollback.mjs          # 汇入失败必须回滚、不留目录
node scripts/test-import-security-live.mjs     # 恶意压缩档（zip-slip）必须被拒
node scripts/test-import-compat-live.mjs       # 跨版本未知事件补上 ignorable 标记

DSH 升级后（会话格式版本可能变动），跑这一组即可确认本插件仍然相容。

贡献

发现 bug 或想要新功能？欢迎提交 issue，也欢迎直接送 PR —— 两种都同样有价值：只回报（不写代码）也会在 changelog 与贡献者表里记名。

关于 PR：我们会先审查，再决定是否并入 main（不会盲目合并）。可以參考 @ron0115 在 #3 的做法：

• 一个聚焦的分支，改动只涵盖修复所需；
• 简短说明「失败现象」与「为什么这样修」；
• 有意义的地方补测试 —— scripts/test-*.mjs 是纯 node 脚本（无测试框架），实机测试把 harness 位址当第一个参数传入（桌面版 App 端口不同）。

风格：纯 ESM、无构建步骤、零运行时依赖；针对 lib/host.js 的改动请补充并运行测试。

贡献者

感谢每一位让这个插件变得更好的人：

回报 bug、提出问题或送 PR，都算一份贡献 —— 见上方「贡献」。

已知限制

• 打包在内存中完成。 备份/汇入的 ZIP 与 tar.gz 读写都是零依赖的纯 JS 实现，整个压缩档（含附件）会驻留内存；实测 20 MB 附件备份约 0.2–0.25 秒、汇入约 0.2 秒，但单一附件到数百 MB 时内存用量会是其数倍。（已压缩的内容不会再浪费 CPU 做 deflate：20 MB 随机附件 0.84 秒 → 0.23 秒，可压缩内容仍会正常压缩。）
• 会话清单要走一遍机器上所有会话。 persistence.list() 本身实测 ≈1.8 ms/会话（本机 11 个约 20 毫秒、311 个约 0.5 秒）。标题过去是更贵的一块 —— 每个真实会话都要读完整日志再折迭，约 60 ms/会话 —— 现已按日志 revision 快取，只有变动过的会话会重查：本机 11 个会话冷启动首次约 0.7 秒、之后约 25 毫秒。外挂自己新增的 unreadable 扫描实测几乎不增加成本。
• unreadable 只涵盖读不出 header 的会话目录（日志截断/损坏、没有日志、中断的汇入残留）。其他形式的损坏由 harness 自身的载入检查处理。

授权

MIT