SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

dsh 插件源怎么换:npm 镜像、Git 源和自定义索引

dsh plugin add 很慢或装不上?先分清 npm registry、钉死提交的 Git 源和发现页索引,再按单次、profile 或整个用户切到 npmmirror,最后在 VPS 上给团队自建 HTTPS 插件索引。

dsh 插件源指的是哪一样

「dsh 插件源」在 DeepSeek Harness(下面简称 dsh)里可以指三样不同的东西,换镜像之前先分清你卡在哪一样。第一种是 npm registry,也就是 pnpm 解析 name@version 并下载包的地方。第二种是 Git 源:一个 https 仓库地址,加一个完整的 40 位十六进制提交 SHA。第三种是「发现」页的插件索引:一个 JSON 文件,只有打开实验性开关后才会用到。

dsh plugin add 很慢或报错,几乎都出在第一种上,因为 dsh plugin 自己不下载任何东西,它把参数交给 pnpm。发现页一片空白则是第三种,因为官方文档写明「DSH 不内置任何索引源」。没有人添加索引,发现页就没有内容。

本文依据 2026 年 11 月 11 日读到的 deepseek-harness 仓库 master 分支文档。当天 master 根目录 package.json 的版本号是 0.2.2-rc.2,对应 GitHub 上最新的预发布 dsh-v0.2.2-rc.2(11 月 11 日发布)。GitHub 上没有任何版本被标为 Latest。同一天查询 npm registry,@deepseek-ai/dsh 的 latest 和 next 两个 dist-tag 都指向 0.2.2-rc.1。2026 年 11 月 15 日复核时,master 根目录的版本号已是 0.2.2-rc.3,GitHub 最新预发布为 11 月 13 日发布的 dsh-v0.2.2-rc.3。版本变化很快,动手前自己查一次:

npm view @deepseek-ai/dsh dist-tags

如果连 dsh 本身都装不上,先看 dsh 安装失败和版本报错的排查。本文只讲插件。

dsh plugin 其实是在跑 pnpm

dsh plugin 的帮助文本是这样说的:管理一个 profile 的插件,方法是把剩下的参数转发给 profile 目录里的 pnpm。参数原样转发,例如 add <pkg>、remove <pkg>、why <pkg>。--profile <name> 指定 profile,第一次使用时会自动初始化。官方示例:

dsh plugin --profile tui add <package>

这意味着换插件源,就是改 pnpm 的 registry 设置。dsh 的 CLI 文档里没有出现 registry 或 .npmrc 这两个词,所以下面的规则全部来自 pnpm 自己的文档。

pnpm 文档里有几条规则直接决定结果:

  • .npmrc 文件里,pnpm 只读认证、registry、TLS(传输层安全)、代理和本地地址这几类设置。其他 pnpm 设置来自命令行、环境变量、pnpm-workspace.yaml 和全局 config.yaml。
  • 它读的 .npmrc 依次是:workspace 根目录的 .npmrc、pnpm 配置目录里的 auth.ini、用户主目录的 ~/.npmrc。同一个键出现在多个文件里时,排在前面的文件生效。
  • 命令行上的 --registry 和 --@scope:registry 优先于其他所有来源。
  • pnpm config get 从 INI 文件读取 registry 和认证设置:全局 rc 文件、auth.ini 和本地 .npmrc。

有一点要注意。pnpm 当前文档描述的是 12.x 的行为,而 dsh 文档没有说明 dsh plugin 用的是哪个版本的 pnpm。dsh 仓库的 package.json 写着 pnpm@11.28.5,但那是仓库自己开发用的版本,不代表插件命令用的版本。所以下面每一步改完,都要用命令核对,不要只看配置文件。

先查 profile 现在用的是哪个 registry

因为参数原样转发,config get 也可以通过 dsh plugin 在 profile 目录里执行:

dsh plugin --profile web config get registry

把 web 换成你的 profile 名。正常情况下它会打印一个 URL。打印 undefined 表示配置文件里没有设置这个键。写作时没有在真实 profile 里跑过这条命令,所以这里不给示例输出。你机器上看到的结果才是答案,它取决于你的机器上有哪些 .npmrc。

