乐于分享
好东西不私藏

DeepSeek Harness 使用教程:从安装到搭出一个自己的 Agent

DeepSeek Harness 使用教程:从安装到搭出一个自己的 Agent

前天刚写完 Work Buddy 的教程, DeepSeek Harness 的开发者预览版也紧接着放了出来。

我第一时间安装了,打开官网,第一眼看到的却是「一切皆插件」几个大字。

模型、工具、会话、沙箱、存储、循环、调度,连眼前这个 Web 界面,都可以由插件组合出来。

我在本地把它跑起来以后,又用创造模式做了一套「产品评测编辑」预设。做这套预设的过程,刚好把「一切皆插件」这个 DSH 的灵魂完整的体验了一下。

DSH 的「一切皆插件」

Agent = Model + Harness

当前版本还是开发者预览版,如果只按 Coding Agent 的完成度来衡量,它还没有 Claude Code 和 Codex 那么顺手。

我这次就碰到了创建预设时反复调用错误工具、社区插件需要手动安装,以及不少设置仍要读文档才能弄清楚的问题。

除了 Agent 外, DSH 同时是一套 Agent 开发框架。

现在看到的 Web 版 Coding Agent ,只是 DeepSeek 用这套框架拼出来的一份官方预置。想换成 TUI 或接入其他交互方式,也可以另做 Profile 、 UI 插件或外部协议驱动。

如果把 DSH 想成一盒乐高汽车,会更容易理解。 DeepSeek 已经用盒子里的零件拼好一辆能开的车,但引擎、轮胎、方向盘和车身都没有焊死。

你可以替换其中一部分,也可以拿同一盒零件拼出别的东西,最后得到的未必还是 Coding Agent 。

这就是 DeepSeek Harness 最大的特色:模型、工具、文件系统、 Shell 、沙箱、权限、会话存储、 Subagent 、 UI ,连负责驱动模型一步步工作的 Agent Loop ,本身都是插件。

想换模型,只要换掉接在 ctx.llm 上的模型适配器,上面的 Agent 不用跟着重写。想加工具,就把名称、参数和执行方法注册到 ctx.tools。工具的 schema 会进入系统提示词,模型下一轮便能看到并调用。

文件读写、 Shell 、网页搜索、后台任务和持久终端都沿着这套方式加入, MCP 工具接进来以后也进入同一个工具注册表。

文件系统、 Shell 和沙箱也不是绑在一起的一份固定实现。权限插件可以在工具执行前决定放行还是拒绝,沙箱插件负责限制命令在哪里运行。

会话由 core/session 插件维护。用户消息、模型输出、工具调用和结果都会写进一条只追加的事件流,恢复会话、分叉、回放、 Trajectory 和持久化都从这里取数据。

插件还可以在模型请求前补一段上下文,拦截某个工具,或者在 Agent 准备停下时让它继续处理后续工作。

Web 界面同样是后来叠上去的一层。dsh-base 先装模型、工具、存储、沙箱、审批、设置和凭据,dsh-web-app 再提供浏览器界面。headless 换掉最后这一层,就变成一个不带服务器的一次性任务运行器。

插件不只负责替换已有零件,还能给正在运行的 Agent 临时加一项新能力。

创造模式里有一组 Cordis 工具, Agent 可以先检查当前 runtime 里有哪些服务、事件和接口,再现场写一段 JavaScript 插件代码。cordis_define 负责定义插件,用户确认后,cordis_run 把它挂进当前进程。插件注册的新工具或界面随后就能在同一个任务里使用。

Cordis 会记住一项插件注册了哪些服务、事件和工具。插件停掉或卸载时,这些注册也会跟着撤回,不需要改一遍核心代码再恢复。这是 DSH 所说的热插拔。

它现在可以临时增加工具、监听事件、在 Web 页面里加一块交互区域,也可以给已有能力加一层审批、重试或日志。

我后面创建「产品评测编辑」时,它发现手里没有管理预设的工具,就临时写了一个 prst-1 插件,给自己加上读取、复制和校验预设的五个工具,然后接着把任务做完。

这种用法已经有一点自进化软件的意思: Agent 在执行任务时发现缺少能力,自己写出能力,装上以后继续工作。

但现在还只能算实验功能。动态插件的定义只存在于当前 DSH 进程,cordis_define 不会修改项目源码、配置或磁盘。服务一重启,刚才生成的插件就没了。

插件运行期间已经写到磁盘里的文件会保留下来,消失的是这套临时能力本身。要长期使用这项能力,仍然要把代码整理成正式插件,再通过 CLI 安装到 Profile 。

