DSH 插件安装教程

DSH 插件的安装主要有两种方式：从 npm 包安装和从 GitHub 仓库安装。两种方式的核心命令模板一致：

dsh plugin --profile <profile名称> add <插件来源>

关于命令前缀：本教程所有命令以全局安装的 dsh 为准。npx 安装只需加前缀 npx @deepseek-ai/dsh；源码安装使用 pnpm exec dsh，并且需要先 cd 到你的 dsh 源码目录。三种方式安装的插件最终都存放在同一个数据目录 ~/.dsh 中，由 DSH 自动识别和加载。

关于 --profile：

  • 网页端填 web（大多数用户使用这个）
  • 桌面端填 desktop

两者 profile 独立，插件不互通。如果两端都想用同一个插件，需要分别为两个 profile 各安装一次。

建议：如果你还没有安装任何插件，可以先安装一个插件市场（见下文第一部分）。这样之后就能在 DSH 界面里直接浏览、搜索和一键安装其他插件，比手动查包名或 GitHub 地址方便得多。

一、插件市场（推荐先装）

插件市场本质上也是一个 DSH 插件。安装后，它会在 Web UI 的 设置 → 插件 里增加一个“插件市场”或 “Plugin Market” 的 Tab，让你可以直接在 DSH 界面内浏览、搜索、一键安装社区插件。

推荐安装：dsh-market

dsh-market 是目前社区最主流、功能最完整的插件市场，被多个来源列为插件市场的首选入口。它持续收录 2300+ 插件且每日增长，支持中文搜索、分类过滤、星级排序、插件截图预览和评论区讨论。除此之外，它还提供主题一键安装与切换、配置备份还原（支持 WebDAV 和 GitHub Gist 同步）、插件更新检查、热禁用/启用等实用功能，且多数插件安装后刷新页面即可生效，无需重启。

安装命令：

# 全局安装的 dsh
dsh plugin --profile web add dshmarket

# npx 安装
npx @deepseek-ai/dsh plugin --profile web add dshmarket

# 源码安装（先 cd 到你的 dsh 源码目录）
pnpm exec dsh plugin --profile web add dshmarket

安装后操作：重启 dsh web，打开 设置 → 插件市场，即可浏览和搜索社区插件。

版本要求：dsh-market 需要 dsh web 0.1.0-rc.6 或更新版本。版本不足时市场会自我禁用，并在浏览器控制台输出提示。

其他插件市场（简要说明）

社区中还有几个功能类似的插件市场，侧重点各有不同：

  • chnjames/dsh-plugin-market：安装走官方 dsh plugin add/remove，不执行第三方脚本，另有公开目录站可浏览和复制安装命令。
  • ouyangyipeng/dsh-marketplace：实时抓取 GitHub topic:dsh-plugin 仓库，安装时使用 pnpm add --ignore-scripts 暂存。
  • @nanmicoder/dsh-plugin-market：经过验证的目录，收录 3500+ 条目，一键安装前会检查包格式和构建就绪状态。
  • dsh-plugin-hub（dshplugin）：内置在“插件中心”，收录 4000+ 人工精选插件，无需构建脚本授权。

以上市场在功能上与 dsh-market 有重叠，选择其中一个安装即可。对于大多数用户，直接安装 dshmarket 是最省心的选择。

有了这个插件市场对小白就比较友好，能在UI界面中安装。

如果这个插件市场已经安装好了，后面的其实可以都不用再看了，只是插件的安装方式不同而已，大部分的插件在这个插件市场都有，如果你想自己找一些自己需要的，可以看看Github的仓库有没有你需要的。这里并没有介绍本地插件的安装方式，如果想自己制作插件的话，期待我的下一个教程。

二、从 npm 包安装（推荐）

适用于已发布到 npm 的插件。这是最标准、最省心的方式。

第一步：找到包名

DSH 插件的包名通常以 dsh-、@scope/dsh- 开头，或包含 deepseek-harness 等关键词。你可以：

  • 在命令行搜索：npm search dsh-plugin
  • 安装前确认包存在：npm view <包名>

第二步：执行安装

以安装 @busabase/dsh-plugin 为例：

# 全局安装的 dsh
dsh plugin --profile web add @busabase/dsh-plugin

# npx 安装
npx @deepseek-ai/dsh plugin --profile web add @busabase/dsh-plugin

# 源码安装（先 cd 到你的 dsh 源码目录）
pnpm exec dsh plugin --profile web add @busabase/dsh-plugin

第三步：处理 allowBuilds 授权（如遇报错）

npm 安装同样可能触发 allowBuilds。如果插件依赖 node-pty、onnxruntime-node、sharp 等原生模块，pnpm 10+ 会拦截它们的构建脚本，报错 ERR_PNPM_IGNORED_BUILDS。

解决方法（推荐）：