profile 存放在 $DSH_HOME/profiles 下,DSH_HOME 默认是 ~/.dsh。想看自己有哪些 profile:

ls "${DSH_HOME:-$HOME/.dsh}/profiles"

把插件源切到 npmmirror 的三种范围

npmmirror 首页给出的 registry 地址是 https://registry.npmmirror.com。按影响范围从小到大,有三种改法。

只改这一次安装

dsh plugin --profile web add <包名> --registry=https://registry.npmmirror.com

这个参数会原样交给 pnpm。按 pnpm 文档,命令行上的 --registry 优先于所有配置文件,所以它不受 profile 里已有 .npmrc 的影响。缺点是每次都要写。

只改一个 profile

dsh plugin --profile web config set registry https://registry.npmmirror.com --location project
dsh plugin --profile web config get registry

pnpm 文档说,--location project 会把 registry 这类设置写进 workspace 根目录的 .npmrc。不加 --location 时默认是 global,设置会写进 pnpm 的全局配置文件。第二条命令应该打印 https://registry.npmmirror.com。如果打印的还是别的地址,不用猜原因,直接退回到上面的单次 --registry 写法。

改整个用户

npm config set registry https://registry.npmmirror.com
dsh plugin --profile web config get registry

第一条是 npmmirror 首页给的命令,它写的是 npm 的用户配置 ~/.npmrc。pnpm 也读 ~/.npmrc,所以这个用户下的 npm 和 pnpm 操作都会走镜像,不只是 dsh。~/.npmrc 排在 pnpm 读取顺序的最后一位。profile 自己的 .npmrc 里如果写了 registry,会盖过它,所以第二条命令仍然要跑。想撤销,运行 npm config delete registry。

镜像跟不上:新发布的 rc 或插件装不到

npmmirror 首页的原话是「我们将尽量与官方服务实时同步」,没有给出同步间隔。我们没有找到 npmmirror 或 cnpmcore 文档说明镜像缺少某个版本时 pnpm 会报什么错,也没有复现过,所以这里不写具体错误码。判断方法很直接:向两个 registry 问同一个问题,对比结果。

npm view <包名> dist-tags --registry https://registry.npmjs.org
npm view <包名> dist-tags --registry https://registry.npmmirror.com

两边的 latest 或 next 不一样,就说明镜像还没同步到。npmmirror 首页提到可以手动触发同步(cnpm sync <包名>)。你也可以等一会儿再装,或者这一次用 --registry=https://registry.npmjs.org 直接连官方源。

还有一个容易误会的地方。发现页的卡片显示插件的推荐版本:与当前 DSH 兼容、且不是预发布版本的最高版本。只有插件没有列出任何非预发布版本时,卡片才改为显示兼容的最高预发布版本。所以一个插件已经有兼容的正式版时,后来发布的 0.2.2-rc.2 这样的 rc 不会出现在卡片上。这和镜像无关。要装 rc,就用 dsh plugin --profile web add <包名>@<版本号> 明确写出版本。

为什么有人装插件时加 --config.minimumReleaseAge=0

hu60 论坛有一篇帖子用下面这条命令从 GitCode 装插件,给出的理由是「pnpm 11 默认拒绝未满24小时的新包」:

dsh plugin --profile web add <GitCode 地址> --config.minimumReleaseAge=0

论坛帖不是一手资料,所以先看 pnpm 文档怎么写。minimumReleaseAge 的单位是分钟,当前文档写的默认值是 1440,也就是一天。它作用于直接依赖和间接依赖,但不适用于用 version+integrity 钉死的配置依赖。registry 元数据缺少 time 字段时,默认也会跳过年龄检查,由 minimumReleaseAgeIgnoreMissingTime 控制。会不会「拒绝」,取决于另一个设置 minimumReleaseAgeStrict。只有你显式配置了 minimumReleaseAge,它才默认为 true,这时找不到满足年龄要求的版本,pnpm 会让解析直接失败。只用内置默认值时它是 false,文档说 pnpm 会退回去使用一个不满足年龄要求的版本。

