Agent之Harness：deepseek-harness的简介、安装和使用方法、案例应用之详细攻略

从架构文档来看，运行中的 dsh 是一棵插件树，由 profile、bundle 和 patch 等层次组合而成。项目的各个组成部分，包括模型适配器、工具注册表、会话日志以及 Agent Loop，都以插件方式参与系统运行；dsh-base 提供模型适配器、工具、持久化、沙箱与审批策略、设置、凭据和遥测等基础能力，dsh-web-app 增加浏览器应用，dsh-headless 提供一次性运行器。项目同时通过 ctx.llm、ctx.tools、ctx.agents、ctx.agentLoop、ctx.fs、ctx.shell、ctx.jobs 等能力 seam 实现模块化扩展。

DeepSeek Harness 目前可以直接通过 npm 启动 Web UI，也可以从 GitHub 源码构建运行。仓库还提供开发指南和 Cookbook，具体覆盖新增工具、增加 LLM 适配器、增加 Web Client Conversation Node、增加 Package 等扩展方式，因此其使用方式不仅包括直接启动已有功能，也包括以插件形式向现有系统增加能力。

Github地址 ：https://github.com/deepseek-ai/deepseek-harness

1、特点

|------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 特点 | 详细说明 |
| 开源 Agent Harness | 项目 README 明确将 DeepSeek Harness 定义为由 DeepSeek AI 开发的开源 Agent Harness。(github.com) |
| 一切皆插件 | 模型适配器、工具注册表、会话日志、Agent Loop 等产品组成部分均以插件方式接入，插件可以通过注册和卸载改变系统能力。(github.com) |
| Cordis 驱动 | DeepSeek Harness 使用 Cordis 作为底层框架，插件向共享上下文贡献服务、类型化事件和可逆副作用。(github.com) |
| Profile 与 Bundle 组合 | 运行中的 dsh 通过 profile 和 bundle 逐层叠加，web 和 headless 作为模板随发行版提供，并允许继续应用用户自己的 patch。(github.com) |
| Web UI | 可以使用 npx @deepseek-ai/dsh web 启动 Web UI，默认服务地址为 http://127.0.0.1:3080。(github.com) |
| Headless 能力 | 架构文档说明 dsh-headless 提供一次性运行器，并且完全不带服务器。(github.com) |
| 工具扩展机制 | 可以通过 ctx.tools.register() 注册面向模型的工具，工具 schema 会自动进入系统提示词组装流程。(github.com) |
| LLM 适配器机制 | 可以实现 LlmAdapter 并通过 ctx.llm.registerAdapter() 注册新的模型提供方；仓库给出 llm-deepseek 和 llm-pi-ai 作为参考实现。(github.com) |
| 会话事件驱动 | 会话事件、Agent 事件和能力事件构成主要扩展点；会话日志是模型上下文的来源，并用于回放、fork、transcript、遥测和持久化等派生能力。(github.com) |
| Agent Loop | core/agent 提供 Agent 接口和活跃 Agent 注册表，core/agent-loop 提供默认驱动器。(github.com) |
| 工具执行流水线 | 项目提供 tools/pre-execute、tools/execute、tools/post-execute、tools/result 等扩展点，可分别用于策略控制、截止时间/重试/指标、结果处理以及结果观测。(github.com) |
| Shell、文件与 Sandbox 能力 | 架构文档将 shell、filesystem、subprocess、sandbox 等作为可替换能力 seam，并支持通过对应上下文注册实现。(github.com) |
| Web Client Conversation Node | 项目提供为 Web Client Chat 增加 Conversation Node 的完整教程，可将持久 Session 事件关联成 Context、逐步构造 State，并渲染类型化 Chat Node。(github.com) |
| MIT 许可证 | 仓库 README 标明项目采用 MIT License，第三方依赖及其许可证记录在 THIRD_PARTY_NOTICES.md。(github.com) |

deepseek-harness的安装和使用方法

1、安装

