# DSH Doctor

> DSH Doctor 为 DSH 插件开发者和 Agent 提供迁移分析、环境诊断、构建产物与临时 profile 验证，并区分可自动修改和需人工判断的变化。

- 原文：https://bruc3van.com/projects/dsh-doctor/
- 作者：Bruce Van
- 分类：桌面与 DSH
- 更新日期：2026-09-06
- 适合谁：需要升级 DSH 插件，或调查依赖、配置与实际运行问题的开发者。
- 预期结果：得到可追溯的诊断或迁移计划，并按静态、构建、安装激活与业务行为逐层验证。

- [GitHub 源码](https://github.com/bruc3van/dsh-doctor)
- [相关指南](https://bruc3van.com/playbooks/dsh-ecosystem/)

## DSH Doctor 解决什么问题？

DSH Doctor 用于调查 DSH 插件升级和 profile 环境问题。它检查源码、依赖、配置层与构建产物，对 catalog 已确认的精确迁移生成修改计划，将需要理解业务语义的变化交给开发者或 Agent。

当前支持 DSH 0.1.1 → 0.1.2 的迁移，具体覆盖的 tag 见迁移规则目录（catalog）。其他版本需要先检查对应规则和源码差异，不能仅凭版本号推定兼容。

## 怎样开始排查？

1. 阅读仓库 README 的 CLI 或 Skill 使用方式，确认本地工具版本。
2. 明确需要调查的是哪个插件仓库和哪个 DSH profile。
3. 先执行只读诊断或迁移分析，保留问题与文件来源。
4. 若涉及升级，明确新版是否还需要兼容旧版，再审阅修改计划。
5. 应用改动后逐层验证，记录尚未验证的业务行为。

已安装 CLI 时，可从普通只读诊断开始：

```sh
dsh-doctor diagnose --json
```

完整参数以该版本的 `dsh-doctor --help` 为准。

## 编译通过以后还要验证什么？

| 证据                    | 能说明什么                       | 仍不能说明什么                         |
| ----------------------- | -------------------------------- | -------------------------------------- |
| 静态分析                | 已知 API、依赖与配置问题是否存在 | 运行时一定正常                         |
| 构建与打包              | 发布产物能生成，内容可检查       | 插件可以激活                           |
| 临时 profile 安装与激活 | tarball 能安装并基本加载         | UI、Service 生命周期和业务流程全部正常 |

## 为什么只自动处理精确改动？

包名或 symbol 的已知等价替换可以机械处理，所有权、生命周期或 Settings Service 的变化通常需要理解原来的意图。自动改写这些语义可能让代码通过编译却产生行为错误。

## 会修改日常使用的环境吗？

普通诊断与迁移分析是只读入口；项目的运行验证使用临时 DSH 环境。更新、持久化隔离与删除属于独立动作，应按当前 CLI 提示检查影响与备份，不能把一次排查请求理解为执行所有恢复操作。

## 项目文档与使用限制

- [项目 README](https://github.com/bruc3van/dsh-doctor/blob/5fc94090de7a9fb7bb692a74c6b6319eaa85983c/README.md)

内容更新：2026-09-06。最新版本与安装要求见项目仓库。

当前 catalog 有明确版本范围；临时环境安装激活成功不能证明插件全部业务行为正确。