DeepSeek Harness 深度解析：当“一切皆插件“重新定义 Agent 运行时

最新推荐文章于 2026-08-16 12:13:22 发布

原创最新推荐文章于 2026-08-16 12:13:22 发布 · 377 阅读

7 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

AI 时代程序员必备技能

Codex、Claude Code、Cursor、Hermes Agent、OpenClaw等工程化实战专栏，讲透 AI 如何接管脏活累活

一键订阅

2026年8月13日，DeepSeek 正式开源 DeepSeek Harness（dsh）开发者预览版，MIT 协议。这不是又一个 Coding Agent 产品，而是一个把模型、工具、沙箱、会话、UI 全部拆成插件的 Agent 运行时框架。本文从架构设计、核心机制、实操指南和行业格局四个维度，带你完整理解这个项目。

一、为什么 Harness 值得关注？

先抛一个公式：

Agent = Model + Harness

模型是 Agent 的灵魂，负责思考和推理；Harness 则是让思考落地为行动的执行层——它决定模型能看到什么上下文、能调用什么工具、出错后如何恢复、任务如何拆分与编排。

过去一年多，大模型的竞争焦点集中在参数规模、Benchmark 分数和 API 价格上。但当模型真正进入代码库、终端和长期任务后，“模型能力强"并不自动等于"Agent 好用”。同一个模型放进不同的 Harness 里，表现可能天差地别。

DeepSeek 显然意识到了这一点。7月31日 V4 Flash 发布时，更新日志里就提到公开 Code Agent Benchmark 使用的测试框架正是"即将发布"的 Harness 极简模式；8月13日，V4-Pro 正式版（Terminal Bench 2.1 得分 87.9，DeepSWE 62.7）与 Harness 同步亮相——一个提供更强的大脑，一个提供可工作的身体。

据麻省理工科技评论报道，Harness 发布当天 GitHub Star 即突破 27,500，Fork 超 2,000。开发者用脚投票，说明市场对一个真正可组合的 Agent 运行时渴望已久。

二、核心设计理念：Everything is a Plugin

2.1 不是"DeepSeek 版 Claude Code"

很多人第一反应是把 Harness 归类为"又一个 Coding Agent"。但读完架构文档你会发现，它的定位完全不同：

维度	Claude Code / Codex	DeepSeek Harness
定位	面向终端用户的成品 Agent 应用	面向开发者的 Agent 运行时框架
架构	垂直集成，核心不可替换	一切皆插件，每层可替换重组
模型	绑定自家模型（Claude / GPT）	模型适配器是插件，支持任意供应商
扩展方式	Skills / Hooks / MCP	Cordis 插件 + 配置叠加 + Seam 替换
开源协议	闭源 / Apache 2.0（CLI）	MIT

Claude Code 比的是默认体验的打磨程度；Harness 选了另一条路——把整个运行时摊开给你换。

2.2 Cordis：插件元框架底座

Harness 没有自己造轮子写插件系统，而是站在 Cordis 之上。Cordis 是一个元框架，只负责三件事：

插件挂载/卸载：每个插件通过 ctx.effect() / ctx.on() 注册服务和副作用，卸载时自动撤销（可逆副作用）
依赖管理：插件声明依赖的服务，Cordis 保证加载顺序
服务与事件协作：插件之间不直接调用对方代码，通过共享上下文注册服务、广播事件来协作

这个设计的关键含义是：没有特权内核。模型适配器是插件，工具注册表是插件，会话日志是插件，连 Agent Loop 本身都是插件。你不需要 fork 源码去改核心逻辑，挂载一个你自己的插件就行。

Cordis 的设计理念在论文 A Programming Paradigm for Spatiotemporal Composability 中有完整阐述，核心思想是让软件系统在空间（模块组合）和时间（生命周期管理）两个维度上都具备可组合性。

2.3 配置叠加：四层插件树

一个运行中的 dsh 实例是一棵插件树，启动时由有序的层叠加而成：

┌─────────────────────────────────────┐
│         --patch 覆盖层（CLI）        │  ← 最高优先级
├─────────────────────────────────────┤
│      Home 级 cordis.patch.yml       │
├─────────────────────────────────────┤
│      Profile 级 cordis.patch.yml    │
├─────────────────────────────────────┤
│  Bundle 层（base → web-app / ...）  │  ← 最低优先级
└─────────────────────────────────────┘