方式一：通过 npm 直接运行

项目 README 要求先安装 Node.js，然后直接通过 npm 的 npx 启动 Web UI：

复制代码

npx @deepseek-ai/dsh web

运行后，Web UI 默认提供在：

复制代码

http://127.0.0.1:3080

这是项目 README 明确给出的最快运行方式。

方式二：从源码构建

从仓库源码运行时，README 给出的完整流程是：

复制代码

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

其中，pnpm install 安装仓库依赖，pnpm run build 执行构建，最终通过 pnpm dsh web 启动 Web UI。

开发环境要求

仓库开发指南列出了源码开发所需的前置条件：Node.js 支持 22.19+ 与 24+；启用 Corepack 的 pnpm，仓库在 package.json 中固定使用 pnpm@11.7.0；Git 要求 2.26 或更高版本；DeepSeek API key 为可选项，用于 Web、headless 和 ACP 自动化 Agent 演示以及真实 API 的端到端测试。

如果使用 Corepack 后 pnpm 无法被解析，开发指南给出的处理命令是：

复制代码

corepack enable

新克隆仓库后，可以执行类型检查：

复制代码

pnpm run typecheck

文档说明该命令成功退出即可视为基础开发环境搭建完成。

2、使用方法

启动 Web UI

安装完成后，最直接的使用方式是：

复制代码

npx @deepseek-ai/dsh web

或者从源码构建完成后：

复制代码

pnpm dsh web

默认访问地址是：

复制代码

http://127.0.0.1:3080

项目 README 将 Web UI 指南作为进一步使用入口。

查看实际启动配置树

架构文档说明，可以使用：

复制代码

dsh --profile web --dump-config

该命令用于查看机器实际启动的配置树。文档指出，输出中的任意条目都可以通过用户自己的 patch 替换。

通过插件增加工具

项目的工具开发指南给出了最小工具实现形式。例如：

复制代码

import { readFile } from 'node:fs/promises'
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'


