DeepSeek Harness：一切皆插件的 AI Agent 框架深度解析

DeepSeek Harness：一切皆插件的 AI Agent 框架深度解析

本项目是 DeepSeek AI 推出的开源智能体框架（Agent Harness），解决现有 AI Agent 系统扩展性差、能力耦合重、模型绑定死板的问题------传统 Agent 要新增一种工具就得改核心代码，要换一家模型提供商就得重写适配层，落地后开发者可以通过「写一个插件」零侵入地扩展工具、接入任意 LLM、替换执行沙箱，从构想到可运行的 Agent 只需一个 YAML 配置。

---

一、项目背景与业务价值

业务痛点

AI Agent 正在从「对话玩具」走向「生产力工具」，但现有 Agent 框架普遍存在三大瓶颈：

痛点	具体表现
能力耦合	Bash 执行、文件读写、搜索等能力硬编码在核心循环中，新增一种工具需改动 Agent Loop 代码
模型绑定	多数框架仅适配单一模型提供商，切换供应商意味着重写 LLM 交互层
执行环境固定	默认本机执行，无法灵活切换到沙箱/容器/远程环境，安全与隔离难以兼顾

开发者经常面临这样的困境：想给 Agent 加一个 Web 搜索能力，却发现要改五个文件；想从 OpenAI 切到 DeepSeek，发现 prompt 拼装逻辑和流式协议绑死了；想让 Agent 在 Docker 里安全执行命令，却只能 fork 整个运行时。

项目目标

DeepSeek Harness（dsh）立项要解决的核心问题是：构建一个「一切皆插件」的 Agent 框架，让工具、模型、执行环境都可以通过插件热替换，无需触碰核心代码。 服务对象是：

• 应用开发者：需要快速搭建面向任务的 AI Agent
• 插件开发者：希望为 Agent 生态贡献可复用能力
• 运维团队：需要安全沙箱、审批策略、可观测性

落地价值

维度	收益
降本	插件化架构避免重复造轮子，社区插件直接复用
提效	从零搭建一个可用 Agent 从「改 N 个文件」缩短到「写一个 YAML + 一个 apply 函数」
自动化	Agent 可自主调用 Bash、编辑器、LSP、搜索等工具完成编码/运维任务
减少出错率	会话事件溯源（Event Sourcing）+ 可逆注册机制，保证运行时可热替换、可回滚、可恢复

---

二、核心功能模块

核心功能（主打能力）

1. 多模型适配与无缝切换

• 内置 DeepSeek 官方适配器 + OpenAI 兼容协议适配器（llm-pi-ai），支持 Anthropic、OpenAI、Bedrock、Vertex、Azure、Codex 等提供商
• 自定义 Provider：填写 Provider ID + Base URL + API Protocol 即可接入任意 OpenAI 兼容端点
• 模型切换无需重启，下一个请求即生效
• 支持视觉模型声明（input: [text, image]）

2. Agent Loop 与工具编排

• 完整的 Turn → Step → Tool Call 流式驱动循环
• 内置工具集：bash（Shell 执行）、str_replace_editor（文件编辑）、terminal（持久 PTY）、web（搜索/抓取）、fs（文件系统）、lsp（语言服务协议）、subagent（子 Agent 委派）
• 工具注册通过 ctx.tools.register() 声明式完成，schema 自动注入 system prompt
• 三阶段工具执行管线：tools/pre-execute → tools/execute → tools/post-execute，支持策略拦截

3. 会话持久化与事件溯源

• Append-Only 事件日志（SessionEvent）作为唯一事实来源
• LLM 消息历史从日志派生（deriveMessages()），而非独立存储
• 支持 JSONL 和 SQLite 两种持久化后端，可插拔切换
• 会话 Fork / Resume / Compaction（上下文压缩）全链路支持

附加功能（配套支撑）

功能	说明
Web UI	浏览器端对话界面，支持工作区管理、模型选择、审批策略
Python SDK	deepseek-harness-sdk 一行代码启动 Agent，内嵌 Node.js 运行时
Headless 模式	无服务器一键运行，适合 CI/CD 集成
ACP 协议	JSON-RPC stdio 暴露 Agent 会话，支持自动化编排
审批与沙箱	权限预设（workspace-write / danger-full-access）、E2B 远程沙箱
HMR 热替换	编辑插件源码自动重载，开发体验丝滑
Skill 系统	可复用的 Agent 技能包，通过 Badge / Filesystem Provider 注册
Subagent	支持 In-Process Fork / ACP / Codex / Claude Code 等多种子 Agent 后端

