DSH 理念強調“一切皆插件”。在管理大量 host 與 client profile 插件時，維護清單、追蹤更新、處理升級回滾以及備份遷移是常見痛點。huahua-dsh-plugin-orchestra 是一個插件管理系統，旨在提供統一的清單、更新檢測、一鍵升級、備份與回滾能力。
核心功能¶
該插件提供以下核心能力：
- 插件清單：生成並管理插件列表，支持緩存優先的摘要視圖。
- 更新檢測：檢查可用更新，支持強制刷新緩存（繞過 TTL 但保留 ETag）。
- 升級與回滾：支持指定版本升級或回滾，升級失敗時自動回滾。
- 備份管理：支持備份創建、列表查看與清理。
- 跨 Agent 遷移：支持在 agents 之間進行插件遷移。
- 面板集成：在 DSH 設置頁提供“插件管理”入口卡（含更新角標）及右上角通知中心。
安裝¶
使用 DSH CLI 安裝該插件：
dsh plugin --profile web add huahua-dsh-plugin-orchestra
本地開發安裝可使用路徑方式：
dsh plugin --profile web add file:./huahua-dsh-plugin-orchestra
命令行使用¶
安裝後可通過 CLI 或直接運行 node lib/cli/index.js 進行操作。部分非交互式命令需添加 --yes 標誌。
1. 查看清單與更新¶
查看當前插件清單（L1 用途摘要，優先使用緩存）：
node lib/cli/index.js list --json
檢查更新情況：
node lib/cli/index.js check --json
2. 升級與回滾¶
升級指定插件。--dry-run 僅演練不實際變更；--yes 跳過確認。
node lib/cli/index.js upgrade <pkg> [--to <ver>] [--dry-run] [--yes]
回滾插件到指定備份或最近的可用快照：
node lib/cli/index.js rollback <pkg> [--backup <id>] [--yes]
3. 備份管理¶
管理插件備份：
node lib/cli/index.js backup list|create <pkg>|prune <pkg> [--force]
面板使用¶
安裝插件後，DSH 設置頁面會出現“插件管理”入口卡片。通過該入口可訪問以下功能：
* 插件清單/詳情/變更日誌
* 升級、回滾操作
* 備份管理
* 全局設置
右上角會出現通知中心浮窗，用於展示更新提示。
配置與數據¶
- 數據目錄：
~/.dsh/plugin-orchestra/- 包含
config.json（配置）、cache/（緩存）、backups/（備份快照）、logs/（日誌）。
- 包含
- 環境變量：
DSH_ORCHESTRA_*系列（如DSH_ORCHESTRA_PROFILE）。GITHUB_TOKEN或GH_TOKEN：用於提升 GitHub API 限流配額（匿名狀態爲 60/h，使用 Token 可提升至 5000/h）。
退出碼說明¶
命令執行返回以下退出碼：
0：操作成功2：用法錯誤3：目標不存在4：無操作（未滿足條件）5：失敗已回滾（可重試）6：失敗需人工介入130：用戶中斷
技術細節與注意事項¶
- Node 版本：要求
^22.19.0 || >=24。 - 沙箱/CI 環境：若
node --test在沙箱中因權限問題（spawn EPERM）失敗，建議直接執行node tests/xxx.test.mjs。 - 構建與測試：
- 類型檢查：
pnpm typecheck - 構建：
pnpm build - 測試：
pnpm test（引擎側）或pnpm test:client（面板側）。
- 類型檢查：
該插件基於 MIT 許可證開源。安裝前請檢查源碼與許可證，確保符合您的安全與合規要求。
