DeepSeek Harness 是 DeepSeek 推出的首款 Agent 产品，它把大模型变成能够管理项目、编排多 Agent、执行长任务的智能体。本教程将介绍 DeepSeek Harness 的核心概念、安装方法、模型配置与日常使用，帮助你在本地搭建一个开源 AI Agent 工作台。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

1. DeepSeek Harness 概述

1.1 DeepSeek Harness 是什么

DeepSeek Harness 是 DeepSeek 于 2026 年 8 月 13 日发布的首款 Agent 产品，开发者预览版（v0.1）面向全球开放公测，源代码以 MIT 协议在 GitHub 开源，并提供 npm 插件生态。官方将其定位为"把模型变成智能体的工具"，主打编程与办公场景的 AI 生产力工具。

Harness 原意是"马具、缰绳"，在 AI 领域指连接模型与实际执行环境之间的工程层。DeepSeek Harness 充当模型与真实环境之间的桥梁：模型负责理解需求与生成方案，Harness 负责调度上下文、工具、任务状态与反馈，让模型能够完成从理解需求到交付代码的完整闭环。这一结构符合 Agent概念详解 中讲解的通用 Agent 架构。

DeepSeek Harness 与 Claude Code、OpenAI Codex 属于同类产品，均以"智能体 + 项目"为工作单元。区别在于 Harness 可自由接入近 40 家模型厂商，并以 MIT 协议开源。

1.2 Model + Harness = Agent

官方给出的产品公式为 "Model + Harness = Agent"：模型是"大脑"，负责推理与生成；Harness 是"执行层"，负责在模型之外调度上下文、工具、任务状态、反馈与边界。缺少 Harness 的模型只能回答问题，加上 Harness 之后才能执行多步骤真实任务。

graph LR A[用户
自然语言指令] --> B[Harness 执行层] B --> C[LLM 模型
推理与生成] C --> D[上下文管理] B --> E[工具调用] B --> F[多 Agent 编排] B --> G[Skill 技能] B --> H[联网搜索] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#ffecd6,stroke:#e67e22,stroke-width:2px style D fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style E fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style F fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style G fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style H fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px

1.3 核心功能

据官方发布信息，DeepSeek Harness 支持以下本地 Agent 工作台功能：

功能 说明
管理项目 以项目为单位组织任务与文件，支持会话的恢复、分支、检索与回放
长任务协作 通过计划、目标与工作流机制处理多步骤、跨时长的复杂任务
多 Agent 编排 支持子 Agent 调度，多个 Agent 分工协作完成复杂需求
上下文管理 管理上下文注入与压缩，记录系统提示词、思维链、工具调用与结果
联网搜索 内置文件搜索与联网搜索工具
Skill 以插件形式组合技能，可自定义 Agent 预设，概念详见 Skill概念详解

1.4 四种 Agent 预设模式

DeepSeek Harness 内置四种 Agent 预设模式，覆盖从基准测试到日常开发的不同场景：

模式 名称 适用场景
极简模式 minimal 简单修改与测试，仅保留 shell 与文本编辑工具，用于基准测试
标准模式 standard 日常写代码、修 Bug、分析项目，工具集完整
代码模式 code 大批量搜索、并行读取与多步骤自动处理
创造模式 cordis 检查运行时，试验与组合 Cordis 插件，创建新预设

2. 环境准备与安装

2.1 环境要求

安装 DeepSeek Harness 需要满足以下条件：

环境 要求 说明
Node.js 已安装 DeepSeek Harness 基于 Node.js 运行，建议使用最新 LTS 版本
npm 随 Node.js 安装 用于安装 @deepseek-ai/dsh 包
API Key DeepSeek 开放平台 在配置模型时使用，也可接入其他厂商模型

2.2 安装 Node.js

DeepSeek Harness 依赖 Node.js 运行。你可以前往Node.js和Npm安装与使用教程查看 Node.js 的安装方法。安装完成后，在终端中验证：

node --version
npm --version

能输出版本号即说明 Node.js 环境就绪。

2.3 获取 DeepSeek API Key

在配置模型前，需要先获取 DeepSeek API Key。你可以前往大语言模型LLM服务商Api服务调用教程查看 DeepSeek API 的注册与 Key 获取方法。API Key 以 sk- 开头，在 DeepSeek 开放平台生成。

DeepSeek Harness 允许接入第三方模型，若使用其他厂商的 API Key，同样支持配置。

2.4 通过 npm 快速启动

使用 npx 无需全局安装即可直接启动 Web 界面：

npx @deepseek-ai/dsh web

首次运行会从 npm 拉取 @deepseek-ai/dsh 包并启动 Web UI。也可以全局安装后使用 dsh 命令：

npm install -g @deepseek-ai/dsh

dsh web

启动成功后，终端会提示访问地址，默认是 http://127.0.0.1:3080。在浏览器中打开该地址即可看到 DeepSeek Harness 的 Web 界面。

