dsh-plugin-adaptlisted
Install: claude install-skill taxueseek/plugin-fast-adapt
# 适配升级车道
把「插件适配到新版 DSH」拆成四步,每步一个脚本,每步都能单独跑;另有两个可选步骤补全「修完即验、升级顺带优化」。以下命令都相对工具根目录执行,工具根即本文件真实路径往上两级、含 `scripts/` 的那一层。脚本用自身文件的绝对路径定位,不必先 cd,从任何目录直接 `node <工具根>/scripts/<脚本>.mjs` 同样可行。本目录常以软链别名加载,shell 的 `cd ../..` 会按软链走错地方,确实要 cd 时用 `cd "$(realpath <本文件所在目录>)/../.."`。`<插件目录>` 指被查插件的仓库根。
环境本身有问题(覆盖层旧包、悬空软链、客户端半死链)先转 `../diagnose/SKILL.md`,别在坏环境上做适配判断。
## 第一步:看清本机环境
```sh
node scripts/env-doctor.mjs <插件目录> --brief
```
`--brief` 只影响输出体积(本机实测 80.5KB → 4.5KB,约省 2.1 万 token):`installedPlugins` 的 patch 行原文换成计数、进程命令截断到 120 字符。要查具体挂载行时去掉 `--brief` 拿全量。
本车道只取四段:
- `globalDsh`:全局安装的 DSH 版本和位置,后面定目标版本要用
- `target.peerWindows`:待查插件自己声明的 peer 版本窗口,决定扫描走廊起点
- `ghostHost`:磁盘代码已换新、宿主进程还在跑旧代码时判 `stale`(进程启动时间早于磁盘变更超过 120 秒)。先重启宿主再做适配判断,否则改完也验不到;`ok` / `no-running-host` / `unknown` 看 `reason`,不猜
- `falseGreen`:`tsconfig` 的 `paths` 指向不存在的 checkout(M1)。此时 TypeScript 静默回落到 `node_modules` 的已发布类型,本地 `typecheck` 可能全绿而实际类型是旧的;`findings` 非空先修路径或删 alias,再信 typecheck 结果
`overlayFindings`、`sharedFarmFindings`、`activation` 非空,或 `ghostHost.verdict` 为 `stale`,说明环境本身要修,转 `../diagnose/SKILL.md`。
## 第二步:定目标版本
```sh
node scripts/guide-sync.mjs <本机版本>
```
它读 npm 的 `dist-tags`(`latest` / `next` / `alpha`),判断本机在官方通道里的位置:
| 判定 | 含义 | 下一步 |
| --- | --- | --- |
| `upgrade-available` | 有通道版本高于本机 | 取 `target`(官方所有通道的最高版本)继续 |
| `up-to-date-on-channel` | 本机已是某通道最新版 | 无需适配,收工 |
| `ahead-of-upstream` | 本机比官方所有通道都新 | 无需适配,收工 |
| `unknown-local` | 没检测到本机版本 | 默认跟 `latest`,但要人工确认 |
**不要盲目取 `latest`。** 本机完全可能跑在 `next