跳到正文
  • 首页
  • 插件说明
  • dsh-session-health

omdsh-dev/dsh-session-health

80最近提交 2026年8月14日

dsh-session-health DSH 插件

dsh-session-health 是一个 DSH 插件，对 `$DSH_HOME/sessions` 下的多帧 zstd 会话文件进行帧级扫描诊断，检测断裂、损坏、空会话及残留文件，输出健康报告与清理建议。该工具为只读操作，绝不修改或删除任何文件。

developer-tools

如何安装 dsh-session-health DSH 插件

dsh plugin --profile web add github:omdsh-dev/dsh-session-health

复制不会执行命令。安装 dsh-session-health DSH 插件前请核对仓库和版本。

dsh-session-health DSH 插件数据来源

dsh-session-health DSH 插件快照日期：2026年8月16日

discovered

dsh-session-health DSH 插件能做什么

  • 对多帧 zstd 会话文件进行帧级扫描，检测断裂、损坏、空会话及残留文件。
  • 生成包含错误计数、可疑项和可操作清理建议的健康报告。
  • 保证只读操作，具有路径围栏、符号链接防护，无网络及执行面。
  • 支持可选深度分析（deep:true），动态导入官方解码器获取事件统计。
  • 提供三种操作：scan（全目录扫描）、file（单文件分析）、stats（汇总统计）。

dsh-session-health DSH 插件适合哪些场景

  • 检查 DSH 会话目录下所有会话文件的健康状态，识别损坏或不完整的会话。
  • 调查特定会话文件的帧级问题，如写入中断或 turn 断裂。
  • 检测残留的临时文件（如 *.tmp），以便安全清理。
  • 在分析或修复工作流之前验证会话文件格式是否正确。
  • 生成可读的健康报告，用于向 DSH 团队或社区报告问题。

dsh-session-health DSH 插件适合谁

  • 需要监控会话文件完整性的 DSH 用户。
  • 排查会话损坏问题或调试 DSH 内部机制的开发者。

dsh-session-health DSH 插件的限制

  • 深度分析（deep:true）依赖动态导入官方解码器，若不可用则降级为帧级扫描，并在报告中标注。
  • 事件批次估算为近似值（帧数-1），并非精确事件数，报告已注明为估算。

dsh-session-health DSH 插件的仓库 README 摘录

以下文字摘自 dsh-session-health DSH 插件的上游仓库 omdsh-dev/dsh-session-health 的 README，版权归原作者，仅作引用。

DSH 会话健康检查插件 —— 对 `$DSH_HOME/sessions` 下的**多帧 zstd 会话文件**做帧级扫描诊断（torn / 损坏 / 空会话 / stray 文件），输出健康报告与清理建议。**只读**：绝不修改或删除任何文件。 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) 仓库：[https://github.com/omdsh-dev/dsh-session-health](https://github.com/omdsh-dev/dsh-session-health)（public） ## 动机 8/7 调查 issue #376 时对 39 个会话文件做了全量解码分析，过程中发现一个关键事实：**DSH 会话文件是多个 zstd frame 的串联**（一个 19MB 会话 = 119,952 个 frame），用单帧解码 API 读多帧文件只能看到 header——曾导致"会话全空"的误判。这套诊断逻辑值得产品化为工具：模型可以直接问"我的会话文件健康吗"，而不是靠人手工写脚本。 与 `dsh-session-repair-skill`（修复损坏会话）互补：本工具**只读诊断发现** → repair 技能**修复**。 ## 安全模型 - **只读保证**：绝不修改/删除任何文件（测试覆盖"扫描后文件字节数不变"，见 files.spec SH-06 用例） - **路径围栏**：session id 严格目录名白名单（防 `../` 穿越）；绝对路径与最终文件均做 `fs.realpath` 真实路径 containment（防符号链接/junction 逃逸）；枚举用 lstat 拒绝 symlink - **零业务依赖**：zstd 帧扫描器为独立实现（DataView 读字节，RFC 8878 结构，与官方 `scanZstdFrames` 差分一致） - **深度分析可选**：`deep: true` 时动态 import 官方解码器；解析失败明确降级 `deep: "unavailable"`，绝不静默 - 输入范围固定（sessions 目录），无网络、无执行面 ## 工具声明 注册 `session_health` 工具（`@deepseek-ai/dsh-session-health`，row id `tool-session-health`），统一输出 JSON 文本。 | 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | `action` | string | ✅ | `scan` / `file` / `stats` | | `path` | string

阅读完整 README仓库许可: MIT

dsh-session-health DSH 插件常见问题

session_health 工具是做什么的？

session_health 工具扫描 DSH 会话目录下的多帧 zstd 会话文件，检测断裂帧、空会话、残留文件及结构损坏等问题。它输出 JSON 格式的健康报告，包含错误计数和清理建议，并且绝不修改任何文件。

如何安装 dsh-session-health 插件？

推荐从 GitHub 安装：`dsh plugin --profile web add github:omdsh-dev/dsh-session-health`。也可以先运行 `npm pack` 生成 tarball，然后执行 `dsh plugin --profile web add dsh-session-health-*.tgz`。安装后可使用 `dsh --profile web --dump-config | grep tool-session-health` 验证。

为什么 deep 模式不可用？

deep 模式（deep: true）需要动态导入官方解码器 `@deepseek-ai/dsh-session-persistence-jsonl`。如果该包在运行时无法解析，深度分析会优雅降级为帧级扫描，并在报告中标注 `deep: "unavailable"`。帧级扫描不受影响。

dsh-session-health 会修改或删除文件吗？

不会，它是严格的只读工具。README 明确声明“绝不修改或删除任何文件”，测试用例中也包含验证扫描后文件字节数不变的检查。此外，该工具实现了路径围栏，防止意外写入或符号链接逃逸。

dsh-session-health 和 dsh-session-repair-skill 有什么区别？

dsh-session-health 是只读的诊断工具，检测损坏并生成报告。dsh-session-repair-skill 是另一个技能，用于实际修复损坏的会话文件。两者互补：健康检查发现问题，修复技能解决问题。