DeepSeek Harness 插件开发：从零到跑起来-Day18

Deepseek扩展：

第一个插件

开发一个工具

实操手册：扩展插件形态
核心思路：插件是一个通过 ctx （上下文对象）注册能力，并导出 apply 函数的 TypeScript 模块。

一、环境准备

1.1 安装 Node.js

Harness 需要 Node.js 22.19.x 或 24+（推荐 24+）。

# 检查当前 Node 版本
node --version

# 如果版本不够，去 https://nodejs.org 下载 LTS 版
# 或用 nvm 切换
nvm install 24
nvm use 24

1.2 安装 pnpm（如果用源码安装）

npm install -g pnpm

二、安装 DeepSeek Harness（两种方式）

方式 A：快速体验（5 分钟，适合先用起来）

不需要克隆仓库，直接用 npx 启动：

npx @deepseek-ai/dsh web

第一次运行会自动下载安装。启动后打开浏览器访问：

http://127.0.0.1:3080

⚠️ 但这种方式不适合开发插件 ，因为插件源码需要放在 Harness 能找到的位置。如果你想写插件，请用方式 B。

方式 B：源码安装（推荐，适合开发插件）

# 1. 克隆官方仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git

# 2. 进入目录
cd deepseek-harness

# 3. 安装依赖
pnpm install

# 4. 构建项目
pnpm run build

# 5. 启动 Web UI
pnpm dsh web

构建完成后，你的目录结构大概长这样：

deepseek-harness/           ← 你克隆的目录（这就是"项目根目录"）
├── packages/               ← Harness 自身的业务插件（core, llm, shell, tools...）
│   ├── core/
│   ├── llm/
│   ├── shell/
│   └── ...
├── vendor/                 ← Cordis 框架源码（之前讲的 vendor 方式）
│   ├── cordis/
│   ├── loader/
│   └── hmr/
├── docs/                   ← 官方文档
├── examples/               ← 示例代码
├── cordis.yml              ← 启动配置文件（关键！）
└── package.json

三、理解"插件放在哪里"

Harness 的插件有两种存在方式：

方式	说明	适合场景
内置插件	在 packages/ 目录下，随 Harness 一起构建	官方核心功能
外部插件	你自己写的 .ts 文件，通过 cordis.yml 引入	个人开发、社区插件

你写的插件属于"外部插件"，可以放在项目根目录下的任意文件夹，比如：

deepseek-harness/
├── my-plugins/             ← 你自己创建的插件目录
│   ├── hello.ts
│   └── weather.ts
├── packages/               ← 官方内置插件（别动这里）
└── cordis.yml

四、写第一个插件（真正可运行）

4.1 创建插件目录和文件

# 在项目根目录（deepseek-harness/）执行
mkdir -p my-plugins
cd my-plugins

# 创建第一个插件文件
touch hello.ts

4.2 编写插件代码

用任意编辑器打开 my-plugins/hello.ts，写入：

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

export const name = 'hello'

export function apply(ctx: Context) {
  console.log('✅ 我的第一个插件跑起来了！')
}

代码解释：

• name：插件的名字，Harness 靠这个识别你
• apply：插件的入口函数，Harness 加载插件时会调用它
• ctx：Harness 给你的"万能遥控器"，后面注册工具、监听事件都靠它

4.3 创建配置文件 cordis.yml

回到项目根目录 （deepseek-harness/），创建或修改 cordis.yml：

# 确保你在 deepseek-harness/ 目录下
cd ..

创建 cordis.yml：

- name: './my-plugins/hello.ts'

这行配置的意思 ：Harness 启动时，去 ./my-plugins/hello.ts 加载这个插件。

💡 如果你项目根目录已经有 cordis.yml，不要删掉原来的内容，在末尾追加你的插件配置即可。

4.4 运行插件

# 在项目根目录执行
node --import tsx ./vendor/cordis/bin.js

预期输出：

✅ 我的第一个插件跑起来了！

然后进程会退出（因为只有一个 console.log，没有其他任务在跑）。

五、让插件持续运行（不立即退出）

