本文依据 2026 年 9 月 1 日前的公开版本整理。DeepSeek Harness 仍处于开发者预览阶段，插件名称、配置字段和兼容方式可能继续调整，正式使用时应以当前版本文档为准。

2026 年 8 月，DeepSeek 发布了首款 Agent 产品 DeepSeek Harness，并以 MIT 协议开放源代码。

理解这款产品，可以从一个简单公式开始：

Model + Harness = Agent

模型负责理解、推理和生成决策；Harness 则负责连接文件、终端、工具、网络、子 Agent 与外部模型 API，把模型给出的方案转化为能够执行、检查和交付的真实任务。

截至目前，DeepSeek Harness 仍被官方定义为开发者预览版，并明确提示后续可能出现破坏兼容性的更新。因此，它更适合作为 Agent 运行时、模型评测环境和插件开发框架，而不是已经完全成熟的普通用户桌面应用。

一、DeepSeek Harness 并不是另一个聊天机器人

DeepSeek Harness 并不是类似网页版聊天工具的封闭应用，也不是单纯在终端中调用模型的命令行客户端。

它更接近一套可扩展的 Agent 运行基础设施。启动后，用户通过浏览器访问本地 Web UI，选择工作区并配置模型。Agent 可以在权限控制范围内读取和修改项目文件、执行命令、维护任务计划、调用工具，以及把部分工作委派给子 Agent。

这意味着，Harness 关注的重点不是“模型回答得好不好”，而是以下问题：

1. 模型如何获得当前项目的真实上下文；
2. 模型如何调用文件、终端和搜索工具；
3. 多轮任务如何持续保存和恢复；
4. 不同模型如何在相同工具环境中进行比较；
5. Agent 的执行过程如何被检查、回放和调试。

因此，DeepSeek Harness 更适合开发者、模型评测人员和 Agent 基础设施研究者，而不是只需要日常对话功能的普通用户。

二、“一切皆插件”是 Harness 的核心架构

DeepSeek Harness 最重要的设计原则是：

Everything is a plugin，一切皆插件。

它基于 Cordis 插件框架构建。模型适配器、工具注册表、会话日志、Agent Loop、文件系统、沙箱、子 Agent、持久化能力和 Web 界面，都可以作为独立插件安装、替换或重新组合。

官方架构中没有一个必须修改的“特权核心”。开发者可以通过配置挂载新的插件，也可以替换现有服务。插件卸载时，由插件注册的相关作用会随生命周期自动撤销。

这种设计主要带来三个价值。

第一，模型提供商可以替换。Agent Loop 只需要面向统一的模型服务接口，上层任务逻辑不必与某一家模型厂商绑定。

第二，执行环境可以替换。本地文件系统、本地 Shell、远程沙箱和其他隔离环境，可以通过不同插件实现。

第三，Agent 能力可以按场景裁剪。用于日常开发时可以加载完整工具集，用于模型基准测试时则可以只保留最少的 Shell 和文件编辑工具。

这也是 DeepSeek Harness 与很多开箱即用型 Agent 产品之间最大的区别：它提供的不是一套固定工作流，而是一套可以重新组装的 Agent 运行框架。

三、四种运行模式对应不同的任务类型

DeepSeek Harness 的 Web 版本通过 Agent Preset 组合不同的插件和提示词。v0.1 系列主要包含标准、PTC、极简和 Cordis 等预设，具体名称可能随着预览版本调整。

运行模式	主要用途	适合场景
标准模式	加载较完整的文件、终端、计划、搜索和子 Agent 能力	日常代码分析、项目修改、仓库研究
PTC 模式	让模型生成程序来编排多次工具调用	批量搜索、并行处理、复杂自动化
极简模式	仅保留少量 Shell 与文件编辑能力	基准测试、最小复现、模型能力对比
Cordis／创造模式	检查和修改插件组合	插件开发、自定义 Agent 运行模式

