DeepSeek Harness 是什么？AI 编程 Agent 的全貌

截至 2026 年 9 月 1 日，DeepSeek Harness 已不再是只面向少数开发者开放的内测项目。

2026 年 8 月 13 日，DeepSeek 正式推出 DeepSeek Harness v0.1 开发者预览版，并同步公开源代码。项目采用 MIT 协议，开发者可以直接查看、运行和修改其模型适配器、工具、会话系统、Agent Loop、沙箱与用户界面。官方同时强调，Harness 目前仍处于快速迭代阶段，核心插件和接口可能出现破坏兼容性的更新。

DeepSeek 对它的定义可以概括为：

Agent = Model + Harness

模型负责理解、推理和生成决策；Harness 则负责连接文件、终端、工具、搜索、记忆、子 Agent 与执行环境，让模型从“回答问题”进一步走向“完成任务”。

一、Harness 是模型之外的工程执行层

理解 DeepSeek Harness，首先要区分“模型”和“Agent”。

一个大模型本质上仍然是输入 Token、输出 Token。即使模型具备很强的代码理解与推理能力，它本身也不知道项目文件位于哪里、测试是否通过、命令有没有执行成功，更无法自动保存长期任务状态。

要让模型真正参与软件工程，需要在模型外部增加一层运行框架，负责完成以下工作：

1. 整理代码库、项目规则和历史任务，构造模型能够理解的上下文；
2. 为模型提供文件读取、代码修改、Shell、搜索和测试工具；
3. 控制模型与工具之间的多轮执行循环；
4. 将错误日志、测试结果和命令输出重新反馈给模型；
5. 管理上下文压缩、会话恢复、权限审批和任务状态；
6. 在复杂任务中调度子 Agent，并保存完整执行轨迹。

这一整套模型之外的工程调度能力，就是 Harness。

因此，DeepSeek Harness 并不是一种新的大模型，也不是单纯套在 DeepSeek V4 外面的聊天界面。它更接近一套面向开发者的 Agent 运行基础设施。

二、DeepSeek Harness 已从内测进入开源预览阶段

DeepSeek Harness 的公开时间线可以分为三个关键节点。

DeepSeek 官方在 7 月 31 日公布 V4-Flash 基准时，仍将 Harness 极简模式标记为“即将发布”；到 8 月 13 日，Harness 已转为公开开发者预览，源代码、开发文档和 npm 启动包均已开放。8 月 21 日，官方进一步确认 Harness 0.1.1 已支持新的视觉模型。

因此，原先“Harness 仍处于封闭内测、需要签署保密承诺函”的描述，已经不符合当前状态。现在普通开发者可以直接运行：

npx @deepseek-ai/dsh web

启动成功后，默认在浏览器中打开：

http://127.0.0.1:3080

也可以克隆完整源码进行二次开发：

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

官方仍将当前版本定义为 Developer Preview，而不是稳定生产版。用于正式项目之前，需要评估版本升级、插件兼容与沙箱权限等问题。

三、“一切皆插件”是 Harness 的核心设计

DeepSeek Harness 最重要的架构原则是：

Everything is a plugin，一切皆插件。

它基于 Cordis 插件框架构建。Cordis 负责插件挂载、卸载、依赖关系、服务注册和副作用撤销，具体的 Agent 能力则由不同插件提供。

在 Harness 中，以下组件都可以是独立插件：

• 模型适配器；
• 工具注册表；
• 文件系统；
• Shell 与沙箱；
• Skills；
• 会话与存储；
• 上下文管理；
• Agent Loop；
• 子 Agent 调度；
• 任务计划；
• Web 用户界面。

这意味着开发者不必修改 Harness 的核心源代码，就可以通过配置替换模型、增加工具、切换沙箱，或者重新组合一套 Agent 运行模式。

例如，同一套 Agent Loop 可以接入 DeepSeek 官方模型，也可以接入 OpenAI、Anthropic、自托管模型或企业内部网关。上层任务流程只面向统一的模型服务，不需要与某一家模型厂商强绑定。

这种架构的价值不只是“方便换模型”，更重要的是可以让开发者分别研究 Agent 的不同组成部分：究竟是模型能力不够，还是提示词、工具描述、上下文压缩、权限策略或执行循环出现了问题。

四、四种运行模式覆盖不同开发场景

DeepSeek Harness 当前提供四种主要运行模式。

Standard Mode 更接近完整的 AI 编程 Agent；Minimal Mode 则刻意减少外围能力，便于在相对统一的工具环境中比较不同模型。

Code Mode 的重点是程序化工具调用。普通 Agent 通常采用“调用工具—读取结果—再次推理”的串行方式，而 Code Mode 可以让模型生成一段程序，通过循环、条件和并行逻辑组织多次工具调用，从而减少模型与运行环境之间的往返次数。

五、Trajectory 让 Agent 执行过程可以追踪

AI 编程 Agent 的一个常见问题是过程不透明。

