摘要：DeepSeek Harness（简称 dsh）是 DeepSeek AI 开源的 Agent 运行时框架，基于 Cordis 插件架构，核心理念是“Everything is a Plugin”（一切皆插件）。本文详细介绍了 dsh 的安装部署、配置使用、四种运行模式、插件系统以及实用技巧，帮助开发者快速上手这一强大的 AI 开发工具。

一、环境准备

1.1 系统要求

项目	要求	说明
Node.js	v22 及以上（推荐 v24 LTS）	运行基础，必须安装
包管理器	npm（自带）或 pnpm	源码安装需 pnpm
Git	建议安装	源码安装及版本管理需要
API Key	DeepSeek 或其他兼容模型 Key	认证必需
操作系统	Windows / macOS / Linux	全平台支持

1.2 安装 Node.js

前往 nodejs.org 下载 LTS 版本，或使用 nvm 管理：

# macOS/Linux (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 24
nvm use 24
验证
node --version   # 应显示 v24.x.x
npm --version    # 应显示 10.x.x

⚠️ 国内用户建议：配置 npm 国内镜像加速下载

npm config set registry https://registry.npmmirror.com

1.3 获取 API Key

1. 访问 DeepSeek 开放平台
2. 注册账号 → 充值余额 → 创建 API Key
3. 复制以 sk- 开头的密钥，妥善保存（只显示一次）

🔐 安全提醒：API Key 是调用凭证，切勿贴到公开文章、GitHub、群聊或截图中。如怀疑泄露，立即到平台作废重建。

二、安装方式

方式一：npx 一键启动（推荐，最快）

无需全局安装，一条命令直接运行：

npx @deepseek-ai/dsh web

• 首次运行会自动下载依赖包，按提示输入 y 确认
• 等待几秒钟后，终端显示 dsh web: 及本地地址
• 默认服务地址：http://127.0.0.1:3080
• 浏览器打开该地址即可使用

方式二：全局安装

适合需要频繁使用 dsh 命令的场景：

# 安装
npm install -g @deepseek-ai/dsh
验证
dsh --version
启动 Web UI
dsh web

方式三：源码安装（二次开发/修改配置）

适合需要修改源码、开发插件或深度定制的用户：

# 1. 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
2. 安装依赖（必须装 pnpm）
pnpm install
3. 构建（不要省略！）
pnpm run build
4. 启动
pnpm dsh web

⚠️ pnpm run build 必须执行，否则 Web 页面会缺少构建产物，导致界面异常。

方式四：Docker 部署（社区版）

适合服务器部署或隔离环境：

# 使用 Docker Compose
git clone https://github.com/AlliotTech/deepseek-harness-docker.git
cd deepseek-harness-docker
cp .env.example .env
# 编辑 .env 填入 DEEPSEEK_API_KEY
docker compose pull
docker compose up -d
或直接运行
docker run --rm -it 
--name deepseek-harness
-p 127.0.0.1:3080:3080
-e DEEPSEEK_API_KEY
-v deepseek-harness-home:/home/node/.dsh
-v "$PWD:/workspace"
alliot/deepseek-harness:0.1.0-rc.6.2

三、首次配置

3.1 配置 API Key（Web 界面方式）

1. 浏览器打开 http://127.0.0.1:3080
2. 点击左下角 Settings（设置）
3. 进入 Models（模型） 页面
4. 找到 DeepSeek 卡片，填入 API Key
5. 点击保存，无需重启即可生效

3.2 配置 API Key（环境变量方式）

适合喜欢命令行或自动化脚本：

# macOS / Linux
export DEEPSEEK_API_KEY="sk-your-key-here"
Windows (PowerShell)
$env:DEEPSEEK_API_KEY = "sk-your-key-here"
然后启动
dsh web

3.3 配置 API Key（凭证文件方式）

DSH 的凭证解析优先级：环境变量 → .credentials.yaml → .env 文件

直接编辑凭证文件：

