Deepseek harness

一 概念

源码部署的版本：0.1.5-rc.2
查询地址：deepseek-harness-master\apps\cli\package.json
或者根目录控制台执行命令：pnpm dsh –version

I 什么是 Agent Harness

DeepSeek Harness（dsh）是由 DeepSeek AI 开发的开源 agent harness，即 "智能体框架"。

它的核心特征是：

• 采用 “一切皆插件” 的架构。
• 由 Cordis 驱动。
• 提供 Web UI 与 CLI 等使用入口。
• Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。
• 当操作在当前权限策略下需要审批时，界面会先询问用户。

图中可以看到，<code>dsh</code> 位于用户入口、模型提供方和工作区之间：

• 用户通过 Web UI、CLI 或 Python SDK 与 Harness 交互。
• Harness 内部组合 Agent Loop、Tools、LLM、Session 等插件能力。
• Agent 调用模型，并操作工作区中的文件和命令。

II DeepSeek Harness 解决什么问题

一个能执行编码任务的 Agent，不只是调用大模型生成文本，还需要：

• 读写工作区文件。
• 执行命令。
• 组织多轮工具调用。
• 维护会话状态。
• 处理权限与审批。
• 允许开发者扩展工具和模型能力。

<code>dsh</code> 把这些能力组织成一个可运行的 Harness。学习者可以把重点放在 "如何使用它完成任务" 和 "如何扩展它"，而不必从零实现一整套 Agent 运行环境。
需要特别注意：DeepSeek Harness 目前处于开发者预览阶段，正在快速迭代，未来可能出现破坏兼容性的变更。学习时应以当前版本的实际行为为准。

III 运行方式

可以选择以下两种运行方式。

1 方式一：通过 npm 运行

安装 Node.js 后，直接运行：

npx @deepseek-ai/dsh web

该命令会启动 Web UI，默认地址为 http://127.0.0.1:3080。
这种方式适合快速体验，不需要克隆仓库。

2 方式二：从源码运行

如果需要在源码仓库中开发、调试或修改插件，使用源码运行：

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

IV 环境要求

需要满足以下版本要求：

• 包管理器：<code>pnpm@11.7.0</code>
• Node.js：<code>^22.19.0 || >=24.0.0</code>

因此开始前需要确认：

node -v
pnpm -v

如果 Node.js 版本不在支持范围内，应切换到 22.19.0+ 或 24.0.0+。

• Node.js 下载地址：https://nodejs.org/
• pnpm 安装说明：https://pnpm.io/installation

V 实操步骤

1. 打开终端（macOS / Windows）

后续所有命令都要在终端窗口中执行。

macOS

1. 按下 Command + 空格，打开 Spotlight。
2. 输入 Terminal 或 终端。
3. 回车打开终端。
4. 也可以从访达进入：应用程序 → 实用工具 → 终端。

Windows

1. 按下 Windows 键 + R，打开 "运行" 对话框。
2. 输入 <code>powershell</code> 或 <code>cmd</code>。
3. 回车打开 PowerShell 或命令提示符。
4. 也可以点击 "开始" 菜单，搜索 PowerShell、终端 或 命令提示符 后打开。
5. Windows 11 用户也可以右键点击 "开始" 按钮，选择 "终端"。

2. 检查环境

在终端中执行：

node -v
pnpm -v

确认 Node.js 版本满足 <code>^22.19.0 || >=24.0.0</code>。

3. 选择运行方式

快速体验：

npx @deepseek-ai/dsh web

源码运行：

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

4. 验证启动

观察终端输出。正常情况下，命令会打印 Web UI 访问地址，默认是：

http://127.0.0.1:3080

二 Web-UI基础使用

整个操作流程分为四步：打开 Web UI、配置 DeepSeek 模型、选择工作区、发送第一个任务并处理审批。

第 1 步：打开 Web UI

启动 Web UI 后，命令会打印访问地址。默认地址是：http://127.0.0.1:3080
dsh 进程会把调用命令时所在的目录作为默认文件系统位置，但新的 Web UI 在添加工作区之前不会选中任何工作区。

