DeepSeek Harness：一个“一切皆插件”的 Agent 框架

就在本文发布时，DeepSeek Harness 的开发者预览版已经上线，并且正式开源。它可以理解为 DeepSeek 推出的 Agent 框架，缩写为 dsh，定位上类似 Claude Code。

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

DeepSeek Harness 最值得关注的地方，不只是它能够完成编程任务，而是它提供了非常强的自定义能力。默认情况下，系统按照标准方式调用；但只要安装或编写插件，界面、工具、工作方式，甚至智能体本身的组成，都可以发生变化。

一、DeepSeek Harness 到底是什么？

如果把模型看作 Agent 的“灵魂”，那么 Harness 就像 Agent 的“身体”。模型负责理解问题、生成判断，Harness 则负责让它理解环境、调用工具，并在真实任务中持续工作。

DeepSeek Harness 的核心理念可以概括为一句话：

一切皆插件，Everything is a plugin。

在许多软件中，核心逻辑往往是固定的，用户只能通过少量预留接口进行有限调整。DeepSeek Harness 的设计则更加开放，模型接入、工具注册表、会话日志、审批策略，甚至驱动智能体运行的主循环，都被设计成可以替换和组合的插件。

例如，默认的 dsh 可能没有画板功能，但安装画板插件后，就可以获得画板能力。想更换搜索引擎、接入企业自建模型服务、调整审批策略，也可以通过配置和插件完成，不需要直接修改框架源码。

二、为什么说“一切皆插件”？

1. 扩展功能不必修改核心代码

在 DeepSeek Harness 中，给系统增加功能，主要方式是挂载新的插件。插件卸载时，已经注册的内容也会自动撤销，尽量不在系统中留下残余状态。

这种设计带来的直接好处是：开发者可以在不修改核心框架的情况下，独立选择、替换或扩展某一项能力。

2. 不同场景可以自由组装

企业可以根据合规要求裁剪工具集，个人用户也可以按照自己的工作习惯调整插件组合。大家使用的是同一套框架，但实际运行的 Agent 可以完全不同。

因此，同一个 DeepSeek Harness，既可以组成一个功能完整的编程助手，也可以组成一个只能读取代码、不能修改文件的审查智能体。

3. 插件可以改变界面和交互

内测期间，参与者已经尝试制作了多种界面插件，包括同花顺风格、娘化风格、Excel 风格以及复古 XP 风格等界面。

这些皮肤并不是写死在主程序中的功能，而是独立插件。它们说明，DeepSeek Harness 的插件机制不仅可以改变工具能力，也可以改变用户界面和交互方式。

三、DeepSeek Harness 的技术基础：Cordis 插件系统

DeepSeek Harness 基于具有时空可组合性的 Cordis 插件系统构建。

Cordis 作为元框架，主要负责：

• 插件加载
• 插件卸载
• 插件依赖关系管理

Agent Harness 中的具体组件，则分别作为不同的 Cordis 插件存在。插件之间通过服务和事件协作，并且可以在配置层面进行自由组合。

这意味着，开发者不必直接修改 DeepSeek Harness 的源码，就可以对其中的模型、工具、会话、沙箱、循环和界面等能力进行选择、替换或扩展。

四、分层组装：Bundle、Profile 与 Patch

运行中的 dsh 可以理解为一棵插件树。这棵树由多层配置按照固定顺序叠加而成。

1. Bundle：官方发布的组合包

Bundle 是官方发布的成套插件配置，可以理解为一组已经组合好的能力集合。

2. Profile：用户机器上的组装清单

Profile 是用户本地使用的具名配置清单，用来决定当前环境采用哪些插件和配置。

3. Patch：用户自己的覆盖层

Patch 是用户自定义的覆盖层，可以精确定位到任意插件条目并进行替换。

这些配置按照层级叠加，上层配置始终覆盖下层配置。因此，用户既可以直接使用官方组合，也可以在本地进行精确调整。

五、能力接缝：服务、提供方与消费方相互独立