Bundle：Cordis 配置行和代码的分发包，是可复用的插件组合单元
Profile：命名的插件组合，存储在 Harness Home 中，声明它堆叠哪些 Bundle。web 和 headless 是内置模板
Patch：按插件 ID 定位并整体替换其配置，或插入新行

四层叠加有一个清晰的工程含义：发行版、Profile、用户、命令行四个改配置的入口分得清清楚楚。你改坏自己的层，往上回溯到 Bundle 就能排障。

查看实际启动的完整插件树：

dsh --profile web --dump-config

输出的每一行都可以被你自己的 Patch 替换。

三、核心机制深度拆解

3.1 Session Log：一切模型可见的，必可重建

这是 Harness 最让我欣赏的设计之一。

架构文档中有一条硬性不变量：

Model-visible ⟺ logged：任何到达模型请求的内容，都必须能从 Session Log 重建。

Session Log 是一个仅追加（append-only）的事件流，记录：

系统提示词（System Prompt）的组装结果
模型推理内容（Reasoning）
工具调用与返回结果
子 Agent 调度
每一次上下文注入
用户消息、助手消息的原始 chunk

用户消息 → 组装 Prompt → agent/request → llm/stream
    → assistant/chunk* → assistant/message
    → tool/call* → tools/pre-execute → tools/execute → tools/post-execute
    → tool/result* → （循环或结束）

这些事件不只是日志，它们是系统状态的唯一来源（Source of Truth）。会话恢复、分叉（Fork）、回放、搜索、转录、遥测、持久化——全部从这条事件流派生。

这意味着什么？Agent 的执行过程第一次变得可以被系统化记录、分析和调试。你可以在 Trajectory 视图中按来源检查每条记录，精确复盘"模型为什么做出这个决策"。

3.2 Agent Loop：Turn / Step 状态机

默认的 Agent Loop 实现是 ReactLoopAgent，它把工作切成两个层级：

Step（步骤）：一次模型请求 + 它调用的工具
Turn（轮次）：零个或多个 Step，从领取首条输入开始，到不再有未完成工作时关闭

状态机流程：

turn/start
  ├─ claim 输入（next-step 队列 + 可选 next-turn 消息）
  ├─ 组装 Prompt 片段 + 工具 Schema
  ├─ agent/pre-step（可拒绝或重写消息）
  │
  ├─ step/start
  │   ├─ 追加消息到日志
  │   ├─ 从日志派生模型历史
  │   ├─ agent/request → llm/stream → assistant/chunk*
  │   ├─ tool/call* → tools/execute → tool/result*
  │   └─ step/end
  │
  ├─ 工具还欠请求？或有新输入？→ 下一个 step
  └─ agent/turn-stopping → turn/end

一个精妙的设计是 Inbox 队列。输入不直接进状态机，而是进入两条队列：next-turn 和 next-step。claim() 批量领取输入，有些消息立即唤醒驱动，注入的上下文则留在队列里等下一条消息触发。

循环不直接读"消息数组"，循环读队列。 输入、注入、中断都变成队列操作，状态机只关心"队列里还有没有活"。

3.3 Capability Seam：可替换的能力接缝

Harness 把可替换能力称为 Seam（接缝），每个 Seam 包含三个角色：

角色	职责
Service Definition	声明接口
Service Provider	实现接口
Consumer	使用接口（通常是面向模型的工具）

三个角色必须一起设计，单独一个不构成 Seam。目前已有 16+ 个 Seam：

llm          模型适配器
fs           文件系统
shell        Shell 执行
subprocess   子进程管理
sandbox      沙箱策略
terminal     持久终端
lsp          语言服务器
web          网页访问
subagent     子 Agent
workflow     工作流引擎
compaction   上下文压缩
skill        技能系统
...

Seam 的威力在于：换一个 Provider，整个产品行为就变了。比如把文件系统和子进程 Provider 指向远程沙箱，Bash、PTY、LSP 就一起搬过去了，不需要为每个工具写 fork。

3.4 四种运行模式

Harness 内置四种 Agent 预设，对应不同场景：