当任务失败时，开发者往往只能看到最后一次回答，却不知道模型接收了什么上下文、调用了哪些工具、在哪一步发生偏离，以及 Token 为什么快速增长。

DeepSeek Harness 使用仅追加的会话日志记录 Agent 运行事件，包括：

• 系统提示词；
• 模型推理字段；
• 工具调用与返回结果；
• 子 Agent 调度；
• 上下文注入；
• 会话状态变化。

开发者可以在 Trajectory 视图中按来源检查这些记录，并基于同一份事件流恢复、分叉、搜索和回放会话。

这里的 Trajectory 不宜简单理解为“无条件展示模型完整思维链”。实际能够保存哪些推理内容，仍然取决于模型接口与适配器返回的字段。它更准确的价值，是记录 Agent 真正使用过的上下文、工具和执行事件。

六、V4 基准说明了模型和 Harness 必须一起评估

DeepSeek 在公布 V4-Flash 和 V4-Pro 的 Agent 基准时，使用了 Harness Minimal Mode 作为部分代码任务的运行框架。

这些数字来自 DeepSeek 官方披露，并非统一第三方环境下的独立横向测试。官方还说明，部分 DSBench 测试集属于内部测试集，因此更适合用于观察同一厂商模型版本之间的变化，而不应直接等同于真实项目成功率。

这也说明，评价 AI 编程 Agent 不能只看模型分数。

同一个模型放在不同 Harness 中，可能因为工具定义、上下文整理、重试策略、编辑器实现和执行权限不同，表现出明显差异。反过来，同一个 Harness 接入不同模型，也可以用于测试不同模型在统一工程环境中的实际表现。

七、Harness 支持官方 API，也支持自定义模型网关

DeepSeek Harness 并没有把模型入口完全锁定在 DeepSeek API 上。

在 Web UI 的 Settings → Models 中，开发者可以采用三种方式配置模型：

1. 直接填写 DeepSeek 官方 API Key；
2. 从内置目录中添加 OpenAI、Anthropic 等 Provider；
3. 添加自定义 Provider，接入企业网关、自托管服务或其他兼容接口。

添加自定义 Provider 时，需要填写 Provider ID、Base URL、API 协议、API Key 和至少一个模型 ID。模型配置会在下一次请求时生效，不需要重新启动 Harness。

这为 API 中转站和多模型聚合网关留下了接入空间。

例如，已经使用 4SAPI 中转站的开发者，可以将其作为一个自定义 Provider 添加到 Harness。4SAPI 提供 OpenAI-compatible 接口，因此基础接入逻辑与其他兼容网关相同：将 Base URL、API Key 和实际模型 ID 填入 Harness 即可。

参考配置如下：

Provider ID：4sapi
Display Name：4SAPI
Base URL：https://4sapi.com/v1
API Protocol：openai-completions
API Key：在4SAPI后台创建的Key
Model ID：从当前模型列表中复制

也可以在 Harness 的配置文件中手动设置：

llm-pi-ai:
  providers:
    4sapi:
      apiKeyEnv: FOURSAPI_API_KEY
      api: openai-completions
      baseURL: https://4sapi.com/v1
      models:
        - id: <实际模型ID>

真实 API Key 建议存放在环境变量或 Harness 的凭证系统中，不要直接提交到 Git 仓库。

八、通过 4SAPI 接入的价值主要在统一管理

4SAPI 并不是使用 DeepSeek Harness 的必要条件。

如果开发者只准备使用 DeepSeek-V4-Flash 或 V4-Pro，并且重视官方原生功能、更新速度和问题排查路径，直接接入 DeepSeek 官方 API 通常更简单。

当团队需要在同一套 Harness 中测试 DeepSeek、GLM、Qwen、Kimi、Claude 或其他模型时，统一中转入口会更方便。其主要价值体现在三个方面。

1. 减少重复配置

开发者不需要在 Harness 中维护大量不同格式的 Endpoint 和密钥，可以先将模型调用收口到一个 Provider，再通过模型 ID 切换具体模型。

2. 方便做同环境模型对比

Harness 负责提供相同的工作区、提示词、工具和执行循环，4SAPI 负责提供不同模型入口。这样可以在相对一致的 Agent 环境中比较模型表现。

调用关系可以理解为：

DeepSeek Harness
        ↓
4SAPI OpenAI-compatible Provider
        ↓
DeepSeek / GLM / Qwen / Kimi / Claude / 其他模型

3. 通过任务分级控制综合成本

简单的文件整理、代码解释和批量生成任务，可以选择成本较低的模型；复杂重构、长期推理和最终检查任务，再切换到能力更强的模型。

这里所说的“节省成本”，主要来自 按任务选择模型和减少多平台维护工作，不代表中转方式下的每一个模型都必然比官方接口便宜。最终成本仍需要结合模型单价、输入输出 Token、缓存、失败重试和平台服务费进行计算。

九、OpenAI 兼容不代表完全没有适配问题

