Quophic/dsh-plugin-installer

dsh-plugin-installer

DSH 插件自动安装/卸载/重启助手：让 agent 通过模型工具完成「备份 → 安装/卸载 → 重启 → 自动继续对话」，安装或卸载失败、或操作后 dsh 启动失败时自动回滚并报告问题；也提供不含安装流程的 restart_dsh 直接重启工具。

功能

- 模型工具 install_plugin：安装持久化插件（bundle）到指定 profile。
1. 备份：安装前自动把 profile 的 package.json、cordis.patch.yml、cordis.yml、settings.yaml 备份到 $DSH_HOME/backups/plugin-install-/（含 manifest 清单）。
2. 安装：调用官方 dsh plugin --profile  add （pnpm add + bundles reconcile 同一路径）。
3. 成功 → 记录当前运行中的会话 → 自动重启 dsh → 重启完成后自动向会话注入「继续」提示词，对话无缝接续。
4. 安装命令失败 → 自动回滚备份 → 记录问题详情 → 重启 dsh → 把问题写入会话，让 agent 分析并解决。
5. 重启后 dsh 起不来（新插件破坏启动）→ 独立的 detached helper 探测端口，起不来则自动回滚备份并再次重启，随后把回滚结果写入会话。
6. 工具健康验证（端口能起来 ≠ 一切正常）：端口起来后，新进程里的本插件会审计所有已注册工具的参数 schema（要求顶层 type: 'object'）。像 parameters: {} 空对象、或把原始属性映射直接传给 ctx.tools.register（不经 defineTool 编译）这种写法，注册时不报错，但 dsh 把工具投影给 LLM 时 API 会拒绝——每次对话都报 Invalid schema for function 'X'，完全没法聊。审计发现这类损坏会自动回滚备份并再次重启，并把问题详情写入会话。

- 模型工具 uninstall_plugin：卸载已安装的持久化插件（bundle）到指定 profile。
1. 备份：卸载前自动把 profile 的 package.json、cordis.patch.yml、cordis.yml、settings.yaml 备份到 $DSH_HOME/backups/plugin-install-/（含 manifest 清单）。
2. 卸载：调用官方 dsh plugin --profile  remove  移除该插件。
3. 成功 → 记录当前运行中的会话 → 自动重启 dsh → 重启完成后自动向会话注入「继续」提示词，对话无缝接续。
4. 卸载命令失败 → 自动回滚备份并重新安装该插件（把包装回，还原卸载前状态）→ 记录问题详情 → 重启 dsh → 把问题写入会话，让 agent 分析并解决。
5. 重启后 dsh 起不来（卸载了被其他配置引用的包）→ 独立 detached helper 探测端口，起不来则自动回滚备份并重新安装该插件后再次重启，随后把回滚结果写入会话。
6. 工具健康验证：与 install 一样，端口起来后审计所有已注册工具的参数 schema；发现损坏同样回滚备份并重新安装该插件后再次重启。

- 模型工具 restart_dsh：直接重启 dsh —— 不安装/卸载/修改任何插件或配置。记录当前运行中的会话 → 以隐藏控制台方式重启（无窗口闪出）→ 重启后自动恢复当前对话。适合让新加载的插件/最新配置生效、或恢复正常进程状态的场景，但没有安装流程的备份/回滚/工具健康验证保护。同样受单次提权审批约束。

安装

dsh plugin --profile web add file:E:/GitHub/dsh-portal/dsh-plugin-installer

装完重启一次 dsh（bundle 补丁层在启动时加载）。

install_plugin 工具用法（agent / LLM）

{
"package": "dsh-xxx",            // npm 包名 / file: 路径 / git URL
"profile": "web",                // 可选，默认 web
"version": "0.1.0",              // 可选版本号
"restart": true,                 // 可选，安装后是否重启，默认 true
"delayMs": 2000                  // 可选，重启前等待（结果回传时间），默认 2000
}

uninstall_plugin 工具用法（agent / LLM）

{
"package": "dsh-xxx",            // 已安装的插件包名
"profile": "web",                // 可选，默认 web
"restart": true,                 // 可选，卸载后是否重启，默认 true
"delayMs": 2000                  // 可选，重启前等待（结果回传时间），默认 2000
}

卸载含与安装对等的保护：备份 → 卸载 →（失败/启动失败/工具损坏时回滚并重新安装该插件）→ 重启 → 自动继续对话，并把原因写入报告。

restart_dsh 工具用法（agent / LLM）

{
"profile": "web",                // 可选，默认 web（仅作记录；重启不针对单个 profile）
"delayMs": 2000                  // 可选，重启前等待（结果回传时间），默认 2000
}

restart_dsh 不会备份/安装/回滚，只做一件事：记录会话 → 隐藏控制台重启 dsh → 自动恢复对话。需要让新加载的插件或最新配置生效时使用它；需要伴随安装/更新（含备份回滚保护）时请用 install_plugin（把 restart 留默认 true）。

