DeepSeek Harness Agent 框架的详解"微内核时刻"：一切皆插件,连 Loop 都能热插拔

2026 年做 Agent 的人,大概都有过这样的经历:换了个模型,重写一遍工具注册;换了个场景,重写一遍主循环;想给会话加个断点续跑,发现状态散落在七个模块里,谁也不敢动。每个团队都在重复发明同一套东西——loop、工具调度、上下文管理、session、沙箱——而且发明得都不太一样,也都不太能复用。 与此同时,行业悄悄形成共识:**模型决定能力上限,harness 决定实际下限**——同一个模型换个脚手架,表现判若两"模",Claude Code 们真正的护城河,一大半在模型外面那圈工程里。 DeepSeek 对这个乱局出手了。 DeepSeek Harness(简称 dsh)以 MIT 许可开源,v0.1 开发者预览版上线,底层由名为 Cordis 的元框架驱动,同日还发布了一篇阐述其设计范式的论文。它只押注一个核心理念——**一切皆为插件**:模型、工具、技能、会话、沙箱、文件系统、循环、编排、UI,九类能力全部以插件实现,可以自由混搭、替换、扩展。 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 。 这篇文章不做发布通稿的复读机。我把仓库文档、官方产品页和社区讨论翻了一遍,想回答的是给 Agent 开发者和框架设计者的问题:"一切皆插件"在工程上到底怎么落地?哪些设计值得直接抄进你自己的 harness?以及,插件化的账单背面写着什么? --- ## 一、正名:什么是 Harness,为什么 2026 年它成了兵家必争之地 先把概念钉死,因为"harness"这个词在中文圈还没有稳定译法,很多讨论一开口就歪了。 Harness,直译"马具、束具",在 Agent 工程语境里指的是**包裹在模型外面的那一整圈运行时**:主循环怎么转、工具怎么注册与调度、上下文怎么组装与裁剪、会话怎么持久化、代码在哪个沙箱里跑、失败了怎么恢复。它不是模型,也不是某个具体 Agent 应用,而是介于两者之间的那层"底座"。 为什么这层东西突然值钱了?因为过去一年整个行业被反复上了一课:**换 harness 带来的体验差,常常大于换模型**。同样的旗舰模型,接在一个粗糙的循环里,表现平平;接在一个精心设计的 harness 里——上下文管理得当、工具返回处理细腻、失败有重试策略——立刻脱胎换骨。各家 benchmark 报告里越来越常见的一个脚注也是佐证:"成绩依赖于所用 harness"。模型能力在收敛,harness 工程在分化,竞争的重心自然就漂移了。 但 harness 领域此前的状态,用一个词形容就是"各自为战":闭源产品(Claude Code、Codex CLI 这一档)的 harness 与自家模型深度耦合,不开放;开源框架要么是上一代的重量级编排库,要么是每个团队攒的私有轮子。社区里流传的自嘲很传神:我用的 harness 已经多到,需要再来一个 harness 管理这些 harness 了。乱局的病根,是**缺一个开放的、中立的、专门为"被替换"而设计的底座**——这正是 dsh 报的位置。 dsh 的基本盘,发稿时的事实是:MIT 许可(注意,不是什么社区定制许可,是真·宽松);v0.1 开发者预览,官方用大写字母明示"必然会有破坏性变更";TypeScript 技术栈,pnpm 构建,npx 可直接拉起,自带 Web UI(默认 127.0.0.1:3080);GitHub 上已有约 5000 star、300 fork,Discord 与 Discussions 社区已经转起来了。 一句话:这是一个诚实标注了"毛坯房"的项目,但地基的设计图,值得每个做 Agent 的人细看。 --- ## 二、Cordis:一个从聊天机器人社区长出来的元框架 dsh 最有故事性的部分,是它脚下的 Cordis——而这个故事,中文读者应该格外有共鸣。 先说 Cordis 是什么。官方文档的定义很克制:一个小型插件运行时,所有能力——工具、LLM 适配器、文件访问、乃至 Agent 循环本身——都是挂载到共享上下文(context)里的插件。拆开看,它的概念模型就三件东西: **第一,插件(Plugin)。** 形态极简,三种写法:一个带 `apply(ctx)` 的函数、一个带 apply 方法的对象、或者一个 Service 子类。没有框架引导代码,插件只声明"我贡献什么",由配置文件 `cordis.yml` 负责把整个应用组合出来。 **第二,上下文(Context)。** 本质是一个**服务仓库**。每个服务认领一个稳定的键,比如 `ctx.llm`、`ctx.tools`、`ctx.sessions`;其他插件**按键发现服务,而不是按实现导入**。这一条是整个架构的依赖倒置支点:调用方只认识 `ctx.llm` 这个键,背后是 DeepSeek 的模型、开源模型还是任何第三方适配器,一行调用代码都不用改。 **第三,可逆副作用(Reversible Effects)。** 这是 Cordis 最硬核也最容易被低估的设计:插件的每一次注册——事件监听、连接、内存分配、handler——都是一个记录在案的 effect,**插件卸载时全部自动回滚**,不留残渣,也不打扰其他插件。热插拔和 HMR(热重载)不是靠"重启进程"糊弄出来的,而是靠副作用账本一笔笔清算出来的。 图表说明:Cordis 的微内核式结构——context 充当极简内核,只提供服务注册与发现;所有实际能力由外围插件认领服务键接入,注册均为可逆 effect。  然后是出身。社区讨论里被反复提起的一个细节:**Cordis 不是为 dsh 新造的轮子**——它的 v3 版本已经在一个叫 Koishi 的项目里实战了四年,这次随 dsh 登场的是 v4,并配套发布了设计论文《A Programming Paradigm for Spatiotemporal Composability》。Koishi 是中国开源社区孕育的跨平台聊天机器人框架,插件生态是它的立身之本;换句话说,**一个在中文开源社区里被聊天机器人场景磨了四年的插件运行时,如今被一家前沿模型实验室选中,成了 Agent 底座的内核**。 这条路径本身就是个信号:聊天机器人框架十年里踩过的坑——插件热更、依赖管理、多平台适配、社区生态治理——恰好是 Agent harness 今天要重踩的坑。DeepSeek 没有从零造,而是把社区里已经被验证的答案捡了起来。开源世界最好的样子,大概就是这样。 --- ## 三、"一切皆插件"的架构解剖:没有特权核心 理解了 Cordis,再看 dsh 的架构宣言就不觉得夸张了。官方架构文档里最重要的一句话,我转述如下:**产品的每个部分都是插件——模型适配器、工具注册表、会话日志、乃至 Agent 循环本身——所以每个部分都可以从配置层面被替换;不存在一个需要打补丁的特权核心,扩展 dsh 的方式是在其他插件旁边再挂一个插件。** 工程落地是一套分层组合机制:一个运行中的 dsh,是启动时按有序层级组装出来的**插件树**。`cordis.yml` 描述组合关系;**profile(配置档案)**是存放在 Harness 主目录里的命名组合,声明它叠了哪些插件包、装了哪些树外插件、以及用户自己的 `cordis.patch.yml` 补丁;官方发行自带 web 和 headless 两个模板档案。你想换掉某个能力?改配置,不改源码。 熟悉软件史的读者,此刻脑子里应该已经浮出两个参照物了。 一个是 **VS Code**:极小的核心加扩展宿主,连很多"内置功能"都是以扩展形式实现的——这套架构让它赢下了编辑器战争。另一个是**微内核操作系统**:内核只管最小机制,文件系统、驱动、网络全部跑在核外服务里。dsh 的野心比 VS Code 还激进一格:VS Code 的核心编辑循环终究是核心,而 dsh 连"循环"这个通常被视为框架灵魂的东西,也放进了插件位。 这带来一个微妙但重要的性质:**框架作者与插件作者的权力是对等的**。在传统框架里,"官方功能"走的是内部 API,第三方扩展走的是受限的外部 API,二等公民感明显;在 dsh 里,官方的模型适配器和你写的模型适配器,挂在同一棵树上,用同一套服务键,享受同一套可逆 effect 待遇。这种"官方不留后门"的对等性,是插件生态能不能长大的关键变量——Eclipse 和 VS Code 的插件生态之所以繁荣,底层原因都在这。 --- ## 四、最激进的一步:连 Loop 都是插件 九类插件位里,最值得单独拿出来讲的是 loop——因为它动的是所有 Agent 框架最不敢动的地方。 绝大多数框架里,主循环是"宿命":框架作者选定了 ReAct 也好、plan-and-execute 也好,你用这个框架,就接受了这个循环范式。想换?等于换框架。但 Agent 领域偏偏是**循环范式还在高速演化**的领域——单步工具调用、多步规划、代码编排、树搜索、多智能体调度,每半年都有新范式冒头。把 loop 焊死在框架里,等于给框架预定了保质期。 dsh 把 loop 做成插件,而它自带的四种运行模式,就是这个设计的第一组活体证明——**模式不是代码分支,而是插件组合**: **Standard 模式**,完整工具集,日常主力。**Code 模式**,由模型生成代码来编排多轮工具调用——熟悉文献的读者一眼能认出这是 CodeAct 一系的范式:让模型写代码当"胶水",一段代码顶过去十几轮往返的 tool call。**Minimal 模式**,只保留一个 shell 工具和一个文件编辑器,官方明说用途:在最小环境里对模型做基准测试。**Creator 模式**,可以内省当前运行时、在内存中测试 Cordis 插件、并把它们组合成新模式——一个拿来造模式的模式。 图表说明:同一个插件池,通过配置组合出四种官方模式;模式即组合,而非硬编码分支。  我想特别抬一下 **Minimal 模式的深意**,这一点发布材料只用了一句话带过,但对做评测的人价值极大。前面说过,benchmark 成绩越来越依赖 harness——那么评测模型时,harness 就成了一个**混淆变量**:你测出的到底是模型的能力,还是脚手架的功力?Minimal 模式等于官方给出了一个"控制变量"开关:把 harness 压到最小(一个 shell、一个编辑器),模型的裸能力就被剥离出来了。反过来,固定模型、切换插件组合,你测的就是 harness 本身。**把"评测的对照组"做成产品功能,这是我第一次在开源 harness 里看到。** 再往前想一步:编排(orchestration)与子代理调度同样在插件位上。这意味着"单智能体循环"与"多智能体协作"在 dsh 里不是两套系统,而是同一棵插件树上的两种组合——今天跑单循环,明天要上 subagent 分工,理论上换的是编排插件,不是重写应用。多智能体范式眼下还在剧烈演化,谁也说不准明年的主流形态;把编排做成可替换件,等于给这份不确定性买了保险。 --- ## 五、被低估的杀手锏:Append-only 会话日志,轨迹的事件溯源 如果说插件化是 dsh 的骨架,那会话子系统就是它藏在骨架里的杀手锏——发布讨论里,海外工程师社区反应最热烈的其实是这一条。 官方描述值得完整转述:**模型看到的一切,都被记录在一份 append-only(只追加)的会话日志里**——系统提示词、推理过程、工具调用与结果、子代理调度、以及每一次上下文注入。Trajectory(轨迹)视图里可以按来源逐条审计这些记录;而 resume(续跑)、fork(分叉)、search(检索)、replay(重放)四种操作,全部构建在**同一条事件流**之上。 做过后端的读者立刻能对上号:这是**事件溯源(Event Sourcing)进了 Agent 运行时**。状态不是被覆盖的快照,而是事件的累积;任何历史时刻都可以重建,任何分支都可以从中间长出来。类比一下:git 之于代码,就是这条 session log 之于 Agent 行为。 图表说明:一条 append-only 事件流,同时支撑审计、续跑、分叉与重放四种操作——事件溯源思想在 Agent 运行时的落地。  这个设计解决的是 Agent 工程里最疼的三件事。**调试**:Agent 出了怪行为,以前你对着残缺的日志猜"它到底看到了什么";现在上下文注入逐条在案,按来源过滤,水落石出。**实验**:想验证"换个 system prompt 会不会好"?fork 一条历史轨迹,改一个变量,重放——这是 Agent 的 A/B 实验台,而不再是玄学调参。**回归**:harness 升级后老任务还能不能跑对?replay 全量轨迹,diff 结果。 还有一层对比价值,来自社区讨论(观点转述,非官方口径):闭源 Agent 产品的执行轨迹往往是加密或混淆的,你花钱买的是黑箱;而 dsh 把**全透明可审计**做成了默认属性。在企业越来越关心"Agent 到底替我干了什么"的 2026 年,可审计性本身就是开源 harness 对闭源产品最锋利的差异化武器。 --- ## 六、给开发者与设计者的六个要点 铺垫完毕,进入这篇文章真正想交付的部分。无论你是打算用 dsh、抄 dsh,还是继续维护自家的 harness,以下六条是我从这次发布里提炼的设计要点——每一条都对应一个可以立刻检查自己系统的问题。 **要点一:设计接缝,而不是设计功能。** dsh 最大的启示不是它实现了九类能力,而是它把九类能力定义成了九个**接口承诺**:模型、工具、技能、会话、沙箱、文件系统、循环、编排、UI。功能会过时,接缝决定寿命。检查你自己的 harness:这九个位置,有几个是能不改源码就换掉的?换不掉的那几个,就是你未来的技术债所在。 **要点二:服务按键发现,把依赖倒置贯彻到底。** `ctx.llm` 这一个键,隔离了调用方和所有模型实现。这条老原则(面向接口编程)在 Agent 时代有了新的紧迫性:模型的更换频率,已经从"按年"变成了"按月"。如果你的代码里还散落着对某个具体 SDK 的直接 import,每次换模型都是一次小手术。 **要点三:副作用必须可逆——写插件先想"卸载时如何清场"。** Cordis 的可逆 effect 是热插拔的全部底气:注册有账,卸载清算。这对写插件的人是一个思维翻转:传统思维是"启动时把东西装好",Cordis 思维是"每装一样东西,同时登记怎么拆"。哪怕你不用 Cordis,这个纪律也值得引入——所有做过长驻服务热更新的人,都为"卸不干净的状态"流过泪。 **要点四:把 Loop 当策略,不当框架。** 检验一个 harness 设计水平的最狠问题:**换掉主循环,需要动多少代码?** dsh 的答案是"零,改配置"。你的答案如果是"重写",那么下一次循环范式迁移(它一定会来)时,你换的就不是循环,是整个框架。设计层面的操作建议:把"感知—决策—行动—观察"的循环骨架抽成接口,让 ReAct、CodeAct、树搜索成为该接口的三个实现,而不是三套系统。 **要点五:轨迹先行——先设计事件流,再设计功能。** dsh 的 resume/fork/replay 不是三个功能,是同一条 append-only 事件流上的三个视图。这个次序值得抄:**先定义"哪些事件构成完整轨迹",再让一切功能消费这条流**。反过来做(先堆功能、后补日志)的系统,日志永远是残缺的,复现永远是玄学。评测、调试、合规审计,三件大事都长在这条流上。 **要点六:用"Minimal 模式思维"做评测。** 固定最小 harness 测模型,固定模型测 harness——把混淆变量拆开,一次只测一个东西。哪怕你不用 dsh,也应该给自家系统留一个"最小配置"档位:它是你的评测对照组,也是你排查"到底是模型笨还是脚手架烂"时的第一现场。 把六条压成一张自查清单,建议直接带去下一次架构评审:①九个能力位,有几个能不改源码就替换?②换一个模型,要动几个文件?③任一插件卸载后,它的状态与副作用能清零吗?④换主循环的成本,是改配置还是重写?⑤系统的完整轨迹,今天能逐条重放吗?⑥有没有一个"最小配置"档位可做对照实验?六问全绿的系统,2026 年也不多见;能答对四问,你的 harness 已经赢过大多数自研轮子。 --- ## 七、冷水:插件化的税,和微内核的历史课 按惯例,吹完要泼水。"一切皆插件"不是免费午餐,历史上类似的架构豪赌,输过的比赢过的多。 先上历史课。三十多年前,Tanenbaum 与 Torvalds 那场著名论战里,学院派断言微内核是未来、宏内核是倒退;结果统治世界的是"不优雅"的 Linux,而架构完美主义的 GNU Hurd 至今没有交付出主流可用的系统。教训不是"微内核错了"——后来 VS Code、Eclipse 用插件架构赢了各自的战争——而是:**抽象的收益要用变化率来支付,变化率不够高的领域,抽象税会拖垮交付**。 那么 dsh 要交哪几笔税?我数了四笔: **第一笔,接口 churn。** v0.1 官方明示会有破坏性变更,这很诚实,但也意味着现在写的插件,三个月后可能要跟着接口重构。插件架构的价值锚定在接口稳定性上,而接口稳定性恰恰是 preview 阶段最不可能提供的东西。 **第二笔,调试的间接层。** 一次工具调用穿过服务键、事件总线、若干策略监听器,栈追踪会比直调深好几层。dsh 用轨迹视图部分对冲了这一点,但"经过 N 层间接的排障"依然比单体框架费神——这是所有插件系统的原罪。 **第三笔,抽象泄漏。** 沙箱与文件系统这两个插件位尤其危险:本地 shell、容器、远程沙箱的语义差异(权限、路径、生命周期、网络),很难被一个接口完美盖住。Joel Spolsky 的老话在这里依然成立:所有非平凡的抽象都会泄漏。接缝设计得再好,这两处也要准备好打补丁。 **第四笔,技术栈摩擦。** dsh 是 TypeScript/Node 生态,而 AI 工程圈的默认语言是 Python。这不是能力问题(Node 做 I/O 密集的编排层其实很称手),是**社区引力问题**:多少算法工程师愿意为一个 harness 跨栈?Koishi 社区的 TS 人才库是存量优势,但要吃下 AI 工程主流,这道栈间峡谷必须正视——比较现实的过渡形态,是 Python 侧经由工具协议(MCP 一类)与 dsh 对接:编排层归 TS,算法与数据管道留在 Python,各守各的主场。 最后是平衡判断,亮我自己的观点:dsh 的赌注本质上是一句话——**Agent 领域的范式变化率,高到值得预付抽象税**。看看过去十八个月循环范式、工具协议、沙箱方案换了几轮,我倾向于认为这个赌注押对了方向。但"方向对"不等于"现在就上生产":developer preview + 明示破坏性变更,当下的正确姿势是**学它的设计、试它的水、缓它的生产化**。 --- ## 八、今晚就能上手,和写在最后 想亲手摸一遍的读者,路径很短(以官方当日文档为准): **第一步,拉起来。** `npx` 一行命令或克隆仓库后 `pnpm install && pnpm run build && pnpm dsh web`,浏览器打开 `127.0.0.1:3080` 进 Web UI。**第二步,进 Creator 模式。** 在运行时里内省当前插件树,在内存中试写第一个插件——不用碰配置文件就能感受热插拔和可逆 effect。**第三步,写一个真插件。** 照着官方 Cordis 教程,给自己的场景注册一个模型可调用的工具,挂进 Standard 模式,再到 Trajectory 视图里看它被调用的完整轨迹。三步走完,这套架构的手感就有了。 给三类读者各留一句。**自研 harness 的框架作者**:就算一行代码不用它的,第五节的 append-only 事件流和第二节的可逆 effect 也值得直接抄进你的设计——这两条是普适的,不依赖 Cordis。**Agent 应用团队**:preview 阶段观望生产化,但第六节那六个问题,现在就可以拿去审自己的系统。**Koishi 与 TS 社区的老朋友**:你们磨了四年的东西被抬进了前沿实验室的主舞台,这波时代红利,别接得太谦虚。 展望层面,harness 的标准化之争才刚开幕:闭源产品靠深度耦合换体验,dsh 靠开放接缝换生态,两条路线会在未来一年正面相撞;而 DeepSeek 选择用 MIT 许可和社区框架当开场白,至少把"开放"这张牌打到了最大。 留一个问题收尾。当模型可换、工具可换、连循环本身都可热插拔的时候——你的 Agent 产品里,还剩下哪一块,是真正不可替换的? 想清楚这个问题的团队,才配得上插件化交出来的自由。 --- **参考资料** 1. DeepSeek Harness GitHub 仓库:github.com/deepseek-ai/deepseek-harness 2. DeepSeek Harness 官方产品页:deepseek.com/harness/en/ 3. 仓库文档:architecture.md / cordis-primer.md / cordis-tutorial(同仓库 docs 目录) 4. DeepSeek 官方 X 发布贴(v0.1 Developer Preview 公告) 5. Cordis 设计论文:A Programming Paradigm for Spatiotemporal Composability 6. Zeli / 社区讨论聚合:DeepSeek Harness 发布讨论串 (注:本文事实性描述均基于发稿时的官方文档与仓库内容;项目处于 developer preview 阶段并明示会有破坏性变更,具体接口与命令请以仓库最新文档为准。)