模式	工具集	适用场景
Standard	完整工具集：文件编辑、Shell、文件/网页搜索、Skills、规划、目标、子 Agent、工作流	日常编码 Agent
Code（PTC）	Standard 全部能力 + Code Mode SDK，模型用 TypeScript 程序组合多步工具调用	复杂多步编排
Minimal	仅 Shell + 文件编辑器	模型基准测试
Creator	Standard 全部能力 + 运行时检查、插件实验、预设创作引导	构建自定义 Agent

其中 PTC（Programmatic Tool Calling）模式值得特别关注。传统 Tool Calling 是模型一次调一个工具，多步操作靠多轮对话驱动。PTC 让模型先生成一段 TypeScript 代码，在代码中编排多个工具的调用顺序、条件分支和错误处理，然后一次性执行。这对于需要确定性流程的复杂任务（如"克隆仓库→安装依赖→运行测试→修复报错→提交 PR"）是质的提升。

3.5 扩展点速查

架构文档给出了一张非常实用的"新行为去哪里"映射表：

目标	机制
添加模型供应商	在 `ctx.llm` 注册适配器
添加面向模型的工具	在 `ctx.tools` 注册，Schema 自动加入 Prompt 组装
添加 Shell 执行	注册 `ctx.shell` 后端
添加持久终端	注册 `ctx.terminals` 后端 + `dsh-tool-terminal`
添加人类命令	在 `ctx.commands` 注册，不经过模型轮次直接分发
添加后台任务	在 `ctx.jobs` 注册
限制进程权限	使用 `ctx.sandbox` 后端
拦截请求/工具/轮次	使用 `agent/` 或 `tools/` 事件
Fork 活跃会话	`ctx.sessions.fork()`
管理会话目标	使用 `ctx.goals`

四、快速上手

4.1 环境要求

Node.js ^22.19 或 >=24
pnpm（从源码构建时）

4.2 npx 一键启动（推荐体验）

npx @deepseek-ai/dsh web

启动后访问 http://127.0.0.1:3080，在 Web UI 中配置模型 API Key 即可开始使用。

4.3 从源码构建

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

4.4 Headless 模式（适合 CI/脚本）

# 需要设置 DEEPSEEK_API_KEY 环境变量
pnpm dsh --profile headless "帮我检查这个项目的 TypeScript 类型错误"

4.5 Python SDK

Harness 同时提供 Python SDK 和 JSON-RPC 接口，适合集成到自动化流程：

# 参考 docs/user/guide/python-sdk.md
# 可用于运行 jsonrpc-agent 极简变体进行 Benchmark

4.6 配置模型

Harness 不绑定 DeepSeek 模型。模型适配器本身是插件，支持：

DeepSeek 官方 API
OpenAI 兼容端点（自定义 Base URL）
其他供应商（通过注册适配器插件）

在 Web UI 的设置中配置 API Key 和 Base URL 即可。

五、和主流 Coding Agent 的横向对比

维度	DeepSeek Harness	Claude Code	Codex CLI	Gemini CLI
定位	Agent 运行时框架	自主编码代理	终端编码代理	终端编码代理
开源	✅ MIT	❌ 闭源	✅ Apache 2.0	✅ Apache 2.0
模型绑定	无（插件化）	Claude 系列	GPT 系列	Gemini 系列
可替换核心	✅ 全部可换	❌	⚠️ 部分	⚠️ 部分
多 Agent	✅ 子 Agent + 工作流	✅ Agent Teams	⚠️ 实验性	❌
运行模式	Standard/Code/Minimal/Creator	单一模式	三种审批模式	单一模式
UI	Web UI + Headless + TUI	CLI + IDE + Web + Mobile	CLI + IDE + Cloud	CLI + IDE
会话追踪	✅ Append-only Session Log	⚠️ 有限	⚠️ 有限	⚠️ 有限
沙箱	✅ Pluggable Sandbox Seam	⚠️ 权限策略	✅ 沙箱模式	⚠️ 有限
程序化工具调用	✅ PTC 模式	❌	❌	❌
适合场景	深度定制/研究/企业平台	日常编码（开箱即用）	ChatGPT 用户/CI	免费额度/Google 生态