企业官网建设流程全解析

DeepSeek Harness 30 分钟上手指南：搭建智能体框架与第一个插件

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

想给 AI 应用加自定义工具、或者换个模型接入方式，却不知道框架内部从哪下手？DeepSeek Harness（下称 dsh）是一个以"Everything is a Plugin（一切皆插件）"为核心理念的智能体框架：模型接入、工具调用、会话管理、界面元素都是可独立替换的插件。这篇指南带你走最短路径——约 30 分钟内完成安装、启动 Web 界面、接入模型，并挂载你自己的第一个插件。

"一切皆插件"到底指什么

这一节只回答一个问题：框架里哪些东西可以被换、怎么换。

可以把框架想象成一个线路固定的配电盘：模型接入、工具调用、会话管理、界面元素各占一路"断路器"，每一路都在铭牌上声明"我需要哪路供电（服务）、我对外提供什么功能"，框架按声明顺序接通。想加功能，就并一路新断路器；想换实现，就拆下旧的一路、换上新的。你不需要看懂箱内走线，只要符合接口约定就能替换——这就是"一切皆插件"的全部含义。

环境三件套：要求、用途与缺失后果

动手前先确认运行环境。对照下面这张表逐项核对，缺哪项补哪项：

特别提醒：如果 Node.js 版本偏旧，先把版本升上去再继续，否则依赖安装阶段的报错会浪费你大量排查时间。

跑通 Web 界面：从拉代码到启动的四步主线

这一节把"装好 → 启动"压缩成一条直线，每条命令各配一句解释，照抄即可。

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

第一条把仓库克隆到本地，第二条进入项目目录，后续所有命令都基于这个目录执行。

corepack enable

启用 Node.js 自带的 corepack，让 pnpm 以最佳兼容性生效。

pnpm install

安装全部依赖。仓库体积较大，请等它完整跑完。

pnpm run build

把源码构建成可运行的产物。首次运行这一步不能跳过，否则启动时找不到构建结果。

pnpm dsh web

启动 Web 界面，终端会打印访问地址，默认是http://127.0.0.1:3080，浏览器打开看到主界面即表示运行成功。

两个行内小提示：不想让它自动拉起浏览器时追加--no-open参数；3080 端口被占用时改用pnpm dsh web --port 8080换端口继续。

配置模型：官方密钥与自定义提供方两条路

界面能打开只是第一步，接上模型框架才能真正工作。全部操作在"设置 → 模型"页面完成。

官方提供商：找到 DeepSeek 卡片，在 API 密钥字段填入密钥后保存即可，无需其他配置。

自定义提供商：如果你用的是兼容 OpenAI 协议的第三方网关、中转站或自建服务，点击"添加模型提供商"并切到自定义表单，需要填四个关键字段：

三步写出一个会在终端打印日志的插件

这一节验证整条插件链路：你的代码能否被框架加载、执行、清理。

第一步，建目录：

mkdir -p scratch-first/src

插件代码就放在这个目录里。

第二步，写插件代码，创建scratch-first/src/beacon.ts：

import type { Context } from '@deepseek-ai/cordis' export const name = 'beacon' export function apply(ctx: Context) { console.log('[beacon] 你好，我已经挂载到 Harness 上了！') ctx.effect(() => { const tick = setInterval(() => { console.log('[beacon] 心跳正常，插件还活着。') }, 5000) // 卸载时执行：停掉定时器 return () => clearInterval(tick) }) }

apply是插件入口，框架挂载时会传入上下文ctx；ctx.effect注册的返回值会在插件卸载时执行，用于清理定时器。

第三步，注册并挂载，创建scratch-first/cordis.yml：

- insert: - id: beacon name: '/你的绝对路径/deepseek-harness/scratch-first/src/beacon.ts'

注意这里的路径必须写绝对路径，请替换成你自己的。然后：

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

--patch的作用是把这份配置文件叠加到默认配置之上。启动后如果终端打印出[beacon] 你好，我已经挂载到 Harness 上了！，说明插件链路已经打通；之后每 5 秒会多一条心跳日志，Ctrl+C 停止时定时器会被自动清掉，不会残留。

插件还有另外两种写法：对象形式用export default { name, inject, apply }组织，结构更清晰；类形式继承Service，适合封装长期运行的服务（比如某个外部 API）。三种形态走的都是"声明依赖 → 框架保证依赖就绪 → 执行 apply"这一套流程，学会函数形式就能触类旁通。

常见报错速查：版本、端口、构建与路径

前面散落的坑集中整理成"现象 → 原因 → 处理"，遇到问题直接对照：

接下来往哪走：插件开发三条进阶路线

框架跑通、插件能挂载之后，可以按这个顺序深入：

1. 给插件声明inject: ['tools']，用ctx.tools.register()注册自定义工具，让智能体学会调用你的能力——具体做法见工具开发教程
2. 通读插件开发指南，覆盖插件生命周期、服务与事件等完整机制
3. 研究配置说明，搞清每个配置项来自哪个文件、如何被覆盖，再把插件打包发布给别人用

到这里，从安装到插件挂载的完整闭环你已经自己走了一遍。下一步建议很具体：打开scratch-first/src/beacon.ts，把心跳日志换成调用你自己注册的一个工具，看看智能体能不能真正用上它 🚀

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