打开 profile 目录下的 pnpm-workspace.yaml 文件：

~/.dsh/profiles/<profile名称>/pnpm-workspace.yaml

例如 Web profile 的路径是 ~/.dsh/profiles/web/pnpm-workspace.yaml。

在 allowBuilds: 下方按报错信息添加精确的包名和版本号：

allowBuilds:
  node-pty@1.1.0: true

保存后重新执行安装命令。

替代方法：使用交互式命令 dsh plugin --profile web approve-builds，它会逐个询问是否放行。注意该命令在无控制台环境会挂起，CI 场景建议用上面的 allowBuilds 写法。

⚠️ 安全提示：只放行报错点名的包和版本，不要一次性批准全部。陌生插件先看它的 install/prepare 脚本做了什么。

第四步：验证安装

dsh plugin --profile web list
# 或检查配置树
dsh --profile web --dump-config | grep <插件名>

第五步：重启 DSH

安装完成后必须重启对应 profile 的 DSH 服务，插件才会被加载。

三、从 GitHub 仓库安装

适用于市场未收录、或想装源码版的插件。前置条件是本机能访问 GitHub（网络受限时需配置代理），并且已安装 Git。

第一步：执行安装

通用模板：

dsh plugin --profile <profile名称> add github:<用户名>/<仓库名>

以 byxumi/dsh-reasoning-effort 为例：

DSH 安装方式 安装命令
npx npx @deepseek-ai/dsh plugin --profile web add github:byxumi/dsh-reasoning-effort
全局安装 dsh plugin --profile web add github:byxumi/dsh-reasoning-effort
源码安装 pnpm exec dsh plugin --profile web add github:byxumi/dsh-reasoning-effort

第二步：处理 allowBuilds 授权（大概率需要）

GitHub 安装拉取的是源码，pnpm 会尝试运行仓库中的 prepare 脚本。pnpm 10+ 默认阻止 git 依赖的构建脚本，第一次执行大概率失败。

关键区别：npm 依赖的 allowBuilds 用 包名@版本 作为 key，但 git 依赖的 key 规则不同——pnpm 可能使用精确的 commit hash 作为 key，而不是包名。

解决方法：

打开对应 profile 的 pnpm-workspace.yaml：

~/.dsh/profiles/web/pnpm-workspace.yaml

严格按终端打印的 key 原样复制，不要自己改成包名。格式示例：

allowBuilds:
  dsh-reasoning-effort:
    # 这里会被自动填入精确的 key，按报错提示原样保留

部分插件的 README 会直接给出写法，例如 dsh-reasoning-effort 的 README 提示：把 allowBuilds 里对应行结尾的 "set this to true or false" 改成 true（保持缩进、引号不变）。

保存后重新执行安装命令。

⚠️ 安全提示：allowBuilds 意味着你允许该插件的代码在安装时于本机执行构建脚本。只对你信任的插件进行授权。

第三步：固定版本（推荐）

避免每次安装都拉最新代码，可以加 commit SHA 或 tag：

# 使用 tag
dsh plugin --profile web add github:owner/repo#v1.2.3

# 使用 commit SHA
dsh plugin --profile web add github:owner/repo#<commit-sha>

例如：

dsh plugin --profile web add github:lance-kanglu/dsh-ssh-bridge#v0.4.2

注意：加 tag 后 allowBuilds 的 key 可能变化，需要按新的报错重新确认。

第四步：验证安装

dsh plugin --profile web list
# 或
dsh --profile web --dump-config

第五步：重启 DSH

安装完成后必须重启对应 profile 的 DSH 服务。

四、卸载插件

dsh plugin --profile <profile名称> remove <包名>

例如：

dsh plugin --profile web remove @busabase/dsh-plugin

五、常见问题

Q：dsh: command not found

说明没有全局安装 dsh。根据你的安装方式选择前缀：npx 用 npx @deepseek-ai/dsh，源码安装用 pnpm exec dsh（并先 cd 到源码目录）。

Q：安装成功但插件不生效

最常见的原因是没有重启 DSH。插件在 DSH 启动时加载，运行中的旧进程无法识别新安装的插件。

Q：allowBuilds 改了还是报错

检查 YAML 缩进和引号是否与报错信息完全一致。YAML 对格式敏感。对于 git 依赖，确认 key 是否是精确的 commit hash，而不是包名。

Q：Web 和 Desktop 插件不互通

两者使用独立 profile（web 和 desktop），需要分别安装。

Q：安装了插件市场，但设置里找不到“插件市场”入口？

通常是因为没有重启 dsh web，或者当前 DSH 版本过低。例如 dsh-market 要求 dsh web 0.1.0-rc.6 或更新版本，版本不足时市场会自行禁用并在浏览器控制台输出提示。建议先重启服务，若仍不显示，检查 DSH 版本并考虑升级。