所以「默认拒绝」和文档的描述并不完全一致。帖子没有写 dsh 版本,也没有写用的是哪个 registry,我们无法重现它当时看到的现象。另外,pnpm 的 CLI 文档介绍了 --config.<键名> 这种命令行写法。

把这个值设成 0,关掉的是这一次安装里的包年龄检查,原本受检查的间接依赖也一起关闭。这个检查的用途,是给新发布的恶意版本留出被发现和撤下的时间。如果你确实需要立刻装一个刚发布的插件,可以权衡后这样做,但不要把它写进日常脚本。pnpm 还提供 minimumReleaseAgeExclude,按包名豁免,范围比整体关掉窄得多。

第二种插件源:钉死提交的 Git 地址

插件索引文档里,Git 版本的写法是 { type: git, url: https-url, commit: 40-hex-sha, path?: directory },DSH 按 git+<url>.git#<commit> 的形式安装。地址必须是 https,提交必须是完整的 40 位 SHA。

自己用 dsh plugin add 装 Git 插件时,可以照同样的格式写:

dsh plugin --profile web add "git+https://gitee.com/<用户>/<仓库>.git#<40位提交SHA>"

GitCode 和 Gitee 上的副本,只有在提交 SHA 和上游一致时才算镜像。dsh 文档没有提到 GitCode、Gitee 或 Git 镜像,这条规则是本文自己的要求。理由很简单:提交 SHA 一致,指向的就是同一个提交。SHA 不一致,不能据此断定代码不同或维护者不同,因为提交还包含父提交、作者和时间等信息,不同提交可以引用同一棵文件树。核对方法是对两边各跑一次 git ls-remote,看同一个 tag 对应的提交 SHA 是否相同:

git ls-remote https://github.com/<上游用户>/<仓库>.git 'refs/tags/v1.2.0' 'refs/tags/v1.2.0^{}'
git ls-remote https://gitee.com/<用户>/<仓库>.git 'refs/tags/v1.2.0' 'refs/tags/v1.2.0^{}'

附注 tag 要比较 refs/tags/v1.2.0^{} 行开头的 40 位 SHA,普通 refs/tags/v1.2.0 行给出的是 tag 对象本身的 ID。轻量 tag 没有 ^{} 行,指向提交时直接比较普通 tag 行。两边核对出的提交 SHA 相同,才按本文的要求使用副本地址,并且在安装命令里写这个提交 SHA,而不是写分支名。注意 npm 镜像对 Git 源本身不起作用,代码是从 Git 服务器拉取的。插件自己的 npm 依赖仍然走 registry,所以 registry 设置依然要配好。

第三种插件源:发现页的自定义插件索引

打开方式:进入插件,在实验性插件下找到自定义插件索引,打开开关,再添加索引地址。官方文档对索引的规定如下:

  • 每个索引源属于当前 profile。换一个 profile,要重新添加。
  • 地址必须是 http: 或 https:,不能带用户名、密码或 # 片段。文档提醒 http: 索引在不安全的网络路径上可能被篡改,建议用 https:。
  • 服务器必须直接返回 2xx 状态码,中间不能有重定向。
  • 文件是 UTF-8 编码的 JSON,默认最大 128 MiB,format 字段的值是 1。

每个版本的 source 可以是上一节的 Git 源,也可以是 npm 源。npm 源的写法:

{ "type": "npm", "registry": "https://registry.npmmirror.com/" }

registry 可以省略。文档的说法是:DSH 按 name@version 安装 npm 版本,存在 registry 时先询问它。插件管理器文档说明,registry 不可达、超时或缺少包或版本时,会按配置继续询问 fallbackRegistries;指定的 registry 不在配置集合里时只询问它,所以不要假设任意索引里的 registry 都会自动退回官方源。

