DeepSeek Harness(dsh)安装使用保姆级教程

DeepSeek Harness（dsh）安装使用指南：一切皆插件的开源 Agent 框架

2026 年 8 月 13 日，DeepSeek 正式开源其 Agent 框架 DeepSeek Harness（命令行名 dsh），MIT 协议。它不是一个新模型，而是让模型能操作文件、运行命令、调用工具的"执行层"——Agent = Model + Harness。

一、DeepSeek Harness 是什么？

1.1 核心理念

Agent = Model + Harness

• Model（模型） 是 Agent 的"灵魂"，负责思考和推理
• Harness（线束） 是 Agent 的"身体"，让它理解环境、使用工具、在真实世界中持续工作

网页版对话 AI 交付的是一段话，Harness 交付的是一件做完的事。

1.2 “一切皆插件”

DeepSeek Harness 构建在 Cordis 微内核之上（源自 Koishi 生态，设计思想来自论文 A Programming Paradigm for Spatiotemporal Composability）。整个系统的每一个环节——模型接入、工具调用、会话存储、审批策略、UI 组件——都是可替换、可组合的插件。

这意味着：

• 想换模型服务？改配置，不动源码
• 想加个工具？装个插件
• 想改审批策略？换个审批插件

与 Claude Code、Codex 等把核心逻辑写死的工具不同，DSH 从模型到工具注册表，从会话日志到审批策略，全部插件化。

1.3 核心能力

1.4 当前状态

• 发布时间：2026 年 8 月 13 日
• 协议：MIT
• 阶段：开发者预览版（Developer Preview），会快速迭代，可能出现破坏性变更
• 官方仓库：https://github.com/deepseek-ai/deepseek-harness
• 官方页面：https://www.deepseek.com/harness/

二、环境要求

检查环境：

node --version   # 应输出 v22.19 或更高
npm -v

如果 node -v 低于 v22.19 或提示 command not found，到 nodejs.org 下载最新 LTS 版安装，务必保留安装器默认勾选的"添加到 PATH"，装完重启终端。

macOS 用户可用 Homebrew：

brew install node@24
brew link --overwrite --force node@24

三、安装与启动（四种方式）

方式 A：一行命令快速启动（推荐首次体验）

npx @deepseek-ai/dsh web

npx 会自动拉取并运行，无需预先安装。首次启动会下载全部依赖，根据网速耗时 1-3 分钟属正常。

启动成功后终端打印：

dsh web: http://127.0.0.1:3080

浏览器打开 http://127.0.0.1:3080 即进入 Web 界面。

方式 B：全局安装（日常使用推荐）

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

方式 C：源码构建（开发者 / 二次定制）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable        # 启用 pnpm
pnpm install
pnpm run build
pnpm dsh web

适合需要修改内核、自定义原生插件、跟进最新迭代或参与开源贡献的用户。

方式 D：Python SDK（程序化接入）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install deepseek-harness-sdk
export DEEPSEEK_API_KEY='你的密钥'

内置运行时，无需单独安装 Node.js。

启动后的三个关键认知

1. 终端窗口不能关：dsh web 进程是真正干活的 Host，浏览器只是操作界面。终端一关，网页立刻失联——这是设计，不是故障。
2. 默认只监听本机（127.0.0.1），局域网其他设备访问不到，这是安全设计。
3. 端口可换：3080 被占用时用 dsh web --port 8080。

四、首次配置三步走

第 1 步：申请 DeepSeek API Key

1. 打开 DeepSeek 开放平台，注册登录并充值少量余额（如 10 元，日常试用消耗极低）
2. 左侧进入 API Keys，点击创建 API key，输入名称
3. 密钥只在创建那一刻显示一次，立即复制保存，关掉页面就再也看不到了

安全规范：禁止截图泄露密钥、禁止明文写入代码文件、禁止上传到 Git 仓库。

第 2 步：配置 API Key

在 Web 界面的设置弹窗中粘贴密钥并保存，无需重启服务即时生效。

密钥字段是只写的——保存后页面只能看到脱敏描述符，不会回显明文。密钥存储在 $DSH_HOME/.credentials.yaml。

第 3 步：选择工作区

官方自带严格安全隔离：未选中工作区时，所有对话输入框是锁定禁用的，这是新手最常见的卡点。

1. 界面左侧点击选择工作区 → + 新增本地文件夹
2. 安全禁忌：禁止选择系统盘根目录、系统文件夹、桌面全目录、隐私文件目录
3. 推荐：新建一个空白专属文件夹，仅用于 Harness 任务处理
4. 选中后输入框自动解锁

验证部署

跑一个只读任务验证一切就绪：

请读取当前工作区的全部文件与目录结构，仅做汇总展示，不修改、不新增、不删除任何文件。

AI 正常输出目录清单、无报错、无超时，即部署完成。

五、Web 界面速览

轨迹面板（Trajectory）

DSH 的核心特色。完整记录：

• 系统提示词
• 模型推理过程
• 工具调用记录（参数 + 返回结果）
• 文件修改日志
• 终端命令执行详情

逐条可回溯、可排查报错。支持按来源筛选、搜索、导出。

“Every run is traceable”——模型看到的一切都记录在只追加的会话日志中。

六、权限与安全

6.1 三档权限模型

danger-full-access 的内部名已经说明了风险等级——它是"危险模式"，不是"高级模式"。

6.2 一个必须建立的认知

权限限制的是"写"，不是"看"。 Workspace Write 只限制写入范围；读取文件、联网、查看系统进程不受同等限制。它的"手"被绑住了，但"眼睛"是自由的。

