首页

手游

资讯

专题

首页 > 教程攻略 > ai教程 >DeepSeek Harness(DSH)的详细使用指南

DeepSeek Harness(DSH)的详细使用指南

来源：互联网时间：2026-08-17 20:51:29

版本说明：本文基于 2026 年 8 月 13 日发布的 v0.1 开发者预览版整理。官方已明确警告

未来会有破坏性变更（breaking changes）

，具体细节请以 GitHub 官方仓库为准。

一、DeepSeek Harness 是什么？

DeepSeek Harness（命令行名 dsh）是 DeepSeek AI 于 2026 年 8 月 13 日开源的 Agent 运行框架（agent harness），MIT 协议，目前处于开发者预览阶段。

1.1 它不是什么

它不是一个新模型
——它自己不含任何推理能力，模型需要你自己配置。
它不只是 DeepSeek API 的套壳聊天页面
——它是一个完整的 Agent 底座。

1.2 它是什么

打个比方：如果把大模型看作

发动机

，Harness 就是

整辆车的底盘和控制系统

。发动机负责推理，Harness 决定模型能看到哪些文件、能调用哪些工具、操作前要不要审批、会话怎么保存、结果从 Web UI 还是程序接口交给你。

它让大模型真正“动手干活”：读写本地文件、执行 Shell 命令、联网搜索、拆分任务、委派子 Agent、维护执行计划，而不是只停留在对话层面。

1.3 核心设计：一切皆插件（Everything is a Plugin）

DSH 基于

Cordis

插件系统构建（其设计有学术论文《A Programming Paradigm for Spatiotemporal Composability》支撑）。模型适配、工具、Skills、会话、沙箱、存储、主循环、调度、UI——

所有能力都是插件

，都可以在配置层面拔掉、替换或扩展，不需要改框架源码。

这是它与 Claude Code、Codex CLI 这类“成品型”编码 Agent 的最大区别：后者是面向终端用户的完整应用，DSH 更偏向

可自由重组的底座框架

，默认自带的 Web UI 和工具集只是其中一种组合方式。

1.4 关键特性一览

特性	说明
一切皆插件	所有能力以插件形式存在，Cordis 内核只负责加载、卸载与依赖管理
运行有迹可循	系统提示词、思维链、工具调用、子 Agent 调度、上下文注入全部写入仅追加的会话日志，Trajectory 视图可回看
会话恢复与分叉	恢复、分叉、检索、回放共享同一份事件流，方便调试和复现
四种运行模式	标准 / PTC / 极简 / 创造（详见第四节）
多形态入口	Web UI、TUI、Headless（一次性任务）、Python SDK、TypeScript SDK
模型无关	原生支持 DeepSeek，也可接任意 OpenAI / Anthropic 兼容端点
开放可控	MIT 开源，Profile + 组合包分层配置，无特权内核，所有注册皆可逆

二、安装

2.1 环境要求

项目	要求
操作系统	Windows 10+、macOS 10.15+、主流 Linux（x64 / arm64）
Node.js	建议 v22.19 及以上，或 v24 系列（npm 一键安装和源码安装都需要）
pnpm	仅源码安装需要（`npm install -g pnpm`）
Python	仅 Python SDK 方式需要，3.10+（SDK 支持 Linux x64/arm64、macOS 14+ arm64，不支持 Windows 原生）
Git	源码安装和 Python SDK 方式需要
API 密钥	DeepSeek 或其他兼容模型提供方的 Key（可在启动后到界面里配置）

先检查环境：

node -v    # 确认 Node.js 已安装
git --version

国内用户提速

：执行安装命令前可先切换 npm 镜像源：

npm config set registry https://registry.npmmirror.com
npm config get registry   # 验证

2.2 方式一：npm 一键安装（推荐，最快体验）

npx @deepseek-ai/dsh web

首次运行会自动下载相关包并初始化 web 配置模板。
启动后终端会打印访问地址，默认 http://127.0.0.1:3080，浏览器打开即可。
npx 会优先读本地缓存，官方更新后再次运行会自动拉取最新版。

如果希望固定版本、离线可用，也可以全局安装：

npm install -g @deepseek-ai/dsh
dsh --version    # 验证安装
dsh web          # 启动 Web UI

小技巧

：dsh 会把

调用命令时所在的目录

作为默认文件系统位置。建议先 cd 到你的项目目录再启动，后续选工作区最方便。

