DeepSeek Harness 插件诊断工具：dsh-composition-doctor

前言¶

DSH 采用“一切皆插件”的架构。在开发或维护 DSH 实例时，安装或升级插件后遇到启动失败是常见问题。当 Web UI 无法打开时，定位根因（例如重复加载器 ID、缺失补丁或配置冲突）通常比较困难。

dsh-composition-doctor 旨在解决这个问题。它将已知的失败模式链接到 Bundle、Patch 或 Profile 层，告诉你下一步应该检查哪个来源，而无需启动 DSH 实例。

是什么¶

dsh-composition-doctor 是一个由 lemonxiny55 维护的客户端诊断工具。它通过分析静态元数据来解释 DSH 插件故障，包括重复插入、缺失补丁、对等依赖不匹配等。目前版本为 0.4.0。

安装¶

使用 npm 安装全局 CLI（注意忽略构建脚本）：

npm install -g dsh-composition-doctor@0.4.0 --ignore-scripts

安装后，验证版本：

dsh-doctor --version

前置条件：运行环境需满足 Node.js >= 20。

核心功能¶

1. 只读与离线：默认离线诊断，不自动修复配置，不访问网络，不启动 DSH 进程。
2. 故障检测：能够检测以下问题：
   • 重复加载器 ID。
   • 捆绑包不可用。
   • 缺失或无效的捆绑包补丁。
   • 目标声明缺失。
   • 对等版本/依赖不匹配。
   • 配置替换或覆盖。
3. 输出支持：支持管道传输和结构化输出（如 JSON 或 Markdown）。
4. Web 探索器：提供可选的 Web 界面查看报告。

使用示例¶

基础检查¶

检查指定配置文件的静态元数据：

dsh-doctor check --profile "$HOME/.dsh/profiles/web"

诊断日志¶

结合错误日志进行诊断：

dsh-doctor diagnose --profile "$HOME/.dsh/profiles/web" --log ./minimal-error.log

结构化输出¶

输出 JSON 格式的结构化结果：

dsh-doctor diagnose --profile "$HOME/.dsh/profiles/web" --format json

查看来源与影响¶

查看特定行（row）的来源链，或查看特定 Bundle 的影响范围：

dsh-doctor why row tool-bash --profile C:\path\to\profile
dsh-doctor impact bundle @example/dsh-bundle --profile C:\path\to\profile

工作原理与注意¶

• 静态分析：check 和 diagnose 命令仅检查静态元数据，不会导入插件代码、运行生命周期脚本或访问网络。
• 健康状态误判：如果输出结果为 unknown、no-match 或退出代码为 0，并不代表配置是健康的。这可能意味着插件无法检测到已知的失败模式。
• 无自动修复：该工具仅提供诊断信息，不会自动修改你的 Profile 配置。

总结¶

dsh-composition-doctor 是一个用于排查 DSH 插件故障的实用 CLI 工具。它通过分析静态元数据，帮助你在 DSH 无法启动时快速定位问题根源。

• GitHub 仓库: lemonxiny55/dsh-composition-doctor
• 插件目录: dsh-composition-doctor