DeepSeek Harness 插件开发入门

DeepSeek Harness（简称 DSH）是 DeepSeek 官方推出的插件化 Agent Harness。官方仓库的定位是：Everything is a Plugin。

官方仓库：https://github.com/deepseek-ai/deepseek-harness

它底层使用 Cordis。工具、服务、事件、模型能力、子 Agent、工作流以及权限控制等，都可以通过插件组合进运行时。

#插件的基本形式

最简单的插件是一个 TypeScript 模块，导出 apply(ctx)：

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] loaded')
}

DSH 加载插件时会调用 apply()，插件通过 ctx 注册工具、服务、事件和其他能力。

#创建一个模型可调用的工具插件

下面创建一个 greet 工具：

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

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(
    defineTool({
      name: 'greet',
      description: '根据名字向用户打招呼。',
      parameters: {
        name: {
          type: 'string',
          required: true,
          description: '需要打招呼的人名',
        },
      },
      output: {
        schema: { type: 'string' },
        render: (_args, value) => [
          { type: 'text', text: value },
        ],
      },
      async execute(args) {
        return `你好，${args.name}！`
      },
    }),
  )
}

关键结构：

inject = ['tools']：声明依赖工具注册服务，服务就绪后再加载插件
defineTool()：定义模型可见、可调用的工具
parameters：描述并约束工具参数
execute()：执行真正的业务逻辑
output.schema：定义工具返回值的数据结构
output.render()：把返回值转换为模型能读取的内容

#项目结构

在 DeepSeek Harness 源码仓库中创建：

scratch-plugin/
├── src/
│   └── my-plugin.ts
└── cordis.yml

cordis.yml 作为 Web 配置补丁加载插件：

- insert:
    - id: greet-tool
      name: 'C:/你的绝对路径/deepseek-harness/scratch-plugin/src/my-plugin.ts'

插件文件需要使用绝对路径。Windows 路径建议使用 /。

#启动并验证

先安装源码依赖：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

带插件启动 Web UI：

pnpm dsh web --patch ./scratch-plugin/cordis.yml

打开：

http://127.0.0.1:3080

对模型说：

请使用 greet 工具向 zxb 打招呼

如果插件加载正常，模型会调用 greet，并收到 你好，zxb！。

#开发环境与注意事项

Node.js 要求为 ^22.19 或 >=24
使用 pnpm 和 TypeScript，模块体系为 ESM
执行真实模型任务需要配置 DEEPSEEK_API_KEY
单独学习 Cordis 插件机制时可以不配置 API Key
插件通过 ctx 注册的事件、工具和计时器会在卸载时自动清理
有显式资源需要释放时，使用 ctx.effect() 返回清理函数
插件加载顺序不应依赖 cordis.yml 中的排列位置；依赖关系通过 inject 声明

#可以扩展什么

DSH 插件可以扩展：

Agent 工具
LLM Provider
文件系统和 Shell
Web 搜索
Skill
子 Agent
工作流
权限与审批
生命周期钩子
Web UI 工具卡片
Agent 自我修改能力

#一句话理解

DeepSeek Harness 插件就是一个通过 apply(ctx) 接入运行时的 TypeScript 模块；普通插件通过 ctx 注册能力，工具插件再使用 defineTool() 把能力暴露给模型调用。