DeepSeek Harness 智能体框架快速上手3 步搭好环境并挂载第一个自定义插件【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harnessdsh是 DeepSeek 出品的开源智能体框架核心能力是「一切皆插件」模型接入、工具调用、会话管理都被拆成独立的插件模块。本文 3 个步骤、约 30 分钟你就能在本机跑起它的 Web 界面写出一枚自定义插件并挂载进框架用终端日志验证整条链路。动手前自检清单逐项核对 Node.js、pnpm、Git 版本环境缺项是安装阶段最常见的翻车原因先逐项确认再敲命令本文成果dsh 的 Web 界面在本机跑起来你写的第一枚插件能在框架里输出日志。Node.js^22.19.0 || 24.0.0即 22.19 以上或 24 以上。这是仓库engines字段的硬性限制版本不够会在安装阶段直接报错。pnpm11.28.5仓库packageManager字段钉住此版本corepack enable后自动取用无需手动安装。Git任意较新版本用于克隆源码。理解架构只需一句话dsh 像公交换乘枢纽每个插件是一趟线路声明自己经过哪几站依赖、停靠哪一站能力框架按时刻表把它们接起来。清单核对完毕下面让代码跑起来。最小步骤跑起来克隆、构建、启动三命令命令一共 3 步每一步都在为下一步准备第 1 步克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/de/deepseek-harness cd deepseek-harness corepack enable pnpm install前两句把源码拉到本地并进入仓库根目录后续命令都在这个目录执行corepack enable启用仓库钉住的 pnpm 版本避免版本漂移pnpm install按 lockfile 解析全部依赖。第 2 步构建产物pnpm run builddsh web直接使用已构建的包产物与前端产物、不再重新构建所以首次运行要先跑这一步备好物。第 3 步启动 Web 界面pnpm dsh web默认在http://127.0.0.1:3080启动终端会打印访问地址不想自动打开浏览器就追加--no-open。界面点亮了但它还是个空壳下一步给它接上大脑。接上「大脑」的基础配置模型提供方关键配置字段表界面只是空壳接上模型智能体才有回应这一步在「设置 → 模型」页完成全部必填配置官方 DeepSeek 提供商只需填入API 密钥并保存密钥只写存储、页面永不回显明文第三方兼容 OpenAI 协议的网关点「添加模型提供商」切到「自定义模型 API」会看到下面四个字段的表单字段含义示例API 密钥网关访问凭证只写存储页面不会回传明文sk-xxxxProvider ID小写唯一标识请求、会话与凭据引用都靠它区分提供方my-gatewayAPI 地址网关 baseURL指向 OpenAI 兼容入口https://gateway.example/v1API 协议网关实际使用的线路协议openai-completions覆盖多数场景openai-completions更细的字段说明见 模型配置指南。模型变更在下一次请求时生效不需要重启服务器。密钥就位下一步动手验证插件链路是否真的通。30 秒动手验证挂载第一个会说话的自定义插件验证插件链路最快的方式是让它说话先证明框架能加载并运行你的代码。先创建scratch-first/src目录写入scratch-first/src/beacon.tsimport type { Context } from deepseek-ai/cordis export const name beacon export function apply(ctx: Context) { // 框架加载时调用 apply此时插件已挂载 console.log([beacon] 你好插件链路通了) // 注册 5 秒心跳返回清理函数插件卸载时自动执行 ctx.effect(() { const tick setInterval(() { console.log([beacon] 心跳正常还活着) }, 5000) return () clearInterval(tick) }) }再创建scratch-first/cordis.yml先在仓库根目录运行pwd把输出路径替换下面的占位- insert: - id: beacon name: /绝对路径/deepseek-harness/scratch-first/src/beacon.ts小提示name写成相对路径 → 启动时找不到插件模块 → 用pwd输出的绝对路径替换。启动命令是pnpm dsh web --patch ./scratch-first/cordis.yml--patch表示把这份配置叠加在默认配置之上。成功判据启动期间终端打印[beacon] 你好插件链路通了之后每 5 秒一条心跳日志按 CtrlC 停止时定时器自动清理不会残留。插件还有对象形式与类形式两种写法流程同样是「声明依赖 → 框架保证就绪 → 执行 apply」详见 第一个插件。链路验证完如果中途报错对照下一节逐条排查。常见坑与排查3 个高频报错的修复方法这三条覆盖了搭环境阶段的大部分失败看到现象直接对号入座现象pnpm install时ERR_PNPM_UNSUPPORTED_ENGINE输出写明 wantednode: ^22.19.0 || 24.0.0→ 原因Node 版本低于 22.19.0 → 一句修复升级到 Node 22.19 或 24 以上再重装。现象pnpm dsh web时报错指向缺少已构建产物并提示run pnpm run build→ 原因跳过了构建步骤产物不存在 → 一句修复先在仓库根目录执行pnpm run build。现象启动时Error: listen EADDRINUSE: address already in use 127.0.0.1:3080→ 原因3080 端口被已有进程占用 → 一句修复启动命令追加--port 8080换个端口。三条都处理完就可以进入进阶玩法了。跑通之后的三步进阶工具、配置、发布链路通了之后插件的价值取决于你注册的能力按难度递增走三步让智能体调用你的能力给插件加inject: [tools]用ctx.tools.register()注册自定义工具 → 详见 工具开发教程。让插件接受用户配置声明配置字段让每个配置项都能被用户在设置里覆盖 → 详见 插件配置说明。打包分享把本地插件做成可安装的包供其他用户直接装用 → 详见 发布指南。从 30 分钟前琢磨「什么是插件」到现在亲手挂载了一枚剩下的路就是去写点有趣的东西。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考