[控场AI]
· 8 分钟阅读· 4,199 字

DeepSeek Harness插件架构拆解:一切皆插件的Cordis系统

DeepSeek Harness插件架构拆解:一切皆插件的Cordis系统

DeepSeek Harness 是基于 Cordis 插件系统的通用 Agent 框架,一切皆可替换。

文章系统介绍了 DeepSeek Harness(DSH)的架构与使用方式。DSH 定位为通用 Agent Harness,自带 Agent 循环、工具、系统提示词、会话存储和界面,并提供 Web、桌面、SDK、ACP 多种交付形态。其底层是名为 Cordis 的插件系统,Agent 循环、工具、模型提供商乃至前端 GUI 都被做成插件,插件通过共享上下文、依赖注入和事件协作。文章详述了四种事件发射方式、三个示例插件的代码结构、YAML 分层配置加载机制,并演示了创建者模式如何让 Agent 为自己编写插件,最后澄清了 Cordis 与 DeepSeek 的关系。

什么是DeepSeek Harness:一款通用Agent框架

据B站搬运的中字视频介绍,DeepSeek广告 Harness(下文简称DSH)并非一个只服务于编码场景的专用工具,而是一个通用Agent Harness。它自带Agent循环、内置工具、系统提示词、会话存储以及完整的用户界面,同时允许用户接入自己的工具与模型。

目前DSH提供多种交付形态:面向开发者的Web应用、基于Electron封装的桌面端、TypeScript与Python SDK,以及ACP集成方式。视频作者演示时更常使用桌面版,因为它是Web版本的包装,二者功能逻辑基本一致。

DeepSeek Harness多种交付形态

界面中最具辨识度的是模式切换:标准模式启动常规编码Agent;PTC模式会把工具调用写成脚本,从而在同一工具调用中并行执行多个工具,视频作者特别提到这正是早期小型Agent的工作方式;最小模式尽量压缩上下文;创建者模式则注入关于DSH自身可扩展性的技能与上下文,让Agent能够修改和扩展自己。

Agent Harness 一词中的 harness 原意为“马具/挽具”,在软件语境下指包裹在核心能力之外、负责驱动与约束其运行的外壳层。对语言模型而言,模型本身只会根据输入生成 token,并不具备持续循环、调用外部工具、保存对话状态的能力;Agent Harness 就是把这套“裸模型”装配成可用智能体的工程骨架,通常包含主循环(决定何时调用模型、何时执行工具、何时停止)、工具调度与结果回填、上下文管理、错误重试与用户交互界面。不同厂商的 Harness 设计差异很大,这也意味着同一个底层模型换上不同 Harness,实际表现可能相差悬殊。理解这一点,才能明白为何文章强调 DSH 是“通用”而非“编码专用”的框架。

Cordis:让"一切皆插件"成为可能的底层系统

DSH的口号是"一切皆插件",支撑这一设计的是一套名为Cordis的插件系统。视频作者特意澄清了一段容易被误解的历史:Cordis与DeepSeek并非同一实体,Cordis仓库并不归属于DeepSeek,其首次提交甚至早于DeepSeek公司成立约一年。但二者联系紧密——Cordis作者后来加入DeepSeek并参与DSH开发,Cordis官方页面也指向DSH项目,相关论文由DeepSeek发布。

Cordis本身并不局限于编码Agent,它可以驱动任何类型的应用,只是在编码Agent场景下组合性优势最明显。视频作者建议先读论文前几页,认为DeepSeek的论文写作质量很高,入门部分并不难读。

被插件化的边界有多彻底

在架构讲解中,作者列举了被做成插件的对象:Agent循环本身、工具注册表与每一个具体工具(Bash工具、文件系统、MCP客户端)、系统提示词、工具执行层、模型提供商(包括DeepSeek模型集成)、技能、会话日志与存储、用户界面。这意味着理论上你可以替换Agent循环,做出一个从不调用语言模型、只回显用户输入的Agent;也可以替换工具执行层,把工具放到远程机器上运行以增强安全性。

更特别的是,DSH实际上包含两个Cordis应用:后端一个,前端GUI本身也是一个,二者通过通信协作。

依赖注入(Dependency Injection) 是 Cordis 插件协作机制的基础,其核心思想是:一个组件不自行创建它所依赖的对象,而是声明“我需要什么”,由外部容器在合适的时机把实例传进来。在 Cordis 中,插件通过 inject 字段声明依赖的服务名,框架据此保证被依赖的插件先完成挂载,再把对应的上下文能力提供给当前插件。这样做的好处是插件之间无需硬编码彼此的导入路径,替换或禁用某个插件时,依赖方会由框架统一处理挂载顺序与清理逻辑。它也为文章提到的“可替换 Agent 循环”“可替换工具执行层”提供了工程前提——只要新实现提供同名服务,上层插件无需改动即可运行。

插件如何协作:共享上下文、依赖注入与事件

所有插件都连接到Cordis暴露的同一个上下文(代码中定义为CTX),因此能访问应用范围内共享的能力。有些插件是服务提供者,比如会话插件、工具插件、模型提供商插件;另一些插件则主要监听上下文中的事件,比如压缩插件、钩子插件以及无头UI。

