# DSH Doctor

> DSH Doctor 帮 DSH 插件开发者（和他们的 AI Agent）应对版本升级：分析要迁移什么、诊断环境、在临时 profile 里验证构建结果，并分清哪些能自动改、哪些得人来判断。

- 原文：https://bruc3van.com/projects/dsh-doctor/
- 作者：Bruce Van
- 分类：桌面与 DSH
- 内容更新：2026-09-26
- 适合谁：要升级 DSH 插件，或者在排查依赖、配置和运行问题的开发者。
- 预期结果：拿到一份有据可查的诊断结果或迁移计划，再按"代码检查 → 构建 → 安装加载 → 实际功能"一层层验证。

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

## DSH Doctor 解决什么问题？

DSH 一升级，插件可能就跑不起来了，环境配置出问题也不好查。DSH Doctor 帮你排查这两类问题：它会检查源码、依赖、配置和构建出来的文件。对于迁移规则里已经确认的、改法很明确的地方，它会生成修改计划；需要理解业务意图才能改的地方，交给开发者或 Agent 来判断。

目前支持 DSH 0.1.1 → 0.1.2 的迁移，具体覆盖哪些版本标签，见迁移规则目录（catalog）。其他版本要先看对应的规则和源码差异，不能光看版本号就认定兼容。

## 怎么开始排查？

1. 读一下仓库 README 里命令行或 Skill 的用法，确认本地装的是哪个版本。
2. 想清楚要查的是哪个插件仓库、哪个 DSH profile。
3. 先跑只读的诊断或迁移分析，把发现的问题和对应的文件记下来。
4. 如果要升级，先确定新版本还要不要兼容旧版本，再看修改计划。
5. 改完之后一层层验证，并记下哪些业务功能还没验证过。

装好命令行工具后，可以先跑一次普通的只读诊断：

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

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

## 编译通过了，还要验证什么？

| 验证到哪一步              | 能说明                           | 还说明不了                           |
| ------------------------- | -------------------------------- | ------------------------------------ |
| 代码检查（静态分析）      | 已知的 API、依赖和配置问题有没有 | 运行起来一定没问题                   |
| 构建和打包                | 能打出发布包，内容可以检查       | 插件能正常启用                       |
| 在临时 profile 里安装启用 | 安装包能装上，基本能加载         | 界面、服务生命周期和业务流程全都正常 |

## 为什么只自动改那些"改法很明确"的地方？

包名、函数名这种已知的一对一替换，可以机械地改。但涉及所有权、生命周期或 Settings Service 的变化，通常得先搞懂原来为什么这么写。如果自动去改这些，代码可能编译通过了，行为却是错的。

## 会动我日常用的环境吗？

普通的诊断和迁移分析都是只读的；项目的运行验证用的是临时的 DSH 环境。更新、持久化隔离、删除这些是单独的操作，执行前要按命令行的提示看清影响、做好备份。你只是让它查个问题，它不会顺手把所有恢复操作都做了。

## 项目文档与使用限制

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

内容更新：2026-09-26。正文依据所列 README 的固定提交整理；内容更新日期不代表已核验最新版本。最新版本与安装要求见项目仓库。

目前支持的迁移有明确的版本范围；在临时环境里装上、能加载，也不能说明插件的所有功能都正常。