Henry Lin

Posted on Aug 18

DeepSeek Harness (`dsh`) 使用教程

本教程面向想要快速上手 DeepSeek Harness 的开发者，覆盖从安装、配置到日常使用与扩展的全流程。

1. 项目简介

DeepSeek Harness（dsh）是 DeepSeek AI 开发的开源 agent harness（智能体框架），采用一切皆插件的架构，由 Cordis 驱动。

核心特点：

一切皆插件：包括模型适配器、工具注册表、会话日志、agent 主循环本身都是插件，任何部分都可以从配置层面替换。
能力缝（Capability Seam）：每个可替换能力由 Service Definition / Provider / Consumer 三角色组成，切换 Provider 即可整体改变产品行为。
会话日志：追加式事件日志是模型上下文的来源，"模型可见 ⟺ 已记录"是一条运行时不变量。
开发者预览：当前处于快速迭代阶段，会有破坏兼容性的变更。

常用术语：

术语	含义
Profile	命名的插件组合，存放在 `$DSH_HOME/profiles/<name>`
Bundle	插件的分发格式，由一组 Cordis 配置行 + 对应代码组成
Step	一次模型请求 + 它调用的工具
Turn	零到多个 step 组成的完整回合
Seam	可替换能力缝（见上）

2. 环境准备与安装

2.1 前置要求

Node.js：要求 ^22.19 或 >=24
pnpm（从源码运行时需要）
DeepSeek API Key（或其他兼容模型的 API Key）

2.2 方式一：通过 npm 直接运行（推荐体验）

不需要克隆仓库，只需安装 Node.js，然后：

npx @deepseek-ai/dsh web

该命令会启动 Web UI，默认地址为 http://127.0.0.1:3080。

2.3 方式二：从源码运行（推荐开发）

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

注意：生产运行需要先执行 pnpm run build 生成构建产物；pnpm dsh 通过 tsx 以 ESM 模式直接从源码启动。

2.4 常用开发命令

pnpm run test            # 单元测试
pnpm run test:e2e        # 真实 API 测试（无 DEEPSEEK_API_KEY 时自动跳过）
pnpm run typecheck       # 类型检查
pnpm run lint            # 代码检查
pnpm run build           # 构建产物

3. 运行 Web UI

3.1 启动

pnpm dsh web
# 或使用 npm 版本：
# npx @deepseek-ai/dsh web

启动后浏览器打开 http://127.0.0.1:3080。

3.2 常用启动参数

pnpm dsh web --port 8080            # 自定义端口
pnpm dsh web --host 0.0.0.0         # 绑定地址（注意：CLI 暂不支持 0.0.0.0，会报错）
pnpm dsh web --trusted-host demo.com  # 添加受信任的域名（可重复）
pnpm dsh web --patch ./extra.yml    # 应用额外的 patch 覆盖
pnpm dsh web --dump-config          # 查看实际组合的插件树而不启动
pnpm dsh web --help                 # 查看 web 应用自身的参数

3.3 工作流程概览

Web UI 的完整使用流程：

配置模型（填入 API Key）
选择工作区（指定一个项目目录）
创建会话
发送任务
观察 agent 执行、审批弹窗与结果

4. 配置模型

4.1 配置 DeepSeek（最快上手）

打开 Settings → Models，在 DeepSeek 卡片中输入 API Key 并保存。

Key 是只写的：保存后页面只显示脱敏后的描述，不会回显明文。
Key 存储在 $DSH_HOME/.credentials.yaml，设置中只保留凭证引用。
保存后立即生效，无需重启服务。

4.2 添加目录中的 Provider

点击 Add provider，选择如 Anthropic、OpenAI 等，输入对应 API Key 保存即可。目录内置了端点、协议和模型列表。

部分 Provider 需要原生认证（如 Bedrock 用 AWS 凭证、Azure 用 api-version 等），只填 API Key 无法生效。

4.3 添加自定义 Provider

点击 Add a custom provider，适用于公司网关、自托管服务器或目录中没有的 Provider。需要填写：

Provider ID（小写，永久，后续请求/会话/默认模型都引用它）
显示名称
Base URL
API 协议
凭证
至少一个模型

模型可以通过 Fetch available models 从 GET /models 端点自动拉取，也可以手动输入。

4.4 图片输入（vision 模型）

手动输入的模型默认按"仅文本"处理。若模型支持图片，需要在 $DSH_HOME/settings.yaml 中声明：

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

4.5 选择默认模型

配置好的 Provider 会出现在模型选择器中。选中的模型会成为新会话的默认模型。已发送过请求的会话会保留其日志中记录的模型。

5. 选择工作区

在 Web UI 中点击 Choose workspace：

添加启动 dsh 时的项目目录并选中。
会话创建入口在选中工作区之前不可用。
dsh 进程默认把启动目录作为文件系统位置。

工作区决定了 agent 可以读写的文件范围（配合权限策略生效）。

6. 创建会话并运行任务

6.1 创建会话

选中工作区后，新建一个会话。默认使用 workspace-write 权限预设：bash 和文件系统写操作被限制在工作区与平台临时目录内；读操作、网络访问和进程可见性不受限制。

