dsh-host-plugin-registry

DSH 宿主插件:记录当前 profile 插件树中所有自定义插件,生成 JSON 清单快照。

功能

• 启动时枚举 loader 插件树,识别自定义插件(模块名不以 @deepseek-ai/、cordis: 开头者;DSH 内置 bundle 的插件全部挂在这些前缀名下)
• 每条记录:entry id、模块名、版本、来源(local/github/npm/link/unknown)、 依赖声明原文、包根路径、启用状态、运行状态、序列化配置
• 插件树变化(新增/卸载/配置更新)时自动刷新快照(默认 300ms 去抖)
• 进程退出前兜底写入一次
• 本插件自身满足"自定义插件"定义,因此也会出现在清单中(自记录)
• AI 对话引用:向 Agent 注册 plugin_registry_list 工具,对话中被问到 "当前有哪些自定义插件"或需引用插件名称/版本/来源/状态时按需调用, 实时返回与 plugins.json 快照同源的清单
• 宿主侧声明注入依赖 inject: ['tools'](与官方工具插件 dsh-tool-todo 等一致):加载器等 tools(ToolRuntime)服务就绪后才启动 本插件,保证 ctx.get('tools') 注册工具时服务已可用。tools 行由 dsh-base 组合保证提供,属硬依赖——若某部署不提供 tools 服务,本插件 apply 不会执行(快照与监听随之不生效);注册过程抛错时才降级跳过并 记录 toolRegistration.failed,不阻断快照与 Web UI 功能;插件 dispose 时回收注册,兼容 HMR/重载

Web UI

在浏览器界面 设置 → 插件 页注册"自定义插件"tab(与"插件配置"、 "插件列表"同级,排在最后):实时展示自定义插件清单——名称、版本、来源 (本地/GitHub/npm)、启用/运行状态,可展开查看 entry id、包路径、依赖声明 与配置。数据经 Host 侧 remote 服务(pluginRegistry.list())实时读取, 与 plugins.json 快照同源。

输出

默认写入 ~/.dsh/storages/plugins.json($DSH_HOME 已设置时写入 $DSH_HOME/storages/plugins.json),原子写(tmp + rename)。

{
  "generatedAt": "2026-08-15T12:00:00.000Z",
  "profile": "web",
  "dshVersion": "0.1.0-rc.6",
  "pluginCount": 3,
  "plugins": [
    {
      "id": "turn-chime",
      "name": "dsh-client-ui-turn-chime",
      "version": "0.1.0",
      "source": "local",
      "sourceSpec": "file:./plugins/dsh-client-ui-turn-chime",
      "entryPath": "C:/Users/.../.dsh/profiles/web/plugins/dsh-client-ui-turn-chime",
      "enabled": true,
      "running": true,
      "config": {}
    }
  ],
  "toolRegistration": {
    "status": "registered",
    "tool": "plugin_registry_list"
  }
}

toolRegistration 为 AI 工具注册诊断字段:插件 apply 时把注册结果随每次 快照落盘(registered/skipped/failed 及原因),复盘时直接从 plugins.json 确认注册状态,避免注册失败被 fail-soft 降级后不可观测。

配置(cordis.patch.yml 的 entry config)

字段	默认值	说明
outputFile	~/.dsh/storages/plugins.json	快照输出路径
excludePrefixes	['@deepseek-ai/', 'cordis:']	视为内置插件而排除的模块名前缀
includeConfig	true	是否记录各插件配置
debounceMs	300	插件树变化后刷新快照的去抖毫秒数

安装

在 DSH profile 目录(例如 ~/.dsh/profiles/web/)下:

1. 添加依赖:

   // package.json
   {
     "dependencies": {
       "dsh-host-plugin-registry": "github:liuyun847/dsh-host-plugin-registry"
     }
   }
   

   然后 pnpm install(或 npm install)。

2. 在 cordis.patch.yml 中注册插件行:

   - insert:
       - id: plugin-registry
         name: 'dsh-host-plugin-registry'
       - id: plugin-registry-gateway
         name: 'dsh-host-plugin-registry/gateway'
   

   其中 plugin-registry-gateway 为 Web UI 提供 remote 服务,仅需 Web 页面功能时也应注册。

3. 重启 dsh web,刷新页面后生效。

开发提示

本 profile 使用 pnpm nodeLinker: hoisted,file: 依赖会被复制到 node_modules/ 而非符号链接。修改 plugins/ 下的插件源码后,必须重新 执行 corepack pnpm install(或手动把文件复制到 node_modules/<plugin>/lib/),否则运行中的 DSH 加载的是旧副本。

新增/修改 cordis.patch.yml 后,运行中的 web 进程通过 HMR 热应用 patch; 若未生效(如插件 import 失败的历史),重启 dsh web 即可。

测试

• 客户端挂载路径回归测试(无浏览器;覆盖 inject 防死锁、$mount 挂载、 ctx.get 获取、tab 注册、list 调用):

node test/client-mount.test.mjs

• 宿主侧 AI 工具注册回归测试(无 DSH 运行时;覆盖 buildToolSnapshot 输出 结构/JSON 安全/includeConfig 开关、registerPluginListTool 工具契约与 disposer、apply 注册失败降级与 dispose 回收):

node test/register-tool.test.mjs

退出码 0 = 通过。

License

MIT