清单格式参考（dsh.plugin.json）

August 18, 2026 · View on GitHub

历史文档（2026-08 转向后）：本文描述 plugin-registry 已移除的独立机制（patch/CLI/ctx.plugins），仅作决策依据与演进记录保留；当前形态见 official-0809-coverage 与 packages/plugin/console。

registry 插件的定义：清单 + Cordis 入口——dsh.plugin.json 声明身份与贡献，main 指向的 Cordis 插件提供实现（apply(ctx)）。两种清单形态：原生插件（publisher/name + 自建 bundle）与官方插件增量（npm 包名 + 复用官方构建产物，见 官方插件增量兼容）。校验实现：packages/plugin/plugin/src/manifest.ts。

字段参考

字段必填默认语义
id✅—插件身份。原生：publisher/name；增量：npm 包名（@scope/name）。校验：严格两段（单斜杠）、首段非 node_modules、段内小写字母数字 + -/.、禁整段 ./..、禁 ?/#/%/控制符/大写
version✅—版本号，与 package.json 的 version 一致（增量形态）
main✅—Node half 入口（构建产物或手写 .mjs），安装时校验存在
description—''一句话说明（Web 面板展示）
engines—{ dsh: '>=0.0.1' }兼容范围；当前 harnessVersion 默认 0.0.1，实际无约束力
contributes—{ tools: [], skills: [] }声明注册面（当前仅 tools/skills）。声明即契约：声明了但入口未注册 → 启用报错回滚
client—省略浏览器 half：main（bundle 路径，安装时校验存在）、inject（图元数据，展示/预检用）、immediately（预取标记）。浏览器 fiber 的注入由 bundle 自身导出决定

最小清单（原生）

{
  "id": "acme/cool-tool",
  "version": "0.1.0",
  "main": "./index.mjs",
  "engines": { "dsh": ">=0.0.1" },
  "contributes": { "tools": ["cool_read"], "skills": [] }
}

增量清单（官方插件）

官方格式插件（npm/cordis 包）加增量清单即可进 registry，package.json/lib/ 不动：

{
  "id": "@vlln/dsh-web-terminal",
  "version": "0.1.0",
  "main": "./registry.mjs",
  "engines": { "dsh": ">=0.0.1" },
  "contributes": { "tools": [], "skills": [] },
  "client": { "main": "./lib/client.js", "inject": ["@deepseek-ai/dsh-client-runtime"] }
}

关键约束（详见 官方插件增量兼容）：

  • id = npm 包名 = bundle 内 __ModuleLoader__ id——三者一致使 client bundle 零重构建
  • client.main 指向现有 bundle；client.inject 平移 package.json 的 dshClient.inject
  • 与官方 Loader 树通道互斥：插件已在 config.yaml 启用时，registry enable 被碰撞守卫拒绝

形态对比

原生插件官方插件增量
idpublisher/namenpm 包名（@scope/name）
bundle自建（ModuleLoader id = 插件 id）复用官方构建（id = 包名）
依赖宿主依赖闭包（deps-link）同左
官方通道不适用保留（两种安装方式二选一）

相关