其中，PTC 是 Programmatic Tool Calling 的缩写。

普通工具调用通常是模型调用一次工具、读取一次结果，再决定下一步。PTC 模式则允许模型生成一段程序，在程序中使用循环、条件判断和并行调用，把多个工具操作组合在一次执行过程中。

这种方式能够减少模型与工具之间的往返次数，但也更依赖模型的代码生成和工具编排能力。复杂模型通常更容易发挥 PTC 的优势，能力较弱的模型则可能出现脚本语法错误或错误调用工具的问题。官方仓库当前已将早期的 Code Mode 命名逐步调整为 PTC Mode。

四、Trajectory 让 Agent 执行过程不再完全黑盒化

长周期 Agent 任务经常面临一个问题：任务失败后，用户只能看到最终结果，却不知道模型在哪一步理解错了、调用了什么工具，或者为什么消耗了大量 Token。

DeepSeek Harness 通过会话日志和 Trajectory 视图记录任务执行过程。

系统会以仅追加的事件流保存模型可见消息、Assistant 输出分块、工具调用、工具结果、回合状态和其他会话事件。后续的会话恢复、上下文投影、执行回放和界面展示，都可以从这份日志中生成。

需要注意的是，Trajectory 不应被简单理解为“必然展示模型完整思维链”。

它能够记录多少推理内容，取决于模型接口和适配器实际返回了什么。更准确的说法是，它提供了比普通聊天记录更完整的任务执行轨迹，适合用于：

1. 定位失败的工具调用；
2. 检查模型实际接收到的上下文；
3. 分析任务在哪一步发生偏离；
4. 观察上下文和 Token 使用情况；
5. 对比不同模型在相同任务中的执行路径。

五、DeepSeek Harness 的安装与快速启动

1. 环境要求

当前源码仓库要求：

• Node.js 22.19 或更高的 22.x 版本；
• 或 Node.js 24 及以上版本；
• 源码安装需要 pnpm；
• Python SDK 需要 Python 3.10 或更高版本。

官方仓库声明的 Node.js 引擎范围为：

^22.19.0 || >=24.0.0

使用 Node.js 20 等旧版本时，即使安装过程没有立即中断，也可能在运行阶段遇到缺失 API 或模块加载错误。

2. 使用 npx 快速启动

npx @deepseek-ai/dsh web

运行成功后，Harness 默认会启动本地 Web UI：

http://127.0.0.1:3080

通常浏览器会自动打开。如果没有自动打开，可以手动访问该地址，也可以尝试：

http://localhost:3080

官方启动命令会默认使用 3080 端口。进入界面后，还需要完成两项配置：

1. 在 Settings → Models 中添加模型；
2. 选择一个允许 Agent 操作的 Workspace。

没有选择工作区时，新的会话输入区域可能处于不可用状态。

3. 缩短日常启动命令

可以在项目的 package.json 中增加：

{
  "scripts": {
    "dsh": "npx @deepseek-ai/dsh web"
  }
}

后续在该项目目录中运行：

npm run dsh

这只是在 npm scripts 中封装启动命令，不会改变 Harness 本身的配置。

六、模型 API 可以选择官方直连或统一中转

启动 Harness 后，真正决定 Agent 输出质量、工具调用能力和使用成本的，仍然是底层模型 API。

目前主要有两种接入方式。

1. 直接接入模型官方 API

在 Settings → Models 中选择 DeepSeek、OpenAI、Anthropic 等已收录提供商，然后填写对应平台的 API Key。

官方直连的优势是接口路径明确，新模型和高级功能通常能够较早获得支持，排查问题时也更容易对照原厂文档。

如果只使用一家模型，或者需要某个厂商的原生高级能力，官方 API 往往是更直接的选择。

2. 通过自定义 Provider 接入 API 中转站

DeepSeek Harness 也支持添加自定义模型提供商。用户可以填写：

