DeepSeekHarness开源Agent底座详解

DeepSeek Harness：一切皆插件的开源 Agent 底座（架构与源码详解）

一、项目整体概述

1.1 项目定位

DeepSeek Harness（命令行 dsh，npm 包 @deepseek-ai/dsh） 是 DeepSeek AI 于 2026 年 8 月 13 日 开源的 Agent 执行底座（Harness） ，采用 MIT 开源协议 ，当前为开发者预览版（v0.1 / 0.1.0-rc.x）。

它不是又一个"类 Claude Code 的编程助手"，而是一个比编程助手更底层的 Agent 运行框架。DeepSeek 官方用一句话定义了它的哲学：

Agent = Model + Harness

模型是 Agent 的"灵魂"（思考与生成）；Harness 负责把模型接入现实世界------文件系统、终端、网页、API、权限、计划、上下文。两者结合，才是能自主行动、真正干完任务的 Agent。

DeepSeek Harness 的核心亮点在于它把业内共识 Agent = Model + Harness 当作产品哲学，并采用 "一切皆插件（Everything is a Plugin）" 的架构，把过去被厂商封死在壳子里的每一个组件------模型、工具、技能、会话、沙箱、存储、循环、调度、UI------全部拆成可热插拔的插件。

1.2 项目核心信息

项目	说明
开发团队	DeepSeek AI（深度求索）
开源时间	2026 年 8 月 13 日
开源协议	MIT
GitHub 仓库	`github.com/deepseek-ai/deepseek-harness`
命令行工具	`dsh`
npm 包	`@deepseek-ai/dsh`
内核框架	Cordis（来自 Koishi.js 生态，vendor 自 `cordis 4.0.1`）
技术栈	TypeScript / Node.js
官方主页	`https://www.deepseek.com/harness/`
定位	Agent 执行底座（编码只是官方预置的一套组合）

1.3 与 Claude Code / Codex 的本质区别

Claude Code、Codex 本质上是把 Harness 这一层做成了闭源成品 ：工具、Skill、会话管理、沙箱、调度、工作流全被厂商封装进一个壳里，用户用的是"精装房"，墙不能拆、格局不能动。

DeepSeek Harness 则把这套房子的施工图和所有预制件都开源，还告诉你"墙随便拆，零件随便换"------模型适配器、工具注册表、技能、会话日志、沙箱、存储、调度、UI，乃至 Agent 循环本身，全部是插件，无需改框架源码就能以配置方式替换任意一层。

二、核心设计理念与设计思想

2.1 核心理念：一切皆插件（Everything is a Plugin）

整个设计可以浓缩为一句话：内核极薄 + 能力全插件化。

Cordis 内核只做一件事：插件的加载、卸载与依赖管理，不提供任何具体能力；
所有真实能力都是插件：模型、工具、Skill、会话、存储、Agent 循环、沙箱、调度、UI，通过 Cordis 的"服务（Service）"与"事件（Event）"机制彼此协作；
配置即插件树 ：cordis.yml 里一行就是一个插件实例，部署方在 patch 层覆盖一行即可替换能力，无需改动源码。

2.2 底层设计思想：时间/空间可组合性（Cordis）

Cordis 是一套成熟的 TypeScript 依赖注入与插件化元框架，DeepSeek 把它 vendor 进仓库并改 scope 为 @deepseek-ai/cordis。其设计有正式论文支撑：《A Programming Paradigm for Spatiotemporal Composability》（arXiv:2608.25512），把"动态组合"拆成两个正交维度：

时间可组合性（temporal composability） ：组件被移除时，它对共享环境做的副作用必须被完整逆转。Cordis 采用"可逆 effect"------每次上下文变换（注册服务、挂监听器、占用资源）都在运行时登记一个逆操作，卸载时按注册逆序（LIFO）回滚。
空间可组合性（spatial composability）：组件声明依赖，依赖的出现/消失/替换会自动驱动该组件激活或停用（"响应式 coeffect"），上下文每次变化都拿组件的依赖规格比对，判定为激活、停用或中性。

两者统一成单一 Context 类型，所有对外交互都经由它中介，论文称之为 "context paradigm" 。核心洞察：进程重启和容器编排其实是粗粒度的可组合性------OS 按进程回收资源、K8s 按服务调整依赖拓扑，但为删一个组件而重启整个进程会丢掉缓存、连接、中间计算。Cordis 把这个保证下推到"进程内组件"级别。

2.3 由架构推导出的设计表现