DeepSeek Harness 会把每种能力拆成三个相互独立的角色：

• 服务定义：规定能力的接口规范。
• 提供方：负责具体实现。
• 消费方：负责使用这项能力。

例如，执行命令、读写文件、网络访问、模型调用和沙箱隔离等能力，都可以按照这种方式拆分。

这样做的好处是，提供方可以替换，消费方不必跟着改变，模型看到的接口也能够保持稳定。具体实现发生变化时，其他组件不需要全部重写。

六、四种随附模式：不同任务使用不同 Agent Preset

DeepSeek Harness 的界面顶部提供了模式选择器。每个模式都对应一份 Agent Preset，也就是智能体预设。

一个预设决定了当前会话中的智能体由哪些插件组成，包括：

• 可以使用哪些工具；
• 采用什么提示词；
• 按照什么方式工作。

选择一个模式，本质上就是选择一套完整的 Agent 配置。

1. 标准模式

标准模式是默认模式，适合大多数用户，提供功能完整的编程智能体。

它包含以下能力：

• 文件编辑；
• Shell 命令执行；
• 文件检索与网页检索；
• Skills；
• 计划与目标管理；
• 子代理；
• 工作流。

2. PTC 模式

PTC 是 Programmatic Tool Calling 的缩写，中文可以理解为程序化工具调用。

PTC 模式拥有标准模式的全部能力，但工具调用方式不同。标准模式下，模型通常是执行一次工具、等待结果、根据结果决定下一步，再执行下一次工具。

例如，一个包含五个步骤的任务，标准模式可能需要进行五次“模型调用工具、等待结果、继续判断”的往返。

PTC 模式则会让模型先生成一段程序，把这五个步骤组合起来，再一次执行。任务步骤越多、中间数据量越大，PTC 模式通常越有利于减少往返，并降低上下文消耗。

3. 极简模式

极简模式只提供两个工具：

• 一个能够保持状态的命令行终端；
• 一个文本编辑工具 str_replace_editor。

该模式的系统提示词只有一句话，也不会加载上下文压缩功能。它适合基准测试、教学演示，以及偏好极简操作的用户。

4. 创造模式

创造模式用于创建自定义 Agent Preset。它可以检查当前运行时，在内存中试验 Cordis 插件，并根据试验结果组合和创作新的模式。

用户可以直接提出需求，例如：

“创建一个只能读、不能写的代码审查模式。”

随后，系统会起草配置文件、挂载并验证配置，将其保存为新的 preset。完成后，这个自定义模式就会出现在模式选择器中。

安全提示：创造模式能够执行模型编写的代码，也能够修改运行时，因此它的信任等级等同于 Shell 访问权限。建议只在受信任的环境中使用。

5. 自定义模式与模式切换限制

四个随附模式属于只读系统预设，会随安装一起发布。用户可以复制任意预设后修改副本，也可以使用创造模式让智能体代为创建。

自定义 preset 与随附模式在界面和运行机制上完全等价。

需要注意的是，会话一旦产生内容，就不能再切换模式。这是因为模式决定了工具集，中途切换可能导致新的工具集无法解释历史中的旧工具调用，从而破坏会话的可复现性。

七、智能体是怎样工作的？

1. Step 与 Turn

智能体执行任务时，主要由两个概念定义其工作过程：

• 步骤 Step：一次模型请求，以及模型在这次回复中要求执行的工具调用。
• 轮次 Turn：从接收到用户任务开始，一直到所有事情完成为止的完整过程。

简单任务可能一个步骤就能完成；复杂任务则会在同一个轮次中连续执行多个步骤。

2. 关键位置都可以被插件拦截

在步骤开始前、工具执行前后、模型请求发出前等关键位置，都可以作为扩展点。

插件可以在这些位置插入：

• 审批逻辑；
• 内容改写；
• 执行记录；
• 拦截逻辑。

3. 会话日志采用只追加事件流

