DeepSeek Harness 零基础上手：10分钟让智能体框架跑起来并挂载你的第一个插件

DeepSeek Harness 零基础上手：10分钟让智能体框架跑起来并挂载你的第一个插件

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

本文带你认识 DeepSeek Harness——一个"万物皆插件"的开源智能体框架（agent harness）。你不需要理解内部架构，只要跟着下面五个问题走，10分钟内就能让 Web 界面跑起来、把模型密钥填进去，并亲手写一个能随启动加载的自定义插件。

先别急着敲命令。这篇文章不是按"安装→启动→配置"的清单式流水账，而是围绕五个真实疑问展开：这个框架凭什么"万物皆插件"？环境要备什么？代码和依赖怎么来？界面怎么起？AI 怎么连、插件怎么跑？每个问题都有可直接复制的命令和结果预期，跟着走完，你就有了一台能自己说话、能装插件的智能体底座。

问题一：这个项目到底解决了什么，为什么值得花 10 分钟？

DeepSeek Harness（命令行里叫dsh）是一个由 DeepSeek 开源的智能体框架，核心设计理念只有一句话：Everything is a Plugin（万物皆插件）。

这意味着什么？你平时用的 AI 应用的"大脑"（模型路由）、"手脚"（工具：读写文件、执行命令、搜网页）、"记忆"（会话管理）、"皮肤"（Web 界面），在 Harness 里全部是插件，可以单独拆装、替换、新增。

对于普通用户来说，这个理念带来的实际价值是：你不用等官方发布新功能。想给智能体加一个"定时提醒"，写个插件挂上去就行；想接一个公司内部的模型网关，填一张表单就行。这种"框架本身是空的、能力全靠插件拼"的架构，正是它和大多数开箱即用的 AI 工具最大的区别。

💡 一句话记住：Harness 是"插座"，插件是"电器"。你装多少电器，插座就有多少能力。

问题二：开始前，机器上要备齐什么？

越少越好，三样就够：

• Node.js 22 或更高版本（项目要求^22.19.0 || >=24.0.0，建议直接装最新的 LTS）
• pnpm 包管理器（推荐用corepack enable一条命令启用）
• Git，用于拉取代码

在终端验证一下，三行命令确认环境就绪：

# 确认 Node 版本，输出需为 v22 及以上 node -v # 启用 pnpm（Node 自带 corepack，无需额外安装） corepack enable # 确认 pnpm 可用 pnpm -v

问题三：代码从哪来，依赖怎么装才不踩坑？

在你想存放项目的目录里，克隆仓库并安装依赖：

# 克隆 DeepSeek Harness 仓库 git clone https://gitcode.com/gh_mirrors/de/deepseek-harness # 进入项目目录 cd deepseek-harness # 安装全部依赖（这是一个 monorepo，首次安装会花几分钟） pnpm install

这里藏着一个新手最容易踩的坑：依赖装完，别急着启动！从源码运行时，需要先构建一次项目产物，再启动 Web UI，否则会报产物缺失。

# 先构建仓库产物（只需执行这一次，之后反复启动都不用再 build） pnpm run build # 启动 Web UI pnpm dsh web

🚧 避坑提示：如果你只是想"体验一下"、暂不打算改代码，其实有更快的路径——直接npx @deepseek-ai/dsh web一条命令就能跑，不需要克隆仓库。两种方式的取舍见下方表格。

问题四：界面怎么跑起来，看到什么才算成功？

输入pnpm dsh web后，等编译完成，终端会打印类似下面的信息，并自动打开浏览器：

dsh web: opening the default browser; pass --no-open to disable

浏览器自动打开http://127.0.0.1:3080，这就是 Harness 的主界面。如果你是在服务器（SSH 连接）上启动，浏览器不会自动打开，但终端会打印宿主机的访问地址，手动复制到本地浏览器即可。

打开界面后你会注意到：此时还没有选中任何工作区，输入框是灰的。别慌，这是设计如此——先给智能体指定一个"工作目录"，它才知道在哪干活。

📌 补充说明：dsh进程会把启动时所在的目录当作默认文件系统位置。建议在一个专门建的空项目目录里启动它，避免它"看到"整个家目录。

问题五：AI 怎么连，模型密钥到底填在哪？

这是大多数人最关心的一步，也是智能体真正"活过来"的关键。操作路径是：设置 → 模型。

步骤如下：

1. 打开设置 → 模型，找到 DeepSeek 卡片；
2. 在"API 密钥"输入框里粘贴你的 DeepSeek API 密钥；
3. 点击右下角保存。

保存后不需要重启服务器，模型路由立即可用。密钥是只写的——界面只显示脱敏描述符，不会回显明文，安全感拉满。

如果你的密钥来自其他服务商（Anthropic、OpenAI 等），点击**+ 添加提供方**，选取对应服务商并填入密钥即可。

