【从零开始 DeepSeek Harness 插件开发教程】一、DeepSeek Harness 初体验：从零跑通开发者预览

前言

简单介绍一下我自己：代码苦手，先前也从来没有写过相关的插件之类的。此次教程也是半学习半参考ai完成的。如果大家有同样开发插件开发的想法可以做一下参考。

目标：从零学会 DeepSeek Harness（DSH），并开发一个「AI 驱动的操作录制插件」（action-recorder），开发者用自然语言描述操作步骤 → DeepSeek 当大脑规划 → 插件提供「控制鼠标/键盘 + 打开网页/应用 + 录屏」的执行工具 → 自动产出动图/视频。

0. 成果预览

• 完成首次对话，运行截图

  

1. 先搞清楚这是什么

DeepSeek Harness（下文简称 dsh）是 DeepSeek 官方出的 agent harness，底层跑着一套叫 Cordis 的微内核。它的核心哲学就一句话：一切皆插件——模型适配器、工具、技能、会话、沙箱、调度、UI 全是插件，没有「内置特权人」。

对我们开发者来说，这意味两件事：

• 你写的自动化插件和官方插件地位完全对等，直接挂载进运行时，不是挂在外面的脚本。
• 当前它处于 dev-preview 阶段，命令式入口是 pnpm dsh，文档和 API 还在演进，所以本文所有版本相关的地方都标了「填写你实测的版本」。

2. 从零安装环境

前置依赖（在你本机实测通过的版本）：

• Node.js ≥ [v22.23.3]
• pnpm [10.33.1]
• Git

基础环境安装这里不多说了，我这里本地使用了nvm，可以快捷切换+安装node版本，这里推荐一下。Node 版本管理如果乱了，用 nvm 切一下。

克隆官方仓库：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

⚠️ 踩坑点（网络）：国内网络环境下 git clone https://github.com/deepseek-ai/deepseek-harness.git 可能卡在拉取 网络超时。 我当时是 [走了ssh地址]，才顺利跑通。 具体命令：[git clone git@github.com:deepseek-ai/deepseek-harness.git]。这块每个人的环境不同，不多描述了。

安装依赖：

pnpm install

编译：

pnpm run build

编译通过，环境就准备好了。

3. 跑起来

pnpm dsh web

启动后它会自动打开浏览器到 http://localhost:3080。这就是 dsh 的 Web UI，后面我们写插件也是在这里对话测试。

第一次发消息时，UI 会提示你配置模型 Key——这就引出了下面的真实踩坑。

4. 配置 Key（我刚踩过的坑）

我在第一步填 Key 时，手滑填错了一个字符，结果对话直接报错。下面是排查 + 修正过程，也是这篇最值得记的一段。

怎么改？两种方式，都不用重启服务：

方式 A：Web UI 里直接改（推荐） 左下角 ⚙️ 设置 → Models → 找到 DeepSeek 卡片 → 把错误的 key 替换成正确的 → 保存。下次发请求立刻生效。

方式 B：直接改凭据文件 UI 填的 key 实际落盘在 $DSH_HOME/.credentials.yaml，Windows 默认路径：

C:\Users\xxxx\.dsh\.credentials.yaml

用编辑器打开，把里面错误的 key 值替换掉保存即可。

⚠️ 踩坑提醒：

• 如果你当初是用环境变量 DEEPSEEK_API_KEY=xxx 启动的（而不是 UI 卡片），那得重新 set DEEPSEEK_API_KEY=正确值 再启动，UI 改不到它。

改完回到对话框随便发一句 你好，能正常回复就说明 key 对了。

5. 验证跑通 + 下一篇预告

完成标志：在 :3080 的对话框里发消息，能拿到 DeepSeek 的正常回复。到这一步， 就算通关。

回顾一下我们做了什么：

步骤	动作	完成标志
环境	装 Node/pnpm、clone 仓库	仓库在本地
依赖	pnpm install && pnpm run build	编译无错
运行	pnpm dsh web	:3080 打开
凭据	填对 Key	对话有回复

结尾

• 这里登录后DeepSeek官网送了6块的api使用金额，还是推荐大家玩一下的哈。

下一篇预告（P1）：现在 harness 是黑盒。接下来我会去读架构文档 + AGENTS.md，把「一切皆插件」的 Cordis 心智模型搞清楚——plugin / service / event / ctx / inject / effect 到底是什么，以及一条「插件挂载 → 工具调用」的完整链路长什么样。

再下一篇（P2）：徒手写第一个插件，先打一行 log 打通挂载链路，再升级成注册一个真正能被模型调用的工具。