什么是 DeepSeek Harness？——“万物皆插件”的代理运行时

什么是 DeepSeek Harness？

DeepSeek Harness，简称 dsh，是 DeepSeek AI 在 MIT 许可下发布的开源 代理 harness。它位于语言模型与外部世界之间，提供工具、会话、沙盒以及维持任务推进的循环。

DeepSeek 自己的表述是“Agent = Model + Harness。”模型负责推理与生成。Harness 则让这种推理能够作用于真实的文件系统，并在无需您每次重新解释任务的情况下持续推进。

它运行在 Cordis 之上——一个早于 DeepSeek Harness 的插件框架。Cordis 允许通过设置独立替换这些部分。后文将回到这种选择的代价。

有了这个框架，来看两个常见误解。

DeepSeek Harness 不是 AI 模型

如前所述，模型与运行时是分层的。这种拆分让您在不更改工具或会话设置的情况下更换提供商。同一个运行时可以使用 DeepSeek、Anthropic、OpenAI，或任何兼容 OpenAI 的端点。

DeepSeek Harness 不止是编码助手

Standard 模式会带来“编码助手”的印象，但这只是其中一种配置。正如后文所述，Minimal 与 Creator 模式会改变代理可用的能力。构建新的配置仍需工程投入；开发者能拿到这些部件。

Cordis 如何组织 DeepSeek Harness 插件

如前所述，Cordis 是 DeepSeek Harness 之下的插件框架。它让每个部分请求服务而不与单一提供商代码绑死。

Cordis 源自 Koishi 聊天机器人生态，由一位名为 Shigma 的开发者构建；DeepSeek 将其引入并扩展。其作者在论文 A Programming Paradigm for Spatiotemporal Composability 中描述了该设计。

这些基础引出项目的主张与两个 Cordis 术语。名字听起来学术，但行为相当直接。

“万物皆插件”

DeepSeek 的架构文档称，您可以通过将插件与其他插件并列挂载来扩展 dsh。模型适配器、工具、会话、沙盒、存储、调度、代理循环与 UI 都是插件。

如果按字面理解，这个口号有些过头。插件之下仍有 Cordis。它负责加载与移除插件、检查其依赖、并运行它们之间通信所用的事件。Cordis 是必需的，而不是又一个可选件。

空间可组合性用于管理插件依赖

插件声明所需服务，而无需手写启动顺序。当这些服务存在时它会激活；当必需服务消失时它会停用。其依赖决定它何时能运行。

DeepSeek 将此称为空间可组合性。依赖关系告诉 Cordis 组件应当放在哪里，因此开发者无需手动安排启动顺序。

时间可组合性用于清理插件效应

Cordis 还会追踪注册信息，如事件监听器、提示片段与工具模式。移除插件时会一并移除这些效应，而不会留下孤儿监听器。这并不会撤销外部动作（如 shell 命令）；可逆性仅适用于 Cordis 追踪的效应。

DeepSeek Harness 架构：运行时如何拼装

一个运行中的实例是由按序加载的设置构建出的插件树。这些设置决定了哪些部分处于激活状态。

Cordis 连接每个可替换的运行时插件。图片来源：作者。

Cordis 服务让插件彼此可见

Cordis 提供共享的服务目录。插件使用稳定的键，如 ctx.tools、ctx.llm 和 ctx.sessions，而不是导入某个提供商的代码。调用 ctx.llm 的工具无需知道背后挂的是哪个模型适配器。

代理预设与运行时配置分别控制不同层

即便一切都可替换，仍需有机制决定某次运行要挂载哪些组件。DeepSeek Harness 在两个容易混淆的层面作出解答。

简而言之：配置（profile）控制程序如何启动，而预设（preset）控制代理能做什么。如果您只使用 Web 应用，可以跳过接下来的两个小节。

运行时配置

运行时配置（web、headless、sdk、sdk-minimal 与 acp 以模板形式提供）决定应用如何启动，以及启动时要叠加哪组 Cordis 插件。大多数读者只会通过运行 dsh web 或类似命令触达这一层。

代理预设

代理预设（Standard、PTC、Minimal 或 Creator）决定活跃会话可以使用什么。通过补丁文件即可更改预设，而无需改动 Harness 源码。

代理循环协调轮次、步与工具调用

