前言¶
在 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。