2.3 方式二：源码安装（开发插件 / 二次开发）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install      # 安装依赖
pnpm run build    # 构建包与前端产物
pnpm dsh web      # 以源码方式启动 Web UI

源码方式的其他入口：

pnpm dsh --profile headless "run the tests"   # 一次性跑一个任务并打印最终答案
pnpm dsh --profile web --dump-config          # 查看实际启动的完整配置树（开发插件时很有用）

2.4 方式三：Python SDK（程序化调用）

适合把 Agent 能力嵌入自己的 Python 程序、脚本或自动化流水线。

SDK 自带运行时，不需要系统安装 Node.js。

要求 Python 3.10+、Git。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate        # Windows 用 .venvScriptsactivate
pip install deepseek-harness-sdk

设置凭据：

export DEEPSEEK_API_KEY=sk-your-key-here
# 如果用的是 OpenAI 兼容代&理而非 DeepSeek 官方端点，还需要：
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash

在程序中调用（可参考仓库 examples/jsonrpc-agent/minimal.py）：

from deepseek_harness import DeepSeekHarness

# 运行后会打印 assistant 的最终回复，
# 会话目录会收到包含模型请求与工具调用的 JSONL 日志

2.5 三种方式怎么选

方式	适合谁	产出
npm 一键安装 ⭐	绝大多数用户，想最快体验 Web UI	启动 Web UI（默认 3080 端口）
源码安装	想开发插件、读源码、参与贡献	本地仓库 + 完整构建产物
Python SDK	想在 Python 程序里调用 Agent	`deepseek_harness` 包 + 内置运行时

三、首次配置与第一个任务

无论哪种方式启动 Web UI，首次使用都只需

三步

：

第 1 步：配置模型

打开

设置 → 模型

，在 DeepSeek 卡片中填入 API Key（sk- 开头）并保存。

API Key 需要在 DeepSeek 开放平台注册、充值后在「API Keys」板块创建。
Key 保存后界面不再显示明文，只显示脱敏描述符。
模型路由立即可用，无需重启服务器。

第 2 步：选择工作区

点击「选择工作区」，添加你希望 Agent 操作的项目目录（即启动 dsh 时所在的目录）并选中。

选中工作区之前，会话输入框是锁定的

——这是正常现象，不是 bug。工作区机制保证 Agent 只能操作你明确授权的目录。

第 3 步：发送第一个任务

在会话输入框输入指令，例如官方推荐的轻量入门任务：

Summarize this repository and identify its main packages.

Agent 会读取工作区文件、运行命令、维护执行计划；

涉及写操作或超出权限策略的动作时，Web UI 会先弹出审批

，你确认后它才会执行。

建议先让 Agent 熟悉工作区，再逐步交付真实任务；第一次别上来就扔一个超大项目进去。

四、四种运行模式

四种模式的本质区别是「

当前会话加载了哪些工具插件

」。[⁶]

4.1 标准模式（Standard）——日常默认

加载完整工具组合：文件编辑、Shell 命令、网页搜索、子 Agent、Skills 技能、计划管理等，覆盖日常开发的全部需求。

绝大多数情况用它就好。

4.2 PTC 模式（Programmatic Tool Calling，程序化工具调用）

普通模式下模型一步一步调工具，每步执行完才能决定下一步。PTC 模式下，

模型直接生成一段 TypeScript 代码，把多步工具调用串联起来一次性执行

。

适合步骤多但逻辑清晰的任务，例如：批量重命名文件、跑一整套自动化流程。效率比逐步确认高得多，流程也更可控。

4.3 极简模式（Minimal）——模型基准测试

只保留

一个持久 Bash + 一个文件编辑器

两件最基础的工具，系统提示词固定为一句简单的“你是一个有帮助的软件工程助手”，同时去掉上下文压缩等额外能力。

用途：在最小环境下对比不同模型的“裸 Agent 能力”。

DeepSeek V4-Flash 公开的 Code Agent 评测用的就是这个模式。

普通用户日常基本用不到。[⁷]

4.4 创造模式（Creative）——让 Agent 改造自己

最能体现 DSH 特色的模式。它继承标准模式的全部能力，还能：

检查当前运行时有哪些插件在跑；
在内存中试验新的插件组合；
现场创建新插件、新模式预设并挂载到正在运行的流程中。

打个比方：