DeepSeek 区分“步”（step）与“轮次”（turn）。一步是一次模型请求加上其工具调用。一个轮次包含零个或多个步：在其首个输入被接收前开启，在没有待处理项后关闭。多数轮次在代理可回答前会运行若干步，但被拒绝的输入会关闭一个未消耗任何步的轮次。

一个轮次可以包含多个步。图片来源：作者。

会话采用仅追加的事件日志

这是我认为最重要的部分。会话是一个带类型的仅追加事件日志，而不是一组聊天消息数组。Harness 从该日志构建模型历史，且会话文档要求发送给模型的任何内容都必须能从日志中还原。

恢复、分支、搜索、回放与 Trajectory 视图都建立在这条事件流之上。

重新推导历史并非确定性的重跑。模型输出与外部状态可能不同，但日志仍提供可检查的“发生了什么”的记录。

会话历史是仅追加日志。图片来源：作者。

DeepSeek Harness 如何控制工具与沙盒

模型可以按名称请求工具，但无法直接运行。请求与文件系统变更之间隔着两个独立的控制。

工具执行流水线

调用会经过策略检查、执行与结果处理。模型选择工具；运行时决定是否以及如何执行。

运行时决定工具如何运行。图片来源：作者。

沙盒与审批

• 审批决定是否需要用户确认某一操作。
• 沙盒限制其执行的范围与方式。

DeepSeek 将两者分离，不过权限预设会同时打包这两类控制，这类似于容器运行时将进程权限与执行边界分开。

这里先提示一下，后文的限制部分会再提：在系统提示中告诉模型“只能读文件”只是它可以遵守的建议，并不等同于操作系统级沙盒限制那样的强制边界。

DeepSeek Harness 模式：Standard、PTC、Minimal 与 Creator

DeepSeek Harness 提供四种模式。它们并无高低之分，而是分别回答“这次会话应暴露多少运行时能力”。合适的选择取决于手头任务。正如架构部分所示，每种模式都会改变代理可用的工具集合。

四种模式共用同一运行时基础。图片来源：作者。

Standard 模式

通用基线：

• 文件编辑
• Shell 访问
• 文件与网页搜索
• 技能
• 规划
• 目标
• 子代理
• 工作流

对于一般的代码仓库工作，我会从这里开始。

PTC 模式

PTC 模式保留了几乎全部 Standard 的工具集，但改变了模型使用它们的方式。（自 0.1.2 版起，Web PTC 模式默认不再暴露通用的 workflow 工具。）

模型不再在多个步骤中逐个请求工具，而是针对生成的 SDK 编写程序。该程序可通过 run_code 调用多个工具。每次调用仍会经过相同的策略检查，因此 PTC 改变的是模型表达计划的方式，而非其被允许执行的范围。

产品页面仍使用“Code 模式”这一标签，但较新的正式版本已将其重命名为 PTC 模式，同时保留旧会话记录的可读性。下文将统一使用 PTC 模式；FAQ 将回到这些字母可能代表什么。

Minimal 模式

Minimal 模式将环境精简为两个工具：持久化 shell 与字符串替换式文件编辑器。DeepSeek 用它来做模型基准测试，因为测试结果部分取决于模型所用的 harness，而不仅仅是权重。

Creator 模式

Creator 模式允许开发者在内存中检查运行时并测试 Cordis 插件。它用于构建预设，而我不会将其称为更深层意义上的“自我改进”。

DeepSeek Harness 与其他代理框架有何不同？

DeepSeek Harness 与许多代理框架的不同之处在于，将运行时的更底层部分做成可替换。我本可以把它并入架构部分，但这种区别很容易被忽略。Cordis 通过一个插件系统处理这些变化。

您可以改变代理的运作方式，而不仅是它能调用的工具。事件日志还能让一次运行对开发者可检查，而非只能作为聊天记录阅读。Minimal 与 Creator 模式则让他们从相反方向测试运行时。

DeepSeek Harness vs. Claude Code、Codex、OpenCode

单纯的功能清单抓不住重点。竞争者均支持扩展；更有用的问题是“开发者能改动哪些部分”。这听上去细微，其实不然。我们的Harness 与 Claude Code 对比专题在两者中使用同一模型，并涵盖了设置、日志与成本。

DeepSeek Harness vs. Claude Code

Claude Code支持项目说明、技能、hooks、MCP、子代理与 Agent SDK，但其内置循环保持固定。DeepSeek Harness 则允许开发者通过设置替换循环、模型适配器与存储层。

