首页
使用教程
插件市场
下载安装
GitHub
English
入门教程

快速上手

系统化掌握 DeepSeek Harness 基础环境依赖、npx 零配置启动 Web UI、源码克隆构建、Python SDK 安装与 API 密钥配置流程。

DeepSeek Harness 是深度求索（DeepSeek）开源的生产级 AI Agent 执行中枢与脚手架。它践行 “Agent = Model + Harness” 范式，为大语言模型提供安全命令执行、精细代码重构工具契约、上下文流转以及基于 Cordis 的全插件化微内核底座。

本文将详解从环境依赖准备、4 种安装启动方式（npx 极速启动、源码克隆、Python SDK 与第三方客户端），到模型 API 密钥配置的完整起步流程。

系统前置环境准备

在安装与运行 DeepSeek Harness 之前，请确保宿主机器已满足以下基础依赖：

依赖组件最低版本要求用途说明
Node.js>= 18.0.0 (推荐 LTS 20+)运行 Harness Web 控制台与 Cordis 插件微内核
npm / pnpm>= 9.0.0管理生态依赖包与 CLI 脚手架
Git任意现代版本克隆官方仓库及社区插件
Python (可选)>= 3.10仅在使用 Python SDK 或 DSBench 评测套件时需要
Docker (可选)任意现代版本启用指令物理容器沙箱时使用

快速检查环境

bash
node -v
npm -v
git --version

方式一：npx 零配置极速启动 Web UI (官方推荐)

对于绝大多数开发者与技术研究人员，无需手动编译源码或搭建本地依赖，推荐使用官方发布的 @deepseek-ai/dsh 命令行工具一键拉起可视化 Web UI。

启动 Web 交互控制台

在终端中执行以下命令：

bash
npx @deepseek-ai/dsh web
  • 该命令会自动从 npm 镜像拉取最新的运行时脚手架；
  • 启动成功后，终端将输出本地服务监听地址，通常为： 
    [DeepSeek Harness] Web UI started successfully!
➜ Local:   http://localhost:5173/
➜ Network: http://192.168.1.10:5173/

访问控制台

在浏览器中打开 http://localhost:5173/，即可直接进入交互式 Agent 工作台。

方式二：GitHub 源码克隆与本地二次开发

如果你需要为 Harness 开发自定义 Cordis 插件、扩充 Tool-Contract 契约、调试底层 Fiber 生命周期或接入企业内部私有网关，建议采用源码部署模式。

克隆官方代码库

bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

安装依赖并编译构建

bash
# 推荐使用 pnpm 或 npm 进行完整依赖安装
npm install

# 启动本地开发热重载服务器
npm run dev

方式三：Python SDK 程序化集成

对于习惯使用 Python 进行算法研究、自动化评测流水线或构建数据管道的团队，可直接通过 PyPI 安装官方 SDK：

bash
# 创建并激活 Python 虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows 用户运行: .venv\Scripts\activate

# 安装官方 SDK
pip install deepseek-harness-sdk

在 Python 脚本中实例化智能体

python
from deepseek_harness import AgentHarness, AgentConfig

# 初始化 Harness 客户端实例
harness = AgentHarness(
    config=AgentConfig(
        model="deepseek-chat",
        api_key="your_deepseek_api_key",
        mode="standard"
    )
)

# 发起多轮交互或代码工程重构任务
response = harness.execute_prompt("分析当前目录下的代码结构并输出依赖拓扑图")
print(response.content)

方式四：第三方桌面客户端安装 (Windows & macOS)

对于不希望配置 Node.js 命令行环境、追求开箱即用原生桌面体验的非前端开发者或产品经理，可选择安装打包好的第三方桌面客户端应用：

  • 图形化操作界面：集成开箱即用的 Web UI 与系统托盘支持，无需通过终端维持后台进程；
  • 本地环境内置：自带沙箱运行容器与轻量化运行时，避免全局 Node.js 环境版本冲突；
  • 快捷模型与密钥管理：支持可视化添加 DeepSeek、OpenAI 及本地 Ollama 密钥，支持配置导入与导出。

获取安装包

你可以前往本站 下载中心 获取对应操作系统的独立安装包：

  • Windows 客户端：下载 .exe 安装程序，双击按提示完成安装；
  • macOS 客户端：下载 .dmg 镜像包，拖拽至 Applications 应用程序目录即可启动。

配置模型提供方与 API 密钥

