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 / ECONNRESET | registry 或代理不可达 | 检查网络与 registry 配置 |
| 装完不显示 | 装进了别的 profile | 用 --profile 指定对,或检查 UI 当前 profile |
| 401 | 打开的是不带 token 的地址 | 用启动日志里完整的 ?token= 地址 |
安全边界
- 第三方插件以你的权限运行,能读工作区文件、执行命令。
- 只装来源可信、能看懂权限要求的插件。
- 不要为了装插件关闭沙箱或放宽审批策略。
- 插件索引本身是第三方内容,DSH 不验证索引里的声明。