DeepSeek Harness（DSH）离线打包插件介绍

前言¶

DeepSeek Harness（DSH）是一个基于插件架构的开发框架。在离线环境中使用 dsh plugin add 安装插件时，由于 pnpm 需要联网解析 npm registry，通常会直接失败。dsh-plugin-offline-packager 解决了这一痛点：在联网机器上完成依赖解析、构建与打包，生成自包含的离线安装包，供离线环境使用。同时，它也支持将打包结果上传到 dsh-admin 插件市场，用于离线环境下的分发。

核心功能¶

该插件提供以下能力：

对话即打包：注册了 offline-pack 工具，在 DSH Web UI 中通过自然语言即可调用，无需记忆命令。
三种插件来源：支持 npm 包名（如 @deepseek-ai/dsh-base）、GitHub 仓库（支持分支指定）以及本地路径。
自包含离线包：通过 bundleDependencies 机制，将完整的生产依赖闭包随 tarball 携带，离线安装无需访问 registry。
peerDependencies 智能排除：由 DSH 宿主提供的 peer 依赖不打入离线包，避免与宿主实例重复或类型不兼容。
自动构建：对于 GitHub 和本地来源，插件会自动安装依赖并执行 prepare / build，构建产物直接进包。
离线元数据：生成 .meta.json 文件，记录包名、来源、打包时间、DSH 版本、打包器版本及捆绑依赖清单，便于审计。
内建安装指引：针对 pnpm ≥ 11 的供应链策略问题，附带自动生成的离线安装解决命令。
自身零依赖：插件本身经 esbuild 打包为单文件，自身安装不依赖任何运行时。
兼容性：基于 @deepseek-ai/dsh-tools@0.1.6-alpha.2、@deepseek-ai/cordis@^4.0.2 构建，兼容 DSH 0.1.6-alpha.2。

安装与启用¶

安装本插件需要满足以下前提：
* 已安装 DeepSeek Harness (DSH)，版本在 0.1.5-alpha.1 / 0.1.5-alpha.2 / 0.1.6-alpha.2 上验证。
* Node.js >= 22，npm，以及系统中有 pnpm（dsh plugin 依赖它转发）。
* 从 GitHub 来源打包时需要 git。

执行以下命令进行安装：

# 1. 进入项目目录
cd dsh-plugin-offline-packager

# 2. 安装依赖并构建
npm install

# 3. 安装到 DSH profile（以 web profile 为例）
dsh plugin --profile web add .

安装完成后重启 DSH。验证安装是否成功：

dsh --profile web --dump-config | grep offline-packager

典型用法¶

通过 AI 对话¶

在 DSH Web UI 中直接输入自然语言指令：

请将 @deepseek-ai/dsh-base 打包为离线安装包

AI 会调用 offline-pack 工具，并返回生成的文件路径及离线安装命令。

通过命令行¶

安装生成的离线包：

dsh plugin --profile web add ./deepseek-ai-dsh-base-0.1.5-alpha.2.tgz

工作原理¶

源码获取：根据来源（npm、GitHub 或本地路径）将插件源码放入临时暂存目录。
依赖与构建：在暂存目录内安装依赖并执行构建脚本（prepare / build）。
打包：安装生产依赖（排除 peer），将实际装出的顶层依赖写入 bundleDependencies，然后执行 npm pack --ignore-scripts 打包。
元数据：生成包含版本、来源等信息的 .meta.json 文件。

适用场景与注意事项¶

打包过程需要联网：离线的是安装端，打包过程仍需访问 npm registry 或 GitHub。
平台一致性：含原生二进制依赖的插件，必须在与目标离线机相同的平台（OS/arch）上进行打包，否则跨平台的 optionalDependencies 可能不可用。
peerDependencies：插件的 peerDependencies 不会被打包进离线包，目标机器需已具备对应的 DSH 宿主框架。
本地路径限制：使用本地路径打包不保证所有项目能成功，可能会因构建失败而报错。
pnpm ≥ 11 配置：目标机器若使用 pnpm ≥ 11，默认开启 minimumReleaseAge 策略，离线安装时会因无法获取元数据而失败。需在 pnpm-workspace.yaml 中设置 minimumReleaseAge: 0，或在安装命令后追加 --config.minimum-release-age=0。
Windows 路径限制：Windows 下 .tgz 所在的完整路径不能包含空格，否则 dsh plugin add 会报 ENOENT 错误。

总结¶

该插件通过在联网环境预置依赖与构建，解决了 DSH 插件在离线环境无法直接安装的难题。开发者可以生成自包含的 .tgz 包，配合内建的元数据与安装指引，在无网络环境中安全、稳定地部署插件。

插件目录
 GitHub 仓库