上面的例子跑完就退出了，因为插件里没有任何"持续运行"的任务。下面写一个真正在 Harness 里工作的插件------注册一个工具。

5.1 创建工具插件

mkdir -p my-plugins
cat > my-plugins/calculator.ts << 'EOF'
import type { Context } from '@deepseek-ai/cordis'

export const name = 'calculator'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.effect(() => {
    const dispose = ctx.tools.register('calculate', async (args: { expression: string }) => {
      try {
        // 注意：实际生产环境不要用 eval，这里仅演示
        const result = eval(args.expression)
        return { result, success: true }
      } catch (e) {
        return { error: '计算失败：' + (e as Error).message, success: false }
      }
    }, {
      description: '执行数学表达式计算',
      parameters: {
        type: 'object',
        properties: {
          expression: {
            type: 'string',
            description: '数学表达式，如 "1 + 2 * 3"'
          }
        },
        required: ['expression']
      }
    })

    console.log('✅ 计算器工具已注册')

    return dispose
  })
}
EOF

5.2 修改 cordis.yml

- name: './my-plugins/calculator.ts'

5.3 启动完整 Harness

pnpm dsh web

启动后打开浏览器 http://127.0.0.1:3080，进入设置配置好模型 API Key，然后创建会话。

在聊天框里输入：

帮我算一下 15 * 23 + 7 等于多少

AI 会自动调用你的 calculate 工具，返回计算结果。

六、用 dsh CLI 管理插件（安装社区插件）

Harness 提供了 dsh 命令行工具来管理插件。

6.1 查看当前加载了哪些插件

# 查看 web Profile 的最终配置树
dsh --profile web --dump-config

6.2 安装社区插件

# 安装文件引用插件（让 AI 能读取项目文件）
dsh plugin --profile web add \
  https://github.com/omdsh-dev/dsh-at-file/archive/refs/heads/main.tar.gz

# 安装桌面通知插件
dsh plugin --profile web add \
  https://github.com/omdsh-dev/dsh-notification/archive/refs/heads/main.tar.gz

6.3 卸载插件

dsh plugin --profile web remove dsh-at-file

6.4 查看插件为什么被安装

dsh plugin --profile web why dsh-at-file

七、项目结构速查表

deepseek-harness/                 ← 项目根目录（你 git clone 的地方）
│
├── my-plugins/                   ← ✅ 你写的插件放这里
│   ├── hello.ts
│   └── calculator.ts
│
├── packages/                     ← ⚠️ 官方内置插件，一般不要改
│   ├── core/
│   ├── llm/
│   ├── shell/
│   └── ...
│
├── vendor/                       ← Cordis 框架源码
│   ├── cordis/
│   ├── loader/
│   └── hmr/
│
├── cordis.yml                    ← ✅ 你的插件在这里声明
├── package.json
└── pnpm-workspace.yaml

八、常见问题排错

Q1: node --import tsx 报错 "Cannot find module 'tsx'"

# 安装 tsx
pnpm add -D tsx

# 或者直接用 pnpm dsh web 启动完整 Harness

Q2: 插件写了但 Harness 没加载

检查清单：

1. cordis.yml 里路径写对了吗？（相对项目根目录）
2. 文件里有 export const name 和 export function apply 吗？
3. 运行 dsh --profile web --dump-config 看看配置树里有没有你的插件

Q3: inject 的服务找不到

比如写了 inject: ['tools'] 但报错说 tools 不存在。确保：

• 你启动的是完整 Harness（pnpm dsh web），不是单独跑 cordis
• tools 服务由内置插件提供，完整启动时会自动加载

Q4: 修改插件后没有生效

Harness 支持热重载（HMR），但有时需要手动重启：

# 按 Ctrl+C 停止，再重新启动
pnpm dsh web

九、一句话总结

克隆仓库 → 在 my-plugins/ 写 .ts 文件 → 在 cordis.yml 里声明 → pnpm dsh web 启动 → 浏览器里验证

这就是写 Harness 插件的完整闭环。现在打开终端，从 git clone 开始吧！