DSH 插件開發指南

官方文檔講清了概念，但從「讀懂」到「裝得上」之間有一段距離。 這篇是我們寫 插件測試平台 和 我們自己的插件 時的真實路徑 —— 包括踩的坑。

一、最小插件：三個文件

一個能裝進 DSH 的插件，最少需要三個文件：

my-plugin/
├── package.json        # 声明这是 dsh 插件，patch 指向哪
├── cordis.patch.yml    # 告诉 DSL 装载器插什么
└── lib/index.js        # 真正的代码

package.json

{
  "name": "dsh-my-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "lib/index.js",
  "files": ["lib", "cordis.patch.yml"],
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  },
  "engines": {
    "dsh": ">=0.2.0-rc.2"
  }
}

cordis.patch.yml

- insert:
    - id: dsh-my-plugin
      name: dsh-my-plugin

只有三行。id 是這個插件在配置樹裡的名字（要唯一）， name 是模塊名（npm 包名，或相對路徑）。

lib/index.js

export const name = "dsh-my-plugin";

export function apply(ctx) {
  console.log("hello from my plugin");
}

就這麼簡單。一個具名導出 apply 函數，Cordis 加載時會調用它， 傳入 ctx（上下文）—— 插件的所有能力都通過 ctx 註冊。

二、註冊一個工具

大部分插件做的事是給 AI 加工具。API 是 ctx.tools.register(defineTool({...}))。

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

export const inject = ["tools"];   // ← 见第三节，这行最容易漏

export function apply(ctx) {
  ctx.tools.register(defineTool({
    name: "my_lookup",
    description: "Look up something and return text.",

    parameters: {
      query: {
        type: "string",
        required: true,
        description: "What to look up.",
      },
      limit: {
        type: "number",
        description: "Max results. Defaults to 5.",
      },
    },

    output: {
      schema: {
        type: "object",
        additionalProperties: false,
        properties: {
          text: { type: "string", required: true },
        },
      },
      render: (_args, value) => [
        { type: "text", text: value.text || "" },
      ],
    },

    isConcurrencySafe: () => true,

    async execute(args, exec) {
      const res = await fetch("https://example.com/api?q=" + encodeURIComponent(args.query));
      const data = await res.json();
      return { text: JSON.stringify(data, null, 2) };
    },
  }));
}

四段結構

三、inject：最容易踩的坑（我們真的踩了）

規則

你在 apply 裡用了 ctx.某某，就必须在 inject 裡聲明它。

export const inject = ["tools", "systemPrompt"];

export function apply(ctx) {
  ctx.systemPrompt.section({       // 需要 "systemPrompt"
    name: "tool:mine",
    order: 120,
    text: "Use my_lookup when asked about X.",
  });

  ctx.tools.register(defineTool({  // 需要 "tools"
    /* ... */
  }));
}

為什麼要聲明

Cordis 會等到所有 inject 列出的服務都存在，才調用 apply。 這解決了加載順序問題 —— 你不用管誰先誰後，依賴關係決定啟動時機。

但也意味著：inject 漏寫的服務，在 apply 裡訪問會直接報錯。

常用服務

四、調試三招

① 看配置樹

dsh --profile web --dump-config | grep -A2 my-plugin

如果這裡沒有你的插件，說明 cordis.patch.yml 寫錯了，或者包名解析不到。

② 看是不是「沒激活」

啟動時如果出現 dsh: warning: 1 entry did not activate， 說明插件被掛上了但 apply 執行時報錯了。往上翻日誌找 Error。

③ 乾淨環境重裝

dsh plugin --profile web remove dsh-my-plugin
dsh plugin --profile web add ./my-plugin

很多「為什麼沒生效」是舊版本還在緩存裡。

五、engines.dsh：第二容易踩的坑

建議寫法

"engines": {
  "dsh": ">=0.2.0"
}

只寫下界，不寫上界。除非你確知未來版本會破壞兼容，否則不要封頂。

六、配置

插件可以從 patch 文件接收配置：

- insert:
    - id: dsh-my-plugin
      name: dsh-my-plugin
      config:
        endpoint: "https://example.com/api"
        limit: 5

export function apply(ctx, config) {
  const endpoint = (config && config.endpoint) || "https://default.example.com";
  const limit = (config && config.limit) || 5;
  // ...
}

永遠給默認值。用戶可能不寫 config 就裝上。

七、權限與安全

DSH 插件跑在宿主進程裡，能力很大。所以權限要寫清楚。

八、完整範例：我們的插件

我們的 dsh-deepseekbase 就是按上面寫的，而且完全開源：

它做的四件事：

• deepseekbase_price — 查 DeepSeek 價格與服務商報價
• deepseekbase_plugin — 搜插件（帶風險等級）
• deepseekbase_specs — 查模型技術參數
• deepseekbase_trend — 查 token 調用量走勢

它用我們自己的 MCP Server 作為數據源 —— 一個插件背後接一層服務，是最省事的架構。

九、寫完之後：讓別人驗證

十、官方文檔

本文是實戰補充，概念和完整 API 請看官方：

相關

插件測試結果 · 插件目錄 · MCP Server