每个会话对应一份仅追加的事件日志。会话中发生的每件事都会按照顺序写入，包括用户输入、模型输出、工具调用和工具结果。

日志只增加，不修改历史记录。模型看到的内容也会被写入日志，包括系统提示词、思维链、工具调用与结果、子 Agent 调度，以及每一次上下文注入。

在 Trajectory 视图中，用户可以按照来源查看这些信息。会话恢复、会话分叉、历史检索和回放，也都共享同一份事件流。

会话日志还支撑以下能力：

• 进程重启后的会话恢复；
• 自动生成会话标题；
• 超出上下文窗口后的自动压缩；
• 跨会话检索过去的工作记录。

4. 计划、任务清单与提问

用户可以要求智能体先提交实施方案，获得批准后再执行。计划状态和批准动作都会被记录在日志中。

面对较长任务时，智能体可以自行拆分任务清单，并逐项推进。界面会将任务实时渲染为可勾选列表。

当任务中出现需要用户决定的事项时，智能体会暂停执行，并通过带选项的问题请求用户选择。收到回答后，任务继续进行。

八、内置工具集：覆盖日常编程工作

工具是智能体执行工作的具体接口。DeepSeek Harness 随附的工具，覆盖了日常编程所需的主要操作。

1. 文件与内容处理

文件工具可以读取文件、精确修改文件，并将内容写入工作区。read_image 可以把图片提供给支持视觉输入的模型。

文件检索支持按照文件名模式查找文件，内容检索支持全文搜索，并且内置了 ripgrep，宿主机不需要另外安装搜索工具。

2. 命令、终端与后台任务

命令执行工具可以执行命令行操作，例如安装依赖、运行测试和启动服务，也支持将任务转入后台。

持久终端可以打开保持状态的真实终端，也就是 PTY，适合需要持续交互的命令行任务。

后台任务管理则可以统一管理后台命令、终端任务和后台子代理。用户可以先处理其他工作，等后台任务完成后再回来查看结果。

3. 代码语义查询与网络访问

代码语义查询接入语言服务器，也就是 LSP，支持跳转定义和查找引用。

网络工具可以进行网页搜索和内容抓取，搜索引擎也可以通过配置进行更换。

此外，系统还提供独立的文本编辑工具和只读的会话查询工具。

4. 三个值得注意的工具设计

先读后写：一个独立的策略插件可以强制要求智能体必须先读取文件，之后才能修改该文件。这项规则不是写死在文件工具中，而是由可选装的门禁插件实现。

结果落盘：当搜索结果超过上限时，完整列表会自动保存到磁盘，后续可以继续读取，避免结果被直接截断。

通用后台：命令执行、终端会话和子代理都可以转入后台，并由统一的后台任务系统管理。

九、Code Mode：PTC 模式的技术基础

Code Mode 是 PTC 模式的技术基础。

传统工具调用通常是一步一步进行的：模型完成一个动作后发起一次调用，等待结果返回，再决定下一步。动作越多，往返次数越多，上下文消耗也越大。

Code Mode 会把所有工具生成一套 TypeScript SDK。模型通过 run_code 工具提交一段程序，然后在程序中直接调用各种工具。

这段程序可以使用：

• 循环；
• 条件判断；
• 并发执行；
• 中间结果过滤。

只有程序最终打印或返回的内容会进入模型上下文，中间执行过程不会全部占用上下文空间。

例如，要完成“统计所有包中的 TODO 标记并汇总排序”，传统方式可能需要进行几十次工具往返；使用 Code Mode，则可以通过一段程序一次完成。

Code Mode 并不会绕开安全机制。程序中的每一次工具调用，仍然会经过完整的执行流程，审批、沙箱、超时和日志记录都会照常生效，并发数量也会受到配置约束。

十、多智能体协作与工作流

一个智能体可以把任务分派给多个子智能体，并管理它们的执行过程。

1. Subagent：可续跑的后台子代理

subagent 默认在后台执行，完成后会将结果自动送回父级会话。执行过程中，父级还可以向它发送消息。

