三88K Stars的Agent框架长什么样DeepSeek Harness架构全解析项目地址https://github.com/deepseek-ai/deepseek-harness⭐ 88,000 Stars | MIT License | 语言TypeScript开篇一个没有核心的Agent框架当大多数AI框架还在争论该用LangChain还是LlamaIndex时DeepSeek扔出了一个重磅炸弹——Harness。这个斩获88K Stars的开源项目用一句Everything is a Plugin彻底颠覆了传统Agent框架的设计哲学。没有特权核心、没有硬编码逻辑甚至连模型适配器、工具注册表、会话管理这些基础设施统统都是可插拔的插件。今天我们就来拆解这个叛逆框架的完整架构。一、整体架构三层金字塔Harness的架构可以用一个三层金字塔来概括┌─────────────────┐ │ Application │ ← 你的Agent应用 │ (Web/CLI/API) │ └────────┬────────┘ │ ┌────────▼────────┐ │ Cordis │ ← 可逆编程运行时 │ (插件系统) │ └────────┬────────┘ │ ┌────────▼────────┐ │ Capability │ ← 能力边界层 │ Seams │ └─────────────────┘1.1 最底层Capability Seams能力边界这是Harness最精妙的设计。Seam原意是接缝在Harness中代表着能力的边界和交换点。传统框架中如果你想把本地执行Bash换成云端E2B沙箱执行可能需要改几十处代码。但在Harness中只需要换一个FS Provider——因为文件系统、Shell执行、工具调用这些能力都被抽象成了Seam。Seam的三角色模型Service Definition能力接口定义如interface IFileSystemProvider能力实现者如LocalFSProvider、E2BProviderConsumer能力使用者如BashTool、FileEditor// 换个Provider整个Agent的工作环境就变了ctx.provide(fs,newE2BFileSystem())// 云端执行ctx.provide(fs,newLocalFileSystem())// 本地执行1.2 中间层Cordis运行时Cordis是Harness的心脏一个专为可逆编程设计的运行时。什么是可逆编程想象一下传统插件系统加载容易卸载难内存泄漏、状态污染Cordis插件加载和卸载完全对称就像搭积木一样想拆就拆Cordis的核心是EffectScope——每个插件都在自己的作用域内运行作用域可以fork创建子作用域ensure确保资源存在reset重置状态dispose完全清理// 插件的生命周期完全可控constscopectx.scope.fork()awaitscope.plugin(MyPlugin)awaitscope.reset()// 干净重置awaitscope.dispose()// 彻底销毁1.3 最上层ApplicationHarness提供三种开箱即用的应用形态形态命令适用场景Web UInpx deepseek-ai/dsh web可视化交互、演示Headlessnpx deepseek-ai/dsh headless服务器部署、API服务CLInpx deepseek-ai/dsh命令行操作、脚本化二、一切皆插件没有特权核心Harness最 radical 的设计是框架本身没有特权核心。让我们看看传统Agent框架 vs Harness的区别组件传统框架Harness模型适配器硬编码在核心llm插件工具注册表全局单例tools插件会话管理核心服务sessions插件Agent Loop内置主循环agent-loop插件系统提示词写死在代码system-prompt插件这意味着什么你可以完全替换框架的任何部分而不会破坏其他功能。2.1 插件的Ctx键Harness使用**上下文Context**作为插件间通信的唯一方式// 核心插件提供的ctx键ctx.sessions// 会话管理core/sessionctx.systemPrompt// 系统提示词core/system-promptctx.tools// 工具注册表core/toolsctx.agents// Agent实例管理core/agentctx.agentLoop// Agent主循环core/agent-loopctx.llm// 模型适配层llm/llm每个插件通过provide注册自己的服务通过inject消费其他服务。三、事件驱动Agent Loop的瀑布流Harness的Agent不是轮询-响应模式而是纯事件驱动。一个完整的对话周期Turn会产生这样的事件流turn/start ↓ agent/pre-step ← waterfall需调用next() ↓ step/start ↓ agent/request ← waterfall ↓ llm/stream ← waterfall ↓ assistant/chunk ← 流式输出片段 ↓ assistant/message ← 完整消息 ↓ tool/call ← 工具调用可能有多个 ↓ tools/pre-execute ← waterfall ↓ tools/execute ↓ tools/post-execute ↓ step/end ↓ turn/end3.1 四种事件分发模式Cordis支持四种事件分发方式模式特点适用场景emit广播不关心返回值日志、通知parallel并行执行所有监听者独立副作用serial串行执行有序处理bail返回第一个非空值策略选择waterfall可拦截、可修改中间件、预处理waterfall事件是Harness的精髓——它允许插件在事件传播过程中插手比如在agent/pre-step中修改输入在llm/stream中拦截并修改模型输出在tools/pre-execute中添加权限检查四、配置系统Profile Bundle PatchHarness的配置系统同样体现了分层叠加的思想4.1 三层配置模型Base Bundle (dsh-base) ↓ Profile Config (cordis.patch.yml) ↓ Home Config (~/.config/dsh/) ↓ CLI Patch (--patch)Bundle代码分发单元包含一组插件和默认配置Profile预定义的配置组合如dsh-web-app、dsh-headlessPatch无侵入式的配置覆盖4.2 常用ProfileProfile用途包含的核心包dsh-base基础功能core/, llm/, tools/*dsh-web-appWeb界面 web-ui, react组件dsh-headless无头服务 api-server4.3 调试配置# 查看实际生效的完整配置npx deepseek-ai/dsh web --dump-config这个命令会输出所有合并后的配置是排查问题的利器。五、60包的组织结构Harness的代码库采用monorepo管理packages目录下包含60多个包packages/ ├── core/ # 核心插件 │ ├── agent/ # Agent实例管理 │ ├── agent-loop/ # Agent主循环 │ ├── session/ # 会话管理 │ ├── system-prompt/ # 系统提示词 │ └── tools/ # 工具注册表 ├── llm/ # 模型适配层 │ ├── llm/ # 抽象接口 │ ├── anthropic/ # Claude适配器 │ ├── openai/ # GPT适配器 │ ├── deepseek/ # DeepSeek适配器 │ └── ... ├── tools/ # 内置工具 │ ├── bash/ # Bash执行 │ ├── file/ # 文件编辑 │ ├── git/ # Git操作 │ └── ... ├── capabilities/ # 能力边界实现 │ ├── fs/ # 文件系统 │ ├── shell/ # Shell执行 │ └── telemetry/ # 遥测 └── apps/ # 应用层 ├── web-ui/ # Web界面 ├── cli/ # 命令行 └── api-server/ # API服务六、为什么Harness值得关注6.1 对比传统框架特性LangChainAutoGPTHarness架构链式调用自主循环插件化事件驱动可扩展性中等低极高可逆性无无原生支持能力边界硬编码硬编码Seam抽象部署形态库应用Web/Headless/CLI6.2 适用场景快速原型用Web UI验证Agent想法生产部署Headless模式提供API服务深度定制替换任意组件打造专属Agent研究实验利用可逆性测试不同策略七、快速上手# 1. 安装npminstall-gdeepseek-ai/dsh# 2. 启动Web界面npx deepseek-ai/dsh web# 访问 http://127.0.0.1:3080# 3. 配置模型config.toml[llm]providerdeepseekapi_keyyour-api-key# 4. 开始对话结语插件化是Agent框架的终极形态吗Harness用88K Stars证明了一件事当一切皆插件创新就没有边界。传统框架的核心团队决定一切模式在Harness中变成了社区共同定义框架。每个人都可以写一个新插件扩展Harness的能力替换现有插件实现自己的逻辑组合不同插件创造全新的Agent形态这不是一个框架而是一个Agent操作系统。下一篇预告四比LangChain更优雅DeepSeek Harness的插件化Agent设计我们将深入对比Harness与LangChain的架构差异看看无核心设计到底强在哪里。本文是「DeepSeek Harness源码分析」系列第3篇系列共100篇涵盖架构、源码、实战全流程。