Harness 与 Agent 工程 · 运行控制与长任务 · 2026-08-25

DSH:DeepSeek Harness 架构解析

深度解析DeepSeek Harness(DSH)架构,聚焦“一切皆插件”理念与Cordis/Session双系统设计,助你理解其插件化实现与源码逻辑。

核心内容:

  1. DSH“一切皆插件”架构理念及Cordis、Session双系统分工
  2. 源码实现细节与参考项目(补丁、论文及开源项目)
  3. 安装方法与开发者预览阶段状态说明

本文基于 DSH[1]47f9438(含其 vendored Cordis 补丁)与独立 Cordis[2]8cc9e33,并参考 OpenClaw[3]f70d5b8、Pi[4]6f707eb、Hermes-Agent[5]fa83af3、Codex[6]fe614a6 及 88 页《面向时空可组合性的编程范式》论文 paper[7]948a07b。讨论聚焦源码中的架构与实现;DSH 尚处开发者预览阶段,当前 API 与论文目标模型均不视为稳定承诺。

在已经安装 Node.js 开发工具链的环境中,可以先通过 npx 启动 DSH 的 Web UI,无需预先进行全局安装:

npx @deepseek-ai/dsh web

DeepSeek Harness(下文简称 DSH)用“一切皆插件”概括自己的架构。源码基本支持官方宣传,但“插件很多”还不足以解释 DSH。

DSH 想插件化的不只是工具。模型适配器、系统提示词、工具目录、会话、存储、沙箱、Agent loop、Web UI,乃至标准、PTC、极简和创造模式,都尽量通过同一种机制组合。真正有辨识度的不是包很多或每个包都有 apply(),而是 Cordis 同时处理了五个通常彼此分离的问题:

  1. 一个插件在当前位置能看到哪些能力;
  2. 必需能力尚未出现时,插件是否应该启动;
  3. 同名 service 能否在不同会话或作用域中解析到不同实现;
  4. 插件退出时,注册项、监听器、进程和句柄由谁清理;
  5. 静态配置怎样变成一棵可以更新和检查的运行时插件树。

更合适的理解方式,是把 DSH 看成两套同时运行的系统:

Agent loop 位于两者之间。它从插件图取得模型、工具、提示词和会话服务,再把执行过程写回事件流。

Cordis 解决“系统现在由什么组成”,Session 解决“系统刚才做过什么”。这两条线合起来,才是 DSH 的主体。

这个区分也解释了为什么一个产品级 Harness 不能只看 Agent loop。最小 loop 只需拼 prompt、调用模型、执行工具并把结果送回模型;完整产品还要处理模型与凭证、会话恢复和压缩、工具策略与审批、沙箱与远程执行、多种宿主、子 Agent、插件启停,以及 UI 如何观察同一份运行事实。DSH 主要把后一组组合复杂度交给 Cordis,把历史连续性交给 Session。

从配置到运行图

DSH 启动时没有直接构造一个固定的 Agent 应用。它先读取 Profile 与 Bundle,再叠加用户 Patch,由 Cordis Loader 将配置行逐条挂载成插件实例。

这里有三层配置概念:

Loader 处理后的结果不是普通配置对象,而是一棵正在运行的插件树。配置行决定插件名称、父子位置、参数、启停条件和 service 隔离域;配置变化后,相应插件实例也可以重新配置、卸载或挂载。

Profile 的各层不是模糊地“合并一下”。源码从空 entry list 开始,依次应用 Profile 声明的 Bundle、Profile 自己的 cordis.patch.yml、Harness home 下的 patch,再应用命令行 --patch;如果启动参数关闭 telemetry,launcher 还会在其后叠加对应的 override。后层按配置行 id 替换整段配置或插入新行。因而调试启动问题时,源码 import 图只表示“可能加载什么”,dsh --dump-config 输出的最终树才表示该机器实际会挂载什么。

这使 DSH 不只支持开发时扩展,也具备了部署时装配的能力。若更换一项实现仍要修改启动代码,选择权就在程序内部;当部署方可以直接通过配置替换它,替换本身才成为系统提供的能力。

DSH 还区分了宿主组合与单个 Agent 的组合。

宿主层持有进程共享的注册表、持久化、沙箱与审批、模型路由等能力。Agent Preset 挂在会话作用域中,主要贡献该会话使用的工具、人格、提示词片段和少量隔离 service。Preset id 还会写入 Session header;恢复会话时必须重新使用同一组合,否则历史中已经出现过的工具和提示词可能与当前 Agent 能力不一致。

