DeepSeek Harness 架构怎么设计的？4把设计钥匙拆开看

 

架构师群里同一个问题挂了三个月：现在的 Agent 框架，Loop 到底该不该焊死在核心里？有人说该留，留住才能收敛；有人说该拆，拆开才能换后端。DeepSeek Harness 在 2026 年 8 月开源时给出了一个明确答案，把内核做到极薄，Loop 本身也变成可替换的插件，只留 Service、Typed Events、Reversible Side Effects 三个原语。内核薄到这个程度，靠什么让人放心？答案是四把设计钥匙：事件溯源做单一事实来源，waterfall 把关位统一挂在事件上，seam 让能力可替换，分层配置加热更新让形态可重组。这套设计的价值在于把 Agent 基础设施的竞争从功能堆叠拉到架构哲学层面，因为能换的都是能力，不能换的只有机制。

 

内核做空凭什么让人放心

 

传统框架的做法更像造一辆整车，Loop 直接焊死在车架上，想换轮子就得拆车重装。DeepSeek Harness 换了个思路，更像在造一个底盘，车架、轮子、缰绳全部做成可拆装零件，只留一截最薄的底盘。这个比喻背后有个更形象的说法叫 Harness，英文原意是马具。

 

模型像一匹野马，有蛮力没方向还爱乱跑，你没法直接让它拉货，得先给它套上马具。缰绳对应工具和上下文，告诉它该干什么；护具对应安全和审批，让它跑不出边界；挽具对应插件和可替换，拆装自如。模型是引擎，Harness 是整车，一个让 AI 会想，一个让 AI 能干活。

 

 

问题随之而来。内核这么薄，如果一切都是插件，谁来保证状态可信、执行安全、能力可换、形态可重组？这四个问题不是功能堆叠，而是面对具体工程问题做出的四种架构取舍。值得留意的是，Agent 基础设施在此前已经走过四种形态，每一代都在回答怎么把 Loop 管好，而这一代开始追问 Loop 为什么非得长在系统里。

 

状态可信怎么靠日志兜住

 

设想一个团队在维护 Agent 应用：模型已经回了消息，但日志里没有；系统崩溃后恢复，历史对不上；出了事故要追责，谁也不知道模型当时到底看见了什么。根源只有一个，状态有多个副本，副本之间会漂移，一份在内存，一份在数据库，一份在模型上下文里，各说各话。

 

DeepSeek Harness 的处理方式很直接，状态不存副本，一切从日志派生。它把会话日志从一条普通记录升级为整个系统的单一事实来源，也就是 SSOT。日志本身是 append-only 的事件数组，seq 就是下标，append 写完即冻结，账本上的每一笔都盖了章，不留任何修改入口。

 

更关键的一层是，模型能看到的全部历史不是另一份记录，而是由 deriveMessages 从同一条事件流增量投影出来的视图。右侧的派生视图、持久化、重启恢复，全都是这条事件流的投影，源头只有一条。Event Sourcing 在 Agent 领域的正确用法不是做报表，而是让恢复成本趋近于零，当崩溃恢复变成日常事务，容错就从灾难恢复降级为重启即重放。

 

执行安全怎么做到零侵入

 

状态可信之后，下一个问题是执行安全。系统能记得一切了，但模型要调用工具了，可能是删除目录、发消息、写数据库。审批、危险操作拦截、超大结果截断、埋点观测，这些横切关注点塞进哪一行代码？

 

传统做法是在每个工具函数里写判断，策略和业务耦合在一起，每加一个工具就要改一遍代码，大概率会有遗漏。DeepSeek Harness 的第二项设计是把统一把关位放进事件机制里，工具执行的每一步都触发类型化事件，而 tools 目录下的三个事件 pre-execute、execute、post-execute 就是把关位。审批、Guard、Spill、遥测全部挂在这三个事件上，不需要改任何插件代码。

 

三道把关位各管一段：执行前把关可拒绝可改写，挂人工确认与危险操作拦截；实际执行是注入点，超时、重试、遥测环绕；执行后处理做结果拦截，Spill 把超大结果替换为 locator，防止上下文被大对象撑爆。策略挂在旁边的车道上，不进入主链路，这就是零侵入的含义，加一个策略不需要碰任何工具插件的代码。

 

 

