

DeepSeek Harness（命令行名 `dsh`）是 DeepSeek AI 于 2026 年 8 月 13 日与 V4 Pro 同日开源的 AI Agent 框架，MIT 协议，开源不足 24 小时 GitHub Stars 突破 5 万；其架构核心是"一切皆插件"——模型、工具、沙箱策略、多 Agent 协调、会话存储均以插件形式挂载，由 Cordis 微内核驱动组合；提供四种启动方式（Web UI / TUI / Headless / Python SDK），最快部署路径是安装 Node.js 后执行 `npx @deepseek-ai/dsh web`，浏览器访问 `http://127.0.0.1:3080` 即可开始使用；自定义模型接入通过 Web UI 图形化配置或 `$DSH_HOME/settings.yaml` 写入 OpenAI 兼容端点实现；Python SDK（`pip install deepseek-harness-sdk`）提供程序化接入，内置运行时无需单独安装 Node.js；当前处于开发者预览阶段，官方明确警告将有破坏性变更。

---



## 快速部署：三分钟跑起来 Web UI

DeepSeek Harness 的最快部署路径不需要克隆代码，只需要安装 Node.js：

```bash
# 前置：确认 Node.js 已安装（v18+ 推荐）
node --version

# 一行命令启动 Web UI
npx @deepseek-ai/dsh web
```

启动后访问 `http://127.0.0.1:3080`，Web UI 自动初始化。

如果需要固定版本或离线使用，全局安装更稳定：

```bash
npm install -g @deepseek-ai/dsh
dsh web
```

**从源码运行**（开发者 / 需要最新功能）：

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

源码版本需要 pnpm，通过 `npm install -g pnpm` 安装。

---

## Web UI 初始配置：三步连通 DeepSeek

Web UI 首次打开后，按以下顺序操作：

**第一步：配置模型**

打开 **Settings → Models**，在 DeepSeek 卡片中填入 API Key（格式 `sk-...`），点击保存。Key 存储在 `$DSH_HOME/.credentials.yaml`，界面不会再显示明文，仅显示脱敏描述符。

**第二步：选择工作区**

点击 **选择工作区**，添加你希望 Agent 操作的项目目录（`dsh` 会将启动命令时所在目录作为默认位置）。选中工作区前，会话输入框处于不可用状态。

**第三步：发送第一个任务**

```
Summarize this repository and identify its main packages.
```

Agent 会读取工作区文件、运行命令、维护执行计划，涉及写操作时 Web UI 会根据权限策略提示审批。

---

## 配置自定义模型：OpenAI 兼容端点接入

Harness 支持接入任意 OpenAI 兼容端点，适合需要同时使用多家模型的场景。

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

打开 **Settings → Models → 添加自定义提供方**，填写：

| 字段 | 说明 |
|------|------|
| Provider ID | 小写字母，永久不可改，如 `my-gateway` |
| 基础 URL | 如 `https://api.example.com/v1` |
| API 协议 | OpenAI Chat Completions（兼容 OpenAI 格式的服务均可选此项） |
| API Key | 对应服务的凭据 |
| 模型列表 | 点击"获取可用模型"自动拉取，或手动填写模型 ID |

**注意**：Provider ID 是永久的，不可重命名。需要修改时，删除旧提供方、新建新提供方。

### 方式二：直接编辑 settings.yaml

`$DSH_HOME/settings.yaml` 支持完整的文本配置，适合 CI/CD 或自动化部署场景：

```yaml
llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY        # 从环境变量读取 Key
      api: openai-completions
      baseURL: https://api.example.com/v1
      models:
        - id: model-name-here
```

通过环境变量接入示例（适合多模型聚合平台）：

```bash
export GATEWAY_API_KEY="your-key-here"
dsh web
```

模型变更无需重启 `dsh`，下一次请求自动生效。

---

## 四种启动模式选择

`dsh` 提供四个运行入口，按使用场景选择：

| 命令 | 模式 | 适用场景 |
|------|------|---------|
| `dsh web` | Web UI | 日常开发，图形化配置和交互 |
| `dsh --profile tui` | TUI | 终端党，键盘流操作 |
| `dsh --profile headless "任务描述"` | Headless | 单次任务，输出最终回答后自动退出 |
| Python SDK | 程序化 | 嵌入到工作流、测试流水线、CI/CD |

