DeepSeek Harness 教程 - Harness 工具教程

产品介绍

DeepSeek Harness（简称 DSH，命令行名 dsh）是 DeepSeek AI 于 2026 年 8 月 13 日开源的全新 AI Agent 运行框架，采用 MIT 协议发布。它将模型能力与运行环境有机结合，让模型能够读取代码、执行命令、修改文件，完成从对话到行动的全链路闭环。DeepSeek 官方将其核心定位概括为：Model + Harness = Agent。

一切皆插件

基于 Cordis 插件系统构建，所有能力——模型、工具、技能、会话、沙箱、存储、循环、调度、UI——全部以插件形式提供，可自由替换和组合。

每次运行可追溯

模型看到的每一条信息都记录在追加式会话日志中：系统提示、推理过程、工具调用与结果、子代理调度、上下文注入，全部可回溯、可恢复、可复现。

多种运行模式

提供 Standard（标准）、Code（代码）、Minimal（极简）、Creator（创造）四种模式，覆盖从全功能编码到极简基准测试的不同场景。

多模型支持

原生支持 DeepSeek V4 系列模型，同时可接入其他 OpenAI 兼容模型，甚至可将 Claude Code、Codex 等外部 Agent 作为子代理调用。

MIT 开源

完全开源，采用 MIT 协议，开发者可自由使用、修改和分发，无需担心许可证限制。

YAML 配置驱动

所有配置通过 YAML 文件管理，模型、工具、Skills、权限策略等均可通过配置文件灵活调整，无需修改源码。

Cordis 插件系统

DeepSeek Harness 构建在 Cordis 框架之上。Cordis 是一个插件系统，插件通过服务、类型化事件和可逆效应向共享上下文贡献能力。在 DSH 中，没有特权核心需要修补——你通过挂载一个插件来扩展它，注册是效应，在插件卸载时会自动撤销。

四种运行模式

模式	用途	工具集
Standard（标准）	全功能编码代理	文件编辑、Shell、文件和网页搜索、Skills、规划、目标、子代理、工作流
Code（代码）	程序化工具调用	全部 Standard 能力 + Code Mode SDK，让模型用一段 TypeScript 代码编排多次工具调用
Minimal（极简）	基准测试、模型裸实力评估	仅提供持久 bash 和 str_replace_editor 两个工具
Creator（创造）	创建自定义 Agent 预设	全部 Standard 能力 + 运行时检查、插件实验、预设创作指导

安装部署

系统要求

Node.js：v22.19 及以上（官方 package.json 中 engines 声明为 ^22.19.0 || >=24.0.0）
pnpm（源码构建时需要）：通过 npm install -g pnpm 安装
Git（源码构建时需要）：2.26 及以上
DeepSeek API Key：用于 Web、Headless 和 ACP 自动化演示
操作系统：Windows、macOS、Linux 均支持

安装方式一：npx 一键启动

最快的安装方式，无需全局安装，适合快速体验：

# 确认 Node.js 版本
node --version

# 一键启动 Web UI（默认地址 http://127.0.0.1:3080）
npx @deepseek-ai/dsh web
                    

安装方式二：全局安装

适合日常使用，可以固定版本：

# 全局安装
npm install -g @deepseek-ai/dsh

# 启动 Web UI
dsh web
                    

安装方式三：从源码构建

适合想阅读源码、追踪最新提交的开发者：

# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 安装依赖
pnpm install

# 构建项目
pnpm run build

# 启动 Web UI
pnpm dsh web
                    

安装方式四：Python SDK

适合嵌入 CI/CD 或脚本场景（官方仓库 python/ 目录）：

# 安装 Python SDK
pip install deepseek-harness-sdk
                    

首次启动配置

启动 Web UI 后，浏览器打开 http://127.0.0.1:3080，需要完成以下初始配置：

配置 API Key：进入 Settings → Models，填入 DeepSeek API Key（sk-...）并保存。Key 存储在本地配置目录中，界面仅显示脱敏后的描述符。
选择工作区：点击「选择工作区」，添加项目目录并选中。你在哪个目录启动的 dsh web，该目录就是默认工作区。
开始使用：选中工作区后，输入框解锁，即可向 Agent 下达任务。

开发搭建

仓库结构

DeepSeek Harness 采用 monorepo 结构，主要目录如下：

