dsh-plugin-precheck

Readme

# dsh-plugin-precheck（插件安装预检助手）

安装 DSH 插件前先做兼容性与启动验证：发现问题即阻止安装并保留原环境，面向不了解插件依赖的新手。

## 它做什么

在 Web GUI「设置 → Plugins」中新增「安装预检」标签页。输入 npm 包名后：

1. **解析并锁定版本**（`pnpm view`）
2. **基础兼容性检查**：peerDependencies 与已装版本比对、Node engines、bundle 清单声明；信息缺失时显示「无法确认」而不是放行
3. **组合检查**：新插件的 `cordis.patch.yml` 与当前配置树（`dsh --dump-config`）比对——插入 id 重复（确定错误）、补丁目标不存在/被多个插件覆盖（疑似风险）
4. **隔离试装 + 试启动**：临时 `DSH_HOME` 中复制 profile 文本文件，`pnpm add` 锁定版本 → `--dump-config` 静态校验 → `--port 0 --no-open` 试启动，等就绪行 + 401 探针，180 秒超时树级杀死。隔离环境不含凭据、不挂载定时任务、不触碰正式环境
5. **检查通过后才允许正式安装**：使用同一锁定版本；安装前备份 profile 四个文本文件，失败自动还原 + `pnpm install` 复原 + `--dump-config` 复验；恢复失败如实告知并给出日志与手动步骤

## 保护范围（如实声明）

- 覆盖：本页面的检查安装；**开关开启时，本浏览器标签页中 dsh-market 的安装/更新点击**（fetch 拦截 → 完整预检 → 通过才放行）
- 不覆盖：命令行 `dsh plugin add`、其他浏览器标签页；市场插件若未来改变端点或传输方式，拦截会失效（探测不到即不启用，不会误拦，UI 有状态显示）
- 检查通过 ≠ 插件永久稳定，≠ 通过安全审计

### dsh-market 拦截的工作原理

`dshmarket` 的全部路由都是 `exact` 注册（webServer 精确表优先，重复注册会抛错），且没有预安装钩子——**Host 层无法插入中间件**。因此拦截做在浏览器层：patch `window.fetch` 识别 `POST /dsh-market/install`、`/dsh-market/update`、`/dsh-market/api/v1/updates`，暂停请求 → Host 半侧把请求映射为安装来源（安装：url → 注册表条目 → npm 包名或 GitHub target；更新：包名 → 市场目标版本）→ 跑完整预检（含隔离试启动）→ 通过才用原始 fetch 放行；阻止/取消则返回合成 400 让市场 UI 自己报错。可在「安装预检」标签页随时停用。

## 安装

```sh
dsh plugin --profile web add dsh-plugin-precheck
# 然后重启 dsh web
```

## 状态词汇

检查中 / 检查通过 / 已阻止 / 无法完成检查 / 正在安装 / 正在恢复 / 已恢复 / 恢复失败。所有结论附判断依据，可复制脱敏诊断报告。