DeepSeek Harness 全景

1. 基本信息#

2. 快速体验#

# 方式一：通过 npm 直接运行，需要已安装 Node.js
npx @deepseek-ai/dsh web
# 默认在 http://127.0.0.1:3080 启动 Web UI；在本机运行时会自动打开浏览器

# 方式二：从源码运行
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install && pnpm run build
pnpm dsh web

以上取自 README³。仓库里还有一个 Electron 桌面应用（apps/desktop），它会把与之精确匹配的 dsh 运行时一起打包进去⁵。

3. 架构总览#

3.1 Profile 与组合包：运行中的 dsh 是一棵插件树#

一个运行中的 dsh 是一棵插件树，由启动时按顺序叠加的若干层组合而成⁵：

一条 patch 可以按 id 找到某个条目并替换它的整个 config，也可以插入新的条目⁵。

以上取自架构文档⁵。dsh-base 是这些 profile 共享的第一层，包含模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测⁵。

3.2 核心包#

以上取自架构文档⁵。

3.3 Agent 预设（Preset）#

dsh-web-app 组合包随附了三个 agent preset，分别定义在 presets/*.patch.yml 中¹⁰：

- insert:
    - id: preset-minimal
      name: '@deepseek-ai/dsh-agent-preset'
      config:
        id: minimal
        order: 3
        plugins:
          - id: persona
            name: '@deepseek-ai/dsh-persona'
            config:
              prefix: You are a helpful software engineer assistant.
              complete: true
              includeRuntimeContext: false

4. 模型#

• 官方的 DeepSeek 适配器 dsh-llm-deepseek 通过 provider: deepseek-official 选择路由，模型 id 会原样传给 API，所以 DeepSeek 推出新模型时不需要重新注册¹¹。
• 不显式配置模型列表时，默认的模型目录里有两个条目，上下文窗口都是 1,000,000 token¹¹：
  • 支持文本和图像的 deepseek-flash；
  • 只支持文本的 deepseek-v4-pro。
• SDK 示例里用的是 model: 'deepseek-v4-flash'，推理强度可以设为 max 等档位¹²。
• 多厂商：dsh-llm-pi-ai 适配器借助 pi-ai，把请求路由到多个 pi-ai 提供方、兼容 OpenAI 的网关或自托管服务器。它的 package 描述称自己是官方 DeepSeek 适配器的设计验证孪生¹³。

5. 与外部生态的互通#

以上取自各包 package.json 的 description 字段⁶。

6. 两个 SDK：用代码驱动 DSH#

两个 SDK 都会以子进程方式启动一个完整的 DSH 运行时，再通过 stdio JSON-RPC 驱动它。两者共用同一个运行时和同一套协议¹²¹⁵。

写法一：仓库源码（commit 5badb15）中 README 的写法。 只需给出 profile，客户端会自动找到同版本的 @deepseek-ai/dsh 可执行文件¹²：

// 片段（no-check）：这是仓库源码 README 的写法，npm 上的 0.0.1-rc.1 还不支持 profile 选项
import { DeepSeekHarness } from "@deepseek-ai/dsh-sdk-client";

await using harness = new DeepSeekHarness({
  profile: "sdk",
  provider: "deepseek-official",
  model: "deepseek-v4-flash",
  maxTokens: 49_152,
});
const result = await harness.run("检查这个仓库，修复失败的测试。");
console.log(result.finalResponse);

写法二：npm 上 @deepseek-ai/dsh-sdk-client 0.0.1-rc.1 的写法。 需要用 launch 显式指定运行时子进程怎么启动。下面的代码取自该版本 npm 包自带的 README¹⁶，已对照这个版本做过类型检查：

import { DeepSeekHarness } from "@deepseek-ai/dsh-sdk-client";

// 子进程在第一次使用时才启动；close() 或 await using 会回收它
await using harness = new DeepSeekHarness({
  launch: { command: "node", args: ["lib/bin.js", "cordis.yml"] }, // 运行时可执行文件，以及要加载的插件配置
  provider: "deepseek-official",
  model: "deepseek-v4-flash",
  maxTokens: 49_152,
});
const result = await harness.run("say hi");
console.log(result.finalResponse); // 这段时间内根会话最后提交的 assistant 文本
console.log(result.events.length, "个事件");

from pathlib import Path

from deepseek_harness import DeepSeekHarness

workspace = Path("/absolute/path/to/disposable-workspace").resolve()
dsh_home = Path("/absolute/path/to/example-dsh-home").resolve()
with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    dsh_home=str(dsh_home),
    profile="sdk-minimal",
) as harness:
    result = harness.run("Inspect the repository and fix the failing tests.", session_id="example-001")

print(result.final_response)

这是官方 Python SDK 指南中的示例¹⁵。Python 的运行时 wheel 里已经打包了 dsh CLI，所以普通的 SDK 运行不需要系统里装有 Node.js¹⁵⁵。

7. “轻量”的两面#

笔者用 find 加 wc -l 粗略统计了 src/ 下非测试的 .ts 和 .tsx 文件：

第三方评测在发布之初给出的数字是约 45.3 万行、约 219 个 workspace 包⁹。

笔者理解：

• 如果把“轻量”理解成“代码少”，DSH 并不轻量。
• 但如果理解成“核心小、每样东西都能拔掉、能替换”，它可以说是最彻底的轻量设计：一个最小可用的 agent 只需要 sdk-minimal 这一个组合包。
• 这与 pi 的取向一致：核心不做，交给插件或扩展去做。区别在于，pi 用的是“扩展 API”，DSH 用的是“依赖注入加可逆副作用的组合框架”。

小结#

• DSH 的关键词：一切皆插件（Cordis）、profile 和 bundle 层层叠加、session log 是唯一事实来源、fail-closed 沙箱、广泛互通。
• 它目前仍是开发者预览版，适合学习架构、做实验、开发插件；不适合直接用于生产。
• 继续阅读：5.2 Cordis 与一切皆插件 讲框架原理；5.3 DSH 核心机制与插件开发 讲事件日志、工具流水线、沙箱，以及动手写插件。

相关笔记#

• 1.1 从 LLM API 到 Agent Harness 的分层
• 5.2 Cordis 与一切皆插件 · 5.3 DSH 核心机制与插件开发
• 对照：4.1 pi 全景与设计哲学 · 3.3 Claude Agent SDK

参考资料#