DeepSeek Harness vs. Codex

Codex需要更细致的比较，因为其 CLI 与 App Server 也是开源的。它提供一个可通过已文档化入口扩展的代理 harness。DeepSeek Harness 则围绕“改造运行时本身”而构建。两者提供的控制粒度不同。

DeepSeek Harness vs. OpenCode

OpenCode同样开源，兼容多家模型提供商，并采用客户端-服务器架构。您可以配置其工具、权限、会话与提供商。它的插件扩展固定的服务器核心，而 DeepSeek 还让循环与会话存储可替换。

何时使用 DeepSeek Harness

单纯替换运行时部件并无意义。只有当这种额外控制能解决您已有的问题时，它才有价值。

• 当运行时本身是项目的一部分。如果您要改动模型适配器、代理循环、存储或会话行为，而不是仅在代理之上构建应用，那么它更契合。
• 当需要在受控环境中比较模型。使用同一运行时，在更换模型时能固定更多测试变量，尽管理模型在工具使用与推理风格上仍可能不同。
• 当复杂运行的调试很重要。会话事件日志与 Trajectory 视图让重建模型所见与所用工具更容易。
• 当您在测试代理内部机制。Creator 模式与 Cordis 更适合研究代理如何组装的开发者，而非只需要生成应用代码的人。

对于简单的模型调用，或团队希望直接使用现成的编码代理且无需触碰其内部机制时，它可能并非必需。只有当这种控制能解决实际问题时，替换更多部件才值得投入。

DeepSeek Harness 的限制：开发者预览与安全风险

若不清楚当前的短板，上述架构意义有限。

仍处于开发者预览

DeepSeek 的仓库明确写道会有破坏性变更。这已经发生过：从 Code 重命名为 PTC 同时伴随会话 API 变更与移除可选的 SQLite 存储选项。请锁定版本。指望配置不变而跳过这一步并非可行方案。

更多控制意味着更多复杂度

让更多运行时可替换，也意味着开发者要学更多：插件依赖、设置、提供商差异与版本兼容性。这是便捷与控制之间的常见取舍。

DeepSeek Harness 是否本地化？

DeepSeek Harness 默认将会话内容、工具记录与设置存储在本地，根据其 数据处理声明。您可以关闭其关于设置与项目列表的匿名报告。

但外部模型提供商、网页工具、MCP 服务器或插件仍可能按其自身政策将数据发送到机器之外。“本地优先”并不涵盖您所连接的每一项服务。

运行代理带来安全风险

一个能编辑文件、运行命令、加载第三方插件的运行时可能造成真实破坏。DeepSeek 的安全说明称该项目尚未进行安全审计。沙盒、审批与权限控制能降低风险，但不能保证完全隔离。

在您自己的机器上运行并不消除风险。对不受信任的工作请使用受限权限与一次性环境，并谨慎对待可能含有隐藏指令的内容。

为何代理行为不只取决于模型

代理行为既取决于模型，也取决于运行时。这回到了“Agent = Model + Harness”，这一拆分同样适用于 DeepSeek 之外的LLM 代理。

模型能产出的内容取决于其权重。代理会做什么还取决于哪些上下文被送达模型、它被允许采取哪些动作、以及执行被约束得多紧。这些都不在权重里。

DeepSeek Harness 通过将周边层拆分为开发者可替换的命名部件，揭示了它的重要性。Minimal 模式则说明了这一点超越 DeepSeek 的意义：基准分数部分反映了用于测试的 harness，而不仅仅是模型本身。Harness 并不会让模型更聪明，它改变的是模型工作的情境。

结语

开篇那句话值得牢记：模型负责推理，而运行时决定这种推理能触达与完成什么。DeepSeek Harness 让这一运行时可编辑，从模型适配器、工具到会话存储与代理循环。

这种控制带来代价。替换更多运行时部件，意味着要承担更多关于安装、版本变更与安全边界的工作。一个带有 Shell 访问的开发者预览，不是装上就能忘的东西。

我的看法很简单：当运行时本身就是工作的一部分时，请使用 DeepSeek Harness。如果您只需要仓库改动，现成的编码代理对您的要求更少。

我们的DeepSeek Harness 教程介绍了安装与配置。Claude Code 替代方案指南比较了更多编码代理，而AI 代理入门则覆盖了本文所假定的基础知识。