（一）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# 方式二：从源码运行gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh 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 的三大核心特性：
- Plugin = Service：插件即服务，无特权核心
- 可逆注册：插件卸载时自动撤销所有注册（取消工具、关闭连接等）
- 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