# 文件路径：~/.dsh/.credentials.yaml
cat > ~/.dsh/.credentials.yaml << 'EOF'
DEEPSEEK_API_KEY: sk-your-key-here
EOF

🔐 该文件包含明文密钥，切勿提交到 Git。

3.4 选择工作区

1. 在 Web 界面点击"选择工作区"
2. 选择一个本地项目目录（Agent 将在此目录下读写文件）
3. 建议先用一个小项目测试，确认正常后再用于生产代码

⚠️ 强烈建议：项目源码务必用 Git 做版本管理！Agent 可能会修改或删除文件，Git 是最好的保险。

3.5 切换语言（可选）

Settings 页面可将界面语言切换为中文。

四、四种运行模式详解

Harness 提供四种预设模式，针对不同场景优化：

模式	英文名	特点	适用场景
标准模式	Standard	完整工具集：文件编辑、Shell、搜索、规划、子 Agent、工作流	日常编码、项目开发
PTC 模式	Code	模型写 TypeScript SDK，一次性组合多步工具调用	批量操作、复杂自动化
极简模式	Minimal	仅保留 bash + str_replace_editor	基准测试、最小干预
创造模式	Creator	标准模式 + 运行时检查 + 插件实验 + 自定义预设	开发插件、定制 Agent

4.1 标准模式（Standard）

默认模式，功能最全：

• 文件读写编辑
• Shell 命令执行
• 文件/网络搜索
• 任务规划与目标管理
• Skill（技能）调用
• 子 Agent 委派
• 工作流编排

4.2 PTC 模式（Code / Programmatic Tool Calling）

核心优化：减少往返次数

传统模式下，模型每调用一个工具都需要一次往返。PTC 模式下，模型生成一段 TypeScript 代码，通过 Code Mode SDK 一次性组合多个工具调用，系统用 run_code 执行。

例如：原本需要 5 次往返的操作，可以压缩为 1 次。

4.3 极简模式（Minimal）

仅保留两个工具：

• bash：持久化终端
• str_replace_editor：按绝对路径编辑文件

DeepSeek 官方模型基准测试就是在此模式下进行的。适合：

• 评估模型在最小手脚架下的真实能力
• 需要严格控制 Agent 行为范围的场景

4.4 创造模式（Creator）

在标准模式基础上增加：

• 运行时检查（Runtime Inspection）
• 插件实验（Plugin Experiments）
• 自定义 Agent Preset 编写
• 预设保存到 ~/.dsh/.agent-presets/

可以把它当成"有 Shell 的会话"，因为 cordis_mount 会在活的运行时上执行模型写的 JavaScript。

五、插件系统

Harness 的核心设计理念是 "Everything is a Plugin"。模型、工具、技能、会话、沙箱、存储、UI 都是插件，可自由替换。

5.1 安装插件

# 官方插件或 npm 包
dsh plugin --profile web add @dsh-external/dsh-vision-toolkit
通过 GitHub 地址安装
dsh plugin --profile web add https://github.com/omdsh-dev/dsh-custom-tool/archive/refs/heads/main.tar.gz
本地路径安装
dsh plugin --profile web add file:/path/to/your-plugin

5.2 管理插件

# 更新插件
dsh plugin --profile web update
移除插件
dsh plugin --profile web remove @dsh-external/dsh-vision-toolkit
查看已安装插件
dsh --profile web --dump-config | grep 插件名

⚠️ 安装/更新/移除插件后，必须重启 Web 服务（Ctrl+C 后重新 dsh web），仅刷新浏览器页面通常不够。

5.3 热门社区插件推荐

插件名	功能	安装
dsh-tool-git	模型侧 Git 操作（status/diff/commit 等）	dsh plugin --profile web add @chenhui2422/dsh-tool-git
dsh-vision-toolkit	视觉工具（OCR、截图分析、元素定位）	dsh plugin --profile web add @dsh-external/dsh-vision-toolkit
dsh-custom-tool	在设置 UI 中自定义 JavaScript 工具	dsh plugin --profile web add https://github.com/omdsh-dev/dsh-custom-tool/archive/refs/heads/main.tar.gz
dsh-browser-bridge	浏览器自动化（点击、截图、导航）	见 GitHub egnmosk/dsh-browser-bridge
dsh-memory-evolve	跨会话长期记忆 + 迭代自我进化	本地路径安装

