自学教程

DeepSeek Harness 插件

DeepSeek Harness

DeepSeek Harness 第一个插件

DeepSeek Harness 最核心的架构优势就是全插件化、可逆、事件驱动。所有官方能力、社区拓展能力全部基于插件实现。普通用户使用插件，开发者可以从零开发自定义插件，实现私有工具、专属模型适配器、自定义存储、UI面板、工作流等无限拓展能力。

本文为零基础插件开发完整教程，讲解插件原理、工程结构、完整开发流程、各类插件模板、配置定义、日志调试、打包发布，是 Harness 高阶二次开发的核心文档。

一、插件开发核心原理

DeepSeek Harness 底层基于 Cordis 微内核，所有插件遵循统一规范，无特权插件、无硬编码依赖。

1. 核心机制

  • 统一入口：所有插件必须导出 apply(ctx: Context) 函数，内核加载插件时自动执行。
  • 上下文 Context：内核注入的全局能力，用于注册工具、监听事件、读取配置、打印日志。
  • 事件驱动通信：插件之间不直接调用函数，通过全局事件总线解耦协作。
  • 完全可逆：卸载插件时，所有注册的工具、监听、UI、配置自动清除，无内存残留、无副作用。

2. 插件开发技术栈

官方推荐：TypeScript（类型完整、适配内核规范），同时兼容原生 JavaScript。

二、开发环境完整搭建

1. 环境依赖

  • Node.js 22+ / 24+（官方推荐）
  • 最新版 DeepSeek Harness 内核
  • TypeScript 编译环境

2. 初始化插件工程

# 全局安装最新 Harness
npm install -g @deepseek-ai/dsh@latest
# 新建插件项目文件夹
mkdir dsh-plugin-custom-demo
cd dsh-plugin-custom-demo
npm init -y
# 安装核心开发依赖
npm install @deepseek-ai/dsh-core
npm install -D typescript @types/node

3. TS 配置文件 tsconfig.json

项目根目录新建 tsconfig.json，适配 Harness 插件编译规范：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"]
}

三、插件工程标准结构

标准 Harness 插件固定结构，所有官方/社区插件统一遵循：

dsh-plugin-demo/
├── src/
│   └── index.ts      # 插件主入口
├── dist/             # 编译产物（自动生成）
├── cordis.yml        # 插件清单（核心识别文件）
├── package.json
└── tsconfig.json

cordis.yml 插件清单详解

该文件是内核识别插件的唯一依据，必须存在：

name: dsh-plugin-demo
version: 0.1.0
description: 自定义 Harness 演示插件
main: dist/index.js
# 依赖版本约束
dependencies:
  "@deepseek-ai/dsh-core": ">=0.20.0"
# 自定义配置面板（WebUI自动生成表单）
config:
  apiKey:
    type: string
    label: 第三方密钥
    secret: true
  enableFeature:
    type: boolean
    label: 启用自定义功能
    default: true

四、最简自定义工具插件（入门必学）

实现一个可被 Agent 自动调用的自定义工具：获取当前系统时间。

src/index.ts

import { Context, defineTool } from "@deepseek-ai/dsh-core";export function apply(ctx: Context) {
  // 注册自定义工具
  ctx.tools.register(defineTool({
    name: "system_get_time",
    description: "获取当前系统时间，支持自定义时区，用于时间查询、任务计时场景",
    parameters: {
      timezone: {
        type: "string",
        required: false,
        description: "时区，默认 Asia/Shanghai"
      }
    },
    async execute(args) {
      const tz = args.timezone ?? "Asia/Shanghai";
      const now = new Date().toLocaleString("zh-CN", { timeZone: tz });
      return 【系统时间】${now};
    }
  }));
  // 读取插件自定义配置
  ctx.logger.info("插件已加载，自定义功能开关：", ctx.config.enableFeature);
}

编译插件

tsc

五、三大主流插件开发模板

1. 事件监听插件（监听系统全生命周期）

可以监听任务启动、工具执行、会话创建、模型返回等事件，实现日志统计、自动告警、任务拦截能力。

export function apply(ctx: Context) {
  // 任务开始
  ctx.on("task:start", (task) => {
    ctx.logger.info("任务开始：", task.taskId);
  });  // 单次工具调用结束
  ctx.on("tool:finish", (res) => {
    ctx.logger.info("工具执行完成：", res.toolName, res.result);
  });
  // 会话创建
  ctx.on("session:create", (sess) => {
    ctx.logger.info("新会话创建：", sess.id);
  });
}

2. 自定义模型适配器插件

用于接入私有模型、小众 VLM、本地私有化大模型，完全替换官方模型能力。

import { Context, defineModelProvider } from "@deepseek-ai/dsh-core";export function apply(ctx: Context) {
  ctx.modelProviders.register(defineModelProvider({
    id: "private-vlm",
    label: "私有多模态模型",
    capabilities: {
      inputModalities: ["text", "image"]
    },
    async chatCompletion(req) {
      return { content: "模型推理结果" };
    }
  }));
}

3. 自定义UI面板插件

可在 WebUI 新增设置页、数据看板、工具控制台，拓展前端界面能力。

export function apply(ctx: Context) {
  ctx.ui.registerPanel({
    id: "custom-dashboard",
    title: "自定义插件控制台",
    component: "./dist/ui/index.jsx"
  });
}

六、插件生命周期规范（开发必遵守）

  • 加载阶段：执行 apply，注册工具、事件、模型、UI。
  • 运行阶段：响应事件、被 Agent 调度执行。
  • 卸载阶段：内核自动销毁所有注册项，零残留。

强制规范：所有定时器、监听、网络请求必须通过 ctx 注册，禁止全局变量，否则无法自动清理。

七、插件打包与社区发布

1. 本地打包

编译完成后，dist 目录即为可运行插件产物。

2. NPM 公开发布

修改 package.json 信息后执行：

npm publish

发布后所有人可通过 dsh plugin add 一键安装。

3. 社区收录

GitHub 仓库添加话题标签：dsh-plugin，即可进入官方社区插件生态索引。

八、插件安全开发规范

  • 禁止硬编码密钥、Token、隐私信息，统一使用插件 secret 配置。
  • 所有工具执行必须参数校验，杜绝命令注入、路径遍历漏洞。
  • 禁止绕过沙箱直接读写系统文件。
  • 禁止静默上传本地用户数据。
  • 工具描述必须清晰，保证大模型可精准判断调用时机。

九、常见开发问题

  • 插件加载成功但不调用工具：工具 description 描述模糊，模型无法识别使用场景。
  • 卸载插件残留功能：存在全局定时器、原生监听，未使用 ctx 托管。
  • UI 面板不显示：前端组件打包路径错误或未编译 JSX。
  • 配置不生效：cordis.yml 配置格式错误，或未重启服务。

本篇小结

DeepSeek Harness 插件开发拥有极低的入门门槛和极高的拓展上限。开发者只需遵循 apply + Context 注册 规范，即可自由开发工具、模型、UI、事件、存储类插件，完全脱离内核源码限制，实现个性化智能体能力定制。开发完成的插件可本地自用、团队共享、开源发布，是进阶 Harness 二次开发的核心能力。

标签：

0 条笔记