每个 Agent 能力都挂在 ctx.<key> 服务上 ：如 ctx.llm（模型适配器）、ctx.tools（工具注册表）、ctx.shell、ctx.sessions、ctx.agentLoop、ctx.subagents 等，提供方均可替换；
前端 UI 也是插件 ：dsh-client-ui-* 系列有几十个包，浏览器里跑着一个独立的 Cordis 客户端运行时，通过 RPC 与服务端"双半插件"相连；
自改造能力（self-modification）：系统本身由插件拼成，因此能在运行时检查自己缺什么插件并当场写一个新插件挂上去，无需重启、不崩（动态 Cordis 插件运行时）。

三、核心架构

3.1 整体架构图（文字版）

复制代码

                    ┌─────────────────────────────┐
                    │   Cordis 内核（@deepseek-ai/cordis）│
                    │  仅负责：插件加载 / 卸载 / 依赖管理 │
                    └──────────────┬──────────────┘
           通过"服务(Service)"与"事件(Event)"机制协作
   ┌──────────┬──────────┬──────────┬──────────┬─────────┐
   ▼          ▼          ▼          ▼          ▼         ▼
会话/存储   沙箱插件    UI插件    调度/工作流  规则插件  工具插件/SQL
插件        (Landlock  (Web界面) 插件        (DeepSeek/   (文件/Shell/
(上下文     等OS级隔离)          (计划任务)   Anthropic/   搜索)
与记忆)                                     OpenAI/自定义)

3.2 核心服务槽位（ctx 服务）

服务槽位	职责	可替换性
`ctx.llm`	模型适配器（接入约 40 家 provider，含 OpenAI / Claude 等）	可替换
`ctx.tools`	工具注册表	可替换
`ctx.shell`	终端执行	可替换
`ctx.sessions`	会话与上下文管理	可替换
`ctx.agentLoop`	Agent 主循环	可替换
`ctx.subagents`	子 Agent 调度	可替换

3.3 四种运行模式（本质是四套预设插件模板）

模式	保留能力	适用场景
标准模式（Standard）	完整 coding agent：文件编辑、shell、搜索、Skills、计划、目标、后台任务、子 Agent、工作流（20+ 工具）	新手首选、日常写代码
PTC / Code 模式	标准全部能力 + 通过 Code Mode SDK 让模型写 TypeScript 程序、在一次 `run_code` 内编排多次工具调用	多步骤、长程、重复工具调用任务
极简模式（Minimal）	仅保留持久化 Bash + `str_replace_editor` 文件编辑器	基准测试、研究模型原生能力
创造模式（Creative）	完整能力 + 运行时巡检、插件实验、Preset/新 Agent 创建	开发 Harness / 插件（自改造在此发生）

PTC 模式动机 ：传统是 LLM→Tool→LLM→Tool 串行往返，中间结果全塞回上下文；PTC 让模型先写一段程序，把"搜索→过滤→读取→修改"一次跑完，中间结果留在代码环境，天然支持 Promise.all 并行，省 Token、降延迟。

四、核心源码解析

4.1 安装与启动

bash 复制代码

# 方式一：全局安装
npm install -g @deepseek-ai/dsh
dsh --version

# 方式二：免安装在线启动（本地 Web UI，默认 http://127.0.0.1:3080）
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

4.2 编写一个插件（"插件就是一个函数"）

typescript 复制代码

import type { Context } from '@deepseek-ai/cordis'

export const name = 'greeter'
// 声明依赖：只有 llm 服务就绪时本插件才激活（空间可组合性）
export const inject = ['llm']

export function apply(ctx: Context, config: { greeting: string }) {
  // 注册服务：卸载时自动从服务表撤回（可逆 effect）
  ctx.provide('greeter', {
    greet: (who: string) => `${config.greeting}, ${who}!`,
  })
  // 注册监听器：同样是 effect，随插件卸载一并移除
  ctx.on('greet', (who: string) => console.log('hello', who))
}

4.3 注册一个模型可调用的工具

typescript 复制代码

export function apply(ctx: Context) {
  ctx.inject(['tools'], (ctx) => {
    ctx.effect(() => ctx.tools.register({
      name: 'hello',
      description: 'greet someone',
      parameters: { name: { type: 'string' } },
      async execute(args) { return `Hello, ${args.name}!` },
    }))
  })
}

register() 返回 disposer，插件卸载时工具自动注销；tools/result 事件让任何插件都能观察每次工具调用，而不必认识执行者。事件有四种派发模式：emit / parallel / bail / waterfall（waterfall 监听器必须调用 next() 才继续，否则短路）。

4.4 自改造能力（最"自指"的包 `@deepseek-ai/dsh-tool-cordis`）

给 Agent 五个工具，使其可在运行中检查/改造自身框架：