Agent 发现自己没有扳手，于是现场造一把扳手装到手上，然后继续工作。

[⁸]

你可以这样下需求：

“帮我做一个只允许读代码、不允许改文件、专门负责安全审计的模式。”

“帮我做一个接入公司内部搜索、固定使用某个模型、拥有三种专属 Skills 的研究 Agent。”

五、能接其他模型吗？怎么接？

当然可以。

DSH 本身就是一个模型中立框架，不会把能力绑死在某一家模型服务上。官方已经支持接入近 40 家模型提供方，覆盖 OpenAI（GPT 系列）、Anthropic（Claude 系列）、Google（Gemini 系列）、Kimi 等国产模型，以及任意 OpenAI / Anthropic 兼容端点。更关键的是，模型适配器本来就是可替换的插件，换接方式并不受限。[⁹][¹⁰]

5.1 方式一：Web UI 图形化配置（推荐）

打开

设置 → 模型 → 添加自定义提供方

，填写：

字段	说明
Provider ID	小写字母，永久不可改，如 `my-openai`。要改名只能删除旧的、新建一个
显示名称	自定义，方便识别
API 地址（Base URL）	如 `https://api.openai.com/v1`
API 协议	OpenAI Chat Completions / OpenAI Responses / Anthropic Messages，按服务商兼容的协议选
API Key	对应服务的凭据
模型列表	点「获取可用模型」自动拉取，或手动填写模型 ID

配置完成后，在会话输入框右下角即可切换模型。模型变更无需重启 dsh，下一次请求自动生效。

5.2 方式二：编辑 settings.yaml（适合 CI/CD 与自动化部署）

配置文件路径为 $DSH_HOME/settings.yaml（模型配置页面有「打开配置文件」入口）。示例：

llm-pi-ai:
  providers:
    ark-plan:                                  # Provider ID
      displayName: ark-plan
      apiKeyEnv: CODING_PLAN_API_KEY           # 从环境变量读 Key，避免明文落盘
      api: openai-responses                    # 协议：openai-completions / openai-responses / anthropic-messages
      baseURL: https://ark.cn-beijing.volces.com/api/coding/v3
      models:
        - id: doubao-seed-2.1-turbo
          name: doubao-seed-2.1-turbo
          input: [text, image]                 # 可选：声明支持图片输入

5.3 方式三：环境变量（Python SDK / 本地代&理场景）

export DEEPSEEK_API_KEY=你的Key
export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1   # 你的 OpenAI 兼容端点
export DSH_MODEL=deepseek-v4-flash                  # 指定模型

5.4 典型接入场景

① 接本地开源模型

：用 vLLM、Ollama、SGLang 等在本地起一个 OpenAI 兼容服务，把 baseURL 指向本地地址（如 http://127.0.0.1:8000/v1）即可，等于白嫖本地算力跑 Agent。

② 接多云平台 Coding Plan

：例如火山引擎方舟 Coding Plan，按官方文档在 DeepSeek 卡片里选「自定义设置」，填入：

API 地址：https://ark.cn-beijing.volces.com/api/coding/v3（OpenAI 协议）或 https://ark.cn-beijing.volces.com/api/coding（Anthropic 协议）
API 密钥：Coding Plan 的 Key
模型：deepseek-v4-pro、kimi-k2.7-code、glm-5.3、doubao-seed-2.1-turbo 等

③ 一套框架多模型对比

：利用极简模式固定工具环境，分别挂不同模型跑同一批任务，做公平的 Agent 能力基准测试——这正是 DSH 的设计初衷之一。

六、好用用法与实战技巧

6.1 Headless 模式：脚本与 CI 利器

一次性运行一个任务，打印最终答案后自动退出：

dsh --profile headless "修复当前仓库中失败的测试并提交说明"

适合：

Shell 脚本批量任务（循环调用多次 headless 命令）；
CI/CD 流水线（代码审查、测试诊断、自动修复）；
定时任务（配合 cron 做每日仓库巡检）。

批量任务更高效的方案是用

Python SDK 在同一进程内多次调用

，内置运行时复用，省去反复启动的开销。需要延续上下文时复用同一个 session ID（Bash 进程、工作目录、Shell 变量都会保留）；独立任务则用新 session ID。

还有官方社区维护的

GitHub Action

（deepseek-harness-action），可直接在 PR 评审、CI 诊断、issue 自动转 PR 等场景调用 Harness。[¹²]