启动 Web UI 或客户端后，首要任务是配置推理大脑（LLM Provider）。

在 Web UI 界面中配置

  1. 点击左下角 Settings (设置) -> Providers (模型提供商)；
  2. 选择 DeepSeek 官方直连（或选择 OpenAI / Anthropic / Local Ollama 兼容端点）；
  3. 填入你的 API Key：
    • DeepSeek API Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
    • Base URL: https://api.deepseek.com (若使用第三方中继或本地网关可自定义)
  4. 设定默认模型：
    • DeepSeek-V3 (deepseek-chat)：适合高吞吐日常编码与指令解析；
    • DeepSeek-R1 (deepseek-reasoner)：适合复杂多步逻辑推导、数学证明与代码架构审计。

通过环境变量或 cordis.yml 声明式注入

如果你通过命令行或 Docker 启动，可以通过 .env 环境变量或 cordis.yml 注入凭证：

yaml
# cordis.yml 配置文件示例
plugins:
  # 官方大语言模型适配网桥
  '@deepseek-ai/dsh-plugin-llm-adapter':
    provider: 'deepseek'
    apiKey: 'env(DEEPSEEK_API_KEY)'
    defaultModel: 'deepseek-chat'
    temperature: 0.0

  # 启用标准终端执行工具
  '@deepseek-ai/dsh-plugin-tool-bash':
    timeout: 30000
    allowRoot: false

常用预设运行模式切换

DeepSeek Harness 内置了 4 种针对不同场景优化的运行模式，启动时可通过 --mode 自由切换：

bash
# Standard 标准模式 (默认，包含代码阅读、Diff 替换与安全终端)
npx @deepseek-ai/dsh --mode standard

# PTC 模式 (TypeScript Code Mode，大模型通过编写 TS 代码精确编排工具)
npx @deepseek-ai/dsh --mode ptc

# Minimal 极简双工具模式 (零噪音，专为 DSBench / LM-Eval 基准测试设计)
npx @deepseek-ai/dsh --mode minimal

# Creative 试验模式 (纯内存模式，方便实时调试 Cordis 插件生命周期)
npx @deepseek-ai/dsh --mode creative

验证安装与首个会话任务

完成上述配置后，在 Web UI 或终端执行首个验证指令：

  • 输入指令：创建一个简单的 Node.js 命令行工具，并为其编写自动化单元测试；
  • 观察执行流程：
    • Reasoning (思考)：模型制定任务分解计划与文件目录设计；
    • Tool Execution (工具调度)：Harness 安全调用文件写入工具创建源码与测试用例；
    • Self-Correction (自愈闭环)：自动在终端运行 npm test，若测试失败模型将提取错误日志自动纠错；
    • Trajectory Trace (轨迹审计)：点击右上角 Trajectory 面板，可以实时追溯每一次 Tool 输入输出与 Token 消耗。

常见问题与排错

Q1: 运行 npx @deepseek-ai/dsh web 提示端口 5173 被占用怎么办？

解答：Harness Web UI 默认监听 5173 端口。你可以通过 --port 参数指定新端口启动，例如：

bash
npx @deepseek-ai/dsh web --port 8080

或者在 macOS/Linux 终端通过 lsof -i :5173 查找占用进程并释放。

Q2: 为什么执行终端指令时未开启 Docker 容器沙箱？

解答：默认 Standard 模式使用受限的本地宿主子进程环境以保障极速响应。如需开启物理级 Docker 隔离，请确保本地已启动 Docker Desktop，并在启动命令中添加 --sandbox docker 参数，或在 cordis.yml 中启用 @deepseek-ai/dsh-plugin-sandbox-docker 插件。

Q3: 离线或企业专网内网环境如何部署？

解答：建议采用方式二（GitHub 源码克隆部署）。在联网环境运行 npm install 下载依赖缓存后，将整包分发至离线内网服务器，通过 npm run dev 启动，并在 Web UI 设置中将 Base URL 指向企业内部的私有大模型网关或本地 Ollama 服务。

Q4: 为什么执行多轮代码编辑任务时 Token 消耗远低于其他 Agent？

解答：DeepSeek Harness 针对 DeepSeek 架构底层进行了原生 Prefix Cache 前缀对齐优化。系统将 Tool 契约与历史执行轨迹严格按照仅追加（Append-Only）规则组织，使得上下文在多轮决策中的前缀缓存命中率高达 99.93%，有效降低了 80% 以上的重复计算 Token 消耗。