• Provider ID；
• 显示名称；
• Base URL；
• API 协议；
• API Key；
• 模型 ID。

因此，只要中转平台提供 Harness 可以识别的兼容协议，就可以作为自定义 Provider 使用。官方文档明确将企业网关、自托管服务和 OpenAI 兼容 Endpoint 列为自定义 Provider 的适用对象。

例如，需要在 Harness 中测试多家模型时，可以把 4SAPI 中转站配置为一个自定义 Provider。4SAPI 提供 OpenAI-compatible 接口，接入思路与其他兼容网关相同：填写平台提供的 Base URL、API Key 和准确模型 ID。

配置时可以参考以下字段：

Provider ID：4sapi
Display Name：4SAPI
Base URL：以4SAPI控制台或当前接入文档为准
API Protocol：openai-completions
API Key：在4SAPI控制台创建的Key
Model ID：从当前模型列表中复制

如果 Provider 支持兼容的 GET /models 接口，可以使用 Harness 的 Fetch available models 功能读取模型列表；如果未提供该接口，则需要手动填写模型 ID。

需要强调的是，4SAPI 并不是运行 DeepSeek Harness 的必要依赖，而是一种可选的模型接入路径。

对于只调用 DeepSeek 单一模型的个人开发者，直接使用官方接口可能更简单；对于需要同时测试 DeepSeek、GLM、Qwen、Claude 或其他模型的团队，统一中转可以减少多套账号、Base URL 和密钥配置。

在成本方面，中转方式可以帮助团队统一查看消耗，并根据任务选择不同价位的模型，从而降低综合接入和维护成本。但它是否一定比官方接口便宜，仍需结合具体模型单价、输入输出 Token、缓存策略和平台服务费进行计算，不能仅凭“中转站”三个字判断。

七、OpenAI 兼容并不代表所有字段完全一致

接入自定义网关时，最常见的误区是认为“兼容 OpenAI”就意味着每一个请求字段都完全相同。

实际上，不同网关对以下内容的处理可能存在差异：

• 系统提示词使用 system 还是 developer 角色；
• 输出限制使用 max_tokens 还是 max_completion_tokens；
• 推理内容如何传递；
• 流式工具调用的增量格式；
• 图片等多模态输入如何声明。

Harness 官方文档也提醒，自定义网关即使 Base URL 和 API Key 正确，仍可能因为请求字段差异而返回错误。

基础配置可以参考：

llm-pi-ai:
  providers:
    4sapi:
      apiKeyEnv: FOURSAPI_API_KEY
      api: openai-completions
      baseURL: https://<控制台提供的Base-URL>/v1
      models:
        - id: <准确的模型ID>

如果出现与 developer role 或 max_completion_tokens 有关的 400 错误，可以在确认平台实际协议后尝试增加：

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

这两个字段不是所有 4SAPI 模型都必须添加的固定配置，只是在对应兼容错误出现时可参考的排查方向。应先观察实际错误信息，再决定是否修改。

八、源码安装适合插件开发和二次修改

需要研究源码或开发插件时，可以完整克隆仓库：

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

其中：

• pnpm install 安装工作区依赖；
• pnpm run build 构建仓库产物；
• pnpm dsh web 使用已构建产物启动 Web UI。

如果只是体验产品，没有必要先走源码安装，直接使用 npx 启动通常更简单。

九、输入 y 后一直卡住的常见原因

1. npm 下载速度较慢

npx 首次运行时需要下载相关包。网络不稳定时，终端可能长时间没有明显进度。

可以先终止命令，再临时切换镜像源：

npm config set registry https://registry.npmmirror.com
npx @deepseek-ai/dsh web

需要恢复官方 npm 源时运行：

npm config set registry https://registry.npmjs.org

2. Node.js 版本不符合要求

检查当前版本：

node -v

如果低于 22.19，可以使用 nvm 安装并切换：

nvm install 22
nvm use 22

3. 服务已经启动，但浏览器没有自动打开