6.2 插件生态：站在社区肩膀上

社区插件已经非常丰富（GitHub 上搜 dsh-plugin 话题可发现）。安装方式：

dsh plugin --profile web add "github:owner/repo#ref"

dsh plugin 会把包管理操作转发给 pnpm，支持 npm、Git/GitHub、本地路径等包规格。安装/更新插件后需重启对应 profile。管理面板在

设置 → 插件

。

几类值得关注的社区插件：

上下文可视化
：dsh-context（看上下文窗口由什么组成、怎么演化）、context-vista（右侧悬浮面板实时显示 token 用量与成本）、dsh-context-doctor（审计每次请求的 token 开销并给出裁剪建议）；
上下文压缩
：dsh-compressor（压缩工具输出，可省约 20% 上下文）、billion-context-dsh（模型自主决定何时压缩什么）；
工程增强
：dsh-tool-git（结构化 Git 工具 + 危险命令护栏）、dsh-repo-setup（只读扫描仓库并推荐插件与 MCP 配置）；
知识管理
：dsh-bookmarks（给 Agent 回复加书签、跨会话搜索、一键导出 Markdown）、dsh-deepread（深度阅读助手，五种模式）。

6.3 Trajectory 视图：完整的运行轨迹

Agent 在运行过程中接触到的所有内容——包括系统提示词、思维链、工具调用及其结果、子 Agent 调度，以及上下文注入——都会被完整写入一份仅追加的会话日志。借助 Trajectory 视图，还能按来源逐项追踪，

工具究竟改了哪些文件、执行过什么命令，基本都能看得清清楚楚

，无论是排查问题还是审计行为，都会省事很多。与此同时，会话还支持恢复、分叉和回放，这些能力背后共享的是同一条事件流。

6.4 子 Agent 与任务委派

标准模式下 Agent 可以把复杂任务拆分并委派给子 Agent 并行处理，主 Agent 维护整体计划。给它一个明确的复杂目标（如“定位并修复当前测试失败的问题”），它会自动拆解执行——但涉及写操作时仍需人工监督。

6.5 Profile 与配置分层

web 与 headless 两个 profile 首次使用时从内置模板自动初始化；其余 profile 通过 dsh plugin 创建。
启动参数在前、应用参数在后，例如 dsh --profile web --port 8080。
用 dsh --profile web --dump-config 查看实际启动的完整配置树，--dump-default-config 查看默认配置（不含用户 patch）——调试插件组合时非常实用。

6.6 常用命令速查

命令	作用
`npx @deepseek-ai/dsh web`	启动 Web UI（等价于 `--profile web`）
`dsh --profile headless "任务"`	一次性运行任务，打印最终答案后退出
`dsh plugin --profile`	管理某 profile 的插件
`dsh --profile web --dump-config`	查看实际启动的完整配置树
`dsh --profile web --dump-default-config`	查看默认配置树
`pip install deepseek-harness-sdk`	安装 Python SDK（自带运行时）

七、注意事项与避坑指南

它是开发者预览版。
官方明确警告会有破坏性变更，接口和插件配置方式随时可能调整。
不要直接用于生产关键路径
，升级时注意兼容性。
项目务必用 Git 管理。
无论用 DSH 还是其他 Agent 工具，都要养成版本管理习惯——Agent 改错代码时能快速回退。
先在练习目录里试。
单独准备一个测试工作区，熟悉权限审批和文件修改行为后再上真实项目。涉及企业仓库、生产服务器、敏感数据时尤其谨慎。
保护好 API Key。
不要贴到公开文章、GitHub 仓库、群聊或截图里；怀疑泄露及时去平台吊销。配置文件里建议用 apiKeyEnv 从环境变量读取，避免明文落盘。
已知 bug：空 Bash 循环。
当前版本 Agent 偶尔会反复执行空 Bash 命令卡住，遇到时手动中断（Web UI 停止按钮 / SDK 层中断）再重新发起任务即可，官方在修复中。
启动失败排查顺序
：Node.js 版本 → 网络（内网需配镜像）→ 终端环境变量是否刷新（Windows 装完 Node 后要重开终端）。
SDK 沙箱示例的权限很宽。
官方示例组合允许 Bash 和编辑器修改进程可见的任何文件，
只在可丢弃的 checkout 或容器里这么跑
，生产环境换更严格的权限策略。