典型使用流程

配置模型 API Key → 选择工作区 → 发起对话（Agent 自动调用工具）→ 审批敏感操作 → 获取结果 / 导出会话

---

三、技术栈选型

层次	技术选型
框架核心	Cordis ------ 插件化框架（服务注册、事件系统、可逆副作用）
开发语言	TypeScript（Host 侧 + Client 侧双聚合编译）
前端	Web UI（Vite 构建）、Cordis Client 插件体系
后端运行时	Node.js 22.19+ / 24+ / 26+
LLM 协议	OpenAI Chat Completions 兼容协议、流式 SSE
持久化	JSONL（默认）、SQLite（可选）
包管理	pnpm monorepo + workspace
构建工具	tsc（增量编译）+ tsdown（打包）、Typert（类型反射 + Host-Client Remote 生成）
代码质量	Oxlint、Lefthook Git Hooks、Vitest 测试、TypeScript strict mode
CI/CD	GitHub Actions 多 Node 版本兼容矩阵
SDK	Python SDK（deepseek-harness-sdk），内嵌 Node.js 运行时
容器/沙箱	E2B 远程沙箱、Docker 兼容

---

四、整体架构设计

分层架构

DeepSeek Harness 采用 插件驱动的事件溯源架构，没有传统的 MVC 分层，而是以 Cordis 插件体系为核心：

┌──────────────────────────────────────────────────┐
│                   Profile 层                      │
│  (web / headless / acp --- 预置运行模板)            │
├──────────────────────────────────────────────────┤
│                   Bundle 层                       │
│  (dsh-base / dsh-web-app / dsh-headless --- 能力包)│
├──────────────────────────────────────────────────┤
│              Plugin / Service 层                  │
│  ┌─────────┐ ┌─────────┐ ┌──────────┐           │
│  │ Agent   │ │ Session │ │ System   │           │
│  │ Loop    │ │ Log     │ │ Prompt   │           │
│  └────┬────┘ └────┬────┘ └─────┬────┘           │
│       │           │            │                  │
│  ┌────┴────┐ ┌────┴────┐ ┌─────┴────┐           │
│  │ Tools   │ │ LLM     │ │ Compac-  │           │
│  │ Registry│ │ Stream  │ │ tion     │           │
│  └─────────┘ └─────────┘ └──────────┘           │
├──────────────────────────────────────────────────┤
│             Capability Seam 层                   │
│  (Shell / FS / Subprocess / Sandbox / Web / ...) │
├──────────────────────────────────────────────────┤
│               Provider 层                        │
│  (bash-local / fs-local / fs-sandbox / e2b / ...)│
└──────────────────────────────────────────────────┘

部署架构

• 单体进程：一个 Node.js 进程承载所有插件，Profile 决定加载哪些 Bundle
• Host-Client 双面：Host 侧运行服务逻辑，Client 侧运行浏览器 UI，通过 API Gateway / Remote RPC 通信
• 可扩展为微服务：Subagent 支持 ACP / Codex / Claude Code 等外部 Agent 进程委派

数据流

用户输入 → Agent Inbox → Turn/Step 开启
  → System Prompt 组装（工具 schema + prompt sections）
  → LLM 流式请求（ctx.llm → Provider Adapter → 远程 API）
  → Assistant Response + Tool Calls
  → Tool 执行管线（pre-policy → execute → post-policy）
  → Tool Result 追加到 Session Log
  → 判断是否继续 Step / 结束 Turn
  → 事件持久化（JSONL / SQLite）

关键设计：模型可见即日志可溯。任何到达模型请求的信息必须可从日志重建，这是运行时不变量。

---

五、项目目录与工程规范

目录结构