vendor/                     # Vendored Cordis 源码
packages/                   # @deepseek-ai/dsh-<pkg> 工作区
  core/                     # 产品 API 核心：session, system-prompt, tools, agent, agent-loop
  api/                      # Remote BFF 组装和 Typert RPC 网关
  llm/                      # LLM 能力：Service Definition/Consumer + DeepSeek providers
  shell/                    # Bash 能力：Service Definition + local/pwsh providers
  subprocess/               # 子进程能力 + 本地进程树 provider
  fs/                       # 文件系统能力 + 安全策略
  skill/                    # 技能提供者注册表 + 本地实现 + 目录/加载器工具
  web/                      # Web 能力：Service Definition + search/fetch providers
  subagent/                 # 子代理能力：Service Definition + providers + delegation Consumers
  bundle/                   # 可安装的 dsh --profile 补丁层 bundle
  workflow/                 # 工作流能力 + worker-thread provider + 工具 Consumer
  settings/                 # 用户设置能力 + 文件 provider
  credentials/              # 凭据引用能力 + env/.env provider
  guard/                    # 循环卫生 + 工具超时插件
  hooks/                    # Claude Code/Codex hook 桥接 + 线协议库
python/                     # Python SDK 和捆绑运行时
docs/                       # 架构文档、生成目录、事后分析、指南
examples/                   # 可运行的 cordis.yml 示例
                    

开发环境搭建

前置条件：

Node.js 22.19+ 或 24+
启用 Corepack 的 pnpm（仓库在 package.json 中固定 pnpm@11.7.0）
Git 2.26 或更新版本
可选：DeepSeek API Key 用于运行 Web、Headless 和 ACP 演示

首次设置：

# 从仓库根目录安装依赖（同时配置 Lefthook hooks 和 Git merge driver）
pnpm install

# 如果从缓存恢复或跳过了 postinstall，手动安装 hooks
node scripts/install-lefthook.mjs

# 首次克隆后运行类型检查
pnpm run typecheck
                    

常用开发命令

pnpm install              # 安装依赖
pnpm run clean            # 清理构建产物
pnpm run test             # 运行单元测试
pnpm run test:coverage    # CI 覆盖率检查（每文件 100%）
pnpm run test:e2e         # 真实 API 测试（需要 DEEPSEEK_API_KEY）
pnpm run typecheck        # 类型检查
pnpm run lint             # 代码检查
pnpm run build            # 构建项目（tsc 生成 lib/types，tsdown 打包运行时）
pnpm run hygiene          # 代码卫生检查（knip + publint + workspace constraints）
pnpm run doc-sync         # 文档同步检查
pnpm run website:build    # VitePress 构建（含死链检查）
                    

运行 Headless 模式

无界面模式，适合集成到 CI/CD 流水线中：

# 需要设置 DEEPSEEK_API_KEY 环境变量
pnpm dsh --profile headless "summarize this workspace"
                    

运行 ACP 模式

Agent Client Protocol 自动化服务器，通过 JSON-RPC stdio 提供 Agent 会话：

pnpm run demo:acp

Cordis 自引用演示

Agent 可以检查和修改自己的运行时插件：

pnpm run demo:cordis

配置模型提供方

环境变量配置（在仓库根目录创建 .env 文件）：

DEEPSEEK_API_KEY=sk-...
DEEPSEEK_BASE_URL=https://...  # 可选，默认使用公共 API
                    

DSH 也支持接入其他 OpenAI 兼容的模型端点，在 Settings → Models 中配置即可。

插件开发

DeepSeek Harness 的架构决定了所有扩展都通过插件实现。开发新插件时，需要了解以下核心扩展点：

目标	机制
添加模型提供方	在 `ctx.llm` 上注册适配器
添加模型可用的能力	在 `ctx.tools` 上注册，schema 自动加入提示组装
添加 Shell 执行	注册 `ctx.shell` 后端
添加文件系统访问或策略	注册 `ctx.fs` 提供者或监听 `fs/*` 事件
添加子代理	注册 `ctx.subagent` 提供者
拦截请求、工具或回合	使用 `agent/` 或 `tools/` 事件
添加模型可见上下文	调用 `agent.inject()`
添加 UI 或编辑器集成	驱动 `ctx.agents` 并从 `session/event` 渲染

使用教程

基本使用流程

1. 启动 Web UI

npx @deepseek-ai/dsh web
# 浏览器打开 http://127.0.0.1:3080
                    

2. 配置模型

打开 Settings → Models，输入 DeepSeek API 密钥并保存。模型路由会立即可用，无需重启服务器。也可以在此配置其他 OpenAI 兼容的模型端点。

3. 选择工作区

点击「选择工作区」，添加启动 dsh 时所在的项目目录，然后选中它。选中工作区前，会话输入框不可用。

4. 运行任务

启动一个会话，输入任务描述，例如：

Summarize this repository and identify its main packages.

Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。当操作在当前权限策略下需要审批时，Web UI 会先询问你。