🔍 发现更多插件：GitHub 搜索话题 dsh-plugin

5.4 开发自己的插件（最小示例）

在 Harness 源码目录下：

mkdir -p scratch-plugin/src

创建 scratch-plugin/src/greet-tool.ts：

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'greet-tool'
export const inject = ['tools']
export function apply(ctx: Context) {
ctx.tools.register(defineTool({
name: 'greet',
description: 'Greet someone by name.',
parameters: {
name: {
type: 'string',
required: true,
description: 'The name to greet',
},
},
output: {
schema: { type: 'string' },
render: (_args, value) => [{ type: 'text', text: value }],
},
async execute(args) {
return 你好，${args.name}！你的第一个 Harness 插件已运行。
},
}))
console.log('[greet-tool] loaded; tool name: greet')
}

创建 scratch-plugin/cordis.yml（使用绝对路径）：

- insert:
    - id: greet-tool
      name: '/Users/yourname/deepseek-harness/scratch-plugin/src/greet-tool.ts'

重启 DSH 后，模型即可调用 greet 工具。

六、常用命令速查

命令	说明
npx @deepseek-ai/dsh web	一键启动 Web UI（无需全局安装）
dsh web	启动 Web UI（全局安装后）
dsh web --port 8080	指定端口启动（默认 3080）
dsh web --host 0.0.0.0	允许局域网访问
dsh --version	查看版本
dsh --profile web --dump-config	查看完整配置树
dsh credentials set KEY_NAME	交互式设置凭证
dsh plugin --profile web add <plugin>	安装插件
dsh plugin --profile web update	更新插件
dsh plugin --profile web remove <plugin>	移除插件

七、实用技巧与注意事项

7.1 模型选择

模型	特点	建议
DeepSeek V4 Flash	速度快、成本低	日常编码首选，性价比最高
DeepSeek V4 Pro	能力强、成本高	复杂任务、深度推理时使用

早期测试表明，Flash 在典型编码任务中性价比更优；Pro 更适合难题而非日常编码。

7.2 费用优化

• DeepSeek API 已采用峰谷定价，长时任务可安排在空闲时段运行

• Harness 界面会显示实时统计：tokens/秒、缓存命中率、轮次、运行时间

• 在一次 ISS 追踪器实测中，Harness 消耗约 2000 万 tokens，最终达到 100% 缓存命中率

7.3 安全与权限

• 沙箱隔离：文件操作有只读、工作区写入、完全访问三种权限级别

• 审批策略：敏感操作（如删除文件、执行危险命令）可设置人工审批

• Git 保险：务必对项目做 Git 版本管理，Agent 改错时可快速回退

7.4 会话管理

• Harness 使用追加式会话日志（Append-only Session Log），记录模型看到的所有内容

• 支持恢复、分叉、搜索、重放任意运行

• Trajectory 视图可按来源检查记录

7.5 多模型接入

Harness 不绑定 DeepSeek 自家模型，支持接入：

• 官方目录：OpenAI、Anthropic、Google、Kimi、GLM 等近 40 家厂商

• 自定义端点：任何兼容 OpenAI / Anthropic 协议的 API

• 本地模型：通过配置指向本地部署的模型

配置自定义提供商示例（~/.dsh/settings.yaml）：

llm-pi-ai:
  providers:
    my-gateway:
      displayName: 我的网关
      apiKeyEnv: MY_API_KEY
      api: openai-completions
      baseURL: https://api.mygateway.com/v1
      models:
        - id: gpt-4
          name: GPT-4
          contextWindow: 128000
          maxTokens: 4096

---