dsh-safe-install

DSH 插件安全安装全流程自动化:四重安全检查 → 自动安装 → 自动重启。 Safe, one-shot installation of DeepSeek Harness plugins: verify → install → restart.

🌐 English docs: README.en.md

装插件有风险(dsh-mask 重复加载器崩溃、工具名冲突、版本不匹配),且装完要手动重启 DSH。本插件把「装插件」变成一句话: 安检通过 → 打快照 → 安装 → 自动重启 → 新插件生效,全程无需手动操作。

功能特性 (Features)

🔍 四重安全检查(安装前):版本兼容 / patch 冲突 / 工具名冲突 / 供应链
⛔ 阻断机制:任一检查为 block 即拒绝安装并说明原因;warn 不阻断但提示风险
📸 安装前自动打快照(集成 dsh-undo-savepoint,可随时回退)
🔄 安装后自动重启 DSH(Node detached spawn,原进程释放端口后自动拉起)
📋 状态追踪:最近检查/安装/重启记录,重启后仍可查询
👁 变更检测:轮询 profile package.json bundles,感知外部安装/卸载

工作流程 (Flow)

用户说"装 XX 插件"
  │
  ├─ ① 四重安全检查
  │     ├─ 版本兼容   peer 要求的 @deepseek-ai/* (minor,patch,rc) ≤ 当前 DSH
  │     ├─ patch 冲突  cordis.patch.yml insert id 不与核心/已装插件重复
  │     ├─ 工具名冲突  注册工具名不与已装插件/内置工具重复
  │     └─ 供应链     npm 已发布 + 维护活跃(<30天) + license 清晰
  │        └─ 有 block? → 拒绝安装,返回报告
  │
  ├─ ② 打快照(undo CLI,失败不阻断)
  ├─ ③ dsh plugin --profile web add <pkg>
  │     └─ 失败 → 返回错误
  ├─ ④ 验证入列(读 profile package.json bundles)
  ├─ ⑤ 自动重启(restart=true 时)
  │     ├─ spawn 独立辅助进程(detached + unref)
  │     ├─ 原进程延迟退出(留时间 flush 工具结果)
  │     └─ 辅助进程等端口释放后拉起新 DSH
  └─ ⑥ 返回报告:检查结果 + 安装结果 + 重启状态

注册工具 (Tools)

工具名	功能	参数
`safe_install_check`	只做四重安全检查,返回通过/警告/阻断报告	`{ pkg, source? }`
`safe_install`	检查 → 通过则安装 → (可选)自动重启	`{ pkg, source?, restart? }`
`safe_install_status`	查询上次检查/安装/重启状态与历史	`{}`

pkg — npm 包名,如 dsh-startup-guard
source — GitHub 源(推荐,提供后 patch/工具名检查才完整),如 github:lire1131/dsh-undo-savepoint#master

四重安全检查 (Four Checks)

#	检查	数据源	判定
①	版本兼容:插件 `peerDependencies` 中 `@deepseek-ai/*` 的要求 `(minor, patch, rc)` 必须 ≤ 当前 DSH(本机 `0.1.0-rc.8`)	npm registry / GitHub raw `package.json`	超则 block
②	patch 冲突:`cordis.patch.yml` 的 insert id 不得与核心保留 id(`storage` / `storage-json` / `storage-domain` 等)或已装插件重复 —— 防 `duplicate loader entry id` 崩溃	GitHub raw `cordis.patch.yml` + 本地扫描	重复则 block
③	工具名冲突:注册的工具名不得与已装插件/内置工具重复 —— 防工具名冲突崩溃	GitHub raw `lib/index.js` + 本地扫描	冲突则 block
④	供应链:npm 有正式发布 + 维护活跃(`pushed_at` < 30 天) + license 清晰(MIT/Apache/BSD/ISC 等)	npm registry + GitHub API	不满足则 warn

⚠️ 未提供 source 时 ②③ 无法检查,返回 warn(不阻断)。建议总是提供 GitHub 源以获得完整检查。

架构 (Architecture)

dsh-safe-install/
├── package.json          # 插件声明(dsh.bundle.patch)
├── cordis.patch.yml      # 挂载条目(insert id: safe-install,唯一)
├── lib/
│   ├── index.js          # 入口:注册 3 工具 + 事件监听 + 轮询
│   ├── env.js            # 环境事实(profile 路径 / rc 探测 / 已知工具名清单)
│   ├── net.js            # 网络封装(Node https + TLS 绕过 + 自动重试)
│   ├── check.js          # 四重检查汇总(并行执行)
│   ├── checkVersion.js   # ① 版本兼容
│   ├── checkPatch.js     # ② patch 冲突
│   ├── checkTools.js     # ③ 工具名冲突
│   ├── checkSupply.js    # ④ 供应链
│   ├── install.js        # 安装执行(快照 + dsh plugin add + 验证入列)
│   ├── restart.js        # 自动重启(Node detached spawn)
│   ├── detect.js         # 轮询 profile package.json bundles
│   └── state.js          # 状态记录(内存 + 磁盘)
└── tests/
    ├── run-tests.mjs     # 离线单元测试(纯函数,无需网络)
    └── integration.mjs   # 真机集成测试(真实 npm/GitHub 数据)

快速开始 (Quick Start)

安装

# 从 GitHub 安装
dsh plugin --profile web add github:goodaiaiai/dsh-safe-install#master

# 或本地源码安装
dsh plugin --profile web add <本目录路径>

# 安装后重启 DSH 生效(或让 AI 用 safe_install 装,它自己会重启)

在对话中使用

safe_install_check { pkg: "dsh-startup-guard" }                          # 只检查
safe_install { pkg: "dsh-better-sidebar", source: "github:omdsh-dev/DSH-better-sidebar" }  # 检查+安装(默认自动重启)
safe_install_status                                                       # 查状态

⚠️ safe_install 默认 restart: true,会重启 DSH 进程(响应返回后约 2.5s 退出,辅助进程 3s 后拉起新进程)。测试完整流程前确保有恢复手段。

开发与测试 (Development)

# 单元测试(离线,无需网络):覆盖 rc 判定 / patch 提取 / 工具名 / license
node tests\run-tests.mjs

# 集成测试(需要网络):对真实插件执行四重检查,验证判定
node tests\integration.mjs

当前测试状态:

单元测试 33/33 通过(含 rc.6/rc.8/rc.9、跨 patch 0.1.1-rc.1、跨 minor 0.2.0-rc.3、storage 冲突 patch、undo_* 工具名冲突、license 判定)
集成测试 4/4 通过(dsh-startup-guard 放行 / 已装插件防重复安装阻断 / dsh-better-sidebar 0.16.1 版本兼容 / dsh-plugin-notify 放行)
安全用例:未知供应链包 → warn 不阻断

兼容性 (Compatibility)

项	值
DSH	0.1.0-rc.8(peer 要求 ≤ 当前 rc;跨 minor/patch 系列会被拦截)
profile	`web`(GUI http://127.0.0.1:3080)
Node	≥ 18(使用 `node:https`、`node:child_process`)
依赖	仅 `@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`(peer)

其他 rc 版本可通过环境变量 DSH_VERSION / DSH_RC 覆盖探测结果(调试用)。

已知限制 (Limitations)

②③ 检查依赖 GitHub 源;npm 包在未下载时无法读取其 patch/源码内容
工具名清单为内置快照 + 启动时扫描已装插件,新装插件后需重启刷新
dsh plugin add 在 workspace-write 沙箱下可能 EPERM(临时文件权限),需 danger-full-access
版本检查覆盖 (minor, patch, rc) 三元组;核心模块缺失(如 dsh-client-ui-slots)属运行时依赖完整性,不在本插件检查范围(建议配合 dsh-startup-guard)

安全说明 (Security)

插件运行在你的 DSH 进程中,只安装通过四重检查的插件
安装前自动打快照,改错了随时可回退(dsh-undo-savepoint)
Node 访问网络内置 NODE_TLS_REJECT_UNAUTHORIZED=0(本机 CA 链不完整);网络请求带重试(2 次)+ 20s 超时

贡献 (Contributing)

Fork 本仓库
新增/修改后运行 node tests\run-tests.mjs 与 node tests\integration.mjs
提交 PR,说明改动与测试结果

License

MIT

dsh-safe-install

Install

Source

Tags

Creators

Readme

dsh-safe-install

功能特性 (Features)

工作流程 (Flow)

注册工具 (Tools)

四重安全检查 (Four Checks)

架构 (Architecture)

快速开始 (Quick Start)

安装

在对话中使用

开发与测试 (Development)

兼容性 (Compatibility)

已知限制 (Limitations)

安全说明 (Security)

贡献 (Contributing)

License