跳到主内容

发布插件：npm / GitHub / tarball

三种发布渠道怎么选、bundle 自检 6 项、发布前必查与失败模式——把插件送到用户手里的完整路径。

约 9 分钟读完

读完这篇你会

  • 选对发布渠道（npm / GitHub ref / tarball）匹配你的用户场景
  • 把插件打包成 dsh.bundle 并通过 dsh plugin add 自检
  • 知道发布前要勾选哪些兼容性 / 安全检查项

适用版本

Compatible with: dsh 0.1.1-rc.2（基于官方 apps/cli/README + docs/user/develop/publish/ 整理；DSH 迭代快，发布前请核对最新文档）

三种发布渠道怎么选

DSH 的插件分发不绑定单一市场——只要在仓库里能找到代码，CLI 就能装。主流三种渠道各有取舍：

渠道命令形态适用注意点
npm 包dsh plugin add npm:@scope/name 或 npx @deepseek-ai/dsh plugin add @scope/name长期维护、版本迭代、想接 npm 生态（下载统计/依赖管理）需要打 tarball 上 registry；包名加 @scope 防撞名；体积别超 10MB（npm 默认）
GitHub refdsh plugin add github:owner/repo#v1.2.0 或 github:owner/repo#main还在频繁迭代、不想维护 npm；CI 自动 tag 友好ref 必须是 commit/tag/branch；私有仓库需配 token
tarballdsh plugin add https://example.com/path/to/plugin.tgz内部企业分发、内测版本、绕开 registryURL 必须可公网访问；自己管版本号；CDN 缓存可能让用户拿到旧版

参考实例：

  • npm 派代表：dsh plugin add npm:@liustack/modlens（详情），版本自动接 npm registry
  • GitHub ref 派代表：dsh plugin add github:ccch1mneyyy/dsh-TUI#v1.0（详情），tag 锁版本
  • 兼容层组织 dsh-plugins 走的多是 GitHub ref，方便测试期快速回滚

发布前必查 6 项

  1. bundle 声明完整：仓库根有 dsh.bundle 文件（或 cordis.patch.yml），里面 name / version / entry 三项齐全
  2. 安装命令自检：本机跑一遍 dsh plugin add github:owner/repo（用你自己的仓库），确认无报错且出现在 dsh plugin ls
  3. README 头部三句话：插件名 + 一句话价值 + 安装命令——详情页 AI 百科会从这里取
  4. dshTarget 声明：在 README 或 wiki 注明适配的 dsh 版本（Compatible with: dsh 0.1.x 即可被机审抓取）
  5. License：仓库根有 LICENSE 文件且 SPDX 标识可识别（MIT / Apache-2.0 / BSD-3-Clause 等）
  6. topic dsh-plugin：GitHub 仓库加这个 topic 才能被 awesome-dsh-plugin 列表抓取

机审 5 维证据（详情页显示的 N/5 分）就来自这 6 项的自动化判定。少一项就少一个 ✓。

失败模式

  • "command not found"：多半是 entry 字段写错路径，CLI 找不到 apply 导出
  • "bundle manifest missing"：仓库根没 dsh.bundle；CLI 退化为通用 npm 包安装，但失去 Cordis 兼容性保护
  • npm 发布后没人装：包名没加 dsh- 前缀难被发现；awesome-dsh-plugin 是当前主要发现入口，主动去 awesome-dsh-plugin 提 PR

FAQ

应该先发哪个渠道？

先用 GitHub ref，仓库稳定后再发 npm。tarball 只用于内部场景。

npm 发包后还能改 version 吗？

可以，但必须严格遵循 semver：补丁版本可静默更新，minor/major 必须让用户明确知道升级内容（GitHub Release notes 是好习惯）。

全部教程