八、常见问题（FAQ）

Q：DeepSeek Harness 收费吗？

A：框架本身完全免费（MIT 开源），但模型调用费用由你接入的供应商按各自定价收取。

Q：只能用 DeepSeek 的模型吗？

A：不是。支持 OpenAI、Anthropic、Gemini、Kimi 等近 40 家提供方和任意 OpenAI / Anthropic 兼容端点，详见第五节。

Q：和 Claude Code、Codex CLI 有什么区别？

A：那些是面向终端用户的成品 Agent 应用；DSH 是可替换、可重组的底座框架，每一层（模型、工具、UI、存储甚至主循环）都能换成自己的插件。

Q：关闭终端后服务还在吗？

A：一般会停止。需要常驻可考虑全局安装 + 进程管理工具，或部署到服务器。

Q：

$DSH_HOME

默认在哪？

A：官方文档未明确，通常为 ~/.dsh 或系统约定目录，可通过 DSH_HOME 环境变量显式指定（容器环境推荐这样做）。

Q：如何参与生态？

A：自研插件开源后给仓库加 dsh-plugin 话题标签即可被检索收录；bug 和建议去 GitHub Discussions 提交。

DeepSeek Harness(DSH)的详细使用指南

未来会有破坏性变更（breaking changes）

一、DeepSeek Harness 是什么？

1.1 它不是什么

它不是一个新模型

它不只是 DeepSeek API 的套壳聊天页面

1.2 它是什么

发动机

整辆车的底盘和控制系统

1.3 核心设计：一切皆插件（Everything is a Plugin）

Cordis

所有能力都是插件

可自由重组的底座框架

1.4 关键特性一览

二、安装

2.1 环境要求

建议 v22.19 及以上，或 v24 系列

不支持 Windows 原生

国内用户提速

2.2 方式一：npm 一键安装（推荐，最快体验）

小技巧

调用命令时所在的目录

2.3 方式二：源码安装（开发插件 / 二次开发）

2.4 方式三：Python SDK（程序化调用）

SDK 自带运行时，不需要系统安装 Node.js。

2.5 三种方式怎么选

三、首次配置与第一个任务

三步

第 1 步：配置模型

设置 → 模型

模型路由立即可用，无需重启服务器。

第 2 步：选择工作区

选中工作区之前，会话输入框是锁定的

第 3 步：发送第一个任务

涉及写操作或超出权限策略的动作时，Web UI 会先弹出审批

四、四种运行模式

当前会话加载了哪些工具插件

4.1 标准模式（Standard）——日常默认

绝大多数情况用它就好。

4.2 PTC 模式（Programmatic Tool Calling，程序化工具调用）

模型直接生成一段 TypeScript 代码，把多步工具调用串联起来一次性执行

4.3 极简模式（Minimal）——模型基准测试

一个持久 Bash + 一个文件编辑器

DeepSeek V4-Flash 公开的 Code Agent 评测用的就是这个模式。

4.4 创造模式（Creative）——让 Agent 改造自己

Agent 发现自己没有扳手，于是现场造一把扳手装到手上，然后继续工作。

五、能接其他模型吗？怎么接？

当然可以。

5.1 方式一：Web UI 图形化配置（推荐）

设置 → 模型 → 添加自定义提供方

永久不可改

5.2 方式二：编辑 settings.yaml（适合 CI/CD 与自动化部署）

5.3 方式三：环境变量（Python SDK / 本地代&理场景）

5.4 典型接入场景

① 接本地开源模型

② 接多云平台 Coding Plan

③ 一套框架多模型对比

六、好用用法与实战技巧

6.1 Headless 模式：脚本与 CI 利器

Python SDK 在同一进程内多次调用

GitHub Action

6.2 插件生态：站在社区肩膀上

设置 → 插件

上下文可视化

上下文压缩

工程增强

知识管理

6.3 Trajectory 视图：完整的运行轨迹

工具究竟改了哪些文件、执行过什么命令，基本都能看得清清楚楚

6.4 子 Agent 与任务委派

6.5 Profile 与配置分层

6.6 常用命令速查

七、注意事项与避坑指南

它是开发者预览版。

不要直接用于生产关键路径

项目务必用 Git 管理。

先在练习目录里试。

保护好 API Key。

已知 bug：空 Bash 循环。

启动失败排查顺序