dsh 插件安装与排错:三种入口和一张症状表

核验于 2026-10-31dsh 0.2.1-rc.5版本说明

三种安装入口

  • Web UI 插件页:适合日常安装,能在页面上看见安装状态;先打开带 token 的 Web UI 地址。
  • 命令行 dsh plugin:适合在服务器上执行、写进脚本,以及需要留下安装记录的场景;本机要有 pnpm。
  • 本地路径:适合还在开发中的插件,从本地目录直接装进 profile;本机要有 pnpm。

三种入口都会把插件写进某个 profile 的依赖记录,区别只在于由谁执行安装命令。

命令行:dsh plugin add

dsh plugin 本身不实现安装,而是把参数原样转发给 profile 目录里的 pnpm,实际安装由 pnpm 执行。

dsh plugin --profile web add <package>

安装后检查:

dsh plugin --profile web list

移除:

dsh plugin --profile web remove <package>

实测问题:PATH 里必须先有 pnpm。 2026-10-31 在 Windows 上执行 dsh plugin --profile web list,因为本机没有 pnpm,命令直接失败:

'pnpm' 不是内部或外部命令,也不是可运行的程序或批处理文件。
dsh: plugin command failed; diagnostics: ...\.plugin-manager\logs\operation-...\pnpm.log

先安装 pnpm,再重新执行上面的 dsh plugin 命令。诊断信息里的 pnpm.log 会保留 pnpm 的原始输出,比 dsh 的汇总行更有用。

Web UI:插件页与发现

打开 Web UI 后,从左侧导航进入“插件”页。插件页会列出已安装的组合包,每个组合包都有独立的开关。

“发现”页默认没有索引源。官方文档写明:DSH 不内置任何索引源;要在“发现”页浏览插件,你要先打开“实验性插件”下的“自定义插件索引”,再添加索引文件 URL。

添加索引时注意:

  • URL 必须是 http: 或 https:,不能带用户名、密码或 # 片段
  • 优先 HTTPS;能修改 http: 索引内容的人,也能修改该索引列出的安装来源
  • 索引是第三方内容,安装确认框里显示的来源要你自己核对

本地路径安装(开发用)

本地开发插件时,把插件目录直接装进一个测试 profile。下面两条命令里的 ./examples/01-hello-plugin 是相对路径,要在本手册仓库 dsh-handbook 的根目录执行:

dsh plugin --profile hello add ./examples/01-hello-plugin
dsh --profile hello --dump-config

--dump-config 不需要模型 Key,能看到 profile 里是否多了你的插件。确认插件加载成功后,再从测试 profile 装进主 profile,避免污染日常环境。

报错对照表

现象原因处理
pnpm 不是内部或外部命令pnpm 未安装或不在 PATH安装 pnpm,重开终端,确认 pnpm -v
plugin command failed; diagnostics: ...pnpm 执行失败打开提示里的 pnpm.log 看原始错误
EADDRINUSE ... 3080上一个 dsh 进程还占着端口结束占用进程,或换端口
404 Not Found / ETARGET包名或版本不存在核对 npm 包名与版本范围
ETIMEDOUT / ECONNRESETregistry 或代理不可达检查网络与 registry 配置
装完不显示装进了别的 profile用 --profile 指定对,或检查 UI 当前 profile
401打开的是不带 token 的地址用启动日志里完整的 ?token= 地址

安全边界

  • 第三方插件以你的权限运行,能读工作区文件、执行命令。
  • 只装来源可信、能看懂权限要求的插件。
  • 不要为了装插件关闭沙箱或放宽审批策略。
  • 插件索引本身是第三方内容,DSH 不验证索引里的声明。