dsh plugin add 怎么用？DSH plugin 安装命令、--profile 必填、目标写法与装完验证

dsh plugin add 的完整形态是 dsh plugin --profile <名字> add <目标>，三段各管一件事：dsh plugin 进入插件管理通道、--profile 指定改哪个 profile、add <目标> 就是 pnpm 的 add 动作。--profile 是必填项且没有短写，add 之后的参数会整条转发给 profile 目录里的 pnpm；装完用 dsh --profile <名字> --dump-config 就能确认插件有没有真的生效（来源）。

DSH plugin 命令概览：一条 add 拆成三段

dsh plugin --profile <name> <args...> 是 dsh 的插件管理通道，它把 --profile 之后的所有参数原样转发给该 profile 目录里的 pnpm，所以 add、remove、list 这些动词都是 pnpm 的动词（来源）。 DSH插件 与 DeepSeek插件 的安装、卸载、查看都走这条通道，先记住三段结构：

1. dsh plugin：声明「我要动某个 profile 的插件依赖」，而不是启动应用；
2. --profile <name>：指定目标 profile，对应目录 $DSH_HOME/profiles/<name>，必填且无短写；
3. add <目标>：这一段整体传给 pnpm，所以 add、remove、list、update 乃至 pnpm 自己的参数都成立。

一句话：这是「dsh 帮你把 pnpm 跑在对的目录里，并顺手维护 profile 清单」的一条命令。

dsh plugin add 的语法：--profile 必填，add 整条转发给 pnpm

--profile 是必填参数，没有简写，省略后命令非零退出；而 --profile 之后的 add <目标> 会被原样转发给 profile 目录里的 pnpm（来源）。 完整走一遍：

1. 确认目标 profile 的名字：内置的 web 与 headless 首次使用会从随包模板自动初始化，其他名字的 profile 必须由 dsh plugin 通道创建。启动 dsh web 用的就是 web 这个 profile。

2. 执行安装命令，把插件装进 web profile：

# 完整形态
dsh plugin --profile web add <包名>

# --profile 的等号写法同样成立
dsh plugin --profile=web add <包名>

3. 看命令输出：pnpm 会打印依赖解析与安装进度；如果目标写错，报错会由 pnpm 抛出，命令以非零状态退出——CLI 层面「无效命令、参数错用、配置错误、启动失败」都返回非零（来源）。

4. 观察 dsh 的后续动作：若这个包声明了 dsh.bundle，dsh 会把它追加进 profile 的组合包清单，这一步不是 pnpm 做的：

{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {
    "<包名>": "…"
  },
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "<包名>"]
    }
  }
}

首次初始化时，profile 会以 @deepseek-ai/dsh-base 作为它的第一个 bundle；此后每装一个带 dsh.bundle 的包，就按安装顺序追加一个（来源）。

一个必须知道的边界：包没声明 dsh.bundle 时依然会被装上，但只是普通依赖——dsh plugin 会打一条警告，并且不激活任何配置层。这类包是给插件当库用的，不是让用户直接启用的（来源）。

dsh plugin add 的目标写法：npm 包、GitHub 源码与本地目录

add 后面的目标决定插件从哪来：npm 包名最省事，github:owner/repo 拉的是源码要额外构建授权，本地目录与 .tgz 适合自测和内部分发。 三种照抄即可：

1. npm 包——预构建产物，零授权：

dsh plugin --profile web add <包名>

2. GitHub 源码——拉源码而非构建产物，作者要有 prepare 脚本，你还要授权构建：

# 基础写法
dsh plugin --profile web add github:owner/repo

# 建议锁 commit，防止后续推送悄悄改变实际运行的内容
dsh plugin --profile web add github:owner/repo#<sha>

第一次执行大概率失败：pnpm ≥10 默认拒绝运行 git 依赖的构建脚本，dsh 会把修法指给你——把 pnpm 打印的确切包键写进该 profile 的 pnpm-workspace.yaml：

allowBuilds:
  <包名>: true

保存后重新执行 add。这段授权等于允许该包代码在安装时于你机器上执行，只对源码可信的包放开（来源）。

3. 本地目录与 tarball——自测与内部分发：

# 本地目录（以 link 形式装进 profile，改完即时生效）
dsh plugin --profile web add ./hello-plugin

# 作者用 pnpm pack 打出的压缩包
dsh plugin --profile web add ./hello-plugin-0.1.0.tgz

三条路线的取舍与授权差异，可以对照《DeepSeek Harness 插件从哪里安装？》里的来源对比表。

装完怎么验证 DSH plugin 真的生效

dsh --profile <name> --dump-config 能在不启动应用的前提下打印组合后的配置树，插件生效时会多出一个 # == <包名> 层；再对照 profile 的 package.json，包名要同时出现在 dependencies 与 dsh.profile.bundles 才算挂上了配置层（来源）。 按顺序做四步：

1. 不启动，先看层：

dsh --profile web --dump-config | grep -n "== <包名>"

能看到 # == <包名> 这一层，说明 bundle 的 patch 已经进入组合树。

2. 看 profile 清单，确认包名在 dependencies 与 dsh.profile.bundles 两处都在：

cat ~/.dsh/profiles/web/package.json

3. 列出已装插件，确认 pnpm 侧也认得它（--profile 之后的参数转发给 pnpm，所以 list 可用）：

dsh plugin --profile web list

4. 启动应用看日志：dsh web 启动时插件加载信息会打印在终端；启动后界面里的插件面板也应出现对应条目。

顺带记住层序，排查「配置没生效」时有用：bundle 层按 dsh.profile.bundles 顺序先铺，然后是 profile 自己的 cordis.patch.yml、再是 $DSH_HOME/cordis.patch.yml，最后才是命令行 --patch 覆盖层——后面的层按行取胜，且 patch 是整块替换 config 而不是深合并（来源）。

DSH plugin add 注意事项

一句话总结：--profile 不能省、目标写法决定要不要构建授权、没声明 dsh.bundle 的包装了也不会激活。 五条提醒：

1. --profile 必填且无短写：它是定位 profile 目录的唯一依据，省略即非零退出，别指望有默认 profile 兜底；
2. 启动器参数必须在前：dsh --profile web --port 8080 里 --port 属于 web 应用；启动器只解析自己的参数，第一个它不认识的词开始就是应用的参数（来源）；
3. GitHub 源是安全决策：allowBuilds: true 等于放行安装期代码执行，务必配 #<sha> 锁版本；
4. 装了不生效先查 dsh.bundle：打了警告却没激活层，说明这是库不是插件；
5. 卸载用同一条通道：dsh plugin --profile web remove <包名> 会同时移除依赖与配置层，不会留下空壳行。

装插件嫌命令行麻烦？用 DSH Plugin Hub 一键装

上面每个坑（目标写法记不住、GitHub 源授权、装了没激活）在图形界面里都能绕开。 装好 DSH Plugin Hub 后打开设置 → 插件市场，8,000+ 个社区插件按分类浏览，卡片直接点安装、实时进度、装前有信任确认弹窗与安装命令预览；GitHub 源缺构建产物这类问题，Hub 会在装前预检拦截，不会再出现「装完重启即崩」。命令行适合脚本化和自测，日常使用与其手记参数，不如让市场替你选对通道。

来源：DeepSeek Harness 官方文档 - 打包与安装插件、dsh CLI README、deepseek-ai/deepseek-harness