大数跨境

全网最简单的 DeepSeek Harness 入门指南

全网最简单的 DeepSeek Harness 入门指南 AI大模型-木子
2026-11-15
0
导读:前两天把 DeepSeek 开源的 Harness 装上跑了一圈。社区里最热的一句评价是「国产 Claude Code」。这个说法,只对了三分之一。

前两天把 DeepSeek 开源的 Harness 装上跑了一圈。社区里最热的一句评价是「国产 Claude Code」。
这个说法,只对了三分之一。

Claude Code、Codex 这类东西,我们习惯把它当成「一个产品」来看。但 DeepSeek 这次干的事,是把产品拆开,把里面那层壳子直接开源给你。

它叫 DeepSeek Harness,命令行简写 dsh,MIT 协议,目前是开发者预览版。官方给了一行公式,我觉得那是理解它的唯一入口。

1先记住这个公式

Agent = Model + Harness

模型是大脑,负责推理、决策、生成。Harness 是身体——工具、权限、会话记忆、执行循环、沙箱、存储、调度,全在它这儿。

图 1 Agent = Model + Harness,这次开源的是右半边

为什么要强调这个拆分?因为我们平时评价一个 Agent 好不好用,几乎都归因给模型。但真实情况是,同一个模型换一套 Harness,体验能差出两个产品。

工具描述写得含糊,模型就会选错工具;没有上下文压缩,长任务跑到一半就崩;没有断点恢复,进程一挂,前面半小时全白干。这三件事,模型一件都解决不了。

再加上一句:Harness 不绑定模型。DeepSeek 自己的模型能用,任何 OpenAI 兼容的端点也能接。这就是为什么它把「模型适配器」也做成了插件。

2五分钟跑起来

前提只有一个:装好 Node.js。然后一行命令。

# 启动 Web UI,默认自动打开浏览器
$ npx @deepseek-ai/dsh web

# 不想自动打开(SSH / 容器里常用)
$ npx @deepseek-ai/dsh web --no-open

图 2 从零到第一个任务,四步

默认起在 127.0.0.1:3080,本地启动会自动帮你开浏览器;走 SSH 的话只打印地址,因为那个转发端口归你的 SSH 客户端管。

首次启动会要 DeepSeek API Key,去 platform.deepseek.com 建一个。如果环境变量里已经有了,会直接跳过这一步。

进界面之后第一件事是选工作区——就是 Agent 能在哪个目录里干活。这一步别图省事选个巨大的目录,它的检索和搜索都在这个范围内跑,范围越大越容易翻到无关文件上。

想读源码或者自己改,也可以从仓库装:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

一个前提得说清楚:预览版迭代很快,官方明说会有破坏性变更。所以别把三个月前的教程当准,端口、模式名、模型名,一律以你终端和界面里看到的为准。

3四个模式,选错很浪费时间

界面上方有个模式选择器。官方叫 Agent Preset,本质就是一份插件清单——决定这次任务里 Agent 手里有哪些工具、用哪套系统提示词。

图 3 四个模式对照

标准模式(Standard)。日常选它。文件读写、终端、检索、Skills、计划、子 Agent、工作流全配好了。官方帮助里专门澄清过一句:批量任务不一定非得用 PTC,标准模式同样能写脚本批量处理文件。

PTC 模式。全称 Programmatic Tool Calling,早期叫 Code Mode,2026 年 8 月改成现在这个名字。差别在哪儿:标准模式里,模型每调一次工具,返回结果整段塞回上下文;PTC 模式下,模型写一段 TypeScript,用 run_code 去调工具,循环、条件、并发都能写在里面,最后只把输出交给模型。

中间数据不进上下文,所以又快又省 token。代价是它对模型的代码规划能力要求更高,一段程序写错了,排查起来比单次工具调用麻烦得多。

极简模式(Minimal)。最容易误解的一个,只给一个持久 Shell 和一个读图工具。很多人以为这是「新手友好版」,官方原话是:工具少,不代表对新手更容易。它是拿来测模型基线、做对比实验的,不是入门用的。

创造模式(Creator)。标准模式的全部能力,加上运行时检查和插件、预设的开发指引。你可以在里面让它帮你写一个插件,或者造一个自定义模式,保存之后会出现在模式选择器里。

两个必须知道的细节:
一,PTC 和极简默认是隐藏的,要在通用设置里打开「代码工作工具」才会出现。
二,会话一旦有内容,模式就锁死了。中途切模式,历史里的工具调用在新工具集下无法解释。所以第一个任务就选对,比后面补救省事。

4「一切皆插件」到底意味着什么

现在不少 Agent 工具都能配工具、配 MCP、配 Skills,但每家的「可扩展边界」画得不一样。dsh 把这条边界画到了最外面:模型适配器、会话日志、存储、调度、子 Agent、Web 界面,甚至 Agent 的主循环本身,都是插件。

图 4 Cordis 内核只负责装和卸,能力全在插件里

中间那个内核叫 Cordis,只干三件事:挂载插件、卸载插件、管理依赖。卸载一个插件,它注册过的能力全部消失,不留残余。这点很重要——很多框架的插件卸载是不彻底的,跑久了互相干扰,出问题还查不出来。

