DeepSeek 发布 Harness(下文简称 dsh)那天,很多人拉到本地跑起来的第一反应是:界面怎么这么像 Codex?单从 UI 上看不出什么差异。但一个「和 Codex 长得差不多」的东西,为什么值得 DeepSeek 专门做一套?
答案藏在源码里。这篇基于 dsh 0.1.1-rc.2 的源码阅读与试用,不打算从架构图逐项拆模块,而是沿着阅读路径走一遍:先看最本质的 Agent loop,再顺着两个「没看懂的模式」往下挖——一个是把多次工具调用压成一次的 PTC 模式,一个是让模型在运行中自造工具的创造模式——最后落到承载这一切的底层框架 Cordis。
本文基于百度 Geek 说公众号文章 《DeepSeek Harness:重新设计 Agent 运行时》(作者 Cheer)整理,代码与结论引自原文,部分示意图为本文重绘,评论与引申为笔者补充。除源码外,文中部分个人观点不代表 DeepSeek 官方定位。
1. 起点:所有 Agent 都绕不开的那个循环
看一个 Agent 实现,我习惯先找最本质的那段:它的循环长什么样。
把 Agent 说得简单一点,它本质上就是一个围绕 LLM 的循环:把工具交给模型,模型决定是否调用;如果调用,Agent 执行工具、把结果带回下一轮请求,直到模型给出最终文本。
const messages = [systemPrompt, userMessage]
while (true) {
const reply = await llm(messages, tools)
if (!reply.toolCalls.length) return reply.text
for (const call of reply.toolCalls) {
messages.push(await runTool(call))
}
}一次调用里,Agent 把规则、工具定义和对话消息一起发给 LLM;模型返回工具调用后,Agent 执行工具、把结果追加回消息,再进入下一轮。把这个最小循环画出来,就是一个模型、一个工具执行器、一条回环消息链:
┌──────────────┐
│ LLM 模型 │◄──────────┐
└──────┬───────┘ │
tool_calls? messages
┌──────▼───────┐ │
│ 工具执行器 │───────────┘
└──────────────┘ 把结果追加回消息Codex、Claude Code,以及眼下大多数 LLM + Agent 架构,在这个最小抽象层上都差不多。dsh 也一样——在 packages/core/agent-loop/src/agent.ts 里,它的基本循环没有不同:外层按待处理输入推进 turn,内层不断执行 step,每一步请求模型并处理 tool call,直到模型不再调用工具。
看到这里有点扑空:既然核心流程注定长一样,DeepSeek 为什么还要自己做一套 harness?
2. 动机:Agent 之后要解决的是「持续学习」
答案要往 DeepSeek 的长期路线上找。梁文锋在投资人会议实录里给出的 AGI 实现路径,被描述成爬楼梯:去年那级台阶是 CoT(思维链),今年这级是 Agent,Agent 之后要解决的问题是持续学习。实现持续学习之后,可能来到一个渐进的奇点——模型能完成人类能做的所有事,包括自己开发更前沿的模型,也就是 AI 加速 AI 的研究。
顺着这个方向做一个假设:dsh 这套 harness,就是在为「持续学习」这个长期目标搭建运行时基础。
这里的「持续学习」不等同于模型训练层面的持续学习,而是 Agent 系统能把新能力沉淀下来、在后续运行中继续使用。顺着这个假设,很多取舍就好理解了:模型现在能执行任务、能推理,却攒不下经验——一次会话结束后,这些经验不会自动沉淀成下一次可复用的能力。要让模型自己开发更前沿的东西,运行时得先允许它修改自己的能力边界。
带着这个想法再翻 dsh,会发现它出厂带四个 Agent 模式:极简、标准、PTC、创造。前两个看名字好懂,后两个让人迷惑。就从这两个看不懂的开始。
3. 四个模式:不是四套 loop,是四套能力配置
先纠正一个直觉:四个模式不是四种完全不同的 Agent loop,而是四套预先组合好的能力配置——每套配置决定当前会话用哪些工具、提示词和其他运行能力。
一个模式实际就是一个目录加一份配置文件:
- id: tool-bash
name: '@deepseek-ai/dsh-tool-bash'
- id: tool-presentation
name: '@deepseek-ai/dsh-agent-tool-presentation'
config:
mode: code标准、PTC、极简、创造都是这样的能力配置。切换模式,切换的是当前会话要装入哪一套能力,而不是在一份大配置里逐项开关。PTC 模式额外选了 Code Mode,创造模式则增加了操作运行时的工具。那两个「看不懂」的模式,落到配置文件上,其实就是能力组合的差别。
4. PTC 模式:把多次往返压成一次
PTC,即 Programmatic Tool Calling(程序化工具调用):模型用一段程序把已有工具组合起来,改的是调用流程,不是工具本身。
标准模式下,每个工具都是一个声明好参数的函数,模型发一个调用、拿到结果、再发下一个。单步任务没问题,可一旦要在一批结果上循环、按中间值走分支、或并发几路再汇总,每一小步都要占一次完整的模型往返。
举个具体任务:找出仓库里所有写了 TODO 的文件。标准模式下的流程是这样的:
模型 → grep("TODO") → 回来 40 个文件名
模型 → read(文件 1) → 回来整个文件
模型 → read(文件 2) → 回来整个文件
...每一趟往返都是一次完整请求,而且无论后续是否需要,这些中间结果都会回到上下文,占用额外空间。
PTC 换了个呈现方式:不再让模型通过多轮调用反复组合 grep 和 read,只给它一个写程序的入口,工具变成程序里可以调的函数:
const files = await tools.grep({ pattern: 'TODO' })
const hits = []
for (const f of files) {
const text = await tools.read({ path: f })
if (text.includes('TODO')) hits.push(f)
}
return hits // 只有这一行的结果回到上下文dsh 在本地执行这段程序,再把程序返回的结果交回模型。这个例子里,中间读文件的结果只在程序内部使用,最终数组才回到模型。PTC 那份配置文件的注释写得更直白:「a sequence that would be five round trips becomes one」——五次往返变成一次。
本质上变的不是工具,而是工具呈现给模型的方式:
| 标准模式 | PTC 模式 | |
|---|---|---|
| 模型的动作 | 从工具表里挑一个发调用 | 照着类型声明写一段程序 |
| 请求里的工具 | 每个工具一个可调用函数 | 只有一个 run_code |
| 中间结果 | 每次都回上下文 | 只在程序内部,最终结果才回 |
| 多次组合 | 每次组合 = 一次完整往返 | 一次往返内完成 |
| 来源 | 通用 tool-calling | 源自 Cloudflare 的 Code Mode |
Code Mode 的具体做法:为 Agent 提供一段类型声明放进系统提示——一个 tools 对象,每个工具在参数表和返回值表里各占一行,工具描述作为注释挂在旁边。请求里真正可调用的只剩一个 run_code,它收两个参数:程序体 + 一句说明。上面那段程序能写出 await tools.grep(...),就是因为声明里有 grep 这一行。
这个思路来自 Cloudflare 的 Code Mode,理由是:模型见过几百万行真实代码,见过的 tool-calling 轨迹要少得多,所以它写程序比发调用更顺手。
需要注意两个实现细节:程序里的子调用没有绕过 dsh 的工具管线,仍会经过前置钩子、监控守卫、执行和结果处理;程序本身则在一个新开的 Worker 线程里运行,权限上按 bash 同级对待,并发也受上限控制。
5. 创造模式:把挂载口交给模型
PTC 让模型在一次请求里组合已有能力。再往前一步,是让它往运行时里加一个原来没有的能力。
创造模式允许模型在运行过程中提交一个插件,把原本不存在的工具注册进当前运行时;用完或需要替换时,再停止并撤销这个插件。整个过程四步:
- 检查当前运行时已有的插件和能力,发现缺口;
- 提交一段插件代码;
- 显式启动某个版本,新工具从下一轮模型请求开始可用;
- 需要改版或失败时停止当前版本,并按需恢复旧版本。
几个关键限制决定了它的边界:
- 提交的单位是插件,不是工具。 工具只有在插件启动时才会被注册,插件停止时,工具也随之撤销。
- 提交和运行分离。 提交时运行时先保存并检查插件代码,但不立即执行;模型显式启动某个版本后,插件才真正运行。
- 版本可回退,但有讲究。 同一个插件可以提交多版本;更新时先停旧版再启新版,若新版失败,旧版保留但需显式重启(不自动恢复)。能回退的是插件版本和运行时登记,不是已经写入文件、数据库或外部服务的副作用。
和常见 Agent「会话开始时固定工具表」不同,dsh 允许会话进行中增加、替换和撤销工具。但这些动态插件只活在进程内存里,重启 dsh 就消失;想把结果留下来,仍需走常规流程整理成正式插件。
把两个模式并排看,方向就出来了:PTC 让模型编排已有工具(改编排方式),创造模式让它提交插件新增工具(改可用能力)。先编排、再造工具,这可以看成自进化的两个台阶。
6. 底层:Cordis 的时间与空间两个维度
更底层的答案不在某个 packages/ 插件里,而在 vendor/ 中那套名为 Cordis 的框架,仓库里还配着一篇题为 A Programming Paradigm for Spatiotemporal Composability 的论文(作者来自北大和 DeepSeek)。
论文第一句就把动机说清:现代软件——从插件系统到自我演化的 Agent harness——越来越需要动态组合,但其形式化基础仍不成熟。它把动态组合拆成两个正交维度:
- 时间维度:一个组件被移走时,它对环境做过的改动能不能全部退回去?
- 空间维度:组件之间的依赖能不能写明白、被找到,并在依赖换人时自动重新接上?
创造模式要的正是这两条:中途撤掉一个插件不能留残骸,换掉一个别人在用的组件不能把用它的人弄坏。
看一个具体场景——一个插件提供数据库,另一个依赖它:
const databasePlugin = {
apply(ctx) {
const db = createDatabase()
ctx.provide('db', db)
return () => db.close()
},
}
const queryPlugin = {
inject: ['db'],
apply(ctx) {
ctx.db.query('select ...')
},
}第一个插件启动时创建数据库连接并命名为 db;第二个声明自己需要 db,启动后通过 ctx.db 使用。
6.1 时间维度:可撤销效应(revertible effects)
插件装上时可能注册事件、工具和服务,也可能创建定时器、连接或子进程。传统写法要求作者在另一处手动补齐卸载逻辑,漏一项,插件被移除后就留下仍在运行的资源。
Cordis 的做法,是要求那些需要随插件生命周期回收的操作通过 ctx 登记,归到当前插件实例名下;插件卸载时,运行时找到这批操作并执行对应的清理函数:
export function apply(ctx) {
ctx.on('message', handler)
ctx.effect(() => {
const timer = setInterval(poll, 1000)
return () => clearInterval(timer) // 清理函数
})
ctx.tools.register(myTool)
}监听器、工具和定时器都属于当前插件。插件停止时,监听器和工具登记被撤销,定时器执行 ctx.effect() 返回的清理函数。论文把「执行改动时同时把撤销动作交给运行时管理」的机制称为可撤销效应。
它的能力边界同样明确:Cordis 能回收通过 ctx 登记的运行时资源,但不会自动回滚插件已经写入文件、数据库或外部服务的业务副作用——清理函数是否真能恢复状态,仍由插件作者负责。
6.2 空间维度:响应式余效应(reactive coeffects)
再看数据库插件。普通依赖注入只解决启动时「调用方拿到哪个实现」,但插件如果已经通过 get() 拿到了 db v1,容器后来换成 db v2,旧引用不会自动更新。
Cordis 把依赖写成插件的一条声明 inject: ['db']。关键差异在于:inject 不是一次性取值,而是一张运行条件清单。db 没准备好时,插件不会先启动再报错,而是保持等待;db 被撤销或替换时,运行时找到声明了这项依赖的插件,让它们重新检查运行条件。
提供者注册 db → 找到声明了 db 的插件 → 重新检查依赖是否满足
→ 依赖失效,卸载旧运行 → 新依赖可用,重新执行插件所以数据库从 v1 换成 v2 时,Cordis 不会把新对象直接塞进旧插件,而是先结束旧的一次运行、清理旧资源,等 v2 可用后再重新执行插件。使用方重新建立的依赖视图来自新的提供者,不会继续握着失效的旧连接。
这正是 Cordis 与普通依赖注入的关键差异:它不只负责「把实现交给调用方」,还把依赖变化纳入插件生命周期,负责通知使用方、停止旧运行、重新建立新运行。论文称之为响应式余效应——组件先声明依赖什么,运行时在环境变化后重新判断依赖是否满足,并据此启动、停止或保持组件状态。
6.3 回到 dsh
dsh 的动态工具、工具表、模型服务和 Agent loop,都可以放进「提供能力、声明依赖、随组件生命周期装卸」的模型里。创造模式提交的不是孤立工具而是插件,插件启动时登记工具、停止时撤销工具。未来若模型能力、调用协议或 Agent 工作方式发生破坏兼容的变化,dsh 可以通过替换对应插件来承接新实现,而不必把整个运行时推倒重来。
不过要把论文能力与实际运行分开看:当前版本默认配置里,只有创造模式预装了 Cordis 插件工具,模型只有在这个模式下才能运行中定义、启动、停止动态插件。普通插件安装流程并不会让已经运行的 dsh web 自动发现并挂载新插件,通常仍要重启 dsh web。也就是说,Cordis 在框架层提供了热插拔与依赖协调的基础,但还没有完全贯通到 dsh 的常规安装部署流程里。
上面这一节只讲了 Cordis 的「时间/空间两个维度」的结论。它的形式化推导——Revertible Effects、Reactive Coeffects、Fiber 惯性状态机,以及 Theorem 16/70/73/80 与源码的逐条对应——见 Cordis:时空可组合性——动态组合的形式化。
7. 三个层次,别混为一谈
到这里可以总结出 dsh 的三层结构:
- 模式配置决定当前会话一开始带哪些能力;
- 插件机制负责这些能力在运行过程中如何增加、替换和撤销;
- Agent loop 是驱动模型请求和工具执行的共享运行部分。
切换模式只改变能力配置,不会替换 Agent loop;一份模式配置通常在运行期间建立一套共享插件注册,多个会话可复用这些工具和提示词贡献,而需要按会话区分的运行状态仍由各自的 Agent 和 Session 独立保存。
8. 判断:运行时骨架,而非成熟产品
回到「持续学习」这个问题:模型是否真正具备持续学习能力,取决于训练方式、记忆机制以及模型本身的演进。dsh 目前提供的是另一层能力——让 Agent 在运行中临时增加、替换和撤销能力。动态插件只活在进程内存里,改起来快、重启就消失;preset 则以目录和配置文件保存,后续创建的会话仍能发现使用。两者都能改变 Agent 能力,但生命周期不同。
作者对 dsh 的产品状态判断是:更侧重运行时的组合与替换,距离 Codex 和 Claude Code 的完整体验还有差距。从 Agent 核心 loop 看,大家的基本逻辑没有拉开太大差距,体验差异更多来自工具质量、提示词、默认工作流以及各种细节的打磨——这些工作不像重写一套运行时那么显眼,却都需要长期投入。
所以更稳妥的定位是:dsh 是面向未来自进化 Agent 的一种设计思路,先把插件化、动态组合、可撤销、可重连这些基础能力的骨架搭好;真正决定使用感的插件内容、preset、模型适配和默认工作流,还要继续迭代。如果未来的持续学习包含系统层的能力沉淀,留下来的不一定只有模型参数,也可能是一个新工具、一段角色设定、一套工作流、甚至一整套插件组合——到那一步,自我迭代就可能表现为插件树的持续演化。
9. 对我们的启发
抛开 dsh 本身,这套设计里能带走的东西不少。
① 先问「loop 之外」还有什么。 所有 Agent 的 loop 都大同小异,真正的差异在 loop 之外:工具质量、提示词、工作流、运行时能不能承载能力变化。如果只盯着 loop 优化,很难做出差异化。
② 该不该上 PTC,看任务形态。 如果你的 Agent 经常做「循环一批结果、按中间值分支、并发几路再汇总」这类任务,多次往返的 token 与延迟成本会迅速累积,值得评估 PTC 式的「程序化组合」;如果只是单步调用工具,PTC 的收益不大。
③ 动态工具 ≠ 动态插件,别把粒度搞错。 dsh 强制「提交单位是插件而非工具」,因为工具的注册/撤销必须挂靠在一个可管理生命周期的单元上。自建类似机制时,先想清楚最小可撤销单元是什么、它依赖什么、停了会怎样。
④ 可撤销能力是动态系统的前提。 想支持运行中装卸,就必须先解决「装了之后怎么干净地退」——把撤销动作和注册动作绑在一起(ctx.effect 的思路),比事后到处补卸载逻辑可靠得多。同时清醒认知边界:运行时能回滚的是自己登记的资源,不是业务副作用。
⑤ 依赖变化要纳入生命周期,而不只是一次注入。 普通 DI 只在启动时装配一次;真正动态的系统要把「依赖失效→通知→卸载→重连」做成闭环。这正是 Cordis 的响应式余效应要解决的。
⑥ 分层看一个框架的成熟度。 框架层的「能热插拔」和产品层的「安装即生效、替换不重启」是两回事。评估 dsh 这类系统时,把「论文能力」「框架能力」「产品贯通度」三件事分开打分,才不会高估或低估。
参考资料
- DeepSeek Harness:重新设计 Agent 运行时 — 百度 Geek 说,作者 Cheer
- A Programming Paradigm for Spatiotemporal Composability — 北大 & DeepSeek(Cordis 论文)
- Code Mode — Cloudflare Agents docs(PTC 思路来源)
- Cloudflare Code Mode:让 LLM 写代码而非调工具 — 本文关联阅读