这也是理解官方四种“模式”的前提(标准、PTC、极简、创造)。源码中的组合实际有两条轴:

所以,四种模式属于 per-session preset,不是四套互斥的进程启动方案。一个 Web 进程可以同时承载使用不同 preset 的会话。

Cordis 运行时

一份 YAML 能描述插件树,仍然没有回答运行时问题:依赖未就绪怎么办,同名能力怎样隔离,Provider 被替换后谁需要重启,插件制造的副作用由谁回收?

下面把 minimal preset 中的文件系统组合缩成一个例子。为便于阅读,工具源码已有的 inject 被显式写进 Entry,并故意把 Consumer 放在 Provider 前面:

## agent.cordis.yml- id: filesystem name: cordis:group group: true # 为这棵子树创建私有的 fs service realm。 isolate: fs: true config: # Consumer:tools 或当前 realm 的 fs 缺失时,Fiber 保持 PENDING。 - id: editor name: '@deepseek-ai/dsh-tool-str-replace-editor' inject: [tools, fs] config: maxOutputChars: 16000 # Provider:在上面的私有 realm 中发布 ctx.fs。 - id: fs-provider name: '@deepseek-ai/dsh-fs-local' config: cwd: !!js process.env.DSH_CWD ?? process.cwd()

isolate.fs: true 让这个 group 拥有 entry-local realm,另一个 group 可以发布自己的 fs 而不冲突。inject 让 editor 在 tools 和 fs 都可解析之前保持等待,因此 YAML 行顺序不承担启动顺序;Provider 出现后,Cordis 才激活它。在宿主已经提供 sandboxPolicy 的 DSH 组合中,若把 fs-provider 这一行替换为 @deepseek-ai/dsh-fs-sandbox,Provider Fiber 的身份变化会刷新 Consumer 的依赖 epoch,使旧 editor Fiber 先卸载,再用新 fs 重载。

YAML 仍然没有描述“怎样关闭”。这部分留在插件代码中:Provider 和 Consumer 通过 ctx.effect()、ctx.provide()、ctx.on() 登记 disposer,Cordis 在 Fiber 卸载时执行它们。换言之,YAML 声明期望拓扑,Context、Fiber 与 effect 负责让拓扑在运行时成立并安全退出。

Cordis 用 Context、Service、Fiber 与 effect 共同维护这些关系。它们不是四层互不相关的抽象,而是一套插件节点的运行规则。

这也是 Cordis 与普通“插件表 + 事件总线”的差别。下面这种注册循环足以添加几个工具,却没有表达作用域、依赖和退出责任:

for (const plugin of plugins) { plugin.register(app)}

系统扩大后,启动器就会逐渐承担本不属于它的工作:手工排列 A、B、C 的启动顺序,为每个注册项另写卸载逻辑,为两个 Agent 复制并隔离状态,替换 Provider 后追踪旧引用,再另外维护一份“当前到底加载了什么”的诊断表。Cordis 把这些关系收进运行时模型,而不是继续给注册循环增加条件分支。

Context 与 Service

DSH 插件通过 ctx.tools、ctx.llm、ctx.sessions 等 service 名称协作。消费者依赖的是能力接口,不直接绑定具体实现。

ctx 看起来像装满单例的对象,实际是经过 Proxy 包装的 service 解析边界。Context 不只保存“有什么”,还携带父作用域、隔离域、依赖声明和当前 Fiber。子 Context 默认继承父级 service;isolate() 可以为某项 service 建立独立 realm。两个会话即使都访问 ctx.tools,也可以得到各自的工具目录。

Cordis 使用 Proxy 处理 Context 上的 service 访问。通过 ctx.foo 直接读取未声明在 inject 中的 service 会报错;显式调用 ctx.get("foo") 是较底层的读取入口,不受这项声明检查。必需依赖缺失时,插件不会进入活跃状态。

这是一种依赖约束,不是权限控制。原生 JavaScript 插件仍在宿主进程中执行,未注入 fs 不代表它在操作系统层面失去文件访问能力。

在 DSH 中,一条可替换能力通常有三个角色:

三者合起来才构成 capability seam。以文件系统和子进程为例,它们共享一套 execution world;把 Provider 指向远程沙箱,可以连带移动 Bash、PTY 和 LSP,而不是分别 fork 每个工具。isolate 又允许这种替换只作用于某个 Agent,而不是全进程切换。

Fiber:插件实例

