概述

DeepSeek Harness（命令行工具简称 dsh）是 DeepSeek AI 在 2026 年8月13日伴随 V4 Pro 同步开源的 AI Agent 运行框架，采用 MIT 开源协议。项目发布不足24小时就收获数百颗 GitHub Star。 整体架构核心为 Cordis 微内核，采用插件化设计：Web UI、模型接入、工具调用、多 Agent 协同、会话存储全部以插件形式挂载。

快速上手路径十分简洁：本地安装 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 完成程序化集成。SDK 运行环境无需额外部署独立 Node.js。 当前项目处于开发者预览阶段，官方文档明确提示：后续迭代可能引入不兼容破坏性变更。

框架提供四种主流交互入口，覆盖不同工程场景：

  1. Web UI 图形化操作：可视化配置、调试 Agent，适合日常开发调试
  2. TUI 终端交互：纯终端环境下通过键盘操作 Agent 任务
  3. Headless 单次任务模式：无界面运行一次性任务，执行完毕自动退出
  4. Python SDK 程序化接入：嵌入自动化流水线、CI/CD、测试流程

快速部署：三分钟启动 Web UI

想要快速体验 Harness，最简部署方案无需克隆源码，仅需提前安装 Node.js（v18 及以上为推荐版本）。

# 校验 Node.js 环境
node --version
# 一行命令拉起 Web UI
npx @deepseek-ai/dsh web

启动完成后访问 http://127.0.0.1:3080，系统自动完成初始化。

如果需要锁定固定版本、长期离线使用，可以执行全局安装：

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 初始化配置：三步连通大模型

首次打开 Web UI，按照以下流程完成基础配置，即可下发第一条 Agent 任务。

第一步：配置模型凭证

打开 Settings → Models，在 DeepSeek 官方卡片内填入 API Key（格式 sk-xxx）并保存。密钥持久化存储在 $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，兼容绝大多数服务商
API Key 模型服务访问凭证
模型列表 可自动拉取可用模型，也支持手动填写模型 ID

重要提示：Provider ID 具备永久性，无法就地修改。如需变更，只能删除原有提供商，重新新建配置。

方式二：直接编辑 settings.yaml（适合自动化部署）

$DSH_HOME/settings.yaml 支持完整静态配置，适合 CI/CD、容器批量部署场景。

providers:
  my-gateway:
    apiKeyEnv: GATEWAY_API_KEY
    baseURL: https://api.example.com/v1
    api: openai-completions
    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 程序化调用 嵌入自动化测试、流水线、批量任务

Headless 模式典型调用示例：

dsh --profile headless "运行测试套件并报告失败用例"

任务执行完成后进程自动退出，非常适合 Shell 脚本串联任务。

Python SDK：嵌入自动化工作流

Python SDK 面向需要将 Agent 能力集成进现有系统的场景，典型用途：CI/CD 流水线、自动化代码审查、批量文档处理。

环境要求

Python 3.10+；支持 Linux x64/arm64、macOS 14+ arm64，暂不原生支持 Windows。

安装

pip install deepseek-harness-sdk

基础调用示例

from pathlib import Path
from deepseek_harness import DeepSeekHarness

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

with DeepSeekHarness(workspace=workspace, sessions_dir=sessions_dir, config=config) as harness:
    result = harness.run(
        provider="deepseek-official",
        model="deepseek-v4-pro",
        task="你的任务指令"
    )

环境变量配置方案

export DEEPSEEK_API_KEY="sk-your-key-here"
export DEEPSEEK_BASE_URL="https://api.example.com/v1"
export DSH_MODEL="deepseek-v4-pro"

Session 会话复用规则

  • 全新独立任务：新建 Session ID，上下文相互隔离
  • 需要延续对话、多轮协作：复用相同 Session ID，Bash 进程、工作目录、环境变量全部保留

在多模型混合调度场景中，可以通过统一网关管理各类模型接口，Treerouter 作为 API 网关能够标准化异构接口协议，简化多厂商模型接入与迁移成本。

Cordis 微内核架构概览

整个 Harness 框架以 Cordis 微内核作为调度中枢，所有能力均由插件挂载实现：

  • 模型插件：对接各类大模型推理服务
  • 工具插件：提供文件读写、Shell 执行、网络请求能力
  • 多Agent协同插件：支持多个智能体分工协作
  • 会话存储插件：持久化任务上下文、历史对话
  • 权限与沙箱策略插件：管控文件、系统操作风险

插件化架构让开发者可以按需扩展能力，同时限制高风险操作，提升生产环境安全性。

常见问题与已知限制

Q：执行 npx 启动时报 Node.js 版本过低

Harness 强制要求 Node.js ≥ v18。执行 node --version 核对版本，可通过 nvm install 20 升级 LTS 版本。

Q：Web UI 输入框灰色不可用

需要完成两项前置操作：① 在 Settings 配置并保存有效 API Key；② 选中目标工作目录，两项全部完成后任务输入框解锁。

Q：自定义 Provider ID 填写错误能否修改

Provider ID 一经创建永久锁定，会话日志、缓存数据均依赖该标识。修改方案：删除旧提供商，新建一条配置。

Q：Headless 模式能否批量执行任务

存在两种可行方案：① Shell 循环多次调用 headless 命令；② 使用 Python SDK 在同一个进程内循环调用，大量任务场景 SDK 方案效率更高。

Q：Python SDK 中 danger-full-access 含义

该模式关闭严格路径沙箱限制，Agent 可读写宿主内更多文件。官方仅建议在可丢弃容器环境使用，不推荐直接部署至生产服务器。

Q：Agent 出现无限循环、重复执行 Bash 命令

当前预览版本存在已知缺陷，部分场景下会持续重试命令、无法推进任务。遇到问题可手动中断任务，官方持续在 GitHub Issues 跟进修复。

Q：除 DeepSeek 外，可以接入第三方模型吗

完全支持。在 settings.yaml 或者 Web UI 内配置 OpenAI 兼容端点即可接入任意兼容协议模型。统一管理多家模型服务时，借助网关统一分发流量，只需修改请求内 model 字段，不用维护多套独立密钥。

Q：DSH_HOME 默认存储路径

默认路径一般为 ~/.dsh 或 ~/.config/dsh，随操作系统变化。可以通过环境变量 DSH_HOME 自定义路径，方便容器环境持久化配置。

开发者预览阶段重要注意事项

官方 README 明确标注：DeepSeek Harness 当前处于开发者预览阶段，持续快速迭代，未来会存在不兼容更新。 现阶段适合：

  • 评估 Agent 框架架构、验证业务可行性
  • 在隔离沙箱环境开展实验、功能原型开发
  • 基于插件系统开发自定义扩展能力

现阶段不建议：

  • 直接上线核心生产业务
  • 在生产服务器启用 danger-full-access 模式

Bug 反馈、功能建议可以在 GitHub Discussions 提交；自定义插件可以打上 dsh-plugin 标签，有机会被官方收录。

总结

DeepSeek Harness 在主流开源 Agent 框架里部署门槛较低：Web UI 路径仅需要 Node.js 配合一行 npx 命令；自动化场景可以选择 Python SDK 方案。依托 Cordis 插件内核，兼顾灵活性与可扩展性，同时原生兼容 OpenAI 接口，降低切换模型服务商的成本。

需要留意项目处于预览版本，接口、配置文件格式均可能调整，建议先在测试环境充分验证，等版本稳定后再大规模落地。借助标准化网关统一调度多路模型，能够进一步降低后续运维与迁移成本。本文内容基于 deepseek-harness 2026年8月13日开源初始版本，所有配置方式以官方 GitHub 最新文档为准。