2. Subagent Fork：一次性子代理

subagent_fork 会继承当前上下文启动，完成任务后结束，适合拆分一些就近完成的小任务。

子代理一侧还提供专属的 report 工具，可以把阶段性成果直接投递到父级会话。

3. 工作流引擎：用脚本确定执行流程

工作流引擎通过脚本对多个子代理进行确定性编排。执行顺序、并行关系和结果汇总方式都由脚本定义，不依赖模型临场发挥。

这种方式适合迁移、审计和批量改造等需要固定流程的任务。

4. Ralph 循环：反复执行直到达成目标

Ralph 循环是一种循环执行模式。每一轮都会启动一个全新的子代理，执行同一个目标，直到目标达成。

每一轮都不会携带上一轮的上下文，因此适合“反复尝试直到通过”的任务，例如持续修复测试，直到测试全部通过。

5. 目标管理与完整日志

目标管理可以创建、修改、暂停和恢复长期目标，但这些操作需要人类用户的根权限，智能体不能自行创建或变更目标。

所有子代理的会话也会全程写入日志，因此每个子代理的执行过程都可以完整还原。

十一、内测中的体验插件

内测期间，参与者还制作了许多用于提升体验的功能插件。

例如，进度条插件可以展示任务进度；小游戏插件会默认收到侧边栏中。

还有上下文编辑插件，其中的消息编辑功能支持编辑每一条消息，并通过版本时间线记录每次修改，同时支持“重试此回合”和后续策略选择。

此外，还有表情包插件。它通过系统提示词让模型标记情绪，再由宿主端把情绪标记替换成内联表情图片。该插件提供三档模式：

• 关闭；
• 智能；
• 高频。

模式选择会持久化到本地配置中。表情内容可以是鲸鱼表情包，也可以是贴吧风格的表情内容。

十二、安全与治理：沙箱、审批和隐私保护

1. 进程沙箱

智能体执行的命令可以运行在沙箱中。沙箱用于控制进程能够读取和写入哪些文件。

不同桌面平台使用各自的操作系统原生隔离机制：

• Linux：bwrap / Landlock；
• macOS：Seatbelt；
• Windows：ACL 受限令牌。

沙箱分为三档：

• read-only：只能读取，不能写入。
• workspace-write：可以写入工作区目录和指定的临时目录。
• danger-full-access：不进行隔离，完全放开访问。

沙箱后端会如实报告实际隔离情况。如果当前系统条件只能覆盖部分安全承诺，后端会报告 partial，而不是报告为 full，不会虚报安全边界。

2. 审批与权限

对于修改文件、执行有风险命令等需要授权的操作，界面会先向用户请求批准，只有获得批准后才会执行。

权限提供预置档位，用户可以整体调整权限的宽严程度。

3. 自动守卫

系统提供两个自动纠偏插件：

• 循环卫生：检测智能体是否正在重复执行无效动作。
• 工具超时：强制中断超时的工具调用。

4. 凭据与隐私

API Key 等凭据通过独立通道传递，不会以明文进入会话日志。日志中只保留凭据引用。

数据默认保留在本地，会话日志默认不会上传。遥测功能需要用户显式开启，用户可以选择只在主动提交反馈时附带日志，也可以选择持续上传匿名化数据。

十三、生态兼容能力

1. Model Context Protocol

DeepSeek Harness 支持 Model Context Protocol。任何 MCP 服务器，例如数据库、办公系统和企业内部服务，都可以接入。

接入后的工具与内置工具使用同一条流水线，也同样受到审批和守卫机制的约束。

2. Hooks 桥

Hooks 桥可以让已经为 Claude Code 和 Codex 编写的钩子脚本直接使用，例如提交前检查和通知集成等，不需要重新编写。

3. ACP 服务端

DeepSeek Harness 内置 ACP 服务端实现，支持 ACP 的编辑器和客户端可以直接将 DeepSeek Harness 作为后端智能体使用。

4. Skills、定时任务与模型接入