Plugin 是可复用定义,一次实际挂载则对应一个 Fiber。同一个 Plugin 使用不同配置、挂在不同 Context 下,会得到多个 Fiber。

Fiber 是 Cordis 为这次插件运行创建的实例记录,它把依赖解析、生命周期和资源所有权收束到同一个对象中,主要保存:

Fiber 会根据依赖计算自己的激活状态。必需 Provider 尚未出现时,它停在等待状态;Provider 就绪后加载。Provider 消失或更换实现时,Cordis 通知相关 Fiber,重新计算依赖并触发卸载或重载。

因此,Cordis 维护的不是启动时解析一次的依赖注入,而是一张会随 Provider 变化而刷新的运行图。Plugin 是代码定义,Fiber 才是“这份定义在这个父 Context 下,使用这份配置和这组依赖”的活实例。所谓依赖顺序也不再只是 boot 脚本中的先后关系,而是运行时持续维护的状态。

effect:副作用归属

插件加载通常会产生注册项、事件监听器、定时器、文件句柄或后台进程。Cordis 要求插件在创建这些资源时,同时登记对应 disposer。与单独维护 activate() / deactivate() 相比,资源获取和释放写在同一个 effect 中,不容易随着功能迭代而失配。ctx.on()、ctx.provide() 等框架辅助方法自身也接入了 effect 所有权。

DSH 的 JSON 存储插件可以把这套机制串起来:

export const inject = ["storage"]export function apply(ctx, config) { const backend = new JsonStorageBackend(config.root) ctx.effect(() => { const unregister = ctx.storage.backend.register("json", backend) return async () => { unregister() await backend.close() } }) ctx.provide("storageBackend:json", backend)}

inject 让插件等待存储中心,Context 为它解析当前作用域中的 storage,effect 把注销和关闭 backend 归到本 Fiber,provide 再将 JSON backend 暴露给其他消费者。

单次 ctx.effect() 内收集的 disposer 会按逆序串联,适合处理“后创建的资源依赖先创建的资源”一类关系。Fiber 整体卸载时,DSH 内置的 Cordis 会并发启动多个顶层 effect 的清理并等待它们全部结束,因此不能把所有顶层 disposer 理解为一条严格串行的 LIFO 栈。

effect 的能力止于声明边界。插件没有登记的进程和句柄不会自动消失,已经提交到外部系统的事务也不会因 Fiber 卸载而撤销。它提供结构化资源管理,不提供事务级回滚。

与 React 的类比

React 的类比是论文主动建立的。论文以 useEffect 说明依赖调用顺序和隐藏运行时状态的 effect 定位方式,又比较了两者的 setup/cleanup 与组合能力。Cordis 通过显式 Context 确定 effect 归属,并允许 effect 进入普通控制流、异步函数和 iterator。这属于设计层的参照;源码与提交历史没有显示 Cordis 移植了 React Fiber。React Fiber 服务于 UI 协调和渲染调度,Cordis Fiber 管理插件依赖、生命周期与资源回收。

两边的源码结构可以压缩成下面两个示意。

React 在 render 期间按调用顺序维护 Hook 链。useEffect 将 Effect 记录追加到 Fiber 的循环链表;挂载或依赖变化时,setup 才会在提交后的 passive-effect flush 中执行:

// React 源码结构的简化示意,不是可运行代码currentlyRenderingFiber.memoizedState -> hook1 -> hook2 -> hook3currentlyRenderingFiber.updateQueue.lastEffect -> circularEffectListuseEffect(create, deps) -> 按调用顺序取得或创建 Hook -> 记录 { create, deps, inst: { destroy } } -> 挂载或 deps 变化时标记为待执行 Effect -> passive-effect flush 调用旧 destroy,再执行 create() -> 将新的 cleanup 保存到 inst.destroy

DSH vendored Cordis 没有 Hook dispatcher。ctx.effect() 是当前 Fiber 上的普通方法,调用时立即启动 setup,并由一个 wrapper 持有产生的 disposer:

// DSH vendored Cordis 源码结构的简化示意,不是可运行代码fiber._disposables = [wrapperA, wrapperB, wrapperC]ctx.effect(execute) -> 先将 wrapper 登记到当前 Fiber -> 立即启动 execute() -> wrapper 收集 execute 产生的 disposer -> 提前调用 wrapper 时,等待进行中的 setup 后执行清理 -> wrapper 只清理一次

两者都把 Effect 记录归属到生命周期节点,并由运行时跟踪 cleanup。React Fiber 是带 child、sibling、alternate 和 lanes 的渲染工作节点;Cordis Fiber 保存插件配置、inject、service 绑定、生命周期状态和 disposer。

