DeepSeek Harness 实操:从零跑通智能体框架,25 分钟搭好 Web 界面与第一个插件【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek 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/v1API 协议→ 必须选网关实际使用的那一种,三选一 → 例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 类问题及解法卡住时直接对照,不用逐段回翻。现象:启动即报 3080 端口冲突 →原因:本机已有服务占用该端口 →解法:pnpm dsh web --port 8080换端口启动。现象:跳过 build 直接pnpm dsh web,启动报错或页面异常 →原因:生产运行依赖已构建的产物 →解法:先补跑pnpm run build再启动。现象:cordis.yml 加了插件却毫无输出,像没生效 →原因:name路径写错或不是绝对路径,解析失败只进日志不崩溃 →解法:先pwd核对绝对路径,逐字符检查拼写。现象:模型配好了,会话输入框灰着发不出消息 →原因:未选中工作区,选中前输入框不可用 →解法:点"选择工作区",添加项目目录并选中。现象:pnpm命令找不到或版本不对 →原因:corepack 未启用或系统 pnpm 过旧 →解法:执行corepack enable,再用pnpm -v确认是 11.28.5。进阶路线图:跑通 DeepSeek Harness 之后的四条路径每条都附了项目内文档入口,顺着就能走。注册一个自定义工具(如greet问候工具)——让智能体真正调用你写的逻辑,是插件价值的第一个放大器。入口:开发一个工具给插件加配置与依赖声明(inject)——学会声明式地等待tools、llm等服务就绪再上岗。入口:插件配置深入 Cordis 底层教程——理解生命周期、effect 清理与三种插件形态,把插件从"能跑"写到"写得稳"。入口:Cordis 框架教程打包发布插件——从玩家变成作者,把你的插件分享出去。入口:发布指南到这一步,Web 界面、模型配置、第一个插件三件事全部落地,正是导语里承诺的全部内容。排班表上永远有空位,下一个插件该是什么,由你定 ✨【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepSeek Harness 实操:从零跑通智能体框架,25 分钟搭好 Web 界面与第一个插件【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek 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/v1API 协议→ 必须选网关实际使用的那一种,三选一 → 例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 类问题及解法卡住时直接对照,不用逐段回翻。现象:启动即报 3080 端口冲突 →原因:本机已有服务占用该端口 →解法:pnpm dsh web --port 8080换端口启动。现象:跳过 build 直接pnpm dsh web,启动报错或页面异常 →原因:生产运行依赖已构建的产物 →解法:先补跑pnpm run build再启动。现象:cordis.yml 加了插件却毫无输出,像没生效 →原因:name路径写错或不是绝对路径,解析失败只进日志不崩溃 →解法:先pwd核对绝对路径,逐字符检查拼写。现象:模型配好了,会话输入框灰着发不出消息 →原因:未选中工作区,选中前输入框不可用 →解法:点"选择工作区",添加项目目录并选中。现象:pnpm命令找不到或版本不对 →原因:corepack 未启用或系统 pnpm 过旧 →解法:执行corepack enable,再用pnpm -v确认是 11.28.5。进阶路线图:跑通 DeepSeek Harness 之后的四条路径每条都附了项目内文档入口,顺着就能走。注册一个自定义工具(如greet问候工具)——让智能体真正调用你写的逻辑,是插件价值的第一个放大器。入口:开发一个工具给插件加配置与依赖声明(inject)——学会声明式地等待tools、llm等服务就绪再上岗。入口:插件配置深入 Cordis 底层教程——理解生命周期、effect 清理与三种插件形态,把插件从"能跑"写到"写得稳"。入口:Cordis 框架教程打包发布插件——从玩家变成作者,把你的插件分享出去。入口:发布指南到这一步,Web 界面、模型配置、第一个插件三件事全部落地,正是导语里承诺的全部内容。排班表上永远有空位,下一个插件该是什么,由你定 ✨【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考