自学教程

DeepSeek Harness 插件发布与分发

DeepSeek Harness

DeepSeek Harness 插件发布与分发：NPM / GitHub / Tarball 全流程指南

插件写完只是第一步，可分发、可复用、可版本管理、可一键安装 才是工程化闭环。

DeepSeek Harness 官方统一支持三种插件分发形态，覆盖「公开开源、源码直装、离线交付」全场景：

  • NPM 发布：标准生产级分发，版本可控、安全、一键安装（推荐首选）
  • GitHub 直装：源码快速分享、迭代预览、开源协作场景
  • Tarball（tgz 离线包）：私有化离线部署、内网交付、无网络环境

本文带你从零完成三种发布流程、区分优劣、规避安全坑点、匹配业务场景，实现插件标准化交付。

一、发布前置：插件必须满足的官方规范

无论哪种分发方式，合法 DSH 插件/组合包必须满足以下基线规范，否则无法被 Profile 识别加载：

1. 基础包结构

  • 合法 package.json（name / version / type / main 必填）
  • TS 插件必须编译输出 lib/，禁止下发裸 ts 源码直接运行
  • 入口文件合法导出：name、apply、可选 inject、Config

2. Bundle 组合包强制规范（可自动加载插件）

如果你的包需要被 profile 自动识别、批量加载，必须在 package.json 声明：

{
  "name": "dsh-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "main": "lib/index.js",
  "dsh": {
    "bundle": {
      "plugins": ["."]
    }
  }
}

未声明 dsh.bundle 的包：只能作为依赖库，不会自动加载为插件，需要手动在 patch 注册。

3. 文件白名单

必须在 package.json 声明 files，保证打包体积干净、配置不丢失：

"files": ["lib", "index.js", "cordis.patch.yml"]

二、方式一：NPM 发布（生产首选、官方推荐）

1. 核心优势

  • 版本严格可控：语义化版本、升级回滚、锁版本部署
  • 安全最高：只执行编译后 lib 代码，不执行用户源码、不触发 prepare 编译脚本
  • 体验最好：用户一行命令安装、自动加入 profile bundle、自动热加载
  • 适配生态：公共插件、稳定能力包、正式迭代全部走 NPM

2. 完整发布流程

Step1：编译产物

pnpm build

确保 lib/ 存在、无 ts 源码、产物可独立运行。

Step2：登录 NPM

npm login

Step3：发布正式包

npm publish

3. 用户安装命令（标准）

# 安装到指定 profile，自动加入 bundles 数组
dsh plugin --profile web add dsh-my-plugin

4. 适用场景

  • 公共开源插件、通用能力 Bundle
  • 团队标准化组件、长期迭代的正式能力
  • 生产环境、私有化稳定部署

三、方式二：GitHub 直装（源码快速分享、预览迭代）

1. 原理与特点

支持直接从 Git 仓库拉取源码安装，无需先发布 NPM。适合快速分享、PR 预览、临时试用。

重大安全区别：GitHub 安装会拉取源码并 执行 prepare 编译脚本，拥有本地完整权限，不可用于不信任第三方仓库。

2. 仓库规范

  • 根目录包含完整 package.json + dsh.bundle 声明
  • 支持 main 入口、支持 build 脚本
  • 建议打 tag 版本，固定安装版本

3. 安装命令全集

# 默认拉取 main/master 分支
dsh plugin --profile web add github:username/dsh-my-plugin指定分支
dsh plugin --profile web add github:username/dsh-my-plugin#main
指定 tag 版本（推荐固定版本）
dsh plugin --profile web add github:username/dsh-my-plugin#v1.0.0

4. 优劣总结

✅ 优点：无需审核、快速分发、开源协作友好

❌ 缺点：安全性低、无版本锁、生产环境不建议长期使用

5. 适用场景

  • 插件开发完毕后的快速预览、体验测试
  • 开源项目协作、PR 验证、临时迭代版本
  • 内部可信团队快速同步未发布版本

四、方式三：Tarball tgz 离线包（私有化/内网交付）

1. 原理与特点

使用 pnpm pack 或 npm pack 打出标准 tgz 离线包，包含完整编译产物，可脱离公网、内网部署、离线交付。

安全级别等同于 NPM：只加载产物，不执行编译脚本，适合私有化交付。

2. 打包完整流程

Step1：编译

pnpm build

Step2：打出 tgz 离线包

pnpm pack

执行后生成：dsh-my-plugin-1.0.0.tgz

3. 离线安装命令

# 相对路径安装
dsh plugin --profile web add ./dsh-my-plugin-1.0.0.tgz绝对路径安装
dsh plugin --profile web add /xxx/xxx/dsh-my-plugin-1.0.0.tgz

4. 适用场景

  • 企业私有化部署、内网隔离环境
  • 无公网访问的服务器、离线机房交付
  • 固定版本封存、交付客户、版本归档

五、三种分发方式全方位对比（生产选型核心）

分发方式安全等级版本可控是否执行源码编译脚本最佳场景
NPM高（生产级）严格语义化版本否，只运行编译产物正式发布、公共插件、生产环境
GitHub低（仅可信源码）弱（依赖分支/tag）是，执行 prepare 编译快速预览、开源协作、临时测试
Tarball(tgz)高（同NPM）严格锁定版本否，直接加载产物包内网私有化、离线交付、版本封存

六、统一卸载命令（全部通用）

无论哪种方式安装，卸载命令一致：

dsh plugin --profile web remove dsh-my-plugin
标签：

0 条笔记