依赖变化的处理粒度不同。React 先重新 render,再比较 useEffect 的依赖数组,决定是否清理并重建 Effect;Context value 变化可以调度 Consumer render。Cordis 在 service 变化时主动刷新依赖,把 Provider Fiber UID 编入 Consumer epoch;UID 变化会触发整个 Consumer Fiber 卸载和重载。

Cordis ctx 同时承担命名 service、realm 隔离、依赖声明和 effect 归属。ctx.on()、ctx.provide() 是建立在 fiber.effect() 上的生命周期辅助方法,可以出现在条件、循环和嵌套函数中。Cordis effect 还返回显式 disposer,并支持 Promise、同步 iterator 和异步 iterator;这些能力不受 React Hooks 调用规则约束。

Event:流程拦截

Service 适合“明确调用一个能力”,Event 适合观察、决策和包裹一段过程。Cordis 不是只有一种广播方式:

监听器同样归注册它的 Fiber 所有,因此插件卸载会移除监听器。DSH 使用 waterfall 处理 agent/pre-step、agent/request、llm/stream 和工具执行前后的扩展点;agent/turn-stopping 则使用 serial。审批、提示词注入和 Provider 适配可以进入已有 seam,而不必不断给默认 loop 增加条件分支。

Loader:配置挂载

Loader 负责连接配置与上述运行规则。一个配置 Entry 被导入后,Loader 解析插件、修补 Context,再通过 Registry 创建 Fiber。Entry 被禁用、修改或删除时,Loader 对相应 Fiber 执行更新或 dispose。

因此,cordis.yml 不是“给固定程序填几个参数”,而是在声明装哪些插件、挂在什么父节点、采用什么配置、哪些 service 建立新 realm,以及哪些组合在当前环境启用。若源码支持扩展、部署时却不能替换 Provider,使用者仍需 fork 核心;Loader 把替换从开发行为推进成了配置行为。

Cordis 所说的“时空可组合性”可以由此落到两个具体维度:

所谓时空组合,没有超出这些源码机制。

论文中的 Cordis

Cordis 论文 A Programming Paradigm for Spatiotemporal Composability 为上述机制建立了一套形式模型,说明 Cordis 的组合语义、成立条件与适用边界。其结论不覆盖 DSH 整体架构的正确性或性能。

本文涉及三份材料:

下文分别以“论文”、“独立 Cordis”和“DSH vendored Cordis”称呼它们。按本文固定的源码快照,DSH 本地版本已修补 effect 设置期间重入卸载、异步清理失联、Loader 更新失败回滚、配置监听串行化等问题,与独立仓库快照存在实质差异。包版本号也无法代替实现核对,论文中的性质是否成立仍取决于代码和证明前提。

论文将组件的能力需求、环境贡献和撤销逻辑合成可由运行时持续调和的对象,并研究多个对象交错运行时,系统在什么条件下仍能恢复、正确排序并最终收敛。

组件级组合

论文从动态组合的粒度错位切入。函数调用、模块导入和继承关系擅长静态组合;进程与容器可以在运行时重启、替换和编排;两者之间缺少一种能在同一进程内独立装卸组件、同时保留其他运行状态的通用抽象。重启进程会丢失缓存、连接和进行中的计算,把每项能力拆成远程服务又会增加部署与通信成本。Cordis 试图填补这个组件级空档。

论文以 VS Code 插件系统和自演化 Agent Harness 作为两个动机。前者说明传统插件宿主常把可执行扩展的完整卸载推迟到进程重启;后者把问题推到更动态的场景:Harness 若持续生成并替换自身组件,每次变更都重启宿主,或让每个模块自行监听依赖变化,都难以长期维护。自演化 Harness 在论文中属于后续验证方向。

论文的 88 页主要用于建立语义、状态机和证明,API 只占很小一部分。

工程上,论文把 Cordis 分成三层:core library 实现 effect 跟踪与 coeffect 解析;component loader 负责声明式配置、调和与 HMR;Koishi、DSH 这类应用框架在上面定义领域能力。Cordis 保持领域中立,只提供组件共同运行与退出的底层语义。

Context 范式

论文把动态组合拆成两个正交方向:

Effect 描述组件对环境做了什么,coeffect 描述组件要求环境提供什么。论文将两者递归地合并进同一种 Context:Context 同时保存当前可见环境、effec…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/LargeLanguageModel/2026082536704.html