6.2 发送任务示例

在会话中发送类似以下任务：

总结这个仓库，并指出它的主要包。

agent 可以：

读写和编辑工作区文件（read / write / edit / glob / grep）
运行命令（bash）
搜索网络（web_search / web_fetch）
委派子任务（subagent）
维护计划与待办（plan / todo_write）
询问用户（ask_user_question）

6.3 审批机制

当操作超出当前权限策略需要批准时，Web UI 会弹出确认请求。属于"审批缝（approval seam）"，缺省在没有应答者时 fail-closed 为 unavailable。

6.4 实战操作示例

下面是一组可以直接粘贴到 Web 会话中的任务，并说明预期的 agent 行为。把 <...> 替换为你的实际内容。

示例 1：代码库探索

这个仓库有哪些主要包？用树状图展示 packages/ 的目录结构，并总结每个包组（core、shell、fs、web 等）各自负责什么。

预期行为：agent 依次调用 glob/bash（列目录）、read（读关键 README 和 package.json）、grep（搜索特定模式），最终输出一份结构总结。这类任务通常不需要审批。

示例 2：修改代码并验证

在 src/utils.ts 中新增一个 formatBytes(bytes) 函数，把字节数格式化为可读的 "12.5 MB"。然后给它写一个单元测试并运行 pnpm test 确认通过。

预期行为：agent 先 read 目标文件（read-before-write 策略），再 write/edit 修改，然后写测试、跑 bash。对工作区的写操作一般直接执行，跨出工作区的命令才会触发审批。

示例 3：排查失败测试

运行 pnpm run test，如果失败，诊断根因并修复，最后再次运行确认全部通过。

预期行为：agent 用 bash 运行测试，读到失败后结合 read（看测试与源码）、grep（找相关代码）定位问题，edit 修复，再跑一遍验证。适合演示 agent 的循环-修复-验证工作流。

示例 4：联网检索

搜索 DeepSeek Harness 最新版本发布说明，总结 3 个主要新特性。

预期行为：agent 调用 web_search 获取结果，再对命中链接 web_fetch 读取正文，最后总结。若当前模型未配置搜索 Provider，web_search 会返回错误，此时应检查 base bundle 的搜索配置。

示例 5：计划 + 待办清单

为"给项目添加 CI"制定一个计划，并用待办清单跟踪每一步。

预期行为：agent 先进入计划模式整理步骤（可能调用 ask_user_question 确认选择），然后持续调用 todo_write 维护一个带状态（in_progress / completed）的清单，UI 会实时渲染为复选框。

示例 6：需要确认的交互

我接下来要把日志格式从 JSON 改成文本。开始前先问我：是否同时更新文档？

预期行为：agent 调用 ask_user_question，Web UI 弹出问题卡片（带 id、选项），你的回答会回填到工具结果中，agent 据此继续。审批与提问是两条不同机制：提问走 userQuestions 缝，审批走 approval 缝。

示例 7：并行委派子任务

同时调研两件事：A) 这个项目用到的持久化方案，B) 它的权限预设。分别交给子 agent，完成后汇总成一份对比表。

预期行为：agent 通过 subagent 工具派生子会话并行调研（也可在后台运行，用 job_list/job_output 收集），完成后在父会话汇总。子会话的事件会进入各自的会话日志，可通过会话历史回溯。

示例 8：跨会话检索

在历史会话中搜索所有提到 "sandbox" 的内容，把相关的结论贴出来。

预期行为：agent 调用 session_event_search / session_search 在持久化的会话日志中检索，结果基于当前工作区授权返回。演示了"会话即数据库"的能力。

提示：示例 1、2、3 只用到基础工具，任何配置了模型的工作区都能跑通，最适合首次体验。

7. headless 命令行模式

headless 是一次性运行的 CLI 模式，没有服务器、没有浏览器 UI。

7.1 运行一次性任务

pnpm dsh --profile headless "运行测试"

行为：

创建一个全新的持久化会话
提交任务，等待静默
刷新 Session，输出最后一条非空 assistant 文本
completed 时退出码 0，否则退出码 1
成功时 stdout 输出答案，stderr 无输出，不开放监听端口

7.2 headless 模式的特点

不挂载 ApiProxy、Host、HTTP 服务器、Web 运行时或浏览器客户端
没有任务文本属于用法错误
会话内容持久化，可从日志重建

8. 配置与权限

8.1 环境变量

变量	作用
`DEEPSEEK_API_KEY`	DeepSeek API Key（搜索也用此 key）
`DEEPSEEK_BASE_URL`	自定义 DeepSeek API 地址
`DEEPSEEK_SEARCH_BASE_URL`	自定义搜索 API 地址
`DSH_HOME`	Harness 数据目录（profiles、credentials、settings）
`DSH_PERMISSION_MODE`	改变进程的权限 fallback
`DSH_TOOLS_MODE`	工具模式：`native`、`code` 或 `both`
`DSH_TELEMETRY_MODE`	`FULL`（全量 OTLP 日志）或 `FEEDBACK_ONLY`
`DSH_TELEMETRY_OTLP_URL`	自定义遥测收集器地址
`DSH_TELEMETRY_DISABLED`	非空则彻底关闭遥测