事件是编码Agent功能的核心

插件的能力可以归纳为几类:声明名称以提供服务;通过inject声明依赖,实现依赖注入,确保被依赖的插件先挂载;通过register方法注册到某个服务;监听上下文事件。以视频中的示例来说,greet工具插件必须先注入Tools插件,才能在apply函数中注册新工具;而日志插件同样注入Tools插件,但它监听工具结果事件并打印日志。

作者强调,Cordis会记录插件定义的一切,因此禁用插件时知道按什么顺序清理、需要注销哪些功能、释放哪些名称,避免移除仍被其他插件使用的组件。

事件发射的四种方式

事件是编码Agent运转的核心。插件发射事件有四种方式:普通emit(发出即忘,如工具结果)、瀑布式(如LLM流式生成、一次Agent回合中的多工具执行)、串行(依次等待,如Agent回合停止需等待Agent已创建)、并行。插件还可以声明自己的新事件供其他插件监听,压缩插件就创建了自己的Compaction事件。

事件在相同上下文中汇聚

事件是按上下文作用域的。插件可以嵌套,嵌套后的插件共享父级上下文,事件会向父上下文发射。作者提醒不要把所有插件都嵌套在一起,更理想的做法是让插件连接同一上下文,并通过依赖注入建立依赖关系。

瀑布式事件(waterfall) 是事件系统中较特殊的一种模式,常见于需要多个监听者依次加工同一份数据的场景。与普通 emit 的“发出即忘”不同,瀑布式事件会把上一个监听者的返回值作为下一个监听者的输入继续传递,形成一条处理链;每个监听者必须显式返回 next(或等价令牌)表示放行,若返回 deny 等中断对象,链条即刻终止并阻止后续默认流程。文章中的工具守卫插件正是利用这一点,在工具真正执行前拦截 bash 命令。这种模式在 LLM 流式生成、多工具并行回合中也广泛应用,因为它允许框架在不修改核心代码的前提下插入鉴权、审计、限流等横切逻辑。

三个示例插件看懂代码结构

视频作者在DSH仓库克隆中新建了scratch-plugin目录,放入三个插件。第一个是最小插件:导出一个apply函数,接收上下文参数,内部仅打印hello world。

第二个是greet工具插件:导出name与inject(依赖tools),在apply中通过define tool方法注册一个打招呼工具。

第三个是工具守卫插件:同样注入tools,监听工具结果事件并记录日志;同时拦截tools pre-execute这一瀑布式事件,如果模型调用的bash命令包含rmrf,就返回deny对象阻止执行,并提示模型让用户自行运行。作者解释,瀑布式事件必须返回next才能继续常规流程,要中断则返回deny之类的对象。

插件如何被加载:YAML配置而非硬编码

在Cordis中,插件以配置形式加载,而不是写死在代码里。加载需要一份YAML文件,在insert属性下为每个插件指定ID与名称;若插件已发布为npm包则填包名,若想直接运行本地代码则填文件绝对路径。作者还用--patch参数把自建配置追加到web profile已有的Cordis配置末尾,演示了三个插件在本地Web端生效的过程——greet工具被成功调用,rmrf命令被守卫插件拦截。

插件以包名或路径方式加载

配置是分层叠加的:基础bundle的Cordis配置文件、补丁文件,最后一层是用户配置,位于用户目录下的profiles中,按profile区分并覆盖之前的层。作者打开了自己桌面版的Cordis.patch.yaml,展示其中配置标志与属性如何传递给对应插件,例如默认模型与UI聊天设置,以及通过Hugging Face接入的模型。桌面端加载插件通常需要把插件打成npm包,再通过DSH的服务完成添加,而不是手动改Cordis文件——手动patch只是帮助理解背后机制。

实际工作流:创建者模式让Agent自己写插件

作者演示了日常最省事的做法:切到创建者模式,直接要求DSH创建一个按名字问候的Hello World工具插件。Agent生成了包含package.json与index.js的目录结构,并在测试中成功调用。这也印证了创建者模式的定位——它不改变Agent能力本身,只是注入关于DSH可扩展性与插件架构的知识,让Agent能够为自己写插件。

视频最后用两个插件做了端到端验证:greet工具在桌面端可用,rmrf命令被守卫插件阻断。对于想深入理解这套架构的开发者,作者建议先读Cordis论文前几页建立直觉,再结合仓库中的bundle配置观察插件如何层层组装。

ACP(Agent Client Protocol) 是 DSH 提供的一种集成方式,用于让外部客户端以标准化协议与 Agent 交互。它把“启动会话、发送消息、接收流式输出与工具调用事件”抽象为统一的协议接口,使编辑器、IDE 插件或其他宿主程序无需了解 DSH 内部实现即可接入。相比 Web 应用和桌面端这类自带界面的交付形态,ACP 更适合嵌入到开发者已有的工作环境中。它与 SDK 的区别在于:SDK 是代码层面的库调用,开发者需自行管理生命周期与事件循环;而 ACP 是进程间协议,宿主与 Agent 可以是独立进程,便于隔离与复用。

#DeepSeek Harness#Cordis#插件架构#Agent框架#依赖注入#Agent循环#AI编程
分享:

相关推荐