DeepSeek Harness 实操:从零跑通智能体框架,25 分钟搭好 Web 界面与第一个插件

DeepSeek Harness 实操:从零跑通智能体框架,25 分钟搭好 Web 界面与第一个插件

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

DeepSeek Harness(dsh)是 DeepSeek 开源的智能体框架,把模型接入、工具、会话管理全拆成了可插拔模块。本文写给第一次接触它、想亲手跑起来的新手。按本文跟完,你能独立启动 Web 界面、配好模型,并挂载一个自己的插件。

先看懂一个设计思想:后厨与排班表

搞清你在搭什么,后面每一步都会更顺。

DeepSeek Harness 只有一个核心思想:一切皆插件。模型接入是插件,终端工具是插件,界面上的卡片也是插件。

把它想象成一家餐厅的后厨:框架是中央厨房,每个插件是一个岗位——切配、炉灶、出餐。每个岗位开工前先报"我需要哪些半成品"(代码里叫inject),厨房保证依赖备齐了才让它上岗。

而整张排班表,就是一份叫cordis.yml的清单:哪些岗位今天上班、上在哪一层,全由它说了算。以后加功能,就是往排班表上添一个岗位;换实现,就是换一个人。你不需要拆厨房的墙。

动手前体检:DeepSeek Harness 四项前置条件自查

缺任何一项后面都会报错,先花一分钟核对。

  • Node.js:版本要求 22.19 及以上(或 24 以上),node -v可查。版本不够,pnpm install会直接抛 engine 报错,构建也过不去。
  • pnpm:仓库锁定 pnpm 11.28.5,推荐用 Node 自带的 corepack 启用。没有它,后文所有pnpm命令都不存在。
  • Git:用来克隆仓库。缺它只能手动下载压缩包,目录结构容易对不上。
  • DeepSeek API 密钥:后面配置模型要用。没有它界面能开,但发不出第一条消息。

踩坑预警:最高频的坑是 Node 停在 18/20。症状是安装阶段一堆看不懂的报错——直接升级到 22.19+ 重来,别试图绕过。

点亮项目:DeepSeek Harness 启动命令逐条解释

按顺序执行,每条命令后都有成功判据,随时确认没走偏。

git clone https://gitcode.com/gh_mirrors/de/deepseek-harness cd deepseek-harness corepack enable pnpm install

第一句把源码克隆到本地,第二句进入项目根目录,后续命令都在这里执行;corepack enable启用包管理器管理,它会自动按仓库声明切到 pnpm 11.28.5;pnpm install安装全部依赖,仓库较大,耐心等。

成功判据:终端最终打印完成信息,且没有ERR开头的红色报错。

pnpm run build pnpm dsh web

第一条把源码构建成可运行产物——生产运行只认构建产物,跳过它后面会启动失败;第二条启动 Web 服务,默认地址http://127.0.0.1:3080,会自动打开浏览器,加--no-open可关掉这个行为。

成功判据:build 阶段无 error 并回到干净的 shell 提示符;随后终端打印访问地址,浏览器打开后看到 DeepSeek Harness 的欢迎主界面。

核心能力接入:DeepSeek Harness 模型配置字段逐项填法

界面只是空壳,填好密钥才真正可用。

进入设置 → 模型。

官方路线:DeepSeek 卡片只有一个API 密钥字段 → 粘贴密钥并保存。密钥是只写的,保存后页面只拿到脱敏描述,明文存在本地$DSH_HOME/.credentials.yaml。

自定义路线(OpenAI 兼容网关、中转站):点"添加模型提供商"切到自定义表单,四个字段这样填——

  • Provider ID→ 小写唯一标识,请求与凭据都靠它定位 → 例my-gateway
  • 显示名称→ 仅界面展示 → 例公司网关
  • API 地址→ 网关 base URL → 例https://gateway.example/v1
  • API 协议→ 必须选网关实际使用的那一种,三选一 → 例openai-completions

成功判据:模型选择器里出现你配置的模型,选中后新会话即可对话。模型变更下一次请求即生效,无需重启。

实战小练:10 分钟写出第一个会心跳的 dsh 插件

结果肉眼可见:终端里持续冒出心跳日志。

先建目录(在项目根目录执行):mkdir -p scratch-plugin/src。