8.2 凭证解析顺序

Provider 凭证按以下顺序解析（先到先得）：

继承的环境变量
$DSH_HOME/.credentials.yaml
启动目录的 .env
$DSH_HOME/.env

8.3 权限预设

预设	说明
`workspace-write`（默认）	bash/文件系统写操作限在工作区与临时根目录
`danger-full-access`	放开沙箱与审批限制

8.4 Profile 与 Patch 层

插件树的组合顺序（后层覆盖前层）：

profile 清单 dsh.profile.bundles 中列出的各 bundle（按顺序）
profile 的 cordis.patch.yml
家目录级 $DSH_HOME/cordis.patch.yml
--patch <path> 覆盖（按 argv 顺序）

patch 按行 id 定位，替换该行的整个 config 值（不是深合并），也可以插入新行。

查看实际组合的树：

pnpm dsh --profile web --dump-config
pnpm dsh --profile web --dump-default-config   # 只看 bundle 层

9. 插件管理

9.1 安装插件

pnpm dsh plugin --profile web add <package-or-git-spec>

转发给 pnpm 在 profile 目录执行
add、remove、why、update 等 pnpm 动词都可用
相对路径（.、../plugin）锚定到调用目录
依赖中声明了 "dsh": { "bundle": ... } 的包会自动进入 bundle 层

示例：

pnpm dsh plugin --profile tui add github:deepseek-harness/turtle-ui
pnpm dsh plugin --profile tui remove turtle-ui
pnpm dsh --profile tui

Git 托管的插件源码在安装时通过 prepare 脚本构建，pnpm ≥10 需要先在 profile 的 pnpm-workspace.yaml 中允许构建（按报错提示复制 allowBuilds key）。

9.2 内置 bundle

Bundle	作用
`@deepseek-ai/dsh-base`	每个 profile 的第一层：模型适配器、工具、持久化、沙箱、审批、设置、凭证、遥测
`@deepseek-ai/dsh-web-app`	浏览器应用（Web UI）
`@deepseek-ai/dsh-headless`	一次性运行器（无服务器）

web 和 headless profile 首次使用时会从内置模板自动初始化；其他 profile 需通过 dsh plugin 创建。

10. Python SDK

项目还提供 Python SDK，用于以编程方式驱动 dsh。详见 Python SDK 指南和 python/README.md。

10.1 安装

cd python/sdk
pip install -e .

10.2 基本用法

from dsh import DSHClient

client = DSHClient("http://127.0.0.1:3080")
session = client.create_session()

for event in session.send("总结这个仓库"):
    print(event)

具体 API 以 python/sdk/README.md 为准。

11. 开发插件（扩展能力）

11.1 扩展点速查

目标	机制
添加模型 Provider	在 `ctx.llm` 上注册适配器
添加模型可见能力（工具）	在 `ctx.tools` 上注册，schema 加入 prompt 组装
添加 bash 执行	注册 `ctx.shell` 后端
添加文件系统访问/策略	注册 `ctx.fs` Provider 或监听 `fs/*` 事件
添加持久终端执行	注册 `ctx.terminals` 后端 + `dsh-tool-terminal`
添加人工命令	在 `ctx.commands` 上注册
拦截请求/工具/回合	使用 `agent/` 或 `tools/` 事件
添加模型可见上下文	调用 `agent.inject()`
添加持久会话状态	扩展 `SessionEventMap`，从日志渲染与回放

11.2 快速开始

推荐从示例和 cookbook 开始：

开发指南：docs/development.md
架构文档：docs/architecture.md
扩展 cookbook：docs/cookbook/extension-cookbook.md
添加工具：docs/cookbook/adding-a-tool.md
添加 LLM 适配器：docs/cookbook/adding-an-llm-adapter.md
可运行示例：examples/

11.3 测试与质量门

pnpm run test              # 单元测试
pnpm run test:coverage     # CI 覆盖率门槛（每文件 100%）
pnpm run test:snapshot     # 无 key 的 ACP/headless 回放快照
pnpm run typecheck && pnpm run lint

11.4 插件发布

为插件仓库添加 dsh-plugin GitHub 话题便于被发现。发布流程见发布指南。

12. 常见问题排查

问题	解决方法
`MISSING_CREDENTIAL`	通过 Models 页保存 Provider Key，或提供引用的环境变量
`UNKNOWN_MODEL`	选择已配置的模型，或向自定义 Provider 添加缺失的模型
Fetch models 返回 401	检查 Key；端点无 `GET /models` 时手动输入模型
图片在发送前被拒绝	模型未声明图片模态；给自定义模型加 `input: [text, image]`
Git 插件 add 失败	在 profile 的 `pnpm-workspace.yaml` 中允许 `allowBuilds`
没有任务文本的 headless	headless 需要位置参数任务文本，空参数是用法错误
`dsh web --host 0.0.0.0` 报错	CLI 暂不支持 `0.0.0.0`，用 `--trusted-host` 添加受信任域名

DeepSeek Harness (dsh) 使用教程

目录