（一）DeepSeek Harness炸场：88K星的开源Agent框架，把「一切皆插件」玩到了极致

本文是《DeepSeek Harness 源码分析》100 篇系列的第 1 篇（开篇）。DeepSeek Harness（dsh）是 DeepSeek AI 开源的新一代 AI Agent 框架，短短时间内已斩获 88K+ ⭐，成为 2024-2025 年最受关注的开源 AI 项目。本篇是这个系列的开篇——先全景鸟瞰整个项目，建立全局认知，后续篇章逐一深挖各模块。

一、DeepSeek Harness 是什么

DeepSeek Harness 是一个开源 Agent Harness（智能体框架），定位是让开发者能够以「搭积木」的方式组合出任意能力的 AI Agent。

核心 Slogan：

Everything is a Plugin.

这不仅仅是一句宣传语，而是体现在架构的每一个层面：

  • 模型适配器是插件
  • 工具注册表是插件
  • 会话日志是插件
  • Agent 循环本身也是插件
  • 甚至连沙箱、文件系统、LSP 都通过插件形式提供

这意味着：你可以在不修改任何一行 Harness 核心代码的情况下，替换掉整个模型层、替换整个工具集、替换整个执行环境。

二、快速上手

# 方式一：npm 一键体验（无需克隆仓库）
npx @deepseek-ai/dsh web

# 方式二：从源码运行
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

启动后访问 http://127.0.0.1:3080 即可看到 Web UI。

目前处于 开发者预览版（developer preview）阶段，快速迭代中，生产使用需注意兼容性声明。

三、技术栈一览

层级 技术选型
语言 TypeScript（100%）
运行时 Node.js
包管理 pnpm
核心框架 Cordis（可逆编程插件框架）
UI React（Web App）
协议 MCP（Model Context Protocol）、ACP（内部 Agent 通信）
沙箱 E2B Cloud Sandbox + 本地进程隔离
许可 MIT

四、核心架构：一切皆插件

4.1 为什么选择插件化？

传统 Agent 框架的问题：核心功能与实现紧耦合。换个模型要改代码，换个执行环境也要改代码。

DeepSeek Harness 的解法：把每一个能力都抽象成「插件」，通过配置组合。

┌─────────────────────────────────────────────┐
│           Cordis 运行时（无特权核心）          │
├─────────────────────────────────────────────┤
│  Profile: web                               │
│  ├── Bundle: dsh-base（模型、工具、存储）     │
│  ├── Bundle: dsh-web-app（React UI）         │
│  └── User Patch: ~/.dsh/cordis.patch.yml    │
└─────────────────────────────────────────────┘

Profile 定义了要加载哪些 Bundle，Bundle 是 Cordis 插件的打包格式。每一层都可以覆盖（Patch）下层配置，底层插件完全不知道上层的存在——这就是 Layered Plugin Tree。

4.2 Cordis 运行时

Cordis 是整个架构的基础设施层，由 cordiverse 提供，设计理念来自论文《A Programming Paradigm for Spatiotemporal Composability》。

Cordis 的三大核心特性：

  1. Plugin = Service：插件即服务，无特权核心
  2. 可逆注册：插件卸载时自动撤销所有注册（取消工具、关闭连接等）
  3. Typed Events：强类型事件系统，支持 emit / parallel / serial / bail 四种分发模式

这使得 DeepSeek Harness 可以实现真正的热拔插——测试时卸载插件不留任何副作用。

五、核心模块地图

DeepSeek Harness 的代码分布在约 50 个 packages 中：

Agent 核心

包 职责
core/agent Agent 接口定义、注册表
core/agent-loop 默认 Agent 循环驱动
core/session SessionEvent 持久化日志
core/tools 工具注册与执行管道
core/system-prompt 提示词段落组装
core/scope 作用域隔离机制

LLM 层

包 职责
llm/llm 模型适配器抽象层
llm/llm-streaming 流式输出处理

执行环境

包 职责
sandbox 沙箱隔离（安全执行不受信代码）
shell 本地 Shell 执行后端
subprocess 子进程管理
terminal 持久化 PTY 终端
fs 文件系统抽象（可替换为远程 FS）
code-runtime 代码执行引擎

协议与扩展

包 职责
mcp MCP（Model Context Protocol）协议支持
acp ACP 内部 Agent 间通信协议
skill 技能系统
subagent 子代理抽象（同一接口，多种实现）

会话与存储

包 职责
session 会话管理
session-query 会话查询
compaction 对话压缩（防止上下文爆炸）
storage 持久化存储层
goal 多目标管理
jobs 后台任务调度

UI 与入口

包 职责
apps/cli 命令行入口
apps/web Web UI（React）

六、Agent 的工作流程

一个完整的 Agent 对话周期（Turn）：

turn/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 日志，可重建、可回放、可 fork
  • agent/pre-step / tools/pre-execute 是级联事件（serial / bail），listener 必须调用 next() 继续传递

七、Seam 能力边界：换一处，全部跟着变

DeepSeek Harness 提出了一个精妙的 Seam 概念：

Service Definition（接口）
        ↓
Service Provider（实现，可插拔）
        ↓
Consumer（使用者，通常是工具）

最典型的例子是 fs（文件系统）：

  • 本地实现：直接读写磁盘
  • 远程实现：通过 API 操作远程服务器
  • 切换成本：只需换一个 Provider，整个 Agent 的文件系统能力立即迁移

更令人惊讶的是：Shell 和 LSP（语言服务器）也受益于这个设计——当你把 shell 指向云端 E2B 沙箱时，Bash 工具和代码补全一起迁移到云端，无需逐个修改配置。

八、与主流框架对比

维度 DeepSeek Harness LangChain AutoGPT
架构哲学 一切皆可插拔 Chain 可组合 单体 Agent
插件卸载 ✅ 可逆回滚 ❌ 手动清理 ❌ 无
事件系统 ✅ Typed（emit/parallel/serial/bail） ⚠️ Callback ❌ 无
配置驱动 ✅ YAML Patch ⚠️ 代码配置 ❌ 无
沙箱支持 ✅ 内置 E2B ⚠️ 第三方 ❌ 无
协议支持 MCP + ACP MCP（部分） ❌ 无
stars 88K+ 100K+ 140K+

九、下篇预告

下一篇（二）我们将深入 Cordis 运行时 的核心设计：可逆 Plugin/Service 机制、inject 依赖声明、Typed Event 的四种分发模式，以及它如何支撑起整个 Harness 的插件生态。

附录

  • GitHub：https://github.com/deepseek-ai/deepseek-harness
  • Cordis 论文：https://github.com/cordiverse/paper
  • 官方文档：https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/architecture.md
  • Discord 社区：https://discord.gg/Ycq5dCaS4
# 开源 # 人工智能
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

我测试了一个0.9B模型，它竟然能自动区分多人讲话）

avatar AI Agent技术社区
cover

从一张商品图到正式上架：实测店匠 Shoplazza Athena，AI Agent 不只是聊天框

avatar AI Agent技术社区
cover

【AI Agent】《2026年9月 AI Agent全栈开发技术选型专项面试宝典》

avatar AI Agent技术社区