发布日期：2026-08-14 | 数据来源：deepseek-ai/deepseek-harness 官方 GitHub 文档、53AI 首批实测 | 话题：DeepSeek Harness · dsh · Agent 部署 · Python SDK

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：

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

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

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

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

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

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

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 或自动化部署场景：

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

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

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 模式适合脚本调用：

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

Python SDK：嵌入工作流

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

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

安装：

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

基础用法：

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)

环境变量配置：

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 变量均被保留

常见问题与已知限制

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 提交；自定义插件仓库加 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 官方仓库：https://github.com/deepseek-ai/deepseek-harness

  • Web UI 用户指南：https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/guide/index.zh.md

  • 模型配置指南（含自定义端点）：https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/guide/providers.zh.md

  • 七牛云 Token Plan（多模型统一接入，可配置为 Harness 自定义端点）：https://qiniu.com/ai/plan