几条和安全有关的行为也写在文档里。安装前总会弹出确认框,显示来源。安装时 DSH 会重新检查包自己的 engines.dsh,这是一个 SemVer 范围,表示该版本能在哪些 dsh 版本上运行,缺省表示不限。包没有声明它时,DSH 改为检查包对 @deepseek-ai/dsh* 的 peer 依赖。索引里只要有一处违反格式,整个索引都会被拒绝,并报告出错的 JSON 路径。最关键的一条是:索引内容只是发布者的说法,DSH 只检查文件格式,不检查插件本身。

社区里流传的 dshmarket 之类目录,都是第三方整理的列表,不代表 dsh 官方认可。加入一个索引之前该检查什么,见 安全安装 dsh 插件的检查步骤。哪些插件值得装,见 值得安装的 DeepSeek Harness 插件。

代理设置也会影响插件安装

dsh 的 network-proxy 指南讲的是 dsh 发出的请求:模型调用、网页搜索、网页抓取和 HTTP MCP 服务器,也说明 dsh 运行的工具会继承代理变量。指南里的要点:

  • HTTPS_PROXY 这类标准代理环境变量可以写进 $DSH_HOME/.env(默认 ~/.dsh/.env),和 API key 放在一起。shell 里 export 的变量优先。
  • dsh 不读取操作系统的代理设置。
  • 不支持 SOCKS 代理。值以 socks5:// 开头时,dsh 启动时会报告并跳过它,改为直接连接。
  • 项目自己的 .env 不能设置代理变量。

pnpm 会从 .npmrc 读取代理设置,也会读取代理环境变量。按 pnpm 当前文档,httpsProxy 未设置时先用旧的 proxy 设置,再用 HTTPS_PROXY 或 https_proxy。所以代理变量会影响通过 pnpm 安装插件的请求,不能把插件安装排除在代理设置之外。API key 和 .env 的其他写法,见 dsh 的 API key 和模型配置。

在 VPS 上给团队自建插件索引

团队里每个人各自换镜像、各自找 Git 副本,迟早会装出不同的版本。更稳的做法是在一台 VPS 上放一份团队自己的索引 JSON,通过 HTTPS 提供,并让每个 npm 版本的 registry 指向团队信任的镜像。大家在发现页添加同一个地址,看到的就是同一份经过挑选的列表。

官方提供了参考生成器 @deepseek-ai/dsh-plugin-market-generator,位于仓库的 apps/plugin-market-generator/ 目录。它是 workspace 内部的私有包,不能用 npm i 安装,要在 dsh 仓库的源码目录里运行。仓库要求 Node 24.9.0 或更高版本,并使用 pnpm,安装方法见 pnpm 安装文档。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

如果从 GitHub 克隆太慢,可以改用国内副本,但先按上一节的方法核对 SHA。

然后写插件列表。一行一个 npm 包名或 https Git 仓库地址,空行和 # 开头的注释会被忽略:

# ~/dsh-index/plugins.txt
@your-team/dsh-plugin-example
https://gitee.com/your-team/dsh-plugin-other

运行生成器。--title 必须写,--description 可选。路径用绝对路径;README 说明,相对路径以运行 pnpm 的目录为基准:

mkdir -p "$HOME/dsh-index/site"
pnpm --filter @deepseek-ai/dsh-plugin-market-generator start \
  --input "$HOME/dsh-index/plugins.txt" \
  --output "$HOME/dsh-index/site/index.json" \
  --title "团队插件索引" \
  --registry https://registry.npmmirror.com/

生成器的 README 讲清了几件事:

  • --registry 对整次运行生效,不能逐行设置。默认值是 https://registry.npmjs.org/。用其他地址时,这个地址会写进索引里每个 npm 版本,也就是 DSH 安装时先询问的那个 registry。
  • 它不使用 .npmrc 里的 registry 令牌,所以只能读公开、不需要认证的 registry。
  • 它只列出 package.json 声明了 dsh.bundle 且不是 private 的版本。对 npm 源,已弃用或私有的版本会被跳过。
  • 结果缓存在输入列表旁边的 .plugin-market-cache 目录里。