更新已安装的插件（含自更新）

install_plugin 对任何已安装的包（不限于本插件自己）都会自动「先卸后装」强制刷新——包括正在开发的本地 file: 插件、版本号未变的情况。日常更新开发中插件：
{
"package": "file:E:/GitHub/dsh-plugins/xxx",   // 正在开发的插件，版本号没变也没关系
"profile": "web",
"restart": true
}

更新本插件自己（self-upgrade）同理：

{
"package": "file:E:/GitHub/dsh-portal/dsh-plugin-installer",
"profile": "web",
"restart": true
}

执行流程与普通安装一致，多一步「先卸后装」：

1. 检测已安装：packageNameOf() 解析出包名（file: 读源目录的 package.json，npm 名直接解析），若发现已在 profile 依赖中，会先执行 dsh plugin remove  再 add——保证从最新源码/包重新安装。pnpm 对 file: 依赖在版本号不变时会复用陈旧副本，直接 add 不会刷新，所以必须先 remove。
2. 照常保护：备份 → 安装 → 重启 → 自动继续对话，失败同样自动回滚并报告。

注意事项：

- file: 路径用正斜杠（file:E:/...），反斜杠会被 shell 当转义吃掉导致找不到包；file: 源自带版本号，version 参数只对 npm 包名生效。
- 本地源码更新的完整流程：改 src/ → npm run build → 调用上方工具 → 重启后新逻辑生效。
- 更新操作同样受单次提权审批（非 danger-full-access 会话会请求主人批准）与 allowProfiles 白名单约束。

权限控制

- LLM 如何知道调用：插件会注入一段系统提示词（systemPrompt section），明确告诉模型「安装/升级持久化插件必须调用 install_plugin、卸载已安装插件必须调用 uninstall_plugin，不要直接跑 pnpm/dsh 命令」；工具的 description 也写明触发时机。
- 单次提权审批（默认开启）：requireApproval: true 时，若调用会话不是 danger-full-access 沙箱模式，工具不会硬拒，而是通过 approval seam（ctx.approval.request）向主人发起单次提权审批——主人批准（allowed-once）后本次调用放行，拒绝 / 取消 / 审批通道不可用则 fail closed（拒绝）。这与沙箱 bash 工具的 sandbox_permissions 升权是同一套机制。
- 配置（在 profile 的 cordis.patch.yml 本插件行上）：
- requireApproval: false — 关闭审批（任何模式都可直接调用）
- allowAuto: true — 完全放行 LLM 自动调用（跳过审批）
- allowProfiles: ['web'] — 只允许安装/卸载到这些 profile；空数组 = 不限
- 即使放行，execute 内仍有 allowProfiles 白名单二次校验。

机制说明

- 重启采用 Node 原生方式：spawn 一个 detached helper，等待旧进程退出并释放端口后，以相同 argv/cwd 重新拉起 dsh（输出追加到 %TEMP%/dsh-install-*.log）。
- 重启 helper 会轮询 web 端口（DSH_WEB_URL 或默认 3080）：若 120 秒内起不来，判定为新插件导致启动失败，自动回滚备份文件并再拉起一次。
- 工具健康验证协议：端口起来后 helper 继续等待 $DSH_HOME/dsh-install-verify.json（最多 60 秒）。新进程里的本插件在启动时读到 phase: 'installed' 的 resume marker 后，通过 ctx.tools.schemas() 枚举全部已注册工具，逐个校验 parameters 是否为顶层 type: 'object' 的合法 JSON Schema；tools/change 事件触发防抖复查 + 最多 6 次重试（覆盖加载晚的插件），把结论写入 verify 文件。ok: false → helper 判定安装损坏 → 回滚备份 → 改 marker 为 rolled-back（带审计问题详情）→ 再拉起一次；ok: true → helper 删除 resume marker 收尾。端口没起来但 verify 文件已写了 ok: false 时，回滚报告也会优先采用审计的问题详情。
- 自动继续对话：重启前把运行中的会话 id 写入 $DSH_HOME/dsh-install-resume.json；重启后插件轮询 agent 注册表，对恢复的会话注入 followup（安装成功 → 继续提示；回滚 → 问题详情 + 解决指引）。installed 态的 marker 在 helper 给出最终结论前不会被清理，保证回滚报告不丢失。
- restart: false 时不会重启、也就无法做工具健康验证（响应里会注明）；下次重启后新插件才生效。
- 所有操作写入 $DSH_HOME/dsh-install.log 便于排查。

注意

- 备份目录会累积在 $DSH_HOME/backups/ 下，可定期清理。
- 插件配置类文件（settings.yaml 等）在回滚时也会被恢复，因此安装失败不会留下半修改的配置。
- 本插件自身是 host 半区插件，不需要浏览器 UI。

许可证

MIT