10分钟上手DeepSeek Harness插件开发从环境搭建到运行第一个智能体扩展【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harness命令行工具叫dsh是一个以万物皆插件为核心理念的开源智能体框架本文用10分钟带你完成从环境搭建到跑通第一个自定义插件的完整链路。想给 AI 应用加一点别人没有的能力又不知道从哪下手这篇 DeepSeek Harness 快速上手教程就是为你准备的——不写一行业务代码也能先看到界面跟着动手就能拥有自己的第一个插件。先看结论一条 5 分钟的快速体验路线图与其一步步慢慢来不如先把整条链路在脑子里过一遍。接下来要做的事只有四件装好工具——Node.js 22 与 pnpm 包管理器git 用来拉取代码克隆项目并装依赖——一条命令搞定启动 Web UI——浏览器打开就能看到智能体界面写一个 20 行的插件——通过补丁文件注册进去重启即生效。全程约 10 分钟其中 80% 的时间其实花在安装依赖上。我们先从为什么需要这些东西讲起。开工前三样工具各自负责什么Node.js22 或更高版本整个框架跑在 Node 上插件也是用 TypeScript 写的Node 就是它的运行时。低于 22 会直接报错别省这一步。pnpm项目用 pnpm workspace 管理几十个子包官方推荐的安装方式就是 pnpm。用corepack enable激活即可不需要单独装。git从代码仓库拉取项目源码用的版本控制工具。环境检查可以用这条命令一次确认node -v # 确认 Node 版本应 22 corepack enable # 激活 pnpmNode 自带的 corepack 提供拉取代码并安装依赖两条命令进入开发状态git clone https://gitcode.com/gh_mirrors/de/deepseek-harness cd deepseek-harness pnpm install如果网络条件允许也可以不走源码路径直接用 npm 安装发布版npx deepseek-ai/dsh web一样能启动。但既然是开发插件从源码跑更利于边改边看。装完依赖后建议先执行一次构建把仓库里的产物准备好这样后续启动更快pnpm run build # 编译 host 端与 client 端产物一行命令启动 Web 界面看到主界面就算成功一半pnpm dsh web编译完成后默认会在http://127.0.0.1:3080打开 Web 界面这就是 DeepSeek Harness 的主界面。第一次打开时它还是个空壳——没有配置模型、没有选择工作区会话输入框是禁用的。这正是下一步要解决的。给智能体装上大脑两种模型配置路径界面里找到Settings → Models这里有两种玩法路径一直接用 DeepSeek 官方模型最快在模型列表里选择 DeepSeek 提供商填入你的 API 密钥在 DeepSeek 开放平台申请点Apply保存。不用重启服务模型路由立刻生效。路径二接入自定义模型服务进阶想用别的厂商、或者公司内网自建的 OpenAI 兼容服务点Add a custom provider填上服务地址、密钥和模型名即可。配置好模型后再点击Choose workspace选择你的项目目录就可以开始给智能体下任务了。比如让它总结这个仓库并列出主要包。亲手写第一个插件20 行代码走通注册→加载→验证框架的理念是万物皆插件——界面、工具、定时任务全是插件的形态。下面我们做一个会说话的最小插件。第一步建目录从仓库根目录执行mkdir -p scratch-plugin/src # 创建一个临时插件开发目录第二步写插件代码。创建scratch-plugin/src/my-plugin.tsimport type { Context } from deepseek-ai/cordis export const name hello-plugin export function apply(ctx: Context) { // ctx 是插件上下文通过它注册能力加载时框架会自动调用 apply console.log([hello-plugin] 我的第一个 DeepSeek Harness 插件加载成功) // ctx.effect 注册一个副作用插件卸载时框架会自动执行清理函数 ctx.effect(() { const timer setInterval(() { console.log([hello-plugin] 插件运行中...) }, 5000) return () clearInterval(timer) // 卸载时自动清理定时器 }) }代码里有两件值得注意的事依赖自动清理通过ctx注册的监听器、定时器、工具插件卸载时框架全自动帮你清理不用手写removeListener/clearIntervalctx.effect()的返回函数如果你想主动控制某个资源的释放比如网络连接把清理逻辑作为返回值交给框架。第三步注册插件。创建scratch-plugin/cordis.yml路径换成你机器上的真实绝对路径- insert: - id: hello name: /absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts这里的cordis.yml是一个补丁文件作用是在原有配置之上插入我们的本地插件。注意插件路径必须是绝对路径因为补丁文件不会改变模块解析的基准目录。第四步带补丁启动pnpm dsh web --patch ./scratch-plugin/cordis.yml启动时终端会打出这样一行日志说明插件已被框架加载[hello-plugin] 我的第一个 DeepSeek Harness 插件加载成功之后每隔 5 秒你还会看到[hello-plugin] 插件运行中...关掉服务时定时器被自动清理——一个完整的插件生命周期就这么闭环了。踩坑排查新手最容易卡住的三个地方插件没有加载日志九成是cordis.yml里的路径写成了相对路径或绝对路径写错了。用pwd确认仓库根目录再拼完整路径。启动报 Node 版本错误确认node -v输出的是 22旧版本如 18/20不支持。补丁文件语法报错检查 YAML 缩进- insert:是列表项id和name必须与上面示例对齐。想快速验证配置是否合法可以先用pnpm dsh web --dump-config --patch ./scratch-plugin/cordis.yml查看合成后的完整配置树。进阶玩法三种插件写法与配置化改造上面的函数式写法最常用但框架还支持另外两种形态适用于不同场景对象形式——适合把配置和入口打包在一起export default { name: my-plugin, inject: [tools], // 声明依赖加载前保证 tools 服务已就绪 apply(ctx: Context) { // 插件逻辑 }, }类形式——适合对外提供服务让其他插件调用import { Service, type Context } from deepseek-ai/cordis export default class MyService extends Service { static inject [tools] constructor(ctx: Context) { super(ctx, myService) // 向框架注册名为 myService 的服务 } }再进阶一步插件还能接收配置。导出同名Config类型与 Schemastery schema默认值直接写在 schema 上配置校验、默认值填充都由框架完成import type { Context } from deepseek-ai/cordis import Schema from deepseek-ai/schemastery export const name my-plugin export interface Config { greeting: string maxRetries: number } export const Config: SchemaConfig Schema.object({ greeting: Schema.string().default(Hello), maxRetries: Schema.number().default(3), }) export function apply(ctx: Context, config: Config) { console.log(config.greeting) // 用户配置值或 schema 默认值 }然后在cordis.yml里通过config字段覆盖默认值改完配置框架还会热替换插件旧实例的注册项自动清理非常省心。更多玩法与下一步探索插件的世界远不止打日志。你可以用工具定义 DSL 给智能体添加自定义工具、用inject: [tools]注入系统服务、或者用pnpm dsh --profile headless 一句话任务跑无界面的命令行任务。框架底下是 Cordis 插件体系生命周期、事件、服务注入的机制都很完整。想继续深入推荐按这个顺序看插件开发入门docs/user/develop/basic/index.zh.md开发自定义工具docs/user/develop/basic/tool.zh.md插件配置详解docs/user/develop/basic/config.zh.mdWeb 界面使用指南docs/user/guide/index.zh.md现在你的 DeepSeek Harness 已经跑起来了第一个插件也成功加载——剩下的就是打开想象力把你想加的能力都变成插件。试试给你的智能体写一个专属工具或者把某个重复操作封装成定时任务这就是万物皆插件的起点。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考