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 registrypnpm 文档说,--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 换成镜像,比折腾代理更直接。