export const name = 'my-tool'
export const inject = ['tools']
export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a file from disk.',
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path' },
      limit: { type: 'number' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

项目文档说明，这类工具基于副作用注册；当插件 fiber 被 dispose 时，该工具也会被注销；工具 schema 会自动进入系统提示词组装流程。

工具执行还遵循统一的参数校验、结果 schema、取消信号以及错误处理约定。例如 execute() 接收经过 schema 校验的参数，工具应返回规范 JSON 值，并遵守 exec.signal 的取消信号。

增加新的 LLM 适配器

项目提供了新增模型提供方的标准方式。核心形式是实现 LlmAdapter：

复制代码

class MyAdapter extends LlmAdapter {
  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> { ... }
}

export const name = 'llm-myprovider'
export const inject = ['llm']
export const Config: z<Config> = z.object({ apiKey: z.string(), ... })
export function apply(ctx: Context, config: Config) {
  ctx.llm.registerAdapter(['my-provider'], new MyAdapter(...))
}

项目文档说明，可以使用 options.provider 选择适配器，options.model 表示提供方模型 ID；仓库给出的参考实现包括 packages/llm/llm-deepseek 和 packages/llm/llm-pi-ai。

使用会话事件和 Agent Loop

架构文档定义了一个轮次的基本流程：打开 turn，领取输入，组装 prompt 和工具 schema，进入 agent/pre-step，随后开始 step，并经历 agent/request → llm/stream → assistant/chunk* → assistant/message；如果调用工具，则继续经过 tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result*，最后结束 step 和 turn。

会话日志是模型所见上下文的来源。项目文档说明，deriveMessages() 从会话日志投影出模型历史，而原始 assistant/chunk 事件用于保证回放和 UI 的保真；fork、恢复、transcript、遥测和持久化等能力均从事件流派生。

deepseek-harness的案例应用

案例一：直接运行 Web UI

无需从源码构建时，安装 Node.js 后直接执行：

复制代码

npx @deepseek-ai/dsh web

项目 README 说明，该命令会启动 Web UI，默认服务地址为：

复制代码

http://127.0.0.1:3080

这个案例对应项目提供的最直接运行路径，用户不需要执行仓库构建流程即可通过 npm 启动 dsh 的 Web UI。

案例二：从源码构建并启动 DeepSeek Harness

对于需要从仓库源码运行的情况，项目 README 给出如下流程：

复制代码

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

该案例对应项目官方 README 给出的源码运行方式，依次完成代码获取、依赖安装、项目构建和 Web UI 启动。

案例三：开发一个文件读取工具插件

项目 Cookbook 以 read_file 为例展示工具插件的最小结构。插件首先声明 name 和 inject，然后通过 ctx.tools.register(defineTool(...)) 注册工具，定义参数 schema、输出 schema 和 execute() 实现。示例实现从磁盘读取文件，并将 exec.signal 传递给文件读取操作。

其中核心注册代码为：

复制代码

ctx.tools.register(defineTool({
  name: 'read_file',
  description: 'Read a file from disk.',
  parameters: {
    path: { type: 'string', required: true, description: 'Absolute path' },
    limit: { type: 'number' },
  },

  output: {
    schema: { type: 'string' },
    render: (_args, value) => [{ type: 'text', text: value }],
  },

  async execute(args, exec) {
    return readFile(args.path, {
      encoding: 'utf8',
      signal: exec.signal,
    })
  },
}))

项目文档还指出，工具 schema 会自动进入 prompt 组装过程；工具结果可以通过规范 JSON 值和独立的 render 机制分别服务于模型和 UI。

案例四：接入新的 LLM 模型提供方

项目提供完整的 LLM 适配器扩展路径。新提供方需要继承 LlmAdapter，实现异步流式 stream()，然后通过 ctx.llm.registerAdapter() 注册。

项目文档要求适配器处理流式协议，例如在 finish 之前提供 usage，工具调用参数在流中保持 JSON 字符串形式，按照首次出现顺序分配 block index，遵守 options.signal，并对不支持的 GenerateOptions 字段显式返回 UNSUPPORTED 错误。

案例五：在 Web Client Chat 中增加可回放的 Conversation Node

项目 Cookbook 给出了一个 review job 示例。该案例定义 review/start、review/progress 和 review/end 三类持久事件，以 reviewId 作为稳定身份，然后由 Client 端将这些事件组装成 Context、增量构建 State，并生成 review-job 类型的 Chat Node。

其中事件定义示例为：

复制代码

interface ReviewStartData {
  readonly reviewId: ReviewId
  readonly turn: number
  readonly step: number
  readonly title: string
}



interface ReviewProgressData {
  readonly reviewId: ReviewId
  readonly turn: number
  readonly step: number
  readonly completed: number
}


interface ReviewEndData {
  readonly reviewId: ReviewId
  readonly turn: number
  readonly step: number
  readonly summary: string
}

随后将这些事件注册到 SessionEventMap，再通过 ConversationNodeDefinition 将 review/start 作为 start、review/progress 和 review/end 作为 update，最终把状态渲染成 Web Client Chat 中的 review-job 节点。

案例六：通过 Profile、Bundle 和 Patch 定制运行时配置

DeepSeek Harness 的架构文档说明，运行中的 dsh 是一棵插件树。每个 profile 会保存自身叠放的 bundles、安装的树外插件以及 cordis.patch.yml；随后依次叠加 profile bundle、profile patch、home 级 patch 和命令行 --patch overlay。

可以先查看 web profile 的实际配置：

复制代码

dsh --profile web --dump-config

再利用自己的 patch 替换或新增配置条目。项目文档同时说明，dsh-base 是每个 profile 的第一层，提供模型适配器、工具、持久化、沙箱与审批策略、设置、凭据和遥测；因此该案例体现的是通过插件组合和 patch 机制调整运行时组成，而不是修改一个特权内核。