deepseek-harness/
├── packages/
│   ├── core/                    # 核心子系统
│   │   ├── agent/               # Agent 注册与生命周期
│   │   ├── agent-loop/          # 默认 Agent 驱动循环
│   │   ├── session/             # 会话事件日志
│   │   ├── system-prompt/       # Prompt 组装
│   │   ├── tools/               # 工具注册与执行管线
│   │   └── scope/               # Agent 作用域原语
│   ├── llm/                     # LLM 相关
│   │   ├── llm/                 # 流式协议与适配器缝
│   │   ├── llm-deepseek/        # DeepSeek 官方适配器
│   │   └── llm-pi-ai/           # OpenAI 兼容适配器
│   ├── shell/                   # Shell 执行
│   │   ├── shell/               # Shell 服务定义
│   │   ├── bash-local/          # 本地 Bash 执行器
│   │   └── tool-bash/           # Bash 工具（模型可见）
│   ├── fs/                      # 文件系统
│   ├── terminal/                # 持久终端
│   ├── web/                     # Web 搜索/抓取
│   ├── lsp/                     # 语言服务协议
│   ├── subagent/                # 子 Agent 委派
│   ├── compaction/              # 上下文压缩
│   ├── session/                 # 会话持久化/查询/投影
│   ├── settings/                # 配置管理
│   ├── credentials/             # 凭证管理
│   ├── sandbox/                 # 沙箱策略
│   ├── skill/                   # 技能系统
│   ├── workflow/                # 工作流引擎
│   ├── bundle/                  # 发布 Bundle
│   │   ├── base/                # 基础能力包
│   │   ├── web-app/             # Web UI Bundle
│   │   └── headless/            # Headless Bundle
│   └── ...
├── apps/
│   ├── web/                     # Web 前端应用
│   └── cli/                     # CLI 入口
├── python/                      # Python SDK
├── docs/                        # 文档源码
├── examples/                    # 示例
├── vendor/                      # Cordis 供应商代码
├── scripts/                     # 构建/CI 脚本
├── cordis.yml                   # 插件组合配置
├── lefthook.yml                 # Git Hooks 配置
├── AGENTS.md                    # Agent 开发指南
└── CONTRIBUTING.md              # 贡献指南

编码规范

• TypeScript strict mode，Host / Client 双聚合编译隔离
• 品牌化 ID（Branded ID）：SessionId、CallId 等编译期不可混用
• 判别联合用 switch 而非 if 链，保证类型窄化
• FIXME / TODO / XXX 三级注释标记，按紧急度区分
• 文档类型声明使用 ts type-equiv 围栏，自动与源码同步校验

配套文档

文档	位置
用户指南	docs/user/guide/
插件开发教程	docs/user/develop/
架构文档	docs/architecture.md
API 参考	docs/reference/
Cordis 教程	docs/cordis-tutorial/

---

六、快速上手演示

环境准备

# 前置：安装 Node.js 22.19+ 或 24+
node --version  # v22.19+

一键启动（npm）

npx @deepseek-ai/dsh web

浏览器打开 http://127.0.0.1:3080，进入 Web UI。

从源码运行

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

配置模型

1. 打开 Settings → Models
2. 输入 DeepSeek API Key（获取地址）
3. 保存，即刻生效

运行第一个任务

1. 点击 Choose workspace，添加项目目录
2. 新建 Session，输入：

Summarize this repository and identify its main packages.

Agent 会自动读取文件、分析代码结构、返回摘要。全程无需手动调用任何工具。

Python SDK 方式

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv && . .venv/bin/activate
pip install deepseek-harness-sdk

export DEEPSEEK_API_KEY=sk-your-key-here

python examples/jsonrpc-agent/minimal.py \
  --workspace /path/to/project \
  --session-root /path/to/sessions \
  --session-id demo-001 \
  "Inspect the repository and fix the failing tests."

SDK 内嵌 Node.js 运行时，无需本机安装。

---

七、项目亮点与难点攻坚

亮点

1. 一切皆插件的极致解耦

传统 Agent 框架的能力是「写死在核心里的」。DeepSeek Harness 把模型适配器、工具注册、会话持久化、Shell 执行------全部做成插件。Agent Loop 自身也是插件 （dsh-agent-loop），可被替换。

这意味着：

• 新增一个工具 → 写一个 apply(ctx) 函数 + ctx.tools.register()
• 切换 LLM Provider → 注册新适配器到 ctx.llm
• 换持久化后端 → 替换 session-persistence 的 Provider 插件

所有注册都是可逆副作用（ctx.effect()），插件卸载时自动清理。

2. Capability Seam 三角色分离

每个可替换能力拆为三个角色，放在独立包中：

Service Definition（接口）  ←→  Service Provider（实现）  ←→  Consumer / Tool（消费）

以 Bash 执行为例：

• dsh-shell 定义服务接口
• dsh-bash-local 提供本机执行实现
• dsh-tool-bash 暴露为模型可调用的工具