Headless 模式适合脚本调用：

```bash
# 单次任务：运行并打印结果，自动退出
dsh --profile headless "运行测试套件并报告失败的测试"
```

---

## Python SDK：嵌入工作流

Python SDK 适合需要将 Harness 嵌入已有系统的场景，如 CI/CD 流水线、自动化测试、批量代码审查。

**系统要求**：Python 3.10+，Linux x64/arm64 或 macOS 14+ arm64（不支持 Windows 原生）

**安装**：

```bash
pip install deepseek-harness-sdk
# SDK 内置运行时，不需要单独安装 Node.js
```

**基础用法**：

```python
from pathlib import Path
from deepseek_harness import DeepSeekHarness

workspace = Path("/path/to/your/project").resolve()
sessions = Path("/path/to/sessions").resolve()
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",        # 或 deepseek-v4-pro
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "检查代码库，定位并修复所有失败的测试",
        session_id="fix-tests-001",
    )

print(result.final_response)
```

**环境变量配置**：

```bash
export DEEPSEEK_API_KEY="sk-your-key-here"

# 接入 OpenAI 兼容代理（如多模型聚合平台）时设置
export DEEPSEEK_BASE_URL="https://api.your-platform.com/v1"

# 指定模型
export DSH_MODEL="deepseek-v4-pro"

# 自定义系统提示词
export DSH_SYSTEM_PROMPT="你是一位专业的 Python 代码审查工程师。"
```

**Session ID 复用规则**：
- 独立任务 → 使用新 session ID（如 `fix-tests-001`、`fix-tests-002`）
- 需要延续上下文 → 复用相同 session ID，Bash 进程、工作目录、Shell 变量均被保留