第 2 步：配置 DeepSeek 模型（改源码）

第一次使用 Web UI 时，需要先配置模型。
操作：

1. 打开 设置 → 模型。
2. 在 DeepSeek 卡片中找到 API 密钥输入框。
3. 输入 DeepSeek API Key。
4. 点击保存。
5. 确认模型选择器已经出现可用模型。
   保存后，模型路由会立即可用，不需要重启服务器。密钥是只写的：保存后页面只会显示脱敏信息，不会再次显示明文密钥。

如果是用源码部署，直接改源码

路径：deepseek-harness-master\packages\bundle\base\cordis.patch.yml

在根目录创建环境文件 .env ，编辑文件内容，定义字段API_KEY = 第三方鉴权秘钥key

改动 1：默认模型从 DeepSeek 切到公司模型
现在 cordis.patch.yml:75-79 是：

    - id: agent-default-model
      name: '@deepseek-ai/dsh-agent-default-model'
      config:
        provider: deepseek-official
        model: deepseek-flash

改成：

    - id: agent-default-model
      name: '@deepseek-ai/dsh-agent-default-model'
      config:
        provider: company-qwen
        model: Qwen3.6-35B-A3B

改动 2：激活 pi-ai 并内联公司网关路由

现在 cordis.patch.yml:107-108 是：

    - id: llm-pi-ai
      name: '@deepseek-ai/dsh-llm-pi-ai'

改成：

    - id: llm-pi-ai
      name: '@deepseek-ai/dsh-llm-pi-ai'
      config:
        providers:
          company-qwen:
            apiKeyEnv: API_KEY
            api: openai-completions
            baseURL: http://ai-network-qwen.top/v1
            models:
              - id: Qwen3.6-35B-A3B

第 3 步：选择工作区

工作区是 Agent 可以读取和编辑的项目目录。选中工作区之前，会话输入框不可用，因此必须先完成工作区选择。
操作：

1. 点击 选择工作区。
2. 添加启动 dsh 时所在的项目目录。
3. 选中这个目录。
4. 确认会话输入框已经变为可用状态。

第 4 步：发送第一个任务

启动一个会话并发送任务。可以先用这个任务验证 Web UI 是否正常工作：你好， 你是谁？！
Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。当操作在当前权限策略下需要审批时，Web UI 会先询问你。
操作：

1. 在会话输入框中发送上面的任务。
2. 观察 Agent 是否开始读取文件和执行命令。
3. 如果 Web UI 弹出审批请求，根据任务内容选择允许或拒绝。
4. 等待 Agent 输出最终回复。
   确认收到 Agent 的回复后，操作完成。

三 CLI 入门：用命令完成任务

前面已经通过 Web UI 完成了一次图形界面操作。这里解决一个更简单的问题：不打开浏览器，也能用一条命令让 dsh 完成项目任务。 学会打开终端和确认命令可用，然后认识两个日常入口—— dsh web 是打开网页版， dsh –profile headless "任务" 是直接提交一个一次性任务。接着明确这两种模式分别适合什么场景，再运行一次 headless 任务，观察最终答案和退出码。最后用“运行方案”的类比理解 profile。

实操步骤

上图是完整路径：打开终端后，只需要在“图形界面”和“一次性命令”之间选择一种方式，然后观察结果。下面按这张图逐步操作。
这里命令统一使用 npx @deepseek-ai/dsh 。如果源码运行，并且安装了 pnpm ，也可以把npx @deepseek-ai/dsh 换成 pnpm dsh ，后面的参数完全相同。

第 1 步：打开终端

macOS

1. 按下 Command + 空格 ，打开 Spotlight。
2. 输入 Terminal 或 终端 ，回车打开终端。
3. 也可以从访达进入： 应用程序 → 实用工具 → 终端 。
   Windows

打开 PowerShell 或者 cmd

第 2 步：确认命令可用

在任意目录执行：

pnpm dsh --help

pnpm dsh --version