Skills是打包好的任务指令和配套资源，智能体可以根据需要加载，系统也支持建立自定义技能库。

定时任务支持三种方式：

• 延时触发；
• 定时触发；
• 固定间隔重复触发。

模型接入方面，除 DeepSeek 官方 API 外，还支持任意 OpenAI 兼容端点。用户可以接入企业自建推理服务或其他云服务商，在设置页面完成配置后即可生效。

十四、如何快速体验 DeepSeek Harness？

在已经安装 Node.js 开发工具链的系统中，可以通过一行命令启动 Web UI：

npx @deepseek-ai/dsh web

这里将来源中的命令格式整理为常见的 npm 执行格式：npx 与包名之间需要保留空格。

十五、五种使用方式分别适合什么场景？

1. Web UI

通过浏览器打开本地地址即可使用，可以进行对话、审批、模式切换和设置。

2. Headless CLI

Headless CLI 不提供图形界面，可以执行单个任务，任务完成后打印结果并退出，适合 CI/CD 和脚本集成。

3. Python SDK

Python SDK 自带打包好的运行时，提供高层 turns API 和底层 JSON-RPC 客户端。

4. TypeScript SDK

TypeScript SDK提供 JSON-RPC 协议、服务器和客户端，适合需要深度集成的团队。

5. ACP

ACP 自动化协议服务器面向编辑器和工具链厂商，便于将 DeepSeek Harness 接入相关开发工具。

十六、面向开发者的扩展能力

DeepSeek Harness 提供完整的插件开发文档，覆盖以下流程：

• 工具编写；
• 配置管理；
• 事件与服务开发；
• 插件发布。

项目还提出了明确的工程约定：

• 插件注册必须具备可逆副作用；
• 配置错误必须在加载时直接报错，不能静默跳过；
• 跨边界标识符必须使用品牌类型；
• 随部署变化的参数必须放入配置，不能硬编码。

这些约定由仓库中的自动化门禁强制执行。

质量门禁包括哪些内容？

• 源码目录逐文件达到 100% 单元测试覆盖率；
• 不需要 API Key 即可运行的快照回放测试；
• 真实 API 端到端测试；
• 跨文件代码克隆检测；
• 文档与代码同步检查。

如果文档过期，持续集成流程会直接阻断。

自我修改能力有什么作用？

DeepSeek Harness 还提供一项自我修改能力。开启后，智能体可以检查自己的运行时，并热挂载插件。

创造模式正是基于这项能力搭建的。

十七、当前版本与后续发展

DeepSeek Harness 当前的 v0.1 版本仍处于面向 Harness 开发者测试的阶段，还有许多地方需要继续改进和打磨。

按照来源内容，核心插件和基础接口预计会在接下来的一段时间内快速迭代并持续演化。

写在最后：Agent 的灵魂与身体

Agent = Model + Harness。

模型是 Agent 的灵魂，Harness 则是 Agent 的身体。只有模型，智能体可能拥有理解和生成能力；有了 Harness，它才具备理解环境、使用工具、接受审批、记录过程，并在真实场景中持续工作的能力。

DeepSeek Harness 的特别之处，在于它没有把 Agent 的能力封装成一套不可触碰的固定流程，而是把模型、工具、会话、沙箱、审批、循环、调度和界面都拆成可以重新组合的插件。它让使用者不只是“使用一个智能体”，也可以参与决定这个智能体是什么、能够做什么，以及应该怎样工作。

我认为：一个系统真正的开放，不在于它喊出了多少口号，而在于它是否允许人们修改其中的关键部分。DeepSeek Harness 把“一切皆插件”放在设计中心，至少让 Agent 不再只是一个被动回答问题的窗口，而成为可以被组装、被约束、被审查，也可以被不断改造的工作系统。它目前仍处在开发者测试阶段，路还没有走完；但正因为接口、插件和生态都在持续演化，真正重要的或许不是它今天已经完成了什么，而是它把多少继续建设的权力交给了使用者。

#开源项目