前言¶
DSH 理念是「一切皆插件」。在開發智能體時，開發者常依賴本地插件來擴展功能，這些插件往往包含自定義的依賴和鏈接配置。在更換電腦或重裝系統時，僅僅複製設置文件往往無法恢復完整的開發環境，因爲本地插件及其依賴關係容易丟失。
這個插件解決了上述痛點。它提供了一套完整的備份與恢復機制，能夠將設置、憑據、技能、預設以及本地插件打包成 ZIP 文件。在需要時，可以將環境還原回原來的目錄結構。
功能與特性¶
插件的主要功能圍繞「發現」、「打包」和「還原」展開：
- 發現本地插件：插件不僅讀取 profile 的
package.json依賴，還會掃描node_modules軟鏈接/junction，以及dsh.profile.bundles指向本地的 bundle，生成完整清單。 - 勾選打包：發現插件後會列出清單，支持複選框勾選和「全選」操作，界面會實時顯示發現數量、可打包數量和已勾選數量。
- 插件是一等公民：每個本地插件連同其生產運行依賴都會被打包進歸檔中，manifest 會記錄完整的鏈接拓撲。
- 還原回原位置：還原時優先恢復到備份記錄中的原始絕對目錄；若原目錄不存在，則自動落點到
$DSH_HOME/plugins/<插件名>，並同步改寫 profile 的聲明與鏈接。 - 補齊聲明：對只存在於
node_modules但未聲明的插件，還原時會自動補寫link:依賴，防止下次安裝時被刪除。 - 逐項校驗：還原完成後，會對目錄、入口文件和 profile 鏈接進行校驗，結果直接反饋在設置頁面。
- 恢復可逆：任何一次恢復操作前，都會自動打一份快照，因此恢復過程本身是可撤銷的。
- 不覆蓋更新的內容：系統基於文件系統時間判斷，如果目標文件比歸檔新且內容不同，則跳過並保留原文件。
- 大備份可靠下載：採用 4MB 分塊下載機制，避免因單次響應體過大導致的下載失敗。
- 備份記錄列表：所有備份文件會列在設置頁，支持直接恢復或刪除。
安裝與啓用¶
通過命令行安裝：
dsh plugin --profile desktop add github:hello-heyongping/dsh-helloai-bak
安裝完成後，進入 設置 頁面即可看到「備份與恢復」選項。
使用方法¶
備份
- 打開 設置 → 備份與恢復；
- 在「本地插件」清單中勾選需要打包的插件（默認會勾選可打包項）；
- 點擊 「備份全部配置」，生成 ZIP 文件並下載；
- 備份文件默認保存在
$DSH_HOME/backups目錄，同時出現在下方的「備份記錄」中。
恢復
- 在「備份記錄」中找到對應的備份點，點擊 「恢復」；或者在換電腦時點擊 「從 ZIP 恢復」 手動選擇文件；
- 恢復前系統會自動打快照，確保可逆；
- 恢復完成後，界面會逐項列出每個插件的結果（如已恢復、已保留、未備份、失敗等）。
注意事項¶
- 敏感信息：備份文件包含
.credentials.yaml等敏感憑據，請僅在可信渠道保存和傳輸。 - 覆蓋規則：恢復是整體覆蓋，但會優先保留比備份更新的文件。若需強制覆蓋，界面會提供相應按鈕。
- 無作用域選擇：恢復操作沒有作用域選擇，設置、憑據、技能、預設和插件會一起恢復。若只想恢復部分內容，需在恢復後手工回退。
- 目錄位置：備份目錄固定在
$DSH_HOME/backups，暫不可配置。 - ZIP 限制：採用經典 ZIP 格式，條目上限爲 65535。
- 懸空鏈接：如果
node_modules中的鏈接指向的目錄已被刪除，無法打包，只能在清單中報告。
總結¶
該插件通過將本地插件視爲一等公民，解決了 DSH 環境遷移時的配置丟失問題。配合快照機制和不覆蓋更新策略，提供了可靠且安全的備份體驗。