查看终端中是否出现类似信息：

Server running at http://127.0.0.1:3080

如果已经启动，直接在浏览器中访问：

http://127.0.0.1:3080

或者：

http://localhost:3080

4. 界面打开后无法输入任务

这通常不一定是模型错误。先检查：

1. 是否已经配置并选中模型；
2. 是否已经添加 Workspace；
3. API Key 是否有效；
4. 模型 ID 是否与接口中的真实名称一致。

5. 自定义 Provider 可以保存，但请求报错

重点检查：

• Base URL 是否多写或漏写 /v1；
• 模型 ID 是否准确；
• 协议是否选错；
• Key 是否属于当前平台；
• 是否存在 developer、max_tokens 或流式工具调用兼容问题。

不要仅通过普通对话是否成功判断 Agent 可用性。Harness 会使用工具调用、系统提示词和多轮上下文，普通 Chat Completions 能返回，并不代表完整 Agent 流程一定兼容。

十、Python SDK 适合程序化调用 Agent

除了 Web UI，DeepSeek Harness 还提供 Python SDK，可以在程序、自动化脚本和评测流程中调用 Agent。

官方 Python SDK 要求 Python 3.10 或更高版本。安装包包含匹配的运行时，普通 SDK 使用场景不要求系统另外安装 Node.js。

基础安装方式如下：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

python -m venv .venv

Linux 或 macOS 激活环境：

source .venv/bin/activate

Windows PowerShell 激活环境：

.venv\Scripts\Activate.ps1

安装 SDK：

python -m pip install deepseek-harness-sdk

Python SDK 同样可以通过兼容 Endpoint 使用自定义模型服务。使用 4SAPI 等中转接口时，应根据具体 SDK Profile 和模型适配方式设置对应 Base URL、Key 与模型 ID，并先在隔离测试目录中验证文件修改、工具调用和多轮任务是否正常。

十一、DeepSeek Harness 更适合哪些人

目前的 DeepSeek Harness 更适合以下三类用户。

1. Agent 开发者

需要替换模型适配器、工具、沙箱、持久化服务或 Agent Loop，并希望直接控制运行时结构。

2. 模型评测人员

希望让不同模型在相同提示词、相同工具和相同工作区中执行任务，从而减少评测环境差异。

这类用户可以通过官方接口分别配置模型，也可以通过 4SAPI 等统一中转方式集中接入多个模型，降低反复管理 Endpoint 和 Key 的工作量。

3. 插件生态参与者

希望开发文件工具、搜索能力、MCP 集成、模型适配器、远程沙箱或新的 Agent Preset。

对于只想获得成熟 AI 编程体验的普通用户，当前版本仍存在较高的安装、配置和兼容排查门槛。OpenAI Codex、Claude Code 等成熟产品在开箱即用方面可能更加直接；DeepSeek Harness 的优势则在于开放、可替换和可研究。

十二、总结

DeepSeek Harness 真正值得关注的地方，并不是它又提供了一个 Agent 界面，而是它试图把 Agent 的组成部分全部拆开：

• 模型是可替换的；
• 工具是可替换的；
• Agent Loop 是可替换的；
• 沙箱和文件系统是可替换的；
• 会话记录能够保存和回放；
• 不同插件可以重新组合成新的运行模式。

对普通用户来说，v0.1 系列仍然偏早期；对开发者来说，它已经提供了一个研究 Agent 工程化问题的开放入口。

模型接入方面，用户既可以直接使用 DeepSeek 等厂商的官方 API，也可以把 4SAPI 这类兼容中转站配置为自定义 Provider。前者适合单模型和原生能力优先的场景，后者更适合多模型切换、统一密钥与集中查看消耗的场景。

实际选择时，不需要把官方直连和 API 中转理解成互相排斥的方案。更合理的做法是先验证协议、工具调用和模型质量，再根据稳定性、价格、账单管理和长期维护成本决定最终接入路径。