DeepSeek‑Harness 插件入门|从零开发你的第一个 AI 插件

DeepSeek-Harness（简称 DSH）有一句核心设计理念：一切皆插件。

大模型本身只会聊天；Harness 相当于给 AI 装上手脚，让 AI 可以调用外部能力。

Harness 内部的网页界面、工具调用、日志记录，全部都是插件实现。

我们不用修改框架本身源码，写一小段 TypeScript 代码，开发一个插件，就能给 AI 新增各种各样的本领。

插件本质：一个 TypeScript 源码文件（后缀 .ts）。

作用：给 Harness 框架新增工具能力。比如统计代码行数、对接第三方接口、自定义处理逻辑，全部靠插件实现。

形象比喻：插件就像 U 盘

Harness 框架是电脑主机主板。插件就是一个 U 盘。

• U 盘（插件）本身，存着扩展功能代码。

• 把 U 盘插到主机（Harness 加载插件），主机就获得 U 盘带来的新功能。

• U 盘内部有一个固定的启动按钮，对应代码里面的 apply 函数。

• 插上 U 盘的瞬间，主机递给你一套工具箱，就是代码里的 ctx。

重点：U 盘只是文件代码，拷贝到电脑不等于就生效，必须告诉 Harness 去读取这个 ts 文件，才算真正加载插件。

插件最小完整骨架（就一个 ts 文件）

一个最简单的插件，只需要这几块固定结构，全部写在同一个 .ts 文件里面：

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

// 1. 插件的名字（相当于 U 盘的标签） export const name = "my-plugin" 

 // 2. 固定启动入口 apply，框架自动调用这个函数 export function apply(ctx: Context) {  

 // 3. 在这里，拿 ctx 工具箱，注册新工具，写你的业务逻辑 }

两个核心名词通俗拆解

1. apply 函数

单词本意：应用、施加。相当于 U 盘上面固定的启动按键。

Harness 加载插件的时候，框架会自动执行这个 apply 函数，不需要我们手动调用。含义：把 U 盘（插件）里面的功能，施加、应用到 Harness 框架上面。

⚠️ 硬性铁则：函数名字必须严格叫 apply，拼写错，插件直接完全不工作。

2. ctx（上下文对象）

框架调用 apply 的时候，自动递交给你的万能工具箱。工具箱里面装好了框架提供的各类能力。插件开发最常用：ctx.tools.register()，用它注册自定义工具。注册完成之后，大模型、PTC 生成的脚本，都可以直接调用你写的工具。

Trajectory 轨迹视图

网页 UI 中的轨迹面板。插件工具每一次调用、入参、返回结果，全部完整记录在这里。写插件调试的时候，靠它看运行日志。

我们做一个简单插件：新增工具，用来统计一段代码的行数。

步骤 1：新建文件夹

磁盘上新建文件夹，例如命名 dsh-my-plugin。进入这个文件夹，地址栏输入 cmd 回车，打开终端。

步骤 2：创建插件源码文件

文件夹内新建文件，命名：line-count-plugin.ts

⚠️ Windows 务必打开「显示文件扩展名」，后缀必须是 .ts，不要变成 line-count-plugin.ts.txt。

复制全部代码保存：

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

 // 插件唯一标识名称 export const name = "line-count-plugin" 

 // 插件固定入口，框架加载插件自动执行 export function apply(ctx: Context) {   console.log("✅ 代码行数统计插件加载成功！")   

 // 使用 ctx 工具箱，注册自定义工具 count_code_line   

ctx.tools.register({    

 name: "count_code_line",    

 description: "统计传入代码文本的总行数",  

   parameters: {      

 type: "object",       

properties: {         

code_text: {           

type: "string",           

description: "待统计的代码字符串"        

 }     

  },       

required: ["code_text"]     },   

  async execute(args) {       

const code = args.code_text as string     

  const totalLines = code.split('\n').length       return { 

total_lines: totalLines 

}  

   }

   }) 

}

步骤 3：加载插件，启动 Harness 网页服务

终端保持在这个插件文件夹，执行命令：

npx @deepseek-ai/dsh web --patch ./line-count-plugin.ts

--patch 的作用：告诉 Harness，启动的时候额外加载我们本地写好的这个插件文件。

✅ 校验是否加载成功：看终端控制台打印 ✅ 代码行数统计插件加载成功！，代表插件已经跑起来。

⚠️ 终端窗口不能关闭，关闭服务直接停止。浏览器打开本地地址：http://127.0.0.1:3080

💡 非常重要：修改插件 ts 代码之后，刷新网页没有任何效果！必须 Ctrl+C 终止服务，完整重新执行上面这条启动命令，修改才会生效。

步骤 4：网页测试我们写的插件

1. WebUI 新建会话，工具列表会出现我们插件注册出来的工具：count_code_line。
2. 粘贴一段代码，让 AI 调用这个工具统计代码行数。
3. 打开 Trajectory 轨迹视图，可以完整查看工具调用的全部日志、参数、返回结果，用来调试插件。

看到社区不错的插件，下载代码不等于加载插件，分两种情况。

情况 1：插件已经发布为 npm 包（最省事）

别人已经打包上传，不需要手动下载任何文件。终端执行安装命令：

npx @deepseek-ai/dsh plugin --profile web add 插件包名

⚠️ 参数 --profile web，代表把插件加载到网页 UI 环境，不要漏掉，否则网页看不到插件。

安装完成，关闭旧服务，重新执行：

npx @deepseek-ai/dsh web

重启之后插件直接生效。

情况 2：GitHub 只有 ts 源码，需要 git clone 下载

1. 使用 git clone 把插件仓库克隆下载到本地文件夹。
2. 方式 A（临时调试）：启动命令用 --patch 指向插件 ts 源文件
3. npx @deepseek-ai/dsh web --patch ./克隆下来的文件夹/xxx-plugin.ts

1. 方式 B（永久加载）：把插件文件路径填写到 cordis.patch.yml 挂载清单。
2. 重启 dsh web 服务，插件生效。

💡 补充：部分复杂插件自带第三方依赖，克隆完成后，需要执行 npm install 安装依赖，否则运行报错。

1. 插件入口函数名字必须是 apply，拼写错误插件直接失效。

2. 修改插件代码，必须重启 dsh 服务，网页刷新不会更新插件。

3. Windows 系统注意文件后缀，不要生成 .ts.txt 伪 ts 文件。

4.ctx 是框架调用 apply 时自动传入的工具箱，不要自己手动去创建。

5. 插件在本地运行，不会生成外网访问地址，始终访问本地 127.0.0.1:3080。

6. clone 只是把代码拷贝到电脑，一定要通过 --patch 或者 cordis.patch.yml 告诉框架，插件才会真正加载。