cordis_inspect：只读巡检当前进程（哪些服务在跑、各 fiber 状态、注册了哪些工具）；
cordis_define：现场定义一个小插件；
cordis_run：把宿主半放入 node:vm 沙箱执行；
cordis_stop / cordis_undefine：卸载插件。

即 Agent 可以全程不改 cordis.yml、不装 npm 包、不重启进程地：检查框架 → 写新插件 → 用完卸载。官方对信任边界的说明很直白：动态包与 bash 同权，沙箱隔离全局但不构成安全边界。

五、核心功能与能力详解

5.1 模型无关（多模型接入）

支持约 40 家模型 provider（含 OpenAI / Claude 等），子 Agent 甚至能委派给竞品 Agent。

5.2 会话可观测性（append-only 会话日志）

规则是"模型看到的，一定被记录 "------系统提示词、思维链、工具调用与结果、子 Agent 调度、每一次上下文注入都在里面，可在 Trajectory 视图按来源追溯，并支持恢复、分叉、检索、回放。

5.3 真实 OS 级沙箱隔离

Linux：bwrap + Landlock；
macOS：Seatbelt；
Windows：受限 ACL token；
默认 fail-closed。

5.4 多形态交付

可作为桌面应用（macOS / Windows 桌面端，v0.2 提供）、网页 UI、命令行；v0.2 还带来应用内插件管理、计划任务与实验性的异步问答模式（等待超时后 Agent 继续干活，之后再与用户的回答对账）。

六、项目优势、代价与安全

6.1 核心优势

MIT 协议：可 fork 后闭源嵌入企业产品；
模型无关 + 全组件可替换：把"换模型/换沙箱/换循环"从改装变成配置；
自托管、可自审计：不被托管端点锁住，数据自主可控；
真实 OS 级沙箱：安全隔离更扎实；
可自改造：运行中动态写插件、扩展能力，无需重启。

6.2 需要关注的代价

稳定性 ：官方明确"会有破坏性变更"，建议 npx @deepseek-ai/dsh@<version> 钉版本；
安全（CVE-2026-82533，CVSS 9.4） ：沙箱内 shell 可通过 loopback 访问 Harness 未认证的本地控制 API，被诱导的 shell 命令可把会话设为 danger-full-access 并关掉审批提示。影响 0.1.1-rc.2 及更早版本，官方在 0.1.2-alpha.1 修复。教训："能改写自己规则的沙箱是权限 UI，不是安全边界"，控制平面绝不能落在被约束进程够得着的范围内；
成熟度：目前是开发者预览版，社区对发布节奏、星数含金量存在讨论。

6.3 横向性能参考（同一 DeepSeek V4.1 Flash 模型，社区整理）

实现	mini-SWE v1.1 resolved	Terminal-Bench 2.1 pass@1
mini-SWE	74.2	90.3
DSH 极简	72.6	90.6
DSH 标准	70.5	85.8
Claude Code	69.8	88.0
DSH PTC	67.6	85.8
OpenCode	65.5	85.0

可读信号：极简模式反而略高于标准模式；同一模型换 Harness 分数区间可拉开十几个点------"模型行不行"很大程度上是"你拿什么工具跑它"。

七、适用场景与建议

7.1 适合谁

想自托管、不想被托管端点锁住的团队；
需要在自家产品里嵌入 Agent 运行时的产品团队；
做 Agent 基础设施或插件生态的开发者；
要研究"模型原生能力 vs 脚手架影响"的评测方（极简模式正为此而生）。

7.2 不太适合

只想找一个开箱即用 coding agent 的个人用户------这类场景 Claude Code / Codex 的完成度更省心。

7.3 上生产建议

先在容器或 VM 里验证插件权限模型与第三方插件来源可信度；生产凭证不要靠近运行环境；对稳定敏感就钉死版本号。

八、总结与展望

DeepSeek Harness 是 DeepSeek 从"卖模型"走向"卖模型 + 执行层 + 生态"的关键一步。它的价值不止于多一个开源 Agent 框架，更在于用 Cordis 内核 + 一切皆插件的架构，第一次把"Agent 执行底座"本身变成了可自由拼装、可热插拔、可自审计、甚至可自改造的开源基础设施。

2026 年的竞争正在从"卷模型更聪明"明显向 Harness（执行层） 转移------同一个强模型，套进不同的 Harness，能调用什么工具、能不能持续工作，体验可能天差地别。DeepSeek Harness 正是在这条赛道上，把"车架和车厢的设计图"开源，号召全世界的开发者一起往里塞零件。

参考：GitHub github.com/deepseek-ai/deepseek-harness ｜官方 deepseek.com/harness/ ｜论文 arXiv:2608.25512（北京大学 × DeepSeek-AI，Spatiotemporal Composability）｜ OX Security CVE-2026-82533 分析