← Back to home@mengge237

dsh-legacy-compat

DSH 0.1.2-rc.1 interim compat shim: Session.events alias for legacy presets/plugins, corrupt session-log boot guard (quarantine), Node preflight

Stars
0
Language
JavaScript
Created
Sep 4, 2026
Updated
Sep 5, 2026
Tools
GitHub repo

Introduction

dsh-legacy-compat

lang status

过渡垫片：装完即用、默认安静、一条命令卸载；上游修复后即可移除。

安装（社区直接用，已验证 6 秒装好）

dsh plugin --profile web add github:mengge237/dsh-legacy-compat
# 装完完全重启 dsh web；Settings → Plugins 里能看到 dsh-legacy-compat

能覆盖什么、覆盖多少、怎么自查 请看 COVERAGE.md（含本机实测与 node bin/check-compat.mjs 一键扫描）

DSH 0.1.2-rc.1 过渡期的「兼容垫片 + 启动保护」插件。 设计原则：装上即用、平时安静、一键卸载；上游修复后即可移除。 起因与根因分析见 https://github.com/mengge237/dsh-incident-report-2026-09-04

功能

  1. 启动保护：按官方同款规则校验 sessions/**/session.jsonl.zstd 首个 zstd 帧； 遇到「首帧不是恰好一行 header」的坏日志，自动移入 ~/.dsh/dsh-legacy-compat-quarantine/ （原字节保留、不删除），避免 dsh web 因一个坏日志起不来。
  2. Session.events 兼容别名：给 Session.prototype 补回 get events()（委托新版 snapshotEvents()）， 按旧 API 写的第三方预设/插件（如 session.events.length 这类用法）无需修改即可运行。
  3. 启动预检：Node 版本 / zstd API 检查（rc.1 需要 Node >= 24）。

安装（一条命令，社区可直接用）

# 方式 A：GitHub 渠道（已验证：6 秒装好且自动进 bundle 栈，无需 npm）
dsh plugin --profile web add github:mengge237/dsh-legacy-compat

# 方式 B：本地源码（开发/修改用）
dsh plugin --profile web add link:E:/S_Software/deepseek-harness/plugins/dsh-legacy-compat

# 方式 C：发布到 npm 之后
# dsh plugin --profile web add dsh-legacy-compat

# 装完完全重启 dsh web

任意 profile 均可（web / tui / headless / 自定义），命令里的 web 换成目标 profile 名即可。

发布到 npm 后（一条更短的命令）

# 已发布到官方 npm：@mengge237/dsh-legacy-compat
npm_config_registry=https://registry.npmjs.org dsh plugin --profile web add @mengge237/dsh-legacy-compat

说明：默认 npm 源是 npmmirror 镜像，新包同步通常有几十分钟到数小时延迟； 同步前请用上面的 npm_config_registry=https://registry.npmjs.org 临时走官方源安装， 镜像同步完成后即可省略该前缀。

装好后在哪里能看到它？

  • DSH 原生 Settings Plugins（插件/Plugins 清单） 会列出 dsh-legacy-compat（它就是一层 bundle）；
  • 一切正常时插件保持安静，只在“隔离了坏日志 / Node 不兼容 / 别名安装失败”时提示一行；
  • 想卸载：下面的 bin/uninstall.mjs，或官方命令 dsh plugin --profile web remove dsh-legacy-compat。

为什么隔离的坏会话在会话列表/设置里看不到？

  • DSH 原生的会话列表只读 sessions/**/session.jsonl.zstd 且首帧必须合法；被隔离的文件已移出该目录，所以不再出现（这正是“让 dsh 能启动”的目的）；
  • 隔离文件原字节保留在 ~/.dsh/dsh-legacy-compat-quarantine/，可用 node bin/repair.mjs 查看统计、用文件管理器查看；
  • 如果社区呼声高，后续可做一个“隔离区管理”设置页（一键恢复/清理），需要引入前端分栏——属于过渡期之后的增强。

一键卸载（过渡期专用）

node bin/uninstall.mjs                 # 卸载 web profile 中的本插件
node bin/uninstall.mjs --profile tui   # 指定其它 profile
node bin/uninstall.mjs --dry-run       # 只预览不改动

脚本会：从 dsh.profile.bundles 移除、删除 dependencies 里的 link 记录、删除 node_modules 链接， 并自动备份修改前的 package.json（.bak-uninstall-<时间戳>，可回退）。卸载后完全重启一次即回到未安装状态； 隔离区数据不会被动，可自行决定保留或删除。

日志与“安静模式”

  • 一切正常时不输出任何内容，不打扰使用；
  • 仅在「隔离了坏日志 / 别名安装失败 / Node 版本不兼容」时给出一行简短警告；
  • 想看详情：设置环境变量后重启：DSH_LEGACY_COMPAT_VERBOSE=1；
  • 输出优先走 dsh 自身的 logger，其次才用终端 console。

离线修复（dsh web 已经起不来的情况）

node bin/repair.mjs                      # 扫描并把坏会话日志移入隔离区
node bin/repair.mjs --home <dshHome>     # 指定自定义 home

本地 link 安装的依赖解析

别名功能需要 import @deepseek-ai/dsh-session。

  • npm/registry 安装：依赖随包安装，无需处理；
  • 本地 link 安装：本仓库源码目录已自带 node_modules/@deepseek-ai/dsh-session（junction，指向你机器上 harness 的 dsh-session 包）； 换机器/从 zip 分发时重建即可：
New-Item -ItemType Junction -Path node_modules/@deepseek-ai/dsh-session -Target <dsh安装路径>/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-session

边界与建议