高级使用

1. 自定义 Agent 预设

使用 Creator 模式可以创建自定义 Agent 预设。在 Creator 模式中，你可以检查当前运行时，在内存中测试 Cordis 插件，并将它们组合成新的模式。

2. 配置权限策略

在 Settings 中可配置权限策略，从只读到完全危险操作跳过权限，类似于 Claude Code 中的模式。支持对文件操作、Shell 命令、网络请求等设置不同级别的权限。

3. 管理会话

会话日志是 append-only 的，所有信息都可追溯。你可以：

Fork 会话：从某个点分叉出新的会话分支
恢复会话：从之前的会话日志中恢复状态
搜索会话：在历史会话中搜索特定内容
重放会话：基于事件流重放执行过程

4. 使用 Code Mode

Code Mode 是 DeepSeek Harness 的独特功能。在 Code Mode 中，模型生成一段 TypeScript 代码来编排多次工具调用，将原本需要多轮交互的操作合并为一次执行，大幅提升效率。

// Code Mode 示例：模型生成的编排代码
import { tools } from 'dsh-code-mode-sdk';

// 一次读取多个文件
const files = await Promise.all([
    tools.read('package.json'),
    tools.read('tsconfig.json'),
    tools.read('README.md'),
]);

// 批量搜索
const results = await tools.search('TODO|FIXME');

// 链式操作
const deps = JSON.parse(files[0]).dependencies;
await tools.shell('npm outdated');
                    

5. 使用子代理

DSH 支持将外部 Agent 作为子代理调用，实现多 Agent 协作：

将 Claude Code 或 Codex 注册为子代理提供者
在 YAML 配置中声明子代理及其权限
主 Agent 根据任务类型自动选择合适的子代理执行

6. 查看实时统计

DSH 的 Web UI 提供实时统计面板，显示：

Tokens per second（每秒令牌数）
Cache hit rate（缓存命中率）
Turn count（回合数）
Running time（运行时间）

7. 查看配置树

查看当前运行时的完整插件树：

dsh --profile web --dump-config

输出的每一行都可以通过你自己的补丁替换。

示例演示

示例一：仓库代码分析

在 Web UI 中，选中一个项目仓库作为工作区，向 Agent 发送：

总结这个仓库，告诉我主要的包结构，以及它们之间的依赖关系。
                    

Agent 会主动读取 package.json、tsconfig.json 等关键文件，分析目录结构，并生成结构化的总结报告。

示例二：Headless 模式自动化

在 CI/CD 流水线中使用 Headless 模式自动执行代码审查：

# 设置 API Key
export DEEPSEEK_API_KEY=sk-...

# 运行 Headless 模式
dsh --profile headless "审查最近的代码变更，检查是否有安全问题或逻辑错误"
                    

示例三：Cordis 自引用演示

Agent 检查和修改自己的运行时插件配置：

pnpm run demo:cordis

在这个演示中，Agent 可以检查自己的 Cordis 插件树，动态添加或移除插件，验证插件系统的可组合性。

示例四：真实场景实测

在构建一个实时国际空间站跟踪器的实际测试中，DeepSeek Harness 的表现：

消耗约 2000 万 tokens，跨越 2 个回合
耗时约 35 分钟
运行结束时 缓存命中率达到 100%
使用 Flash 模型在编码任务中获得了比 Pro 更好的性价比

示例五：多 Agent 协作

配置 Claude Code 或 Codex 作为子代理，实现多 Agent 协作工作流：

# 在 cordis.patch.yml 中配置子代理
subagents:
  - name: claude-code
    provider: claude-code
    permissions: read-only
  - name: codex
    provider: codex
    permissions: read-write
                    

主 Agent 会根据任务类型自动选择合适的子代理执行特定子任务。

作用影响

对 AI Agent 领域的影响

DeepSeek Harness 的发布标志着 AI Agent 框架进入了一个新的阶段。与 Anthropic 的 Claude Code 和 OpenAI 的 Codex 等封闭式编码代理不同，DSH 走的是完全开源的路线，将 Agent 框架层整体开源，对行业产生了深远影响：

1. 打破 Agent 开发壁垒

在 DSH 之前，开发者想在 AI 编码代理上做定制化扩展，往往需要依赖厂商提供的有限 API 或插件接口。DSH 的「一切皆插件」架构意味着：

模型适配器可以替换，不再绑定单一模型供应商
工具注册表完全开放，任何工具都可以作为插件挂载
Agent 循环本身就是可替换的插件
会话日志、沙箱、文件系统等基础设施全部可定制

2. 推动 Agent 互操作性

