DeepSeek Harness:一个插件化的开源 Agent 框架

DeepSeek Harness：一个插件化的开源 Agent 框架

当模型能力逐渐趋同，Agent 运行时的设计差异正在成为新的技术分水岭。

一、什么是 DeepSeek Harness

DeepSeek Harness（简称 dsh）是 DeepSeek AI 于 2026 年 8 月开源的 Agent 运行时框架，采用 MIT 协议发布。与近期发布的各类模型不同，DeepSeek Harness 并非大模型本身，而是围绕模型构建的** Agent 运行时基础设施** —— 负责管理工具调用、会话状态、执行环境和用户交互的完整层。

该框架的核心设计理念可概括为一句话：一切皆插件（Everything is a plugin）。模型适配器、工具注册表、会话日志、沙箱环境，乃至 Agent 循环本身，均以独立插件形式存在，开发者可通过配置自由替换或扩展，无需修改框架源码。

二、架构设计：Cordis 插件内核

DeepSeek Harness 建立在 Cordis 元框架之上。Cordis 的职责单一而明确：管理插件的挂载、卸载及依赖关系。其设计思想源自论文《A Programming Paradigm for Spatiotemporal Composability》，强调组件在空间（哪些插件激活）和时间（何时挂载卸载）两个维度的可组合性。

2.1 三层运行时结构

层级	组成	说明
用户界面层	Web UI（:3080）、CLI、Python SDK	开发者与系统交互的入口
内核层	Cordis 插件框架	负责插件生命周期管理与事件分发
能力层	模型、工具、技能、沙箱、存储等	所有可替换的具体能力实现

2.2 关键概念

Profile（配置画像）

存储在 Harness 主目录中的命名组合，定义了启动时加载的 Bundle 列表、外部插件及用户自定义的 cordis.patch.yml。系统预设了 web 和 headless 两种模板画像，分别对应带 Web 界面的交互模式和纯命令行的批处理模式。

Bundle（能力包）

Cordis 配置行及其挂载代码的分发格式。dsh-base 作为每个画像的基础层，提供模型适配、工具集、持久化、沙箱与审批策略、设置、凭据和遥测能力；dsh-web-app 叠加浏览器应用支持；dsh-headless 则提供无服务器的一次性运行器。

Capability Seam（能力接缝）

DeepSeek Harness 中可替换能力的设计单元，由三个角色构成：

Service Definition：声明接口规范
Service Provider：提供具体实现
Consumer：消费该能力的组件

这一设计使得替换单一 Provider 即可迁移整套能力。例如，将文件系统和子进程 Provider 指向远程沙箱后，Bash、PTY 和 LSP 等消费组件将同步迁移，无需逐个修改。

三、核心子系统

从源码结构来看，DeepSeek Harness 的能力覆盖以下核心领域：

领域	关键包	功能
会话管理	`core/session`	追加式事件日志、内存存储、会话回放与分支
提示词组装	`core/system-prompt`	提示词段落与工具 Schema 的组装逻辑
工具执行	`core/tools`	作用域工具注册表、守卫式执行管道
Agent 驱动	`core/agent-loop`	默认的 Agent 接口实现与循环调度
模型接入	`llm/llm`, `llm-deepseek`	消息流词汇与适配器接缝
文件系统	`fs/*`	本地/沙箱文件访问、搜索与策略控制
Shell 执行	`shell/`, `subprocess/`, `terminal/*`	Bash/PowerShell 本地与沙箱执行、持久终端
子 Agent	`subagent/*`	子 Agent 委派，支持 ACP、Claude Code、Codex 等协议
技能系统	`skill/*`	技能注册、本地实现与目录加载工具
工作流	`workflow/*`	工作流能力与 Worker 线程执行器
Web 能力	`web/*`	网页搜索、内容获取工具
MCP 支持	`mcp-client`	Model Context Protocol 客户端
遥测与存储	`session/`, `storage/`	持久化、SQLite/JSON 存储、OpenTelemetry 遥测

3.1 Agent 执行循环

DeepSeek Harness 将一次交互定义为 Turn（轮次），每轮包含若干 Step（步骤），每个步骤对应一次模型请求及其触发的工具调用。执行流程如下：

turn/start
  → claim 输入
  → 组装提示词段落 + 工具 Schema
  → agent/pre-step（可拒绝或改写）
    → step/start
    → 追加用户消息到日志
    → 从日志派生模型历史
    → agent/request → llm/stream → assistant/chunk* → assistant/message
    → tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result*
    → step/end
    → 若有待处理请求或新输入到达 → 进入下一步
  → agent/turn-stopping
turn/end

关键约束：模型可见 ⟺ 已记录。任何进入模型请求的内容必须能从会话日志重构，这一不变性确保了可回放性和可审计性。

四、与现有方案的定位差异

维度	DeepSeek Harness	OpenHands	Claude Code	Cursor Agent
架构	插件化（Cordis）	单体运行时	闭源	闭源
可扩展性	全部可替换	需 Fork 定制	不可扩展	不可扩展
协议	MIT	MIT	专有	专有
阶段	开发者预览	生产可用	生产可用	生产可用
模型绑定	无（插件适配）	无	Anthropic 独占	多模型
会话透明度	完整追加日志	部分	有限	有限

DeepSeek Harness 的差异化在于：框架本身几乎为空。Cordis 提供插件组合能力，所有实质性功能分布在独立包中。这带来了更高的灵活性，也意味着更陡峭的学习曲线。

五、快速上手

5.1 通过 npm 运行（推荐）

npx @deepseek-ai/dsh web

命令启动 Web UI，默认监听 http://127.0.0.1:3080。前置条件仅需 Node.js 和一个模型 API Key。

5.2 从源码构建

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

源码构建要求 Node.js 22.19+ 或 24+，使用 pnpm 作为包管理器。

5.3 Headless 模式运行单次任务

pnpm dsh --profile headless "summarize this workspace"

六、当前状态与适用场景

DeepSeek Harness 目前处于开发者预览阶段，版本号为 0.1.0-rc.5，官方明确声明未来将出现兼容性破坏变更。这意味着：

适合：希望拥有 Agent 运行时主控权的团队、插件开发者、模型评测场景、需要深度定制内部平台的工程团队
不适合：寻求稳定 API 的生产环境、需要托管服务的用户、偏好固定功能集的场景

七、总结

DeepSeek Harness 的发布标志着 Agent 基础设施从"黑盒产品"向"可组装框架"的演进尝试。其核心贡献不在于提供了又一个 Agent 界面，而在于将模型、工具、会话、执行环境等关键能力解耦为独立插件，使开发者能够在不修改源码的前提下替换或扩展任何组件。

对于嵌入式和物联网领域的开发者而言，这种高度模块化的架构思路具有参考价值：当系统复杂度增长时，将能力边界清晰划分、通过标准化接口组合，比在一个单体中堆叠功能更具可持续性。

项目信息

GitHub：https://github.com/deepseek-ai/deepseek-harness
协议：MIT
社区：Discord / GitHub Discussions
插件标签：dsh-plugin