即使一个平台声明兼容 OpenAI API，也不能直接推断它支持 OpenAI 接口的所有字段。

不同网关可能在以下方面存在差异：

• 系统提示词使用 system 还是 developer；
• 输出限制使用 max_tokens 还是 max_completion_tokens；
• 推理内容使用哪种格式返回；
• 流式工具调用如何分段；
• 多模态图片如何声明；
• Responses API 与 Chat Completions 的覆盖范围。

Harness 官方文档特别指出，自定义网关即使 Base URL 和 API Key 正确，也可能因为请求结构差异而拒绝调用。最常见的两个问题是网关不接受 developer 角色，或者只接受 max_tokens 字段。

遇到对应错误时，可以尝试在 Provider 下添加：

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

这不是 4SAPI 的固定必填配置，也不建议在没有错误时提前加入。正确做法是先完成基础请求测试，再根据实际返回的错误码调整兼容参数。

用于 AI 编程 Agent 时，还应单独验证：

1. 普通文本对话能否返回；
2. 流式输出能否稳定结束；
3. 工具调用参数能否被完整解析；
4. 多轮工具调用能否持续运行；
5. 推理模式是否与模型实际能力匹配；
6. 图片输入是否需要声明 input: [text, image]；
7. 长上下文和最大输出 Token 是否符合通道限制。

普通聊天请求能够成功，不代表完整 Agent 工作流一定能够正常运行。

十、Harness 与 Claude Code、Codex 的区别在产品层级

DeepSeek Harness、Claude Code 和 Codex 都涉及模型、工具和工程执行，但三者并不完全处于同一产品层级。

Claude Code 和 Codex 更接近已经组装完成的开发工具，用户安装或登录后即可开始处理代码；DeepSeek Harness 则把底层组件直接开放给开发者，允许重新替换模型、工具、沙箱、存储和 Agent Loop。

因此，三者的区别不应简单概括成“谁更强”。

需要快速完成日常开发任务的用户，通常更重视产品成熟度和开箱体验；需要研究 Agent 架构、对比模型或者开发自定义插件的团队，则更容易体现 Harness 的价值。

十一、常见问题

1. DeepSeek Harness 现在可以直接使用吗？

可以。当前已经开放开发者预览，可通过 npm 命令启动，也可以从公开仓库安装源码。但它仍不是稳定版，官方明确提示后续可能出现兼容性变化。

2. Harness 必须搭配 DeepSeek V4 使用吗？

不是。Harness 内置 DeepSeek 配置入口，也支持添加 OpenAI、Anthropic 等 Provider，还支持企业网关、自托管服务和其他自定义 Provider。

3. Harness 必须通过 4SAPI 接入吗？

不需要。4SAPI 只是可选的模型接入方式之一。单模型用户可以直接调用模型官方 API；多模型测试、统一 Key 管理或集中统计成本的团队，可以考虑将 4SAPI 配置为自定义 Provider。

4. 使用 4SAPI 是否一定更便宜？

不一定。是否节省费用取决于目标模型价格、任务类型、Token 消耗、重试次数和具体通道。它更明确的价值是统一入口，并允许团队将不同复杂度的任务分配给不同价位的模型。

5. 当前版本适合直接用于生产环境吗？

可以进行内部验证和小范围试验，但不宜忽略版本变化风险。涉及自动修改文件、执行 Shell 或访问敏感项目时，应使用隔离工作区、容器或严格的权限策略，并保留人工审批环节。

十二、总结

DeepSeek Harness 的意义，不只是 DeepSeek 又推出了一款 AI 编程工具，而是将“模型之外的 Agent 工程层”作为一个独立产品开放出来。

它把模型适配、文件系统、工具、沙箱、会话、上下文、子 Agent、执行循环和界面全部拆解为可以替换的插件，并通过 Trajectory 保存 Agent 的执行事件。

对普通开发者而言，它可以作为一款本地 AI 编程 Agent 使用；对模型评测人员而言，它可以提供相对统一的工具环境；对 Agent 开发团队而言，它则是一套可以重新组合的运行基础设施。

模型接入方面，开发者既可以选择 DeepSeek 等厂商的官方 API，也可以把 4SAPI 这类 OpenAI-compatible 中转站配置为自定义 Provider。官方直连更适合单模型和原生能力优先的场景，统一中转更适合多模型切换、配置收口和综合成本管理。

真正合理的选型方式，不是预先认定某一种接入路径更好，而是先验证模型质量、工具调用、协议兼容、稳定性和实际 Token 成本，再决定最终架构。

摘要：
DeepSeek Harness 是 DeepSeek 开源的 Agent 运行框架，通过插件化方式组织模型、工具、沙箱、会话、上下文和子 Agent。本文梳理其公开时间线、运行模式、Trajectory 机制及模型接入方式，并说明如何将 4SAPI 作为可选的 OpenAI-compatible Provider，用于多模型测试和统一调用管理。