这里的热插拔指运行中的动态插件。从 GitHub 安装一款新的社区插件,当前版本通常还要在终端执行安装命令,再重启 Web 服务。

第一步:准备 Node.js 、 API Key 和一个工作目录

DeepSeek Harness 目前没有常见的桌面安装包。最省事的启动方式,是直接吧官网地址发给已经在用的 Agent ,直接让 Agent 安装就行。当然也可以用终端手动安装。

开始前准备两样东西:

1.电脑里已经安装 Node.js 和 npm ;
2.一个可以调用模型的 API Key ;

如果不知道 Node.js 有没有装好,可以在终端里分别输入:

node-v npm-v 

两条命令都能返回版本号,就可以继续。没有安装的话,先到 Node.js 官网[1] 安装当前的长期支持版本。

工作目录建议先选一个范围明确的文件夹。第一次尝试可以单独建一个测试目录,放几份不敏感的文档进去。先别把整个用户目录、桌面或装着重要资料的项目直接交给它。

第二步:用一行命令启动 Web UI

npx@deepseek-ai/dshweb 

第一次运行时,npx 会先下载所需的软件包,所以会比后面启动慢一些。如果终端询问是否继续安装,确认以后等它跑完即可。

看到服务启动后,在浏览器里打开:

http://127.0.0.1:3080 

想停掉服务,回到刚才的终端按 Ctrl + C。以后重新使用,再运行一次启动命令就行。

第三步:配好模型

首次进入页面后,需要先配置模型 API ,点左下角的“设置”,再打开“模型”。

如果使用 DeepSeek API ,就在这里添加 DeepSeek Provider ,填入自己的 API Key 。保存后回到会话页面,输入框右下角就能选择已经配置好的模型。

DeepSeek Harness 也支持其他内置 Provider ,以及兼容 OpenAI API 格式的自定义地址。

第四步:选择工作区

模型配好以后,回到“新会话”,点击工作区卡片,选择准备好的文件夹,选好以后, Agent 才知道去哪里读文件、把生成结果写到哪里。

如果项目里有 AGENTS.mdCLAUDE.md 或其他规则文件,也一起放在工作区里。后面跑第一个任务时,可以先让它复述自己读到了哪些规则,确认没有读错目录。

第五步:选模式,第一次用标准模式就够了

输入框左下角可以切换模式。当前版本内置了四种:标准、 PTC 、极简和创造。它们可以理解成四套已经装好不同插件的 Agent 预设。

标准模式的工具最完整,能够读写文件、运行 Shell 、搜索文件和网页,也支持 Skills 、计划、目标、子 Agent 和工作流。第一次使用,直接从这里开始最容易。

PTC 模式保留了标准模式的大部分能力,但模型会写一段 TypeScript 程序,把原本需要多次调用的工具组合起来执行。它适合需要大量重复工具操作的任务,第一次上手不用急着选。

极简模式只保留持久 Bash 和文件编辑器。它主要用来观察模型在很少工具的环境里怎样完成任务,也方便做模型能力测试。

创造模式在标准模式的基础上,多了检查当前运行环境、临时加载 Cordis 插件和创建 Agent 预设的能力。后面做“产品评测编辑”,我用的就是这个模式。

第六步:第一次先用只读权限检查环境

模式旁边还有一个权限菜单,目前可以选 Read OnlyWorkspace Write 和 Full access

Read Only 只能读取,适合第一次检查目录和材料;Workspace Write 可以修改工作区内的文件;Full access 会把范围放得更大,涉及工作区之外的目录时才可能需要。

第一次运行,可以先保持标准模式和 Read Only,给它一个很短的检查任务:

请先只读检查当前工作区,不要修改文件。  告诉我: 1. 这是什么项目; 2. 你读到了哪些项目规则; 3. 如果下一步需要修改文件,你准备改哪些文件; 4. 目前还缺少什么信息。 

这一步不追求产出,主要看三件事:工作区有没有选对,项目规则有没有被读取,模型能不能说清楚自己下一步准备做什么。

确认没问题以后,再切到 Workspace Write,把你真正需要处理的任务交给它。执行过程中如果要访问工作区外的目录,界面可能会弹出额外审批。没有看懂它准备做什么之前,不要直接把权限切到最大。

第七步:出错以后去“轨迹”里看

每个会话上方有“对话”和“轨迹”两个标签。平时聊天只看“对话”就够了;模型卡住、反复调用工具,或者你想知道它为什么花了这么久,就切到“轨迹”。

