插件开发示例集 tanzhangjia/dsh-plugins-examples

DeepSeek Harness 本地插件开发示例

学习如何创建和部署自定义 DSH 插件

📚 简介

本仓库提供 DeepSeek Harness (DSH) 本地插件开发的完整示例和工具链。通过这些示例，你可以学习如何：

- ✅ 创建自定义 DSH 插件
- ✅ 注册模型工具（Tools）
- ✅ 集成第三方 API
- ✅ 部署本地插件到 DSH

🎯 示例插件

| 插件名称 | 工具数 | 功能描述 |
| dsh-tool-example | 7 | 第三方 API 集成示例 |
| dsh-image-recognition | 1 | 图像识别工具示例 |
| dsh-blog-api | 9 | 博客平台 API 集成示例 |
| dsh-design-tool | 9 | 设计工具 API 集成示例 |

总计: 4 个示例插件，26 个工具

🚀 快速开始

1. 创建插件

使用脚本快速创建插件骨架：

.\scripts\create-local-plugin.ps1 -pluginName "my-tool" -seam "tools"

生成的结构：

dsh-my-tool/
├── package.json
├── lib/
│ └── index.js
└── cordis.patch.yml

2. 实现工具

在 lib/index.js 中定义工具：

import z from "@deepseek-ai/schemastery";
import { defineTool } from "@deepseek-ai/dsh-tools";

export const name = "my-tool";
export const inject = ["tools"];
export const Config = z.object({});

export function apply(ctx, config = {}) {
const myTool = defineTool({
name: "my_tool",
description: "My custom tool",
parameters: {
input: {
type: "string",
required: true,
description: "Input parameter"
}
},
output: { schema: { type: "json" } },
async execute(args) {
return { result: Processed: ${args.input} };
}
});

ctx.tools.register(myTool);
console.log('[my-tool] Loaded successfully');
}

3. 部署插件

使用部署脚本 .\scripts\deploy-local-plugin.ps1 -sourcePath "D:\dspace\dsh-my-tool" -pluginName "my-tool"

或手动复制 Copy-Item -Path "D:\dspace\dsh-my-tool\*" -Destination "C:\Users\用户名\.dsh\profiles\node_modules\@deepseek-ai\dsh-my-tool\" -Recurse -Force

4. 重启 DSH

dsh web

查看日志确认加载成功： [my-tool] Loaded successfully

5. 刷新浏览器

访问 http://127.0.0.1:3080 并刷新页面，在工具列表中查看新添加的工具。

🛠️ 开发工具

创建新插件

.\scripts\create-local-plugin.ps1 -pluginName "my-tool" -seam "tools"

参数说明：
- -pluginName: 插件名称（如 my-tool）
- -seam: 插件类型，tools 表示工具类插件

部署插件

.\scripts\deploy-local-plugin.ps1 -sourcePath "D:\dspace\dsh-my-tool" -pluginName "my-tool"

参数说明：
- -sourcePath: 插件源代码路径
- -pluginName: 插件名称（用于目标目录名）

📖 核心概念

插件结构

每个插件包含以下文件：

dsh-<plugin-name>/
├── package.json # 插件元数据 ├── lib/ │ └── index.js # 插件主代码 └── cordis.patch.yml # 注册配置（可选）

package.json 示例

{
"name": "@deepseek-ai/dsh-my-tool",
"version": "0.1.0",
"type": "module",
"exports": {
".": "./lib/index.js"
},
"peerDependencies": {
"@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
"@deepseek-ai/schemastery": "^3.18.1",
"@deepseek-ai/cordis": "^4.0.1"
}
}

工具定义规范

参数 Schema 规则

// ✅ 正确 - 可选参数
parameters: {
requiredField: {
type: "string",
required: true,
description: "必填字段" },
optionalField: {
type: "string",
description: "可选字段", default: "默认值" } }

// ❌ 错误 - required 不能为 false
parameters: {
optionalField: {
type: "string",
required: false, // 不允许!
default: "默认值" } }

输出 Schema

必须包含 output 字段：

output: {
schema: { type: "json" }
}

配置管理

用 z.object() 定义配置 schema：

import z from "@deepseek-ai/schemastery";

export const Config = z.object({
apiKey: z.string().describe("API Key"),
timeout: z.number().default(30000)
});

注意：用 z.string()，不要用 { type: "string" }

⚠️ 重要注意事项

1. 热重载

tools seam 不支持热重载，每次修改后都要重启 DSH：

dsh web

2. 环境变量

第三方 API 的密钥建议通过环境变量配置：

PowerShell 临时设置 $env:API_TOKEN = "your_token"

PowerShell 永久设置
[System.Environment]::SetEnvironmentVariable("API_TOKEN", "your_token", "User")

3. 命名规范

插件名遵循以下规则：

- 工具类插件：dsh-tool-<功能名>
- 功能类插件：dsh-<功能名>
- 包名：@deepseek-ai/dsh-<插件名>

4. 调试技巧

- 查看 DSH 启动日志，确认插件加载
- 在 apply 函数里加 console.log 调试
- 用 ctx 对象访问 DSH 上下文

📝 开发流程

1. 需求分析 - 确定要实现的功能
2. 创建骨架 - 用脚本生成基础结构
3. 实现工具 - 编写 defineTool 和 execute 函数
4. 本地测试 - 部署到本地 DSH 并测试
5. 调试优化 - 根据日志和反馈调整
6. 文档完善 - 更新 README 和使用说明
7. 分享发布 - 推送到 Git 仓库，或分享给团队

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 自由使用、修改和分发。

相关资源:
- DSH 官方仓库
- Cordis 文档
- Schemastery 文档