### 框架升级适配门与升级安全（v0.3.25）

> 缘起：2026-09-04 DSH `0.1.1-rc.2 → 0.1.2-rc.1` 升级事故——升级脚本在错误的工作目录执行，
> 把新 CLI 原位覆盖进旧 `.pnpm` 目录、依赖树混版本，服务无法拉起。本版本把「升级安全」与
> 「插件兼容检测」固化为控制台机制。

**升级安全三件套**

1. **框架安装根识别**：定位真正的框架安装根（含 `.pnpm` 的顶层 `node_modules`），修复
   `require.resolve` 返回 `.pnpm` 内部 realpath 导致的「重链空转 / 新包覆盖旧目录」根因；
   定位不到时**拒绝升级**（不 kill 服务、服务保持运行）；
2. **升级前全树 checkpoint**：镜像 `.pnpm` 全部 `@deepseek-ai` 版本包 + 顶层 scope +
   `lock.yaml`（写入 `~/.dsh/plugin-console/framework-backups/<版本>/fw-tree/`）；
3. **拉起失败自动全树回滚并重试**：安装失败或服务拉起失败都会自动恢复升级前全树并再次拉起，
   不再只留「请手动运行」提示；回滚后跳过重链/修复（避免对已恢复旧树二次破坏）。

**一键回滚**：升级后框架卡片出现「回滚到上一版」按钮（`/plugin-console/framework-rollback`）：
停服 → 全树恢复 → 自动拉起 → 健康检测，全程状态可见。

**插件适配门（插件检测）**

- 升级后写入 `~/.dsh/plugin-console/compat-pending.json` 的插件行被**强制禁用**，启用按钮
  锁定（服务端 `/toggle` 直接 409，无法绕过）；行状态以按钮文案「待适配」提示；
- 「详情」面板给出说明与入口：**检测更新 → 更新并适配**；
- **更新后自动校验**：扫描最新版 `package.json` 的 `dsh.engines.framework` / `engines.dsh`
  显式声明 + `@deepseek-ai/*` 依赖范围（内置零依赖 semver 判定器：依赖判定遵循 npm
  prerelease 严格规则、声明判定宽松）；版本已变化且未判定不兼容 → **自动移除禁用块解锁**；
  聚合包更新连带校验同步的子包；
- **AI 赋能适配预检**：规划时服务端预检 registry 最新版声明与适配门命中情况，注入子代理
  提示词（要求计划向用户解释适配结论），并在计划面板标注（不兼容标红）。