涉及敏感操作（联网上传、系统级改动）会触发审批弹窗，由你确认后才会执行，不会静默放行。

6.3 底层沙箱

三档权限有真实的操作系统级沙箱支撑：

另有两个常驻纠偏插件：

• 重复无效动作检测：防止 Agent 对着同一个失败方案反复重试
• 超时强制中断：防止任务无限期运行

七、四种预设模式

Preset（预设）是能力组合包——同一种模型，挂上不同的工具集和规则，就能承担不同的"岗位"。

注意：模式决定工具集，中途切换会破坏会话可复现性，所以新建会话后无法切换模式，需提前选择。

八、模型接入：不止 DeepSeek

DSH 是 BYO Model（自带模型） 模式——框架本身不带模型，需要自己配置可用的模型端点。

8.1 DeepSeek 官方 API

设置 → 模型 → 在 DeepSeek 卡片中粘贴 API Key → 保存。

可选模型：

• DeepSeek V4 Pro：Agent 能力增强版
• DeepSeek V4 Flash：轻量快速版

8.2 其他官方目录提供方

设置 → 模型 → 添加提供方 → 选择 Anthropic / OpenAI 等 → 输入 API 密钥 → 保存。

使用原生认证的提供方（Bedrock、Vertex、Azure、Codex）需要各自的专属凭据（AWS 凭据与区域、ADC 项目、api-version、OAuth 等），只填 API Key 无法完成配置。

8.3 自定义提供方（公司网关 / 自建服务器）

设置 → 模型 → 添加自定义提供方，填写：

8.4 视觉模型

自定义模型在声明能力之前一律按纯文本对待。要让它接收图片，需在 $DSH_HOME/settings.yaml 中添加：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

8.5 常见报错

九、会话与上下文管理

9.1 会话操作

9.2 上下文管理

• DSH 通常会自动整理较早的对话（自动压缩）
• 需要立即压缩时手动执行 /compact，把早期对话整理成摘要
• 压缩不会删除原始历史——完整日志仍保留在轨迹面板

9.3 快捷键

十、插件系统

10.1 安装方式

官方原生支持 NPM 包 / Git 地址 / 本地路径三种插件安装方式：

# Web 全局插件安装
dsh plugin --profile web add 插件包名
# 示例：安装官方图像识别插件
dsh plugin --profile web add @liustack/modlens

安装完成后刷新 Web 界面自动加载，可在 设置 → 插件 面板统一管理启用/禁用。

10.2 插件分类

发布时即内置 159 个插件，涵盖：

• 模型插件：各 LLM 提供方接入
• 工具插件：文件操作、终端、网页搜索、代码执行等
• 技能插件（Skills）：可复用的任务模板
• 会话插件：存储、压缩、标题生成
• 沙箱插件：各平台隔离机制
• UI 插件：界面组件扩展

10.3 配置即组合

开发者可以在配置文件中选择、替换或扩展任何能力，无需修改 DSH 源码。这是"一切皆插件"的实际体现。

十一、进阶玩法

11.1 终端 TUI

dsh-tui 是官方收录的社区终端插件，界面对标 Claude Code，适配 VS Code 终端、Linux 远程 SSH 运维、全键盘操作：

npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
# macOS/Linux 配置密钥并启动
export DEEPSEEK_API_KEY='你的完整API Key'
dsh-tui

启动后输入 /doctor 自检：检测 Node 版本、系统架构、模型连接、密钥有效性、工作目录权限、插件加载状态。

常用斜杠命令：

11.2 无头（Headless）模式

无需交互界面，后台静默执行任务，适配脚本自动化、CI 流水线、定时任务、服务器批量运维场景。

11.3 Python SDK

import deepseek_harness_sdk as dsh
# 以编程方式启动任务、接收结果

11.4 VS Code 扩展

市场搜索 DeepSeek Harness for Visual Studio Code，安装后可在编辑器侧边栏直接使用 Workbench，支持设置 API Key、查看日志、重载运行时。

十二、常见问题排查

排错第一原则：先看跑 dsh web 的那个终端窗口——绝大多数问题的答案都在它的报错输出里。

十三、安全注意事项

1. API Key 即密码：只在创建时可见一次，不截图、不发公开渠道、不写进代码/仓库
2. 工作区即边界：只给 Agent 授权它该碰的文件夹；敏感目录（桌面、文档、系统盘）不要设成工作区
3. danger-full-access 慎用：切换前会二次确认，理解风险再开
4. 开发者预览版：可能快速迭代、出现破坏性变更，重要环境记得锁版本、看更新日志
5. 写操作需审批：Agent 执行删除、批量修改、高危 Shell 命令时会弹窗确认，留意弹窗内容，不盲目点允许

参考资源

• 官方仓库：https://github.com/deepseek-ai/deepseek-harness
• 官方页面：https://www.deepseek.com/harness/
• 官方文档：https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart
• DeepSeek 开放平台（API Key）：https://platform.deepseek.com/
• VS Code 扩展：https://marketplace.visualstudio.com/items?itemName=skymecode.deepseek-harness-for-vscode
• Cordis 论文：见官方页面链接

DeepSeek Harness 目前处于开发者预览阶段，迭代极快。文中命令与配置如与官方最新版有出入，以官方仓库 README 与文档为准。

到此这篇关于DeepSeek Harness(dsh)安装使用保姆级教程的文章就介绍到这了,更多相关DeepSeek Harness使用指南内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

最新评论