想让不同插件指向不同的 registry,只能分几次运行,或者手工编辑 JSON。README 没有介绍怎样合并多次运行的结果。还要记住:生成器从镜像读取版本列表,所以镜像落后多少,索引就落后多少。自己写插件时 dsh.bundle 怎么声明,见 自己编写 dsh 插件。

把 site/ 目录交给 VPS 上已有的 HTTPS 网站服务。关键是这个地址必须直接返回 2xx。目录末尾补斜杠、http 跳转到 https 这类重定向,都会让 DSH 拒绝这个地址。用 curl 检查:

curl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' https://plugins.example.com/index.json

健康的结果是 200,后面没有任何地址。看到 301 或 302 加一个地址,就把 dsh 里的索引地址改成跳转后的最终地址。

最后,每个成员在每个需要的 profile 里添加这个地址。索引源属于 profile,所以换 profile 要重新加一次。服务器放在境内还是境外,取决于成员在哪里,可以参考 面向中国用户的 VPS:境外还是境内。要把 dsh 本身也跑在服务器上,见 在 VPS 上运行 DeepSeek Harness。

FAQ

dsh 插件源在哪里设置?

要看你说的是哪一种。npm 包的下载源是 pnpm 的 registry,因为 dsh plugin 把参数原样转给 profile 目录里的 pnpm。可以用 --registry=https://registry.npmmirror.com 只改一次,可以用 dsh plugin --profile <名字> config set registry <地址> --location project 改一个 profile,也可以用 npm config set registry <地址> 改整个用户。Git 源直接写在安装命令里,格式是 git+https://<地址>.git#<40位SHA>。发现页的索引在 插件 → 实验性插件 → 自定义插件索引 里添加。

切换到 npmmirror 之后,dsh plugin add 为什么还走官方源?

pnpm 按顺序读取 workspace 根目录的 .npmrc、auth.ini 和 ~/.npmrc,同一个键以排在前面的文件为准,所以 profile 里的设置会盖过 ~/.npmrc。运行 dsh plugin --profile <名字> config get registry,看实际生效的是哪个地址。如果结果不对,就在安装命令末尾加 --registry=https://registry.npmmirror.com,命令行参数优先于所有配置文件。

dsh 的发现页为什么是空的?

DSH 不内置任何索引源,必须先在 插件 → 实验性插件 → 自定义插件索引 里打开开关,再添加一个索引地址。索引源属于单个 profile,换 profile 要重新添加。如果添加了还是空的,检查地址是否直接返回 2xx 而没有重定向。另外,只要有一处格式错误,DSH 会拒绝整个索引,并报告出错的 JSON 路径。

可以用 Gitee 或 GitCode 上的插件副本吗?

可以,但只在提交 SHA 和上游完全一致时才把它当作镜像。对上游和副本各运行一次 git ls-remote <仓库地址> 'refs/tags/<版本>' 'refs/tags/<版本>^{}'。附注 tag 比较 ^{} 行的提交 SHA,不能把普通 tag 行的对象 ID 当作提交 SHA;轻量 tag 指向提交时比较普通 tag 行。两边的提交 SHA 相同,再用 git+https://<副本地址>.git#<SHA> 安装。写 SHA 而不是分支名,这样副本以后被改动,你装到的仍是核对过的那份代码。

在 ~/.dsh/.env 里设置 HTTPS_PROXY 能加速插件安装吗?

能影响插件安装的连接,是否更快取决于代理和网络。dsh 的 network-proxy 指南说明它运行的工具会继承代理变量;pnpm 在没有设置 httpsProxy 和旧的 proxy 时,会使用 HTTPS_PROXY 或 https_proxy。指南还写明 dsh 不读取操作系统的代理设置,socks5:// 会被跳过,改为直接连接。pnpm 也会从 .npmrc 读取自己的代理设置。对多数国内用户来说,把 registry 换成镜像,比折腾代理更直接。

这篇文章对您有帮助吗?

#deepseek-harness#dsh#plugins#npm-mirror#pnpm#china