一、简介
DeepSeek Harness（简称 dsh ）是 DeepSeek AI 于 2026年8月13日开源的 Agent（智能体）运行时框架。它基于 "一切皆插件" 的架构理念，由 Cordis 微内核驱动。
核心定位：把大模型的理解推理能力与可扩展的执行环境结合起来------模型负责"思考"，Harness 负责让 Agent 真正操作本地环境、调用工具并持续执行任务。
⚠️ 重要提示 ：DeepSeek Harness 目前处于开发者预览阶段，正在快速迭代，未来将出现破坏兼容性的变更。不建议直接用于生产环境的关键流程。
二、环境要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10+、macOS 10.15+、主流 Linux（x64/arm64） |
| Node.js | v22.19 及以上，或 v24 系列 |
| 包管理器 | 源码安装需要 pnpm（npm install -g pnpm） |
| API Key | DeepSeek 或其他兼容提供方的密钥 |
| Python（可选） | Python 3.10+（使用 Python SDK 时） |
硬件要求不高，普通笔记本即可运行 Web 界面。
三、快速开始
方式一：通过 npx 一键启动（最快捷）
确保已安装 Node.js，然后在终端中执行：
bash
npx @deepseek-ai/dsh web该命令会自动下载并启动 Web UI，默认地址为 http://127.0.0.1:3080。用浏览器打开即可开始使用。
方式二：全局安装
如需固定版本或离线使用：
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方式四：使用桌面应用（Windows）
从 GitHub Releases 下载 dsh.exe（约 110 MB，内嵌完整运行时），双击运行即可。
方式五：一键部署工具（DSH Launcher）
下载 DSH Launcher-Setup-0.2.2.exe，跟着「一键部署」向导走，自动完成 Node.js + DSH 安装。
四、首次使用配置
启动 Web UI 后，按以下步骤操作：
1. 配置 API Key
打开 Settings → Models ，在 DeepSeek 卡片中填入 API Key（格式 sk-...），点击保存。
Key 存储在 $DSH_HOME/.credentials.yaml 中，界面不会再显示明文。
2. 选择工作区
点击「选择工作区」，添加你希望 Agent 操作的项目目录。建议单独准备一个练习目录作为工作区，避免误操作重要文件。
3. 发送第一个任务
在对话框中输入任务，例如：
"Summarize this repository and identify its main packages."
Agent 会读取工作区文件、运行命令、维护执行计划。涉及写操作时，Web UI 会根据权限策略提示审批。
4. 配置自定义模型（可选）
Harness 支持接入任意 OpenAI 兼容端点：
- 方式一（推荐）：打开 Settings → Models → 添加自定义提供方，填写 Provider ID、API 地址和模型 ID
- 方式二 ：直接编辑
$DSH_HOME/settings.yaml
yaml
llm-pi-ai:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://api.example.com/v1
models:
- id: model-name-here五、四种运行模式
Harness 预置了四种运行模式，面向不同使用场景：
| 模式 | 适用场景 | 特点 |
|---|---|---|
| 标准模式 | 日常复杂任务 | 工具较全，包含文件操作、Shell、搜索、子任务委派等 |
| PTC 模式 | 需要流程可控的场景 | 模型生成代码来编排多轮工具调用 |
| 极简模式 | 最小化基准测试 | 仅保留 Shell 和文件编辑 |
| 创造模式 | 插件开发者、定制化智能体 | 可检查当前运行时并在内存中试验插件组合 |
六、Python SDK 使用
如需在 Python 程序中程序化调用 Harness，可以使用官方 Python SDK。
安装
bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate # Windows 用 .venv\Scripts\activate
pip install deepseek-harness-sdk设置凭据
bash
export DEEPSEEK_API_KEY=sk-your-key-here
# 如使用非默认端点：
export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# 可选：指定模型
export DSH_MODEL=deepseek-v4-flash基本用法
python
from pathlib import Path
from deepseek_harness import DeepSeekHarness
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
max_tokens=49152,
cwd=str(workspace),
session_root=str(sessions),
cordis=str(config),
) as harness:
result = harness.run(
"Inspect the repository and fix the failing tests.",
session_id="example-001",
)
print(result.final_response)注意：复用同一个 harness 与 session id 会保留该会话拥有的 Bash 进程（包括工作目录、已导出的变量与 shell 函数）。独立任务应使用新的 session id。
七、插件开发
Harness 的"一切皆插件"架构允许开发者自由扩展功能。
开发环境准备
- Node.js ^22.19 或 >=24
- 熟悉 Cordis 插件机制
插件开发基本步骤
- 确定插件的唯一职责
- 声明依赖的 service
- 贡献配置行
- 开始编码实现
学习资源
- 官方开发指南：docs/development.md
- 架构文档：docs/architecture.md
- 社区插件模板：为你的插件仓库添加
dsh-plugin话题以便被发现
八、常见问题
Q1：首次运行 npx @deepseek-ai/dsh web 很慢？
首次运行会从 npm 下载依赖包，请耐心等待。后续启动会快很多。
Q2：Web UI 无法打开？
确认终端输出的地址（默认 http://127.0.0.1:3080），检查端口是否被占用。关闭终端后服务会停止。
Q3：如何切换模型？
在 Web UI 的对话框中选择模型即可，无需重启 dsh。也可以在 Settings → Models 中添加更多模型。
Q4：Agent 执行写操作时卡住了？
Web UI 默认会对写操作请求审批，请在界面中确认。也可在设置中调整权限策略。
Q5：工作区是什么？为什么需要？
工作区是 Agent 可以操作的目录范围，是一种安全隔离机制，防止 Agent 误操作系统重要文件。
九、社区与支持
- GitHub 仓库 ：https://github.com/deepseek-ai/deepseek-harness
- 反馈与讨论 ：GitHub Discussions
- Discord 社区 ：https://discord.gg/Ycq5dCaS4
- 企微群：扫码添加企微小助手并填写入群问卷
- 插件发现 ：为插件仓库添加
dsh-plugin话题
十、扩展学习资源
- 社区手册 ：dsh-handbook ------ 从 0 到 1 的深度手册，包含安装、插件开发、性能调优、实测案例等
- 在线阅读 ：https://electricitysheep.github.io/dsh-handbook/
- 插件开发教程 ：hello-dsh ------ 零基础插件开发教程，含 22 个中文技能实例