上方的时间线会把输入、模型运行和工具调用分成不同颜色。下面的记录可以查看具体工具名、参数、返回结果和报错。任务很长时,还可以按关键词搜索。

我一般先搜工具名,看同一个调用有没有在短时间里反复出现。接着看报错有没有重复,文件写入被哪一层权限拦住了。模型如果说任务已经完成,我也会在这里找对应的工具记录。

创建产品评测编辑时,我遇到过一次死循环。对话页只看得出任务迟迟不结束,切到轨迹以后,才发现它一直在用 bash 重复输出 echo stop 和 echo preset_list。这种情况继续等没有意义,直接停止会话、保留日志,再开一轮更省时间。

插件选了什么、工具怎么调用、哪里报错、跑了多久,轨迹都会留下来。

第八步:安装社区插件

设置里的插件页只能管理当前部署已有的组件,还不能像应用商店一样浏览和一键安装。

社区插件主要在 GitHub ,可以从 dsh-plugin Topic[2] 找。我打开时,里面的项目还不算多,搜索结果也会混进不相关的仓库。这个生态才刚开始。

安装之前,先打开插件仓库的 README ,检查来源、版本、依赖和它需要的权限。以社区的 dsh-at-file[3] 为例,它的 README 给出的安装方式是:

dshplugin--profilewebaddhttps://github.com/omdsh-dev/dsh-at-file/archive/refs/tags/v0.4.0.tar.gz 

如果电脑里没有全局的 dsh 命令,也可以沿用本文前面的 npx 方式调用同一个 CLI :

npx@deepseek-ai/dsh@0.1.0-rc.6plugin--profilewebaddhttps://github.com/omdsh-dev/dsh-at-file/archive/refs/tags/v0.4.0.tar.gz 

安装后停掉正在运行的 Web 服务,再重新启动。很多社区插件还要求浏览器强制刷新,具体以各自 README 为准。

上面的 dsh-at-file 只用来展示社区插件现在怎样安装,这次我没有实际装。

我用创造模式做了一个「产品评测编辑」

教程前面的步骤跑通以后,我才开始做这次真正想测试的任务。

我平时写 AI 产品评测,会反复用到一组规则。官方资料、亲身实测、分析推断和未验证信息要分开,失败过程不能删,产品架构也不能直接写成使用体验。材料不够时,先把缺口列出来。

这些要求每次都重新输入很麻烦,所以我想把它们做成一个可以重复使用的 Agent 预设,名字就叫「 Link AI 产品评测编辑」。

这次用的是 @deepseek-ai/dsh@0.1.0-rc.6,模型选 DeepSeek-V4-Pro High,模式选创造模式,文件权限是 Workspace Write

我让它直接复制标准模式,保留原来的文件、 Shell 、搜索和写作能力,再加入产品评测编辑的说明和 persona (角色提示词)。

第一轮没跑通。

模型发现自己需要 preset_listpreset_read 一类工具,却没有正确调用动态工具,而是陷进了前面提到的 bash 循环。我手动停止以后重新开会话,第二轮不再死循环,但检查了很久仍然没有创建出预设。

第三轮终于跑通了。它先用 cordis_define 定义一个临时插件 prst-1,再通过 cordis_run 把插件挂进当前会话。这个插件注册了五个工具:preset_listpreset_readpreset_copypreset_resolve 和 preset_validate

有了这几个工具,它先读取四套内置预设,再把 standard 复制成 link-ai-review-editor,修改预设名称、说明和 persona 。

写入时又被拦了一次。这次卡在权限上:Workspace Write 只能写工作区,而用户预设要保存到 ~/.dsh/.agent-presets/,这个位置在工作区外。界面弹出一次额外权限审批,我确认目标目录以后允许了这次操作。重试完成,preset_validate 返回 mounted OK,新预设随即出现在模式菜单里。

预设建好以后,我切到「 Link AI 产品评测编辑」,让它读取项目规则、已有文章、实测记录和官方资料,然后直接写本次 DeepSeek Harness 的评测稿。

这次写作会话从 14:40 左右开始, 14:48 左右结束, Harness 记录的总用时是 7 分 59 秒。它确实读了 AGENTS.md 和工作区里的材料,也完成了文章文件的写入。

跑到这里,这次测试也就结束了。预设最后建成了,也确实拿来跑完了一轮真实任务。

折腾了三轮,官网那句「一切皆插件」,我算是从头到尾体验了一遍。


参考链接

[1] Node.js 官网: https://nodejs.org/

[2] dsh-plugin Topic: https://github.com/topics/dsh-plugin

[3] dsh-at-file: https://github.com/omdsh-dev/dsh-at-file