pax-beehive/dsh-hub-cli

DSH Hub CLI – 分享與套用 DeepSeek Harness (DSH) 外掛預設

這是什麼 – 一個基於 Node 的命令列工具，可讓您擷取 DeepSeek Harness 的精確狀態（執行環境版本、有序外掛、設定修補、以及必要的環境變數），並將其發布為公開 DSH Plugin Hub 上不可變的 Preset Release。其他人可以取得該預設，並用單一指令重現相同的環境。

為什麼重要

問題	DSH Hub 解決方案
漂移 – 團隊成員手動安裝外掛，版本隨時間改變。	預設鎖定執行環境、外掛版本、載入順序和來源雜湊。
隱藏設定 – 機密資料和修補檔案散落在文件或聊天中。	只發布 `${ENV_VAR}` 佔位符；實際機密值保留在本機。
不可靠的上手 – 「在我機器上可以」的故事。	`profile apply` 暫存、驗證，並原子化替換整個設定檔，具有可逆的修訂歷史。
手動升級 – 有風險且容易出錯。	`profile diff` 顯示確切變更；`profile upgrade` 套用變更；`profile rollback` 還原先前的修訂。

核心概念

Preset Release – 一個小型、內容定址的 JSON/YAML 文件（sha256 雜湊），記錄：
- DSH 執行環境版本（@deepseek-ai/dsh）。
- 有序的 bundles（外掛）清單，包含精確的 npm 完整性雜湊或固定的 Git 提交 ID。
- 作者的 cordis.patch.yml 設定。
- 執行時所需的宣告 inputs（環境變數）。
Profile – 一個本機目錄（~/.dsh/profiles/<name>），存放目前安裝的外掛、鎖定檔和修補。
Plan – 變更（套用/升級）的預覽，包含目前狀態的指紋和到期時間（30 分鐘）。計劃必須在進行任何變更前明確批准，使 CLI 對 AI 代理安全。

主要指令（快速參考）

指令	用途
`dsh-hub profile share <slug> --version <v> --profile <name>`	擷取本機設定檔並發布不可變的預設。
`dsh-hub profile apply <slug> --version <v> --profile <name>`	取得預設、暫存、驗證，然後原子化替換本機設定檔。
`dsh-hub profile diff …`	顯示本機狀態與預設之間的逐行比較。
`dsh-hub profile upgrade …`	升級到較新的預設版本（含差異預覽）。
`dsh-hub profile rollback [revision]`	還原每次套用時自動儲存的先前修訂。
`dsh-hub profile doctor`	執行健康檢查（缺少輸入、版本漂移、鎖定檔完整性）。
`dsh-hub search / info / install`	瀏覽公開外掛目錄並安裝個別外掛。
`dsh-hub login`	透過裝置碼流程驗證 Hub（或使用 `DSH_HUB_TOKEN`）。
`dsh-hub telemetry on	off`

底層運作方式

擷取 – CLI 讀取 ~/.dsh/profiles/<profile>（外掛、順序、cordis.patch.yml、環境變數宣告），並建立 Release 文件，每個工件都有內容定址雜湊。
發布 – Release 上傳到 Hub API；雜湊保證不可變性。
套用 –
- --plan 建立 JSON 計劃，包含 Release 雜湊、目前設定檔的前置條件雜湊，以及到期時間戳。
- 使用者（或監督的人類）批准計劃 ID。
- CLI 在暫存目錄中暫存新外掛，執行結構檢查和 dsh --dump-config 以驗證修補。
- 成功後，暫存目錄原子化替換實際設定檔；先前的版本保留為修訂以供回滾。
安全檢查 –
- 任何安裝前驗證 Release 雜湊。
- 發布的修補中只允許環境變數佔位符；拒絕實際機密值。
- Token 以 0600 權限儲存；遙測可選擇退出。

典型工作流程

# 1️⃣ 全域安裝 CLI
npm i -g @dsh-plugin-hub/cli

# 2️⃣ 將目前工作區分享為預設
dsh-hub profile share my‑workspace --version 1.0.0 --profile web --dry-run   # 預覽

dsh-hub login                                                          # 一次

dsh-hub profile share my‑workspace --version 1.0.0 --profile web        # 發布

# 3️⃣ 團隊成員套用
dsh-hub profile apply my‑workspace --version 1.0.0 --profile web

dsh-hub profile doctor   # 驗證一切正常

與 AI 代理整合

此儲存庫也提供 dsh‑plugin 套件，將 CLI 暴露為 agent tools（例如 dsh_hub_profile_diff）。代理可以產生計劃、呈現給人類，並在明確確認後才執行 dsh-hub operation apply <plan-id>。此設計強制「人在迴圈」的安全屏障。

開發與擴充性

Monorepo 包含四個套件（schemas、registry、cli、dsh-plugin），全部一起版本化。
使用 Node ≥22.13 和 pnpm 建置；以 TypeScript 進行型別檢查，並透過 Node 內建測試執行器測試。
提供貢獻指南、行為準則和治理模型。
CLI 以 MIT 授權 開源。

安全與隱私重點

內容定址的版本（sha256）防止竄改。
所有外掛來源都固定（npm 完整性雜湊或完整 Git 提交 ID）。
計劃在 30 分鐘後過期，若本機設定檔變更則中止。
機密資料永遠不會離開本機；只發布變數名稱。
可選的遙測完全匿名，且可停用。

授權

MIT – 可自由使用、修改和散佈。

底線 – DSH Hub CLI 為團隊提供可重現、可稽核的方式來分享完整的 DeepSeek Harness 設定，將脆弱的「安裝這串外掛清單」流程轉變為單一指令、版本控制的操作，甚至 AI 代理也能安全呼叫。