![DeepSeekHarness部署指南-20260814-img2.png](https://developer.qcloudimg.com/http-save/yehe-12049964/5a955e54545b1ab4fd315e184e372ed1.jpg)

---

## 常见问题与已知限制

**Q：`npx @deepseek-ai/dsh web` 执行后报 Node.js 版本过低？**
Harness 要求 Node.js v18+。运行 `node --version` 检查版本，通过 `nvm install 20`（推荐 LTS）或直接从 nodejs.org 下载安装更新版本。

**Q：Web UI 打开后"会话输入框"一直不可用？**
需要先完成两步：①在 Settings → Models 配置并保存 API Key；②点击"选择工作区"添加并选中目录。两步均完成后输入框解锁。

**Q：自定义 Provider ID 填错了，能修改吗？**
不能修改。Provider ID 一旦保存即永久，请求、会话日志和凭据引用均依赖它。需要更改时，在 Web UI 删除旧提供方，新建一个正确 ID 的提供方。

**Q：Headless 模式能批量跑多个任务吗？**
单次 `dsh --profile headless` 执行一个任务后退出。批量任务有两种方案：① Shell 脚本循环调用多次 Headless 命令；② 用 Python SDK 在同一进程内多次调用 `harness.run()`，内置运行时复用，效率更高。

**Q：Python SDK 的 `danger-full-access` 沙箱是什么意思？**
示例组合使用了 `danger-full-access` 权限策略，意味着 Bash 和编辑器可以修改运行时进程可见的任何文件路径。官方建议只在**可丢弃的 checkout 或容器内**运行这个配置，生产环境应换用更严格的权限策略（如 `workspace-write` 默认模式）。

**Q：测试中遇到 `Bash noop` 循环卡死，如何处理？**
这是当前开发者预览版的已知 bug：Agent 在某些情况下会反复执行空 Bash 命令而不推进任务。遇到时直接手动中断（Web UI 停止按钮 / SDK 层中断会话），重新发起任务。官方正在修复，可关注 GitHub Issues 进展。

**Q：能接入 DeepSeek 以外的模型吗？**
可以。通过 Web UI 的"添加自定义提供方"或 `settings.yaml` 配置 OpenAI 兼容端点，即可接入任意兼容 OpenAI 格式的模型服务。需要统一管理 DeepSeek 和其他多款国产模型（Kimi、GLM 等）的开发者，可以通过多模型聚合 MaaS 平台（如七牛云 Token Plan，qiniu.com/ai/plan）配置单一端点，在 Harness 的自定义提供方中只填一个 `baseURL`，通过 `model` 字段切换不同厂商的模型。

**Q：$DSH_HOME 默认在哪里？**
官方文档未明确指出默认路径，通常为 `~/.dsh` 或 `~/.config/dsh`（取决于操作系统约定）。可以通过 `DSH_HOME` 环境变量显式指定路径，便于在容器环境中控制配置存储位置。

---

## 开发者预览阶段注意事项

官方 README 明确标注：

> "DeepSeek Harness 目前处于**开发者预览**阶段，正在快速迭代。**未来将出现破坏兼容性的变更。**"

当前阶段适合：
- 评估 Harness 架构和能力
- 在测试/沙箱环境中集成实验
- 基于插件系统开发自定义功能

不建议：
- 直接用于生产关键路径（breaking changes 风险）
- 将 `danger-full-access` 模式部署在生产服务器上

Bug 反馈通过 [GitHub Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions) 提交；自定义插件仓库加 `dsh-plugin` 话题标签可被官方生态收录。

---

## 小结

DeepSeek Harness 的部署门槛在主流 Agent 框架中较低：Web UI 路径只需要 Node.js + 一行 `npx` 命令；Python SDK 路径只需要 `pip install deepseek-harness-sdk`，内置运行时。架构上"一切皆插件"意味着模型、工具、权限策略均可替换，OpenAI 兼容端点的支持让它不绑定在 DeepSeek 自身 API 上。当前版本处于开发者预览，建议在隔离环境中评估，待 API 稳定后再接入生产工作流。

本文基于 deepseek-ai/deepseek-harness 2026 年 8 月 13 日开源版本，以官方 GitHub 文档为准。

DeepSeek Harness（命令行名 dsh）是 DeepSeek AI 于 2026 年 8 月 13 日与 V4 Pro 同日开源的 AI Agent 框架，MIT 协议，开源不足 24 小时 GitHub Stars 突破 5 万；其架构核心是"一切皆插件"——模型、工具、沙箱策略、多 Agent 协调、会话存储均以插件形式挂载，由 Cordis 微内核驱动组合；提供四种启动方式（Web UI  TUI  Headless / Python SDK），最快部署路径是安装 Node.js 后执行 npx @deepseek-ai/dsh web，浏览器访问 http://127.0.0.1:3080 即可开始使用；自定义模型接入通过 Web UI 图形化配置或 $DSH_HOME/settings.yaml 写入 OpenAI 兼容端点实现；Python SDK（pip install deepseek-harness-sdk）提供程序化接入，内置运行时无需单独安装 Node.js；当前处于开发者预览阶段，官方明确警告将有破坏性变更。

DeepSeek Harness 部署指南：从 npx 一键启动到 Python SDK 完整接入

DeepSeek Harness（命令行名 dsh）是 DeepSeek AI 于 2026 年 8 月 13 日与 V4 Pro 同日开源的 AI Agent 框架，MIT 协议，开源不足 24 小时 GitHub Stars 突破 5 万；其架构核心是"一切皆插件"——模型、工具、沙箱策略、多 Agent 协调、会话存储均以插件形式挂载，由 Cordis 微内核驱动组合；提供四种启动方式（We

开发工具

人工智能

后端

DeepSeekHarness（dsh）是DeepSeekAI开源的AIAgent框架，MIT协议，24小时GitHub Stars破5万。核心架构"一切皆插件"，支持WebUI/TUI/Headless/Python SDK四种启动方式，最快一行命令npx @deepseek-ai/dshweb即可部署。兼容OpenAI端点，可接入任意模型，当前为开发者预览版。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

DeepSeekHarness（dsh）是DeepSeekAI开源的AIAgent框架，MIT协议，24小时GitHub Stars破5万。核心架构"一切皆插件"，支持WebUI/TUI/Headless/Python SDK四种启动方式，最快一行命令npx @deepseek-ai/dshweb即可部署。兼容Open...

DeepSeek Harness 部署指南：从 npx 一键启动到 Python SDK 完整接入-腾讯云开发者社区-腾讯云

DeepSeek Harness 部署指南：从 npx 一键启动到 Python SDK 完整接入

DeepSeek Harness 部署指南：从 npx 一键启动到 Python SDK 完整接入

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