配置分三层,从下往上覆盖:Bundles 是官方打包好的插件集合,Profiles 是你机器上的具名装配方案,Patches 是你的覆盖层,能精确到某一个插件条目。三层本质上是一摞 cordis.patch.yml,上层盖下层。

所以在这个体系里,「安装一个插件」通常不是跑一条 install,而是往配置文件里加一行。

这个设计真正改变的东西有三个:

一,改配置不改源码。换模型、换沙箱策略、换 UI,都不用 fork 仓库。

二,规则能写成 JavaScript 表达式。所以可以做到「只在这个仓库生效」「只对这类文件生效」这种细粒度控制。

三,能自己造模式。组合工具和提示词,存下来就是一个新预设。官方演示里那个「番茄时钟悬浮插件」,就是直接在对话里让它写、装、验证完的。

5每一轮都留痕,这是它最像工程产品的地方

一个会话就是一条只追加的事件流:系统提示词、模型的推理内容、每一次工具调用和返回、上下文注入、子 Agent 的调度、压缩事件、权限变更,全部落进日志。

界面上有个 Trajectory 视图,能按来源查看这些记录。这个设计的价值在于——模型每一轮看到的历史,是从日志里重新推导出来的,而不是在内存里滚动累积的。所以 resume、fork、搜索、回放,全都基于同一条流。

出问题时你不用猜。可以直接看到是哪一步、哪个工具返回了什么,把它带偏了。这跟只看最终输出反推原因,完全是两种效率。

再往里一层,它还留了拦截点:每一步之前、工具执行前后、模型请求之前,插件都可以批准、改写、记录或者阻止。这是 hooks 那套东西的更底层版本。

6三道闸,别只装第一道

Agent 能跑命令、能改文件,所以权限设计比任何功能都关键。这块分三层,很多人只配了第一层就上生产。

图 5 沙箱、审批、守卫,缺一层都可能出事故

沙箱。三档:只读、工作区可写、完全放开。用系统原生隔离实现——Linux 上是 bwrap / Landlock,macOS 上是 Seatbelt,Windows 上是受限令牌。而且后端会老实告诉你它到底有没有提供承诺的隔离级别,不会假装做到了。

审批。危险操作先问再做,严格程度可按预设调档。删除、推送、装包这类动作,默认会拦一下。

守卫。这是插件,负责中断超时的工具调用、识别反复打转的循环。无限循环是 Agent 里最贵的 bug,不设最大轮次,一次线上调用能烧掉你半个月预算。

还有一条容易被忽略:凭据走独立通道,不进日志。日志里只留引用。所以你可以放心把会话记录发给别人一起排查,不用担心把 key 一起泄露出去。

7和 Claude Code 到底什么关系

这是最容易被误读的地方。Claude Code、Codex 是「成品 Agent」;dsh 是「用来组装 Agent 的运行时」。定位根本不一样。

而且它不排斥那两个。你可以把本地的 Codex、Claude Code 挂成它的子 Agent,让 dsh 去做调度和汇总。它不是来替换的,是来当包工头的。

接入方式有五种,覆盖面挺全,这点能看出它是给开发者准备的:

Web UI —— 本地浏览器用,最直观;Headless CLI —— 跑一个任务就退出,适合 CI;Python SDK —— 自带运行时,高层 turns 接口加底层 JSON-RPC;TypeScript SDK —— JSON-RPC 协议,服务和客户端都能自己封;ACP server —— 给编辑器和工具厂商对接用的。

协议上,MCP 服务器可以直接挂进来,和内置工具走同一条管道。另外还有个 hooks 桥接,你在 Claude Code / Codex 里写的 hook 脚本,大概率能继续用。

8几个真会踩的坑

版本。预览版,官方明说会有破坏性变更。团队用就锁版本,别追 latest。

模式。选错 + 锁定,只能重开会话。第一个任务就选标准。

沙箱。别一上来就完全放开。先工作区可写,跑顺了再考虑放宽。

插件兼容性。社区插件很多,装之前先看它适配哪个版本,功能有没有被官方实现取代。

成本。Harness 本身 MIT 免费,钱花在模型 API 上。PTC 之所以省,是因为中间数据不进上下文——这一点在批量任务上差得很明显。

· · ·

写在最后

用了两天,我的判断是这样的。

如果你只是想要一个顺手的编程助手,标准模式够用,但它不会比你手上那个更好——预览版在产品打磨上确实还粗糙,术语默认你懂开发,第一次装还是得有点耐心。

它真正的价值在另一头:如果你想让 Agent 长成你想要的样子——换掉主循环、换掉 UI、加一层自己的审批策略、把公司内部系统做成工具——这个层级的可替换性,目前市面上确实不多。

它不是「又一个编程助手」,是一个把 Agent 拆成零件的运行时。想清楚你要的是成品还是零件,再决定要不要装。

你现在更想要成品,还是零件?

· · ·

【声明】内容源于网络
0
0
AI大模型-木子
日常分享Ai大模型干货教程。关注我,普通人也能学Ai大模型!
内容 8
粉丝 0
AI大模型-木子 日常分享Ai大模型干货教程。关注我,普通人也能学Ai大模型!
总阅读159
粉丝0
内容8