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 倉庫