Cookbook：创建 registry 插件

August 10, 2026 · View on GitHub

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

目标：从零产出一个可安装、可启用的 registry 插件。前置：DSH 源码环境已集成 plugin-registry（见集成到 dsh），dsh registry 命令可用。

1. 脚手架

dsh registry create acme/cool-tool

在 ./cool-tool 生成三个文件：

文件	内容
`dsh.plugin.json`	清单（完整字段定义见 manifest-format）：`id`（`publisher/name`）、`version`、`main`、`engines.dsh`、`contributes`
`index.mjs`	Cordis 插件入口（空 `apply(ctx)`）
`README.md`	一句话说明 + 安装启用命令

清单经过与安装相同的解析器校验，所以脚手架产物保证可安装（直到你编辑它）。

2. 写入口

index.mjs 导出 Cordis 插件：函数、类或带 apply(ctx) 的对象。通过 ctx 服务注册能力。最小工具示例：

import { defineTool } from '@deepseek-ai/dsh-tools'

export default {
  name: 'cool-tool',
  inject: ['tools'],               // 等待官方树 tools 服务就绪
  apply(ctx) {
    ctx.tools.register(defineTool({
      name: 'cool_tool',
      description: 'What it does.',
      parameters: { /* JSON Schema */ },
      output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
      execute: async (args) => 'result',
    }))
  },
}

其他能力面：ctx.on() 事件、ctx.provide() 新服务、ctx.commands 命令、ctx.systemPrompt、ctx.tui 覆盖层。能力上限是完整 Cordis，不是 contributes 声明（见 architecture.md）。

依赖解析：入口可 import 官方包（@deepseek-ai/*、cordis）及 checkout 依赖闭包内的任意包——registry 在 <dshHome>/plugins/node_modules 维护指向 checkout 的共享链接（安装/挂载时自动确保，built 形态也成立）。插件不能声明自己的 npm 依赖（dsh.plugin.json 无 dependencies 字段），可用依赖 = checkout 的依赖闭包（见 architecture.md）。

3. 同步 contributes

dsh.plugin.json 的 contributes.tools 必须与入口实际注册的工具逐名一致：每个声明的必须注册，每个注册的必须声明。这是清单契约——启用时校验，缺失即报错回滚（architecture.md）。

{ "contributes": { "tools": ["cool_tool"], "skills": [] } }

4. 安装、启用、验证

dsh registry install ./cool-tool        # 安装（默认禁用——信任边界）
dsh registry enable acme/cool-tool      # 启用（实时挂载）
dsh registry list                       # 验证：enabled acme/cool-tool@0.1.0

验证点：dsh registry list 显示 enabled 且版本正确；若启用失败，报错列出声明但未注册的工具。

验证边界：enable 只校验 contributes 名称与 manifest；工具 schema（value-schema DSL）与挂载错误只在 web 重启时暴露——验证循环必须包含一次 web 重启并确认日志无 plugin tree failed to load（实例：输出 schema 的 required 数组通过 enable 却在 web boot 崩溃）。

带 client half 的生效边界：enable 是服务端实时（plugin.list 立即可见），但浏览器端有进程边界——dsh registry enable 在 CLI 进程注册 client bundle，已运行的 web 不感知，需重启 web；在 Web 面板里点启用则是同进程，刷新页面即可（__DSH_BOOT__ 在页面加载时固定，运行时新增的 bundle 不进已加载页面）。开发期 HMR 只对已在图内的 bundle 生效，新增 bundle 仍需刷新。

5. 开发-验证循环

dsh registry disable acme/cool-tool && dsh registry enable acme/cool-tool   # 改完重挂载
dsh registry uninstall acme/cool-tool                                     # 卸载

参考

完整可安装示例：examples/greeter（清单 + 入口 + README）
Agent Skill make-dsh-plugin：同一流程的 agent 指导版，含常见坑
分发：见分发插件