而如果密钥来自公司网关、自建服务器这类"目录里没有"的提供方，就要用**+ 添加自定义提供方**：

表单里四项是必填的：Provider ID（小写唯一标识，创建后不可改）、API 地址、API 协议、API 密钥。填完再添加至少一个模型，保存即可。

🔑 遇到MISSING_CREDENTIAL报错？就是密钥没存进去；UNKNOWN_MODEL则是你选了没配置的模型。到模型页核对一遍即可。

配置完成后，回到主界面点击选择工作区，添加刚才启动dsh的目录并选中它。这时输入框解锁，你可以发送第一条指令试试：

Summarize this repository and identify its main packages.

看到智能体开始读文件、跑命令、输出结论，恭喜你，整套智能体框架已经跑起来了。但这才刚到一半——下面的重头戏是让"万物皆插件"这句话在你手里成立。

重头戏：第一个插件怎么跑起来？

插件本质上就是一个导出了apply函数的 TypeScript 模块。框架加载时调用它，并传入ctx（上下文对象），你通过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] 我的第一个DeepSeek Harness插件加载成功！') // 用 ctx.effect 注册一个定时器：每 5 秒输出一次 ctx.effect(() => { const timer = setInterval(() => { console.log('[hello-plugin] 插件运行中...') }, 5000) // 返回清理函数：插件卸载时框架自动调用，无需手动 clearInterval return () => clearInterval(timer) }) }

注意最后那个return：通过ctx注册的任何东西——事件监听、定时器、工具——在插件卸载时都会被框架自动清理。ctx.effect只是给"需要手动关资源"的情况（比如网络连接）留了个口子。你不需要写任何 removeListener。

第二步：把插件"插"进应用

创建scratch-plugin/cordis.yml，内容如下。注意：name字段必须是绝对路径，把/absolute/path/to/deepseek-harness替换成你机器上的实际路径（在仓库根目录运行pwd就能看到）：

# 通过 patch 文件把本地插件挂载到 Web 应用 - insert: - id: hello name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

第三步：带着插件启动

# 使用 patch 覆盖层启动 Web UI，插件会被一并加载 pnpm dsh web --patch ./scratch-plugin/cordis.yml

打开http://127.0.0.1:3080，回看启动终端——你已经能看到插件在打招呼了：

[hello-plugin] 我的第一个DeepSeek Harness插件加载成功！ [hello-plugin] 插件运行中... [hello-plugin] 插件运行中...

到这里，你的第一个 DeepSeek Harness 插件已经跑起来了！从"框架能跑"到"我的插件被框架加载"，中间只隔了三个文件、一条命令。

进阶小彩蛋：插件不止一种写法

上面用的是最常见的函数形式。除此之外，插件还支持另外两种形态，选择依据很简单：

如果插件要用到框架里的现成服务（比如tools、llm），在函数外再导出一个inject数组声明依赖即可：

export const name = 'my-tool-plugin' export const inject = ['tools'] // 声明依赖：框架会保证 tools 就绪后才加载本插件 export function apply(ctx: Context) { // 在这里 ctx.tools 一定可用 }

框架会耐心等待依赖就绪再加载你的插件，依赖没就绪绝不启动——这就是 Cordis 插件体系"组合优于继承"的体现。想深入了解底层插件框架，可以从docs/cordis-tutorial/的教程入手，它能在临时目录里动手搭建，连 API 密钥都不用。

如果你卡住了，先看这三条

• pnpm dsh web报产物相关错误：回到仓库根目录跑一次pnpm run build，再重新启动。
• 浏览器没自动打开：你多半是在 SSH 环境里启动的，终端会打印 URL，复制到本地浏览器访问即可；也可以在命令后加--no-open关闭自动打开行为。
• 插件日志没出现：检查cordis.yml里的name是不是绝对路径；patch 文件只贡献配置，路径写错 loader 是找不到模块的。

下一步往哪走？

插件已经能"说话"了，但它还没"动手"。接下来的方向很自然：让插件真正干点什么——比如注册一个能被智能体调用的工具，让它在执行任务时自动使用你的能力。入门后值得探索的入口有：

• 开发一个工具：docs/user/develop/basic/tool.md，了解工具定义 DSL，让智能体"手脚"更丰富
• 插件配置化：docs/user/develop/basic/config.md，让插件接受用户配置，而不是写死参数
• 发布你的插件：docs/user/develop/basic/publish.md，把插件打包分享出去

另外，如果你想搞清楚 Harness 为什么能把"万物皆插件"贯彻得这么彻底，docs/cordis-tutorial/这套底层框架教程比源码更容易读——它是从零手搭插件体系的，适合在周末下午配一杯咖啡慢慢看。

把第一个插件跑起来，你已经在用智能体框架"造积木"了。接下来，造什么，由你决定。 🚀

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