创建scratch-plugin/src/my-plugin.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里返回的清理函数会在插件卸载时自动执行,你不用手动clearInterval。

再创建scratch-plugin/cordis.yml:

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

这是叠加到默认配置之上的覆盖层,insert表示往里插入一个插件条目。

踩坑预警:name必须是绝对路径,先pwd拿到根目录再拼接;路径写错时插件会静默失效——不报错、无输出。

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

--patch把这份覆盖层叠到默认配置上,不改动任何默认值。

成功判据:启动时终端打印[beacon] 已挂载到 Harness,之后每 5 秒一条心跳;按 Ctrl+C 停止时定时器被自动回收,无残留。

排坑手册:dsh 新手最常卡住的 5 类问题及解法

卡住时直接对照,不用逐段回翻。

  1. 现象:启动即报 3080 端口冲突 →原因:本机已有服务占用该端口 →解法:pnpm dsh web --port 8080换端口启动。
  2. 现象:跳过 build 直接pnpm dsh web,启动报错或页面异常 →原因:生产运行依赖已构建的产物 →解法:先补跑pnpm run build再启动。
  3. 现象:cordis.yml 加了插件却毫无输出,像没生效 →原因:name路径写错或不是绝对路径,解析失败只进日志不崩溃 →解法:先pwd核对绝对路径,逐字符检查拼写。
  4. 现象:模型配好了,会话输入框灰着发不出消息 →原因:未选中工作区,选中前输入框不可用 →解法:点"选择工作区",添加项目目录并选中。
  5. 现象:pnpm命令找不到或版本不对 →原因:corepack 未启用或系统 pnpm 过旧 →解法:执行corepack enable,再用pnpm -v确认是 11.28.5。

进阶路线图:跑通 DeepSeek Harness 之后的四条路径

每条都附了项目内文档入口,顺着就能走。

  1. 注册一个自定义工具(如greet问候工具)——让智能体真正调用你写的逻辑,是插件价值的第一个放大器。入口:开发一个工具
  2. 给插件加配置与依赖声明(inject)——学会声明式地等待tools、llm等服务就绪再上岗。入口:插件配置
  3. 深入 Cordis 底层教程——理解生命周期、effect 清理与三种插件形态,把插件从"能跑"写到"写得稳"。入口:Cordis 框架教程
  4. 打包发布插件——从玩家变成作者,把你的插件分享出去。入口:发布指南

到这一步,Web 界面、模型配置、第一个插件三件事全部落地,正是导语里承诺的全部内容。排班表上永远有空位,下一个插件该是什么,由你定 ✨

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

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

数学建模竞赛真题解读与源码实战:从模型构建到论文输出全链路

数学建模竞赛真题解读与源码实战:从模型构建到论文输出全链路

简介:一套面向高校数学建模竞赛的完整培训材料,涵盖基础理论、建模方法、真题解析与源代码实现,适合从入门到备赛冲刺的各阶段学生。压缩包共61个文件,约2.02MB,以30个MATLAB脚本、16个Word文档和6个Excel表格为主&…

2026/11/17 17:32:21 阅读更多 →
高职院校智能体应用生态建设:OpenClaw落地实战指南

高职院校智能体应用生态建设:OpenClaw落地实战指南

1. 项目概述:为什么要研究OpenClaw在高职院校的落地先说结论:OpenClaw这个项目本身不是什么新概念,它本质上是一套开源的多智能体编排框架。我接触它是在一次校内数字化转型研讨会上,某高校信息中心的某老师提到他们正在试水智能体…

2026/11/17 17:37:21 阅读更多 →
数据获取与处理实战:从数据源选择到数据清洗的完整指南

数据获取与处理实战:从数据源选择到数据清洗的完整指南

这几年做数据相关的工作,被问得最多的一个问题是:“我该从哪儿拿数据?拿到手之后又该怎么处理?”说实话,大多数人在第一步就卡住了,要么不知道怎么稳定地拿到数据,要么千辛万苦拿到一份Excel&am…

2026/11/17 17:41:26 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/17 8:22:52 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/17 12:46:04 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/17 12:46:04 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/17 11:26:33 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/17 12:46:05 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/17 12:46:05 阅读更多 →

日新闻

周新闻

月新闻