dsh-plugin-dev-guide — DeepSeek Harness 插件开发集成指南

DSH（DeepSeek Harness）插件开发的完整指南仓库：从第一个插件到自动发布到社区。 面向 DSH 插件作者（agent 开发者），内容基于官方源码仓库 deepseek-ai/deepseek-harness。

目录

快速开始

1. 准备

• Node.js ^22.19 || >=24，pnpm（仓库 pin pnpm@11.7.0）
• deepseek-harness 源码仓库克隆（pnpm install && pnpm run build 后可用 pnpm dsh 源码运行）

2. 第一个插件（3 步）

复制 examples/hello-plugin 到你的项目，然后：

// src/my-plugin.ts —— 插件 = 一个导出 apply 的 TS 模块
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'hello-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: { name: { type: 'string', required: true, description: 'The name to greet' } },
    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
    async execute(args) { return `Hello, ${args.name}!` },
  }))
}

# cordis.yml —— 挂载补丁（name 为插件源码绝对路径）
- insert:
    - id: hello
      name: '/abs/path/to/your-plugin/src/my-plugin.ts'

cd <deepseek-harness 仓库根>
pnpm dsh web --patch /abs/path/to/your-plugin/cordis.yml
# 打开 http://127.0.0.1:3080，终端打印 [hello-plugin] plugin loaded!

3. 发布到社区

1. 按 发布指南 把插件改造成 bundle 包（dsh.bundle manifest + cordis.patch.yml + prepare 脚本）；
2. 复制 .github/workflows/publish.yml（发布指南 §3.5 有完整模板），推 tag 即自动发布到 npm + GitHub Release；
3. 用 scripts/discover-plugins.mjs 一键巡检/发布你账号下的所有 dsh 插件。

设计要点速览

• 一切皆插件：DSH 构建在 vendored Cordis 上，工具、LLM 适配器、文件访问、agent 循环都是插件；没有特权内核。
• 插件 = 函数：export function apply(ctx)，可选 name/inject/Config；注册即可逆效果，卸载自动清理，天然支持 HMR。
• ctx = 服务仓库：ctx.tools/ctx.llm/ctx.sessions…… 按 key 取服务，不 import 具体实现；inject 声明依赖。
• 配置：Config 接口 + 同名 Schemastery schema，cordis.yml 传入并校验、填默认值；!!js 表达式可读运行时服务。
• 工具：defineTool({name, description, parameters, output, execute})，args 自动校验、结果规范化、UI 卡片纯函数投影。
• 发布分层：bundle patch → profile patch → 全局 patch → --patch 覆盖；后层按行覆盖，config 整块替换。

官方参考（deepseek-harness 仓库内）

相关项目

• deepseek-harness — DSH 本体
• dsh-web-search-pro — 增强型网页搜索插件（本指南的实践案例）
• dsh-voice-webspeech — 浏览器语音输入插件（client 插件实践案例）

License

MIT