前言¶

DSH 把对话过程持久化为 $DSH_HOME/sessions 下的会话文件。这些文件不是单帧 zstd 压缩块，而是多个 zstd frame 的串联——README 中举例，一个 19MB 会话可包含 119,952 个 frame。若用单帧解码 API 读取多帧文件，往往只能看到 header，容易误判为「会话全空」。

排查这类问题时，通常需要手写脚本逐帧扫描、比对结构。dsh-session-health 把这套诊断逻辑产品化为 DSH 工具：模型或开发者可以直接问「会话文件健康吗」，得到结构化报告与清理建议，而不必每次临时写分析脚本。它与 dsh-session-repair-skill（修复损坏会话）互补：本插件只读诊断，repair 技能负责修复。

这是什么¶

dsh-session-health 由 omdsh-dev 维护，归类为 admin-security。插件对 sessions 目录下的多帧 zstd 会话文件做帧级扫描，检测 torn、损坏、空会话、stray 文件等问题，输出健康报告与清理建议。全程只读，不修改或删除任何文件。

npm 包名 @deepseek-ai/dsh-session-health，版本 0.0.1，MIT 许可。GitHub 仓库：https://github.com/omdsh-dev/dsh-session-health。社区目录页：https://www.skillhub.cn/plugins/omdsh-dev/dsh-session-health。

插件注册 session_health 工具（row id tool-session-health），统一输出 JSON 文本。

核心功能¶

帧级扫描与检测项¶

扫描器基于 RFC 8878 结构独立实现（DataView 读字节），与官方 scanZstdFrames 差分一致，零业务依赖。可识别的异常类别如下：

报告字段包括：root、scanned、errors、suspicious、totals（字节、帧数、事件批次估算）、detail、deep、suggestions。suggestions 按 issue 模板给出清理/修复建议，不自动执行。

工具参数¶

deep: true 时动态 import 官方解码器做事件分布与中断检测；若解码器不可用，报告明确标注 deep: "unavailable"，帧级扫描仍正常进行。

安全模型¶

1. 只读保证：绝不修改或删除文件；测试覆盖「扫描后文件字节数不变」（files.spec SH-06 用例）。
2. 路径围栏：session id 严格目录名白名单；绝对路径与最终文件均做 fs.realpath containment；枚举用 lstat 拒绝 symlink。
3. 输入范围固定：仅 sessions 目录，无网络、无执行面。

安装与启用¶

插件已在 @deepseek-ai/dsh@0.1.0-rc.8 下完成全链路验证。Node 要求 ^22.19.0 || >=24.0.0。

下面介绍从 GitHub 安装的方式（README 推荐）。web 与 headless 是不同 profile：dsh run 默认使用 headless profile，在 web profile 安装不会自动覆盖 headless。

# 交互式（web）profile
dsh plugin --profile web add github:omdsh-dev/dsh-session-health

# 一次性任务（headless）profile —— dsh run 默认使用 headless
dsh plugin --profile headless add github:omdsh-dev/dsh-session-health

也可使用 npm pack 产物安装：

dsh plugin --profile web add dsh-session-health-*.tgz

包内 dsh.bundle.patch 会在安装后自动把插件加入 profile 的 layer stack。peer 依赖（@deepseek-ai/cordis、@deepseek-ai/dsh-tools）由 profile 的 healed profiles/node_modules 回退安装提供。

验证安装是否生效：

dsh --profile web --dump-config | grep tool-session-health

启动 DSH（lib 生产模式，勿全局安装）：

npx -p @deepseek-ai/dsh@0.1.0-rc.8 dsh web

典型用法¶

扫描整个 sessions 目录：

session_health { action: "scan" }

返回示例结构：

{"root":"C:\\Users\\admin\\.dsh\\sessions","scanned":39,"errors":{...},"suspicious":{...},"suggestions":[...]}

对单个会话做深度分析：

session_health { action: "file", path: "session-abc123", deep: true }

也可通过 dsh run 让模型调用：

dsh run "使用 session_health 工具扫描会话目录健康状态"

适用场景与注意¶

适合谁

• 本地 sessions 目录出现异常（会话「看起来是空的」、写入中断、残留 tmp 文件）时，需要快速定位问题文件。
• 不想每次手写 zstd 帧扫描脚本，希望模型在对话中直接查询健康状态。
• 与 dsh-session-repair-skill 配合：先用本插件诊断，再按需修复。

注意事项

1. 插件以当前 dsh 进程权限运行，安装前应检查源码与 MIT 许可证。
2. deep 模式依赖 @deepseek-ai/dsh-session-persistence-jsonl；在 npm 0.1.0-rc.8 下该 tarball 不含 src/、根入口不导出 zstd API，deep 会降级为 decoder-unavailable，帧级扫描不受影响。
3. 事件批次估算 = 帧数 - 1，是估算值而非精确事件数，报告已注明。
4. Windows 路径使用正斜杠（C:/...）。

结尾¶

dsh-session-health 把多帧 zstd 会话诊断从手工脚本变成可复用的 DSH 工具：只读、帧级、带路径围栏，输出结构化报告与建议。若你维护本地 DSH 会话或排查持久化问题，可以把它装进 profile 做一次基线扫描。

• 社区目录：https://www.skillhub.cn/plugins/omdsh-dev/dsh-session-health
• GitHub：https://github.com/omdsh-dev/dsh-session-health