Provider 和 Consumer 互不依赖，只依赖 Definition。换沙箱执行只需替换 Provider 行。

3. 事件溯源 + 可恢复会话

Session Log 是 Append-Only 事件流，12 种事件类型覆盖完整生命周期。LLM 消息历史从日志派生，而非双写。这让 Fork / Resume / Compaction / Telemetry 全部自然衍生，无需额外同步机制。

4. Host-Client 双面编译 + Typert 类型反射

Host（Node.js）和 Client（Browser）共享 Context 接口但声明合并不同服务，TypeScript 编译隔离为两个聚合。Typert 在 Host 构建阶段生成反射元数据和 Host-for-Client Remote 投影，Client 侧通过 ctx.remote 透明调用 Host 服务------类型安全贯穿全栈。

难点攻坚

难点 1：Host-Client Context 声明合并冲突

问题 ：Host 和 Client 都通过 TypeScript declaration merging 向 Context 接口添加服务，但同一 ts.Program 看到两侧合并会报类型碰撞。

解决 ：将仓库拆为 Host 聚合（tsconfig.host.json）和 Client 聚合（tsconfig.client.json），各自形成独立程序。Solution root 只引用两个聚合，不扁平化为一个 Program。API Remotes 是唯一需要双面 tsconfig 的包，通过 DSH_BUILD_FACE 环境变量控制 tsdown 选择 Host 或 Client 入口。

难点 2：模型可见信息的日志一致性

问题：任何到达模型请求的内容必须可从日志重建，否则 Fork / Resume / Compaction 会丢失上下文。

解决 ：建立运行时不变量------「模型可见即日志可溯」。新增模型可见输入必须对应新的 Session Event 类型，通过 SessionEventMap 扩展并从日志渲染。deriveMessages() 是唯一的消息派生入口，拒绝任何绕过日志的「捷径」。

难点 3：插件热替换的资源泄漏

问题：HMR 卸载旧插件时，其注册的事件监听器、工具、定时器可能残留。

解决 ：Cordis 框架的「注册即副作用」机制------所有通过 ctx.on()、ctx.tools.register()、ctx.effect() 的注册都会在插件 Fiber 卸载时自动清理。自定义资源通过 ctx.effect(() => cleanup) 提供清理函数，逆序执行。

---

八、适用场景与后续迭代规划

适用场景

场景	说明
AI 编程助手	Agent 自主读取代码、运行测试、修复 Bug，适合开发团队
自动化运维	Agent 执行 Shell 命令、检查日志、排查故障，适合 SRE
知识库问答	结合搜索 + 文件读取，构建企业内部知识 Agent
CI/CD 集成	Headless 模式一行命令跑 Agent 任务，适合流水线
多 Agent 协作	Subagent 委派 + Team 模式（实验性），适合复杂任务分解
Agent 框架定制	基于插件体系二次开发，适合需要定制 Agent 行为的团队

适用人群

• 需要搭建 AI Agent 的应用开发者
• 希望贡献/开发 Agent 能力的插件开发者
• 需要安全执行环境的运维团队
• 研究 Agent 架构的技术学习者

后续迭代方向

方向	计划
稳定性	从 Developer Preview 迈向稳定版，减少破坏性变更
Team 多 Agent	当前为实验性功能，计划完善共享任务 DAG、持久邮箱、协调策略
更多 LLM Provider	扩展模型适配器生态，支持更多国产/开源模型
沙箱与安全	增强沙箱策略细粒度，支持更多容器运行时
可视化编排	Workflow 引擎可视化配置，降低 Agent 编排门槛
插件市场	建立社区插件发现与安装机制（dsh-plugin topic 已就位）
Windows 支持	当前 Python SDK 和部分 Composition 不支持 Windows Agent，计划扩展
性能优化	大会话 Compaction 性能、长上下文处理、并发 Agent 调度

---

结语

DeepSeek Harness 用「一切皆插件」回答了 Agent 框架的核心问题------如何在不改核心代码的前提下扩展能力。Cordis 框架提供的服务注册、事件分发、可逆副作用三件套，让每个能力都可以被替换、被组合、被热更新。如果你正在寻找一个可以深度定制的 AI Agent 框架，或者想理解事件溯源如何应用于 Agent 系统，DeepSeek Harness 值得深入研究。

项目地址：github.com/deepseek-ai/deepseek-harness

文档站点：deepseek-harness.github.io

许可证：MIT