DeepSeek Harness（DSH）

概览

DeepSeek Harness（dsh）是 DeepSeek AI 开发的开源智能体框架，采用“一切皆插件”的架构，由 Cordis 驱动。模型适配器、工具注册、会话日志和 Agent 循环均可通过插件组合或替换。

DSH 目前仍处于开发者预览阶段，迭代较快，后续可能出现破坏兼容性的变更。

截至 2026-08-17，npm 最新版本为 @deepseek-ai/dsh@0.1.0-rc.6。

核心特点

DSH 不像 Claude Code 或 GPT 那样是开箱即用的成品 Agent。它将各个流程设计为可插拔插件，最终组合成一个 Agent；轨迹模式可以清晰展示运行过程。

安装与升级

需要先安装 Node.js。官方推荐直接通过 npx 运行，无需全局安装：

npx @deepseek-ai/dsh web

也可以全局安装，以便直接使用 dsh：

npm install -g @deepseek-ai/dsh

升级全局安装：

npm install -g @deepseek-ai/dsh@latest

验证版本：

dsh --version

若全局安装后 zsh 仍提示 command not found，可刷新命令缓存或重新打开终端：

rehash

启动 Web UI

在项目目录中运行：

dsh web

dsh web 是 dsh --profile web 的别名。默认访问地址为 http://127.0.0.1:3080，进程以前台方式运行，按 Ctrl+C 停止。

指定监听地址和端口：

dsh web --host 127.0.0.1 --port 8080

端口冲突时可让系统自动选择可用端口：

dsh web --port 0

查看 Web 模式参数：

dsh web --help

确认默认端口是否正在监听：

lsof -nP -iTCP:3080 -sTCP:LISTEN

Web 模式默认仅监听 127.0.0.1。当前 CLI 不支持通过 --host 0.0.0.0 直接对外监听；--trusted-host 用于向浏览器 API 信任检查添加允许的主机名，并不等同于修改监听地址。

首次使用

1. 启动 Web UI 并打开终端输出的地址。
2. 进入 Settings → Models。
3. 填写 DeepSeek API Key 并保存；模型配置在下一次请求时生效，无需重启。
4. 点击 Choose workspace，添加并选中工作目录。
5. 选择模型，新建会话并发送任务。

启动 dsh 的目录只是默认文件系统位置；全新的 Web UI 不会自动选中工作区。在选择工作区之前，会话输入区域不可用。

模型与凭据

DSH 支持以下模型配置方式：

• DeepSeek 官方 Provider。
• 内置目录中的 Provider，例如 Anthropic、OpenAI、Bedrock、Vertex、Azure 和 Codex。
• 自定义 OpenAI 兼容或其他受支持协议的 Provider。

Provider 可在 Settings → Models 中管理。已保存的密钥只以脱敏描述返回到页面，原始密钥不会重新显示。

默认情况下：

• 凭据保存在 $DSH_HOME/.credentials.yaml。
• 普通模型设置保存在 $DSH_HOME/settings.yaml，其中只记录凭据引用。
• 也可以通过环境变量、当前目录的 .env 或 $DSH_HOME/.env 提供凭据。

选择模型后，该模型会成为新会话的默认模型。已经发出过请求的会话会继续使用会话日志中记录的模型；如需彻底切换，建议新建会话。

自定义 Provider 的 Provider ID 会被请求、会话和凭据引用使用，创建后不适合直接改名。需要改名时，应新建 Provider，再删除旧 Provider。

工作区、权限与安全

所有模式都把启动命令时所在的目录作为默认工作区根目录，并加载适用的 AGENTS.md 或 CLAUDE.md 指令。

新会话默认使用 workspace-write 权限预设：文件和 Shell 写入操作被限制在会话工作区及平台临时目录内，部分操作会根据当前权限策略请求确认。

需要注意：

• 读取操作、网络访问和进程可见性并未被完整隔离。
• 不要在不可信仓库中授予高权限。
• 不要把 API Key 写进笔记或提交到项目仓库。
• MCP Server 命令属于沙箱之外的受信任可执行代码，默认不会自动启用。
• 遥测默认关闭；显式启用完整遥测时，导出内容可能包含消息、工具参数与结果以及工作区路径。

Headless 模式

Headless 模式适合脚本或一次性任务，不启动 Web 服务：

dsh --profile headless "总结这个仓库并列出主要模块"

它会创建一个新的持久化会话，等待任务结束，在标准输出中打印最后一条非空回答，然后退出。任务完成时退出码为 0，其他结束原因返回 1。

Profile 与配置层

DSH 通过 Profile 组合插件 Bundle。内置模板包括：

• web：基础能力与浏览器界面。
• headless：基础能力与一次性任务运行器。

web 和 headless 会在首次使用时自动初始化。自定义 Profile 位于 $DSH_HOME/profiles/，其配置按以下顺序叠加，后面的层优先级更高：

1. Profile 声明的各 Bundle 配置。
2. Profile 自己的 cordis.patch.yml。
3. $DSH_HOME/cordis.patch.yml。
4. 命令行中按顺序传入的 --patch 文件。

补丁命中某个配置行时，会替换该行完整的 config，而不是对字段进行深度合并，因此覆盖时需要保留仍然需要的字段。

查看内置 Bundle 的默认组合：

dsh --profile web --dump-default-config

查看包含用户覆盖层的最终组合：

dsh --profile web --dump-config

叠加临时补丁后检查配置：

dsh --profile web --patch ./extra.cordis.yml --dump-config

插件管理

通过 Profile 安装或管理第三方插件：

dsh plugin --profile <profile> add <package>
dsh plugin --profile <profile> remove <package>
dsh plugin --profile <profile> update

插件管理命令会转交给 Profile 目录中的 pnpm 执行，因此 pnpm 必须位于 PATH 中。安装带有 DSH Bundle 声明的依赖后，其配置层会自动加入该 Profile。

从源码运行

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

首次检出以及构建产物需要更新时，都应先执行 pnpm run build。

常用命令

# 临时启动 Web UI
npx @deepseek-ai/dsh web

# 使用全局命令启动 Web UI
dsh web

# 指定端口
dsh web --port 8080

# 查看启动器帮助
dsh --help

# 查看 Web 应用帮助
dsh web --help

# 查看版本
dsh --version

# 运行一次性任务
dsh --profile headless "检查测试失败的原因"

# 查看最终 Profile 配置
dsh --profile web --dump-config

常见问题

MISSING_CREDENTIAL

通过 Settings → Models 保存对应 Provider 的凭据，或提供配置所引用的环境变量。

UNKNOWN_MODEL

重新选择已配置模型，或把缺失模型添加到自定义 Provider。

获取模型列表时返回 401

检查 API Key。模型发现通常调用 OpenAI 兼容的 GET /models；如果服务不支持该接口，需要手动填写模型。

图片在发送前被拒绝

当前模型没有声明图片输入能力。DeepSeek 自身的 Chat Completions 路由为纯文本；自定义视觉模型需要在 $DSH_HOME/settings.yaml 中正确声明 input: [text, image]。

端口被占用

更换端口或使用自动分配：

dsh web --port 0

全局命令不存在

确认 npm 全局可执行目录已加入 PATH，然后执行：

rehash
dsh --version

相关链接

• DeepSeek Harness GitHub
• 中文 README
• Web UI 指南
• npm 包
• GitHub Discussions