或者

npx @deepseek-ai/dsh --help
npx @deepseek-ai/dsh --version

–help 打印启动器自身的帮助信息。
–version 打印启动器版本。
第一次使用 npx 时，它可能会询问是否安装 @deepseek-ai/dsh 包，输入 y 或按提示确认即可。
如果已经从源码运行并安装了 pnpm ，对应命令是 pnpm dsh –help 和 pnpm dsh –version 。
能看到帮助或版本号，说明 dsh 命令已经可以使用。

第 3 步：认识两种日常入口

暂时只需要记住两个命令：

命令	用途
npx @deepseek-ai/dsh web	打开网页版，适合浏览、审批和观察 Agent 的完整过程。
npx @deepseek-ai/dsh –profile headless "任务文本"	不打开网页，直接提交一个任务，适合自动化和脚本调用。

其中， dsh web 是 –profile web 的别名。可以把 profile 先理解成一种“运行方案”：
web ：带网页界面的方案。
headless ：无界面、一次性执行的方案。

第 4 步：明确两种模式的应用场景

学会使用方式后，关键是要知道什么时候选哪一种。选择标准是：这个任务是否需要你全程看着、点着、批着。
优先使用 web 的场景

1. 第一次配置模型、API Key 或工作区。
2. 需要观察 Agent 的思考、计划和工具调用过程。
3. 需要审批 Agent 的文件修改、命令执行等操作。
4. 需要调试 Agent 为什么没有按预期完成任务。
5. 你正在手工使用 Agent，随时可能和它继续对话。

优先使用 headless 的场景

1. 任务明确，不需要人工逐步审批。
2. 你只想要最终答案，不关心中间的图形界面。
3. 要在脚本、CI/CD、定时任务或批处理中调用 dsh 。
4. 要通过 stdout 和退出码把结果交给另一个程序继续处理。
5. 运行环境没有浏览器或图形界面，例如远程服务器、容器、自动化流水线。

简单记法：

1. 需要人看着、批着、调试着，选 web 。
2. 给一个任务、拿回一个结果、交给脚本用，选 headless 。
3. 如果任务运行过程中会不断弹出需要你确认的操作，先使用 web 完成；确认流程稳定、可以被当前权限策略自动处理后，再改成 headless 放入自动化。

第 5 步：用 CLI 打开 Web UI

执行：

pnpm dsh web

默认服务地址是：

http://127.0.0.1:3080

操作：

1. 在浏览器中打开命令打印的地址。
2. 确认页面可以正常打开。
3. 回到终端，按 Ctrl+C 停止 Web UI。
   这里只是把启动入口从图形操作改成了命令行。

第 6 步：运行 Headless 一次性任务

现在尝试不打开浏览器，直接让 dsh 完成一个任务。
执行：

pnpm dsh  --profile headless "用一句话说明当前目录下项目的主要功能"

这条命令会：

1. 把运行命令时所在的目录作为默认 workspace 根目录。
2. 创建一个全新的持久化 Agent。
3. 提交任务，并等待 Agent 完成。
4. 在 stdout 打印最终答案。
   第一次使用 headless 时，它会自动初始化这个运行方案。成功运行时不会打开监听端口。
   如果任务失败且提示与模型凭据有关，请确认秘钥模型是否正确配置

第 7 步：查看退出码

任务完成后，检查命令是否成功：
macOS / Linux

echo $?

Windows PowerShell

echo $LASTEXITCODE

Windows CMD

echo %ERRORLEVEL%

退出码含义：
0 ：最终原因是 completed ，任务正常完成。
1 ：最终原因不是 completed 。

第 8 步：完成本章验证

依次确认以下结果：

1. npx @deepseek-ai/dsh –help 能显示帮助信息。
2. 明白 web 和 headless 分别适合什么场景。
3. npx @deepseek-ai/dsh web 能启动 Web UI。
4. npx @deepseek-ai/dsh –profile headless "任务" 能在 stdout 输出最终答案。
5. headless 任务完成时，退出码为 0 。