真正的关键在于把关位长在内核事件上，才保证了 fail-closed 成立，拿不到安全保证就失败，没有沙箱后端就抛 UNAVAILABLE 绝不裸跑。如果把关逻辑散落在各插件里，安全保证就是可绕过的装饰；当它长在事件里，绕过把关位等于绕过内核，这在架构上不可能。

 

能力可换靠seam三位一体

 

把本地文件系统换成远程沙箱、把 A 模型换成 B 模型、把 CLI 界面换成 Web 界面，在传统框架里通常意味着大动干戈，实现方式变了，调用方也要跟着改，牵一发动全身。DeepSeek Harness 的第三项设计是把每个能力拆成一组三位一体的 seam。

 

Definition 是声明，说明能力长什么样，比如 sandbox.exec 的接口契约，这是不变的部分；Provider 是实现，说明能力怎么实现，本地进程或远程沙箱是同一 schema 的不同 Provider，可以热替换；Consumer 是使用方，只依赖接口不感知实现。这条热替换路径的价值在于，替换一个 Provider，Bash、PTY、LSP 一并迁移，零迁移，因为 Consumer 绑定的不是实现而是接口。

 

 

与 seam 配套的还有一条注册即副作用、卸载即撤销的设计。ctx.effect 管理外部资源并返回 disposer，ctx.tools.register 同样返回 disposer，手动释放、Provider 热替换、配置热变更、应用关闭，四个触发点自动清理，没有单独的卸载 API，dispose 即清理。把可替换性从工程技巧上升为抽象正确性，换后端像换电池，插上就能用。

 

形态可重组靠分层配置

 

一个 Agent 应用长什么样，是 Web 版、Headless 版还是别的 profile，装了哪些 bundle，这些组装信息如果硬编码在代码里，改产品形态就等于改代码加重启服务。DeepSeek Harness 的第四项设计，是把整个产品的组装方式声明为一份分层配置。

 

分层一共四层，从下到上依次叠加。bundle 层是发行版，读取各 bundle 包的 patch 文件按序叠加，只读；profile 用户层针对具体 profile 比如 web，用户可定制；home 层是机器级，跨 profile 通用；--patch overlays 是命令行参数，仅本次运行，后写覆盖全部。关键规则只有一条，后层整体替换配置，覆盖即整体替换而非深度合并，同 id 后写覆盖，产品可以从配置层面完全重组，无需改代码。

 

 

配置能叠加还不够，还要能热生效，这就是配套的 fiber 级热更新。配置变更被 watch 到之后，旧 fiber 卸载且副作用自动清理，新 fiber 创建并 apply，进程全程不重启。配置不再是一次性的设定，而是可编程的声明，dump-config 能看到最终配置树，打印出的任意条目都能被上层覆盖。

 

四把钥匙合起来是什么结论

 

回到开篇那匹野马与马具的比喻。传统框架更像造一辆整车，Loop 焊死在车架里；DeepSeek Harness 更像在造一个底盘。合起来是一句话，能换的都是能力，不能换的只有机制。

 

具体对应下来，事件可以派生、策略可以挂载、Provider 可以替换、产品可以重组，能力全部可换；但三个原语 Service、Typed Events、Side Effects 是机制的底线，替换事件通道等于绕过把关位，机制不可换。四把设计正好印证了这句话，它们不是四个孤立的功能，而是同一套架构哲学在四个维度上的投影。这也把 Agent 基础设施的竞争从功能堆叠拉到了架构哲学层面，模型负责聪明，Harness 负责靠谱。

 

对企业来说，这四个维度恰好对应四个真实的痛点：状态可信对应事故追责与审计，执行安全对应合规与权限边界，能力可换对应避免供应商锁定，形态可重组对应产品迭代不用停服。选 Agent 基础设施时，问一句 Loop 是不是焊死的，比看功能列表更能判断长期成本。DeepSeek Harness 采用 MIT 许可，2026 年 8 月开源，仓库地址是 github.com/deepseek-ai/deepseek-harness，可以直接拉到代码读它的内核实现。

 

如果你的团队正在评估 Agent 平台，也可以先从这四个维度列一张对照表，把候选方案的架构差异摊开比较，再回到业务场景做判断。目前云巴巴平台已经上线，涵盖数字化转型与企业软件选型方案，可以直接联系我们获取针对具体场景的选型建议。