graph LR A[安装 Node.js] --> B[启动 dsh Web UI] B --> C[配置模型 API Key] C --> D[选择项目工作区] D --> E[运行任务] E --> F[会话记录与回放] style A fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#ffecd6,stroke:#e67e22,stroke-width:2px style D fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style E fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style F fill:#fdebd0,stroke:#b7950b,stroke-width:2px

2.5 从源码运行（可选）

如果想体验最新开发版本或参与贡献，可以从 GitHub 克隆源码运行：

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

开发者预览版本迭代较快，可能出现破坏性变更，建议固定所依赖的版本号。

3. 配置模型

3.1 Web 界面配置模型

打开 http://127.0.0.1:3080 后，进入 Settings → Models 设置：

  1. 在模型提供方中选择 DeepSeek，或选择其他支持的厂商
  2. 输入 API Key（以 sk- 开头）
  3. 保存配置，无需重启服务器即可生效

DeepSeek Harness 默认提供 Kimi、OpenAI、Anthropic、Google 等近 40 家大模型厂商，也支持自定义 OpenAI 兼容接口。

3.2 凭据文件

API Key 与可选接口地址保存在 $DSH_HOME/.credentials.yaml 文件中，权限为仅当前用户可读写（owner-only）。你也可以直接编辑该文件完成配置。

3.3 命令行检查配置

dsh 提供配置检查命令，无需启动即可查看组合后的完整配置树：

dsh --profile web --dump-config

4. 开始使用

4.1 Web 模式

配置完成模型后，即可开始使用：

  1. 点击 Choose workspace，选择要使用的工作区目录（即你的项目目录）
  2. 启动会话并发送自然语言提示词
  3. Agent 会读写工作区文件、执行命令，完成编程任务

例如在工作区中运行一个 Python 项目任务：

请读取当前目录下的 requirements.txt，帮我安装依赖并运行 main.py，最后总结输出结果。

4.2 Headless 命令行模式

除了 Web 界面，dsh 还提供 headless 模式，适合脚本与 CI 场景。运行一个全新会话，打印最终答案后退出：

dsh --profile headless "运行当前项目的测试"

4.3 常用 CLI 命令

命令 作用
dsh web 启动 Web 界面（--profile web 的别名）
dsh --profile headless "任务" 以 headless 模式运行一次性任务
dsh --profile <名称> 启动指定的自定义 profile
dsh plugin --profile <名称> <pnpm 参数> 管理指定 profile 的插件
dsh --profile web --dump-config 查看组合后的完整配置树

dsh 启动器只解析自身的参数，其后的内容全部交给对应 profile 处理，启动器参数必须写在最前面。

5. 高级功能

5.1 "一切皆插件"架构

DeepSeek Harness 采用"一切皆插件"（everything is a plugin）设计：模型、工具、技能、会话、沙箱、存储、循环、调度、UI 等所有 Agent 能力均由插件组合而成，可自由替换、灵活重组。插件系统基于 Cordis 插件框架，支持插件的加载与卸载及依赖管理，开发者无需修改源码即可扩展能力。

5.2 配置体系

一个 profile 目录包含以下文件：

文件 作用
package.json 记录插件依赖
dsh.profile profile 元数据清单，按顺序列出组合包（bundles）
cordis.patch.yml 用户自己的配置补丁层

配置树从空根开始按顺序叠加：组合包的补丁 → profile 自身的 cordis.patch.yml → 用户主目录 $DSH_HOME/cordis.patch.yml → --patch 指定的覆盖层。

5.3 会话日志与回放

Harness 的会话日志采用追加写入（append-only）方式记录系统提示词、思维链、工具调用与结果、子 Agent 调度与上下文注入。通过轨迹（Trajectory）视图可以查看完整执行过程，并支持恢复（resume）、分支（fork）、检索与回放（replay），便于排查问题与复盘任务。

6. 总结

6.1 核心内容回顾

  • DeepSeek Harness 是 DeepSeek 首款 Agent 产品，MIT 协议开源，定位对标 Claude Code 与 Codex
  • 核心公式 "Model + Harness = Agent"，Harness 负责把模型能力落地为真实任务执行
  • 通过 npx @deepseek-ai/dsh web 快速启动，默认地址 http://127.0.0.1:3080
  • 内置极简、标准、代码、创造四种 Agent 预设模式，支持近 40 家模型厂商
  • 采用"一切皆插件"架构，基于 Cordis 插件框架，支持会话日志回放与多 Agent 编排

6.2 常见问题与解答

问：DeepSeek Harness 收费吗？

答：Harness 本身以 MIT 协议开源，免费使用；调用模型的费用按所选模型的 API 计费，如 DeepSeek API 按 token 计费。

问：对电脑配置有要求吗？

答：Harness 本地运行，资源占用较小，模型推理在云端完成，无需独立显卡，普通电脑即可使用。

问：能接入 OpenAI、Kimi 等其他模型吗？

答：可以。Harness 默认提供近 40 家模型厂商，支持自定义 OpenAI 兼容接口，在设置中切换即可。

问：与 Claude Code 相比有什么不同？

答：两者定位相同，均面向编程与办公场景。Harness 的优势在于模型选择自由、完全开源，且支持多 Agent 编排与插件化扩展。