dsh-first-plugin

做出你的第一个 DSH 插件

这是一条实测跑通过的路径，不是从文档推的。下面每个报错都真实遇到过，修法也都验证过。

环境：DSH 0.1.0-rc.6，Node 20+。

先问一句：真的需要插件吗

如果你想做的事用自然语言就能说清楚（改变模型的判断标准、输出格式、工作流程），写技能，一个 Markdown 文件，五分钟搞定，也不会被上游 API 变更打挂。

只有需要注册新工具、接外部服务、挂生命周期钩子时才需要插件。

完整流程

一、装 DSH，确认能跑

npx @deepseek-ai/dsh --version

二、写插件

hello-plugin/src/hello.ts：

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

export const name = 'hello-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'pingfan_hello',
    description: '返回一句固定问候，用于验证第三方插件是否加载成功。',
    parameters: {
      who: { type: 'string', description: '要问候的对象' },
    },
    output: {
      schema: {
        type: 'object',
        additionalProperties: false,
        properties: {
          greeting: { type: 'string', required: true },
        },
      },
      render: (_args, value) => [{ type: 'text', text: value.greeting }],
    },
    execute(args) {
      const who = args.who ?? 'world'
      return Promise.resolve({ greeting: `HELLO to ${who}` })
    },
  }))
}

三、写 overlay

hello-plugin/cordis.yml：

- insert:
    - id: hello
      name: '/绝对/路径/hello-plugin/src/hello.ts'

路径必须是绝对路径。 生成方式：

cat > cordis.yml <<EOF
- insert:
    - id: hello
      name: '$(pwd)/src/hello.ts'
EOF

四、加载并验证

DEEPSEEK_API_KEY=sk-xxx npx @deepseek-ai/dsh --profile headless \
  --patch ./cordis.yml "调用 pingfan_hello 工具，参数 who 填 test"

看到工具返回的内容就说明成功了。

Web UI 同理：

npx @deepseek-ai/dsh web --patch ./cordis.yml

实测踩到的三个报错

按遇到的顺序，都是真实报错原文。

报错一：must declare output { schema, render, presentationMeta? }

tool "pingfan_hello" must declare output { schema, render, presentationMeta? }

原因：工具注册必须声明 output，里面要有 schema（返回值的结构）和 render（怎么渲染给模型看）。只写 name/description/parameters 不够。

修法：补上 output 块，见上面的完整例子。

报错二：parameters.who.required must be true when present