DeepSeek Harness（DSH）详细使用教程与操作指南

版本说明：本文基于 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 关键特性一览

二、安装

2.1 环境要求

先检查环境：

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 三种方式怎么选

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

无论哪种方式启动 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 图形化配置（推荐）

打开 设置 → 模型 → 添加自定义提供方，填写：

配置完成后，在会话输入框右下角即可切换模型。模型变更无需重启 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 常用命令速查

七、注意事项与避坑指南

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