前言¶
在 DeepSeek Harness（DSH）裏做插件，常見做法是把倉庫 clone 到本機、在 profile 裏掛上路徑，再在筆記本和臺式機之間用 git 手工 fetch、push、記「哪臺最後推過」。插件一多，側邊欄裏很難一眼看出是已同步、可拉取、有未提交改動，還是已經分叉。viburnum 是 dsh-works 發佈的客戶端類插件：在同一套 profile 下管理已鏈接的插件檢出，用狀態和一鍵 Sync 儘量讓兩臺機器跑同一份代碼，並自帶安裝入口與工作臺界面。社區目錄見 skillhub.cn 上的 viburnum 條目；源碼與說明以 GitHub 倉庫 爲準。
這是什麼¶
viburnum 的定位是一句 README 裏的概括：A workbench for your own DeepSeek Harness plugins: create them, mount them, choose which version runs, and keep two machines in sync. 它監視 profile 已鏈接的 clone，在需要時通過 fetch、fast-forward、rebase 或 push 對齊分支，而不替你 commit，也不 force-push。命令行入口是 vib，viburnum 與之等價。UI 文案以英文爲主；README 寫明無遙測、無獨立網絡守護進程、無賬號，外向流量僅爲對已鏈接目錄執行的 git fetch/push。
核心功能¶
側邊欄與總覽¶
側邊欄在 Plugins 上方有一行彙總：一個色點表示所有已鏈接 checkout 中最差狀態——綠色當前、紫色可拉取、橙色有未提交、紅色未推送或分叉、灰色未知——右側還有聚合的 ↑ahead ↓behind 計數。
viburnum 頁面與工作臺¶
viburnum 主列表展示各已掛載檢出：插件圖標、聲明版本、track、方向計數與目錄，並提供 Refresh、Sync all、Install、Hygiene；點某行進入該插件的工作臺詳情。詳情頁以分支爲主控件，展示 incoming changelog（Markdown）、目標/當前版本、內聯 README 與 CHANGELOG、在桌面打開目錄，以及 Update / Sync / Revert、切換 track 等操作。
每個 bundle 跟隨一條 track（例如 main 或試驗用的 dev），且 track 按機器配置，因此筆記本可以跟 dev 而辦公室機器留在 main。Update 僅是 fetch + fast-forward，不涉及 pnpm、lockfile 或 profile 編輯。
安裝入口¶
支持三種安裝方式：本機目錄（Host 原生文件夾選擇）、倉庫 URL、以及 Organisation（對配置的 GitHub owners 做可搜索分頁列表，在 git 已存 GitHub 憑證時可含私有庫；可預覽 README）。新 clone 進入 shelf（pluginsDir）；profile 已鏈接的檢出不會被移動。安裝統一走 pluginManager.installBundle。README 註明從目錄、倉庫 URL 或 GitHub organisation 安裝的能力隨 0.2 路線演進；以當前倉庫文檔爲準。
Sync 與安全邊界¶
Sync 會推送未發佈的 commit、fast-forward，或對私有分叉 rebase 後再 push；若 rebase 會改寫已發佈歷史則停止並展示兩側；衝突時 abort 並把文件交還給你。Revert 可恢復最近一次 update 或 switch 的快照。
時間線、衛生掃描與漂移¶
Timeline 記錄自上次查看以來的 incoming commits 與 viburnum 自身操作；vib log 可讀並清空。Hygiene scan（vib hygiene）報告重複檢出、未合併進 main 的本地分支、髒工作區並給出建議，不自動刪除或 checkout。
Settings → viburnum 可配刷新間隔、啓動時刷新、檢出目錄、organisation 列表及默認 org、harness 漂移警告等，寫入 profile 狀態後立即生效。
Harness-drift tracking 會在運行中的 DSH 版本相對上次發生變化時警告，並對 engines.dsh 與當前 harness 不匹配的插件逐項提示。
面向模型的工具與 CLI¶
提供五個需批准纔可執行寫操作的工具：vib_status、vib_update、vib_sync、vib_switch、vib_revert（讀操作免費）。
CLI 子命令包括：
vib status | refresh | update | sync | switch | revert | log | hygiene | install | new
支持 --json 與 --dry-run。
狀態保存在 $DSH_HOME/profiles/<profile>/.viburnum/state.json（原子寫入）；頁面通過 Host 上的 /viburnum/status 與 /viburnum/action（需 x-viburnum: 1 頭）拉取與執行操作，瀏覽器側約每 30 秒輪詢狀態路由。
安裝與啓用¶
插件須由 DSH 插件管理器裝入 profile，README 給出的示例爲本地路徑添加（請將路徑換成你的 clone 位置）：
dsh plugin --profile web add C:\Users\<you>\Documents\deepseek-harness\viburnum
若要在終端直接使用 vib，需把 CLI 鏈到 PATH（仍在插件目錄內執行）：
cd C:\Users\<you>\Documents\deepseek-harness\viburnum
npm link
package.json 要求 Node >=22，engines.dsh 爲 ^0.2.1-rc.2。許可證爲 MIT。
配置¶
在 cordis.patch.yml 中，viburnum 條目可按 id 覆蓋字段，例如：
- id: viburnum
config:
checkIntervalMinutes: 15
fetchTimeoutMs: 30000
| 字段 | 默認值 | 含義 |
|---|---|---|
checkIntervalMinutes |
5 |
後臺檢查間隔；0 表示僅在需要時檢查 |
fetchTimeoutMs |
20000 |
單次 git 進程（含 fetch）超時上限 |
catalogOwners |
['dsh-works'] |
Organisation 安裝門讀取的 GitHub owners |
pluginsDir |
'' |
新倉庫 clone 的 shelf；空則 $DSH_HOME/viburnum/plugins |
無效配置會導致插件加載失敗並指出字段與範圍。部分選項也可在 Settings → viburnum 寫入 state，優先於部署默認直至再次修改。
典型用法¶
- 用 profile 鏈接你正在開發的插件目錄（或經 viburnum 的 Install 門安裝新 bundle）。
- 打開 viburnum 頁面，看色點與
↑ahead ↓behind；在一臺機器上 commit 後，在另一臺點 Sync 或對工作臺單庫執行 Update / Sync。 - 試驗分支時用工作臺上的 track 切換；筆記本跟
dev、另一臺跟main時，每臺各自切換即可。 - 終端批量查看：
vib status；需要 JSON：vib status --json；演練不寫盤：vib sync --dry-run。 - 定期
vib hygiene查重複目錄與髒樹；版本與 harness 不匹配時留意設置裏的 drift 警告。
README 用一行示意雙機與 origin 的關係：
laptop ⇄ origin ⇄ work machine
one click: fetch → ff | rebase → push
適用場景與注意¶
適合在兩臺或以上機器上維護同一批 DSH 插件源碼、又希望界面和 CLI 統一回答「哪個 checkout 是當前？」的開發者。它也覆蓋從目錄/URL/組織安裝 bundle 與基本 hygiene，但仍是你本機 git 與 profile 鏈路的編排層，不能替代 code review 或發佈流程。
使用前請注意：插件隨當前 DSH 進程權限運行，會對你已鏈接的目錄執行 git 操作；安裝或啓用前應自行閱讀源碼與 MIT 許可證，確認 engines.dsh 與當前 harness 匹配。README 強調 viburnum 從不 commit、從不 force-push；rebase 衝突或觸及已發佈歷史時需你手工處理。DSH 生態強調「一切皆插件」；skillhub.cn 爲社區目錄，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
viburnum 把多機插件開發裏重複的 git 對齊問題收進一個工作臺：狀態色點、track 按機、一鍵 Sync，加上安裝門與 hygiene。若要查閱簡介與分類，可打開 目錄頁；實現細節、貢獻流程與 docs/PLAN.md、DESIGN.md 見 GitHub：dsh-works/viburnum。
