DeepSeek Harness 快速上手：30 分钟把第一个插件挂上"一切皆插件"的智能体框架

【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness

DeepSeek Harness（dsh）是 DeepSeek 开源的智能体框架，核心理念只有一句话：Everything is a Plugin。模型接入、工具调用、会话管理，全部是独立的插件模块，想加能力就加一个插件，想换实现就换一个。这篇文章带你把框架跑起来，亲手写一个会在终端"说话"的小插件，顺带把每一步为什么这么跑讲清楚。

先看目标：终端一行日志 + 浏览器一个界面

先别急着敲命令，花 30 秒看清"跑通"长什么样，后面每一步就知道自己在干什么：

• 终端里打印一行日志：[hello-plugin] plugin loaded!
• 浏览器打开http://127.0.0.1:3080的 dsh Web 界面，里面可以选工作区、配模型、和智能体对话

倒推回去，这个画面由三件事支撑：页面能出来，是因为框架先被从源码构建了；日志能打印，是因为我们的插件被一个--patch配置文件叠加进了默认配置；对话能发生，是因为模型页里填了密钥。下面按这个倒序把三件事办完。

搭起框架：4 条命令，顺序比细节重要

这一节解决"从源码到运行中的 Web 界面"。四条命令的顺序不能乱——尤其构建必须跑在启动之前，否则产物是空的，启动会直接报错。

先克隆仓库并进入目录，后续命令都基于它：

git clone https://gitcode.com/gh_mirrors/de/deepseek-harness cd deepseek-harness

接着安装依赖。框架要求 Node.js 22.19 及以上（或 24+），pnpm 11；没有 pnpm 的话，Node 22 自带 corepack，corepack enable即可启用仓库锁定的版本。装完再执行：

pnpm install

仓库是一个多包 workspace，安装时间偏长，耐心等它跑完。然后构建产物：

pnpm run build

pnpm dsh web直接消费构建好的产物，不会重新构建，所以首次运行这一步不能跳过。最后启动：

pnpm dsh web

跑完它默认在http://127.0.0.1:3080启动 Web UI 并自动打开浏览器。不想自动开浏览器就加--no-open；3080 端口被占，加--port 8080换个端口就行。

顺手提醒：dsh进程以启动时所在目录作为默认文件系统位置，但全新的 Web UI 不会选中任何工作区。进界面后先点"选择工作区"，把要操作的项目目录加进来并选中，否则会话输入框是灰的，发不出消息。

接上模型：填个密钥，不用重启

界面跑起来只是空壳，这一步给它装上"大脑"。

打开设置 → 模型，DeepSeek 官方提供商的卡片上有一个 API 密钥字段，填入保存。模型路由立即可用，不需要重启服务器：

如果你用的是兼容 OpenAI 协议的第三方网关，点"添加模型提供商"切到自定义模型 API，填 Provider ID、显示名称、API 地址、API 协议（OpenAI Chat Completions对多数场景都适用），再加 API 密钥和至少一个模型：

其中 Provider ID 是永久的：请求、已保存会话、模型默认值、凭据引用都靠它标识，想改名字只能新建一个再删旧的，填之前想好。模型配好后在模型选择器里选一个，它同时会成为新会话的默认值。这时可以发第一句话，比如让它"总结这个仓库并指出主要包"——它会读工作区文件、跑命令，按权限策略需要审批的操作，Web UI 会先问你。

写第一个会说话的插件：2 个文件 + 1 个启动参数

这一节解决"验证插件链路真的通"，同时把插件是什么讲透。在 dsh 里，插件就是一个导出apply函数的 TypeScript 模块：框架加载时调用apply，传入ctx上下文对象，你通过它注册能力。

官方教程让你在仓库根目录建一个临时项目，先创建目录（只新增文件，不动仓库原有内容）：

mkdir -p scratch-plugin/src

创建scratch-plugin/src/my-plugin.ts，写入插件本体——这就是完整配置：

import type { Context } from '@deepseek-ai/cordis' export const name = 'hello-plugin' export function apply(ctx: Context) { console.log('[hello-plugin] plugin loaded!') }

再创建scratch-plugin/cordis.yml把插件注册进框架。路径必须是绝对路径，先在仓库根目录跑pwd拿到：

- insert: - id: hello name: '/绝对路径/deepseek-harness/scratch-plugin/src/my-plugin.ts'

最后把这个文件叠加到默认配置上启动，跑完它你应该在终端看到[hello-plugin] plugin loaded!：

pnpm dsh web --patch ./scratch-plugin/cordis.yml

--patch的语义是"叠加"而不是替换：patch 文件只贡献配置，框架其余部分保持不动，这也是插件体系"换实现"的入口。

顺手提醒：通过ctx注册的事件监听、工具、定时器，在插件卸载时都会被自动清理，不用手动clearInterval；个别需要手动清理的资源（比如网络连接），用ctx.effect()包住并返回清理函数即可。

跑通之后，自然下一步是给智能体加工具

链路通了，别急着写下一个 hello world。最有价值的动作是让智能体真的调用你的能力：在插件里加一行export const inject = ['tools']，框架会等工具注册表就绪后才执行apply，之后就能用ctx.tools.register()注册自定义工具。官方教程里有一个完整的greet工具例子，注册完可以直接在对话里让模型调用，参考 工具开发教程。

另外两个值得知道的点：插件除函数形式外还有对象形式和类形式（继承Service，适合提供长期运行的服务），三者"声明依赖 → 等就绪 → 执行 apply"的流程一致；想深挖底层，Cordis 框架教程会在临时目录里带你从零拼配置，不需要 API 密钥。

30 分钟前你还在琢磨"插件到底是什么"，现在框架已经加载了你的插件，智能体也接上了大脑。剩下的路很明确：找一个你真正想自动化的小事，从把它包成一个工具开始。

【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness