一DeepSeek Harness炸场88K星的开源Agent框架把「一切皆插件」玩到了极致本文是《DeepSeek Harness 源码分析》100 篇系列的第 1 篇开篇。DeepSeek Harnessdsh是 DeepSeek AI 开源的新一代 AI Agent 框架短短时间内已斩获88K ⭐成为 2024-2025 年最受关注的开源 AI 项目。本篇是这个系列的开篇——先全景鸟瞰整个项目建立全局认知后续篇章逐一深挖各模块。一、DeepSeek Harness 是什么DeepSeek Harness 是一个开源 Agent Harness智能体框架定位是让开发者能够以「搭积木」的方式组合出任意能力的 AI Agent。核心 SloganEverything is a Plugin.这不仅仅是一句宣传语而是体现在架构的每一个层面模型适配器是插件工具注册表是插件会话日志是插件Agent 循环本身也是插件甚至连沙箱、文件系统、LSP 都通过插件形式提供这意味着你可以在不修改任何一行 Harness 核心代码的情况下替换掉整个模型层、替换整个工具集、替换整个执行环境。二、快速上手# 方式一npm 一键体验无需克隆仓库npx deepseek-ai/dsh web# 方式二从源码运行gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web启动后访问http://127.0.0.1:3080即可看到 Web UI。目前处于开发者预览版developer preview阶段快速迭代中生产使用需注意兼容性声明。三、技术栈一览层级技术选型语言TypeScript100%运行时Node.js包管理pnpm核心框架Cordis可逆编程插件框架UIReactWeb App协议MCPModel Context Protocol、ACP内部 Agent 通信沙箱E2B Cloud Sandbox 本地进程隔离许可MIT四、核心架构一切皆插件4.1 为什么选择插件化传统 Agent 框架的问题核心功能与实现紧耦合。换个模型要改代码换个执行环境也要改代码。DeepSeek Harness 的解法把每一个能力都抽象成「插件」通过配置组合。┌─────────────────────────────────────────────┐ │ Cordis 运行时无特权核心 │ ├─────────────────────────────────────────────┤ │ Profile: web │ │ ├── Bundle: dsh-base模型、工具、存储 │ │ ├── Bundle: dsh-web-appReact UI │ │ └── User Patch: ~/.dsh/cordis.patch.yml │ └─────────────────────────────────────────────┘Profile定义了要加载哪些BundleBundle是 Cordis 插件的打包格式。每一层都可以覆盖Patch下层配置底层插件完全不知道上层的存在——这就是Layered Plugin Tree。4.2 Cordis 运行时Cordis 是整个架构的基础设施层由 cordiverse 提供设计理念来自论文《A Programming Paradigm for Spatiotemporal Composability》。Cordis 的三大核心特性Plugin Service插件即服务无特权核心可逆注册插件卸载时自动撤销所有注册取消工具、关闭连接等Typed Events强类型事件系统支持emit/parallel/serial/bail四种分发模式这使得 DeepSeek Harness 可以实现真正的热拔插——测试时卸载插件不留任何副作用。五、核心模块地图DeepSeek Harness 的代码分布在约50 个 packages中Agent 核心包职责core/agentAgent 接口定义、注册表core/agent-loop默认 Agent 循环驱动core/sessionSessionEvent 持久化日志core/tools工具注册与执行管道core/system-prompt提示词段落组装core/scope作用域隔离机制LLM 层包职责llm/llm模型适配器抽象层llm/llm-streaming流式输出处理执行环境包职责sandbox沙箱隔离安全执行不受信代码shell本地 Shell 执行后端subprocess子进程管理terminal持久化 PTY 终端fs文件系统抽象可替换为远程 FScode-runtime代码执行引擎协议与扩展包职责mcpMCPModel Context Protocol协议支持acpACP 内部 Agent 间通信协议skill技能系统subagent子代理抽象同一接口多种实现会话与存储包职责session会话管理session-query会话查询compaction对话压缩防止上下文爆炸storage持久化存储层goal多目标管理jobs后台任务调度UI 与入口包职责apps/cli命令行入口apps/webWeb UIReact六、Agent 的工作流程一个完整的 Agent 对话周期Turnturn/start → claim next-step input → assemble system prompt tool schemas → agent/pre-step ← 拦截点可改写消息或拒绝 → agent/request ← 发出 LLM 请求 → llm/stream ← 流式接收响应 → assistant/chunk ← 实时 token 输出 → assistant/message ← 完整消息落盘 → tool/call ← 工具被调用 → tools/pre-execute ← 执行前拦截 → tools/execute ← 实际执行 → tools/post-execute ← 执行后处理 → tool/result ← 结果返回 step/end → 若还有待处理工具 → 进入下一步 → 若有新的输入消息 → claim 并进入下一步 → 否则 → agent/turn-stopping ← 关闭前的最后一个拦截点 turn/end关键点turn/start到turn/end是一次完整的用户输入处理流程每一步step包含一次 LLM 请求 零到多次工具调用所有状态变化都写入 Session Event 日志可重建、可回放、可 forkagent/pre-step/tools/pre-execute是级联事件serial / baillistener 必须调用next()继续传递七、Seam 能力边界换一处全部跟着变DeepSeek Harness 提出了一个精妙的Seam概念Service Definition接口 ↓ Service Provider实现可插拔 ↓ Consumer使用者通常是工具最典型的例子是fs文件系统本地实现直接读写磁盘远程实现通过 API 操作远程服务器切换成本只需换一个 Provider整个 Agent 的文件系统能力立即迁移更令人惊讶的是Shell 和 LSP语言服务器也受益于这个设计——当你把shell指向云端 E2B 沙箱时Bash 工具和代码补全一起迁移到云端无需逐个修改配置。八、与主流框架对比维度DeepSeek HarnessLangChainAutoGPT架构哲学一切皆可插拔Chain 可组合单体 Agent插件卸载✅ 可逆回滚❌ 手动清理❌ 无事件系统✅ Typedemit/parallel/serial/bail⚠️ Callback❌ 无配置驱动✅ YAML Patch⚠️ 代码配置❌ 无沙箱支持✅ 内置 E2B⚠️ 第三方❌ 无协议支持MCP ACPMCP部分❌ 无stars88K100K140K九、下篇预告下一篇二我们将深入Cordis 运行时的核心设计可逆 Plugin/Service 机制、inject 依赖声明、Typed Event 的四种分发模式以及它如何支撑起整个 Harness 的插件生态。附录GitHubhttps://github.com/deepseek-ai/deepseek-harnessCordis 论文https://github.com/cordiverse/paper官方文档https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/architecture.mdDiscord 社区https://discord.gg/Ycq5dCaS4 （一）DeepSeek Harness炸场：88K星的开源Agent框架，把「一切皆插件」玩到了极致
一DeepSeek Harness炸场88K星的开源Agent框架把「一切皆插件」玩到了极致本文是《DeepSeek Harness 源码分析》100 篇系列的第 1 篇开篇。DeepSeek Harnessdsh是 DeepSeek AI 开源的新一代 AI Agent 框架短短时间内已斩获88K ⭐成为 2024-2025 年最受关注的开源 AI 项目。本篇是这个系列的开篇——先全景鸟瞰整个项目建立全局认知后续篇章逐一深挖各模块。一、DeepSeek Harness 是什么DeepSeek Harness 是一个开源 Agent Harness智能体框架定位是让开发者能够以「搭积木」的方式组合出任意能力的 AI Agent。核心 SloganEverything is a Plugin.这不仅仅是一句宣传语而是体现在架构的每一个层面模型适配器是插件工具注册表是插件会话日志是插件Agent 循环本身也是插件甚至连沙箱、文件系统、LSP 都通过插件形式提供这意味着你可以在不修改任何一行 Harness 核心代码的情况下替换掉整个模型层、替换整个工具集、替换整个执行环境。二、快速上手# 方式一npm 一键体验无需克隆仓库npx deepseek-ai/dsh web# 方式二从源码运行gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web启动后访问http://127.0.0.1:3080即可看到 Web UI。目前处于开发者预览版developer preview阶段快速迭代中生产使用需注意兼容性声明。三、技术栈一览层级技术选型语言TypeScript100%运行时Node.js包管理pnpm核心框架Cordis可逆编程插件框架UIReactWeb App协议MCPModel Context Protocol、ACP内部 Agent 通信沙箱E2B Cloud Sandbox 本地进程隔离许可MIT四、核心架构一切皆插件4.1 为什么选择插件化传统 Agent 框架的问题核心功能与实现紧耦合。换个模型要改代码换个执行环境也要改代码。DeepSeek Harness 的解法把每一个能力都抽象成「插件」通过配置组合。┌─────────────────────────────────────────────┐ │ Cordis 运行时无特权核心 │ ├─────────────────────────────────────────────┤ │ Profile: web │ │ ├── Bundle: dsh-base模型、工具、存储 │ │ ├── Bundle: dsh-web-appReact UI │ │ └── User Patch: ~/.dsh/cordis.patch.yml │ └─────────────────────────────────────────────┘Profile定义了要加载哪些BundleBundle是 Cordis 插件的打包格式。每一层都可以覆盖Patch下层配置底层插件完全不知道上层的存在——这就是Layered Plugin Tree。4.2 Cordis 运行时Cordis 是整个架构的基础设施层由 cordiverse 提供设计理念来自论文《A Programming Paradigm for Spatiotemporal Composability》。Cordis 的三大核心特性Plugin Service插件即服务无特权核心可逆注册插件卸载时自动撤销所有注册取消工具、关闭连接等Typed Events强类型事件系统支持emit/parallel/serial/bail四种分发模式这使得 DeepSeek Harness 可以实现真正的热拔插——测试时卸载插件不留任何副作用。五、核心模块地图DeepSeek Harness 的代码分布在约50 个 packages中Agent 核心包职责core/agentAgent 接口定义、注册表core/agent-loop默认 Agent 循环驱动core/sessionSessionEvent 持久化日志core/tools工具注册与执行管道core/system-prompt提示词段落组装core/scope作用域隔离机制LLM 层包职责llm/llm模型适配器抽象层llm/llm-streaming流式输出处理执行环境包职责sandbox沙箱隔离安全执行不受信代码shell本地 Shell 执行后端subprocess子进程管理terminal持久化 PTY 终端fs文件系统抽象可替换为远程 FScode-runtime代码执行引擎协议与扩展包职责mcpMCPModel Context Protocol协议支持acpACP 内部 Agent 间通信协议skill技能系统subagent子代理抽象同一接口多种实现会话与存储包职责session会话管理session-query会话查询compaction对话压缩防止上下文爆炸storage持久化存储层goal多目标管理jobs后台任务调度UI 与入口包职责apps/cli命令行入口apps/webWeb UIReact六、Agent 的工作流程一个完整的 Agent 对话周期Turnturn/start → claim next-step input → assemble system prompt tool schemas → agent/pre-step ← 拦截点可改写消息或拒绝 → agent/request ← 发出 LLM 请求 → llm/stream ← 流式接收响应 → assistant/chunk ← 实时 token 输出 → assistant/message ← 完整消息落盘 → tool/call ← 工具被调用 → tools/pre-execute ← 执行前拦截 → tools/execute ← 实际执行 → tools/post-execute ← 执行后处理 → tool/result ← 结果返回 step/end → 若还有待处理工具 → 进入下一步 → 若有新的输入消息 → claim 并进入下一步 → 否则 → agent/turn-stopping ← 关闭前的最后一个拦截点 turn/end关键点turn/start到turn/end是一次完整的用户输入处理流程每一步step包含一次 LLM 请求 零到多次工具调用所有状态变化都写入 Session Event 日志可重建、可回放、可 forkagent/pre-step/tools/pre-execute是级联事件serial / baillistener 必须调用next()继续传递七、Seam 能力边界换一处全部跟着变DeepSeek Harness 提出了一个精妙的Seam概念Service Definition接口 ↓ Service Provider实现可插拔 ↓ Consumer使用者通常是工具最典型的例子是fs文件系统本地实现直接读写磁盘远程实现通过 API 操作远程服务器切换成本只需换一个 Provider整个 Agent 的文件系统能力立即迁移更令人惊讶的是Shell 和 LSP语言服务器也受益于这个设计——当你把shell指向云端 E2B 沙箱时Bash 工具和代码补全一起迁移到云端无需逐个修改配置。八、与主流框架对比维度DeepSeek HarnessLangChainAutoGPT架构哲学一切皆可插拔Chain 可组合单体 Agent插件卸载✅ 可逆回滚❌ 手动清理❌ 无事件系统✅ Typedemit/parallel/serial/bail⚠️ Callback❌ 无配置驱动✅ YAML Patch⚠️ 代码配置❌ 无沙箱支持✅ 内置 E2B⚠️ 第三方❌ 无协议支持MCP ACPMCP部分❌ 无stars88K100K140K九、下篇预告下一篇二我们将深入Cordis 运行时的核心设计可逆 Plugin/Service 机制、inject 依赖声明、Typed Event 的四种分发模式以及它如何支撑起整个 Harness 的插件生态。附录GitHubhttps://github.com/deepseek-ai/deepseek-harnessCordis 论文https://github.com/cordiverse/paper官方文档https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/architecture.mdDiscord 社区https://discord.gg/Ycq5dCaS4