DSH 支持将 Claude Code、Codex 等外部 Agent 作为子代理调用，这意味着开发者可以构建多 Agent 协作系统，让不同的 Agent 各司其职，由 DSH 统一编排。这种设计思路打破了不同 Agent 产品之间的壁垒。

3. 降低 Agent 使用成本

DSH 的 Code Mode 通过让模型生成 TypeScript 代码来批量执行工具调用，将原本需要多轮交互的操作合并为一次执行，显著降低了 Token 消耗。实测中缓存命中率可达 100%，进一步优化了使用成本。

4. 提升 Agent 可观测性

DSH 的 append-only 会话日志和实时统计面板，让开发者可以清晰了解 Agent 的执行过程、Token 消耗、缓存命中率等关键指标，便于调试和优化。

对开发者的价值

学习参考：DSH 的源码是学习 Agent 框架设计的绝佳教材，特别是 Cordis 插件系统和事件驱动架构
快速集成：通过 npm 一键启动，无需复杂配置即可体验 AI Agent 编码能力
灵活定制：YAML 配置驱动，开发者可以根据自己的需求灵活调整 Agent 的行为
社区生态：通过 dsh-plugin 话题标签，社区可以分享和发现插件

市场反响

DSH 发布后获得了极高的市场关注：

上线不到一天，GitHub Star 数突破 8.7 万
在 GitHub 历史上的涨速排名前列
与 DeepSeek V4 Pro 正式版同日发布，形成模型+框架的完整生态

社区与支持

GitHub Discussions：提交反馈或 bug 报告
dsh-plugin 话题：为你的插件仓库添加 dsh-plugin 话题标签，便于被发现
企微社群：扫码添加企微小助手并填写入群问卷，加入 DeepSeek Harness 企微群
官方文档：https://deepseek-harness.github.io/deepseek-harness/

常见问题

安装问题

Q: 安装时提示 Node.js 版本不兼容怎么办？

A: 确认 Node.js 版本不低于 v22.19。运行 node --version 检查当前版本，如果偏低，请到 nodejs.cn 下载最新 LTS 版本。

Q: npx 启动时报错怎么办？

A: 确保网络连接正常，npx 首次运行需要下载包。如果持续失败，可以尝试全局安装方式：npm install -g @deepseek-ai/dsh。

Q: 从源码构建时 pnpm install 失败？

A: 确保安装了 pnpm（npm install -g pnpm），并且启用了 Corepack（corepack enable）。

使用问题

Q: 启动后输入框是灰色的，无法使用？

A: 需要先完成两步操作：1) 在 Settings → Models 中配置 API Key；2) 点击「选择工作区」添加并选中一个项目目录。

Q: 如何配置其他模型提供方？

A: 在 Settings → Models 中，可以添加其他 OpenAI 兼容的模型端点。DSH 支持接入任何 OpenAI 兼容的 API。

Q: 如何切换运行模式？

A: 在会话设置中可以选择不同的 Agent 预设（Standard、Code、Minimal、Creator），不同预设对应不同的工具集和能力。

Q: Agent 会修改我的文件吗？

A: 涉及写操作时，Web UI 会按照当前权限策略弹出审批提示，不会在未经确认的情况下修改文件。你可以在 Settings 中调整权限策略级别。

技术问题

Q: DSH 与 Claude Code / Codex 有什么区别？

A: Claude Code 和 Codex 是封闭的、固定的编码代理。DSH 的核心区别在于它的框架本身是可分解的——工具、模型、技能、Agent 循环都是可替换的插件。DSH 甚至可以将 Claude Code 或 Codex 作为子代理调用。

Q: 什么是 Cordis？

A: Cordis 是 DSH 底层的插件框架。插件通过服务、类型化事件和可逆效应向共享上下文贡献能力。DSH 的每一个部分——模型适配器、工具注册表、会话日志、Agent 循环——都是 Cordis 插件。

Q: 如何开发自定义插件？

A: 阅读架构文档和 Cordis 入门，了解插件开发基础。然后参考扩展指南中的具体教程。

Q: DSH 目前处于什么阶段？

A: DSH 目前处于开发者预览阶段，正在快速迭代。未来可能出现破坏兼容性的变更。官方建议在有破坏性变更时，通过 AGENTS.md 文档获取更新指导。

其他问题

Q: 如何获取帮助？

A: 可以通过 GitHub Discussions 提交问题，或加入企微社群获取帮助。

Q: DSH 可以商用吗？

A: 可以。DSH 采用 MIT 协议发布，允许商业使用、修改和分发。

Q: 官方文档地址是什么？

A: https://deepseek-harness.github.io/deepseek-harness/

教程目录