前言¶
DeepSeek Harness（DSH）的擴展都走插件形態；社區目錄集中在 dsh-plugin.org，條目規模在官方說明裏約兩萬條。平時要在瀏覽器裏翻目錄，再在終端裏執行 dsh plugin 裝包、改啓用狀態，上下文切換頻繁。下面介紹 dsh-plugin-harbor（維護者 Seraphoenixy，分類：客戶端）：在 DSH 側邊欄開一個整窗面板，用目錄站數據做市場瀏覽，並把已裝插件的安裝、更新、卸載、啓停與熱重載收口到同一處；變更優先經宿主 pluginManager，缺能力時回退 dsh plugin 子進程。
這是什麼¶
插件全名 dsh-plugin-harbor（包名 dsh-plugin-harbor，當前版本 0.1.0-alpha.1，MIT 許可證）。它是 DSH 客戶端插件，不替代官方應用商店——目錄數據來自社區站點 dsh-plugin.org，與 DeepSeek / 幻方無官方從屬關係。dsh-plugin.org 與 api.dsh-plugin.org 提供目錄與詳情；本插件不調用 GitHub API，也沒有遙測端點。
面板結構¶
安裝後側邊欄出現「插件港灣」圖標。面板分四個頁籤：市場、已裝、操作、設置。下面按頁籤說明已覈實的能力。
市場¶
- 目錄同步：從官網拉全量分片，內容尋址做增量；站點改版時走 sitemap 枚舉兜底，並標註 degraded，不靜默返回空目錄；失敗原因會透傳到界面。
- 瀏覽與搜索：支持搜索、11 個一級分類、4 種排序、游標分頁；列表窗口化渲染，大批量滾動時減輕卡頓。搜索側：3 字及以上走 SQLite FTS5 trigram 索引，1–2 字退回單列
LIKE。 - 外鏈與詳情：倉庫名與「詳情頁」用系統瀏覽器打開 dsh-plugin.org 上對應插件頁（按 owner + slug）；按需拉取單條詳情（精確版本、安裝命令、dshTarget），24h 緩存。
打開面板本身不自動聯網檢查更新；進入市場頁且無緩存、或用戶主動刷新目錄、檢查更新、安裝/卸載等操作時纔會出網。
已裝¶
已裝清單由 profile 清單、lockfile 與 node_modules 交叉校驗（git 形態含 commit）。更新是否可用只依據真實來源：registry 的 dist-tags.latest、git lockfile commit 對比 ls-remote、目錄 repoUpdatedAt；都拿不到則標「未判定」，不誤標「已最新」。支持啓用、停用、更新、卸載、熱重載；更新完成後自動複查並落庫。本地路徑或壓縮包形態的插件沒有遠端可比，界面會禁用「更新」，需自行改源碼構建後熱重載。
本頁還提供導出 / 導入與 Git 跨機器同步入口（規則見後文）。
操作¶
安裝、更新、卸載等變更進入隊列，可查看進度、日誌尾部並取消；跨重啓的歷史記在本插件數據目錄的目錄庫中。「進行中」按隊列順序顯示；已完成記錄按時間從新到舊。
設置¶
語言、自動刷新間隔、官網/API 基址、registry 鏡像、代理持久化在插件數據目錄。連通性診斷含站點、API、registry、git、目錄庫、熱重載六項，只讀、手動觸發。
行爲與安全口徑¶
理解這些規則有助於少踩坑：
- 確認才動：所有安裝、更新、卸載、啓停、熱重載先過確認彈窗，服務端再校驗
confirm: true；更新的安裝地址與形態由服務端從已裝事實讀取，客戶端不能傳 spec。 - 重啓與否聽宿主：桌面宿主默認加載
@deepseek-ai/dsh-hmr時，多數變更可原地生效；僅當宿主回覆需要重啓時才提示並說明原因。啓停與熱重載無子進程兜底，缺服務時報錯。 - 目錄庫旁路：寫庫失敗累加
failedWrites並標註，瀏覽與管理不因存儲故障中斷。 - 構建與生效：客戶端
client.js刷新頁面即新；宿主側index.js需重啓或 profile 重新組合；不一致時面板頂部會說明修法。 - 開發 link 安裝：從檢出目錄（
link:指向 clone）安裝時，可監視dist/自動請宿主重新組合；PLUGIN_HARBOR_HOT_RELOAD=0可關；tarball/registry 正式副本無此邏輯。首次啓用監視器仍需重啓一次 DSH。
本插件不寫 profile 的 package.json、cordis.patch.yml、pnpm-lock.yaml；變更交給宿主或子進程，配置合併經宿主 configEditor。數據落在 $DSH_HOME/profiles/<profile>/plugin-harbor/（默認 ~/.dsh），含 catalog.sqlite、settings.json、exports/、git-sync/ 等，按 profile 隔離。
安裝與啓用¶
倉庫提交自帶 dist/，安裝無需本地構建。官方示例（請將路徑換爲你本機 clone 或解壓位置）：
dsh plugin --profile desktop add "D:\path\to\dsh-plugin-harbor"
安裝後重啓 DSH 或刷新頁面，即可在側邊欄打開港灣。插件以當前 DSH 進程權限運行，安裝前宜自行覈對源碼與 MIT 許可證。Node 引擎要求 >=22.19.0（見 package.json）。
典型用法¶
在市場安裝插件¶
- 打開「市場」，必要時觸發目錄同步（首次無緩存會自動拉取）。
- 用搜索或分類縮小範圍，點條目查看按需加載的詳情（安裝命令、dshTarget 等）。
- 發起安裝並在確認彈窗中確認；進度與日誌在「操作」頁查看。
管理已裝插件¶
在「已裝」中啓用/停用、檢查更新、更新、卸載或熱重載；每項操作同樣先確認。registry/git 源拿不準更新判據時，界面會如實顯示「未判定」而非假裝已最新。
導出與導入¶
導出 JSON 到 <dataDir>/exports/<時間>-<profile>.json，含插件清單、profile 補丁行（含 config）、本插件設置，可選各插件設置文件（勾選導出，疑似憑據替換爲 [已脫敏]）。導入前在面板預檢（將安裝/將啓用/將停用/已一致/無法處理），確認後由宿主逐步執行。
三條硬限制（README 原文口徑）：
- 只增不刪：不卸載、不改 profile 的
package.json/cordis.patch.yml/pnpm-lock.yaml；重複導入冪等。 - 帶
config的補丁行：宿主無寫config接口，導入生成 YAML 片段，需人工粘貼。 - 插件設置文件只導出、不導入；未導出項寫入
omissions並說明原因。
導入源：系統文件瀏覽器、導出目錄下拉、或絕對路徑（例如從另一臺機器拷貝的文件）。
Git 跨機器同步（harbor-sync）¶
在「已裝 → 導出/導入 → Git 同步」中配置。使用獨立分支 harbor-sync，快照路徑 harbor/environments/<環境名>/snapshot.json；本地裸倉庫在 <profile>/plugin-harbor/git-sync/。可與 dsh-mnemon 共用遠端 URL，港灣不讀取 Mnemon 私有狀態。
- 填寫 HTTPS/SSH 地址或本機裸倉庫絕對路徑並保存（此步不聯網）。
- 「檢查遠端並預檢」：看待發布快照、應用計劃、版本差異與最近十次提交。
- 源機「發佈本機快照」；目標機重新檢查後「應用遠端快照」。進度在「操作」頁；缺失憑據在目標機補全。
不自動同步：預檢保留 15 分鐘，本機變化需重新檢查；發佈遇遠端變化會拒絕。link: / file: / 本地路徑與壓縮包不參與同步。認證走系統 Git 與 SSH agent 或憑據管理器，無交互失敗即報錯；建議私有倉庫，勿在 HTTPS URL 中寫憑據。
設置與排錯¶
在「設置」中改語言、刷新間隔、基址與代理；亦可用環境變量覆蓋（持久化設置優先），例如：
| 變量 | 作用 |
|---|---|
PLUGIN_HARBOR_SITE / PLUGIN_HARBOR_API / PLUGIN_HARBOR_REGISTRY |
覆蓋默認站點、API、registry |
PLUGIN_HARBOR_DSH |
子進程兜底用的 dsh 可執行文件路徑 |
DSH_HOME |
數據根，默認 ~/.dsh |
手動跑「連通性診斷」可區分站點、API、registry、git、目錄庫、熱重載哪一環異常。Git 的 url.*.insteadOf、代理與 SSH 配置會影響實際連接，以本機 Git 爲準。
適用場景與注意¶
適合：長期在 DSH 桌面 profile 上試社區插件、需要在一個面板裏搜目錄並管生命週期、或多機用 Git 快照對齊「裝了什麼、啓沒啓」（配置合併有宿主校驗與人工項）。
注意：
- 目錄與 API 依賴 dsh-plugin.org 生態，離線或鏡像需自行在設置/環境變量中配基址。
- 導入與 Git 同步遵循「只增不刪」與本地開發插件保護，不能指望同步自動卸掉目標機上多裝的包。
- 子進程兜底能完成的範圍與宿主能力不一致；熱重載與啓停依賴宿主服務。
- 當前爲
0.1.0-alpha.1早期版本，行爲以倉庫 README 與docs/爲準。
資料與鏈接¶
- 社區目錄頁：dsh-plugin-harbor @ SkillHub
- 源碼與說明：GitHub — Seraphoenixy/dsh-plugin-harbor
- 目錄數據來源：dsh-plugin.org
經過上面的步驟，若你主要工作在 DSH 側邊欄內，港灣把「逛目錄」和「管已裝」接到同一套確認隊列與宿主契約上，比單獨開瀏覽器再加終端更連貫；複雜配置與跨機一致仍要按導出/導入與 Git 同步文檔裏的硬限制操作。
