DeepSeek
Harness

DeepSeek Harness（简称 dsh）是由 DeepSeek AI 开发的开源 Agent Harness 框架。 它采用 "一切皆插件" 的架构设计，基于 Cordis 框架 构建—— Cordis 源自论文 "A Programming Paradigm for Spatiotemporal Composability"（一种时空可组合性的编程范式）， 提供了强大的依赖注入、服务注册和事件驱动能力。

快速启动

只需一条命令即可启动带 Web UI 的本地 Agent 服务：

npx @deepseek-ai/dsh web

启动后访问 http://127.0.0.1:3080 即可使用完整的 Web UI 界面。

它能做什么

DeepSeek Harness 的每一个设计决策，都围绕一个中心思想：让一切都可以被替换、组合和扩展。以下五大原则构成了框架的哲学基石。

事件分派模式一览

dsh 提供四种事件分派模式，满足不同的扩展需求：

Profile 与 Bundle

运行中的 dsh 实例是一个在启动时由有序层（layers）组合而成的插件树。

• Profile = 命名组合，列出 bundles + cordis.patch.yml（web 和 headless 作为模板发布）
• Bundle = Cordis 配置行的分发格式

组合层（从先到后）

dsh-base 是第一层，包含模型适配器、工具、持久化、沙箱、审批、设置、凭证、遥测等基础能力。 可以使用以下命令查看最终组合配置：

dsh --profile web --dump-config

核心包一览

Turn 执行流

Step = 一次模型请求 + 它调用的工具。Turn = 零个或多个 Step。 一个完整的 Turn 流程如下：

能力接缝（Capability Seams）

以下是 dsh 暴露的主要能力接缝及其内置提供者。每个接缝都遵循"接口与实现分离"的原则，提供者可自由替换。

Host / Client 双架构

dsh 采用隔离的 Host 和 Client 双 TypeScript 聚合体：

本章是全文最核心的部分。我们将逐一拆解 DeepSeek Harness 的五大核心机制，每个概念都配有生活类比，帮助你在理解技术细节之前先建立直觉。

一、事件分派模式详解

Waterfall 语义与中间件模式

Waterfall 事件是 dsh 中最强大的扩展机制。它允许插件像中间件一样包装核心流程： 每个监听器收到当前值后，可以在调用 next() 前后插入自定义逻辑。

// 中间件模式：拦截模型请求并修改
ctx.on('agent/request', (payload, next) => {
  // before：修改 payload
  const modified = { ...payload, temperature: 0.7 }

  return next(modified).then(result => {
    // after：处理返回结果
    return result
  })
})

二、会话日志系统（Session Log）

三、工具执行管线

每次工具调用都经过五个阶段的管线：

• tools/pre-execute：执行前拦截，可用于审批、参数校验、沙箱策略注入
• monotonic guard：单调性保护，防止重复执行或时序冲突
• tools/execute：实际执行工具逻辑
• tools/post-execute：执行后处理，可用于结果转换、日志记录
• result observation：结果写入会话日志，对模型可见

四、权限与审批

权限系统基于 approval/request waterfall 事件实现。当工具需要审批时触发该事件， 审批策略监听器可以允许、拒绝或要求用户确认。

五、上下文压缩（Context Compaction）

当会话历史超过模型上下文窗口时，compaction-basic 插件自动压缩历史。 其中 toolResultPruner 负责裁剪过期的工具调用结果，以释放上下文空间。 压缩对模型是透明的——模型感知不到压缩发生，只看到正常的对话历史。

DeepSeek Harness 不只是一个代码工具。得益于"一切皆插件"的架构，它能胜任从日常开发到复杂自动化、从单机协作到云端隔离的各种任务。

六大核心场景

使用模式对比

沙箱场景

典型工作流时间线

市面上的 Agent 框架各有侧重。选型时，关键不在于哪个"最好"，而在于哪个最适合你的需求。下面用汽车来类比，帮你快速建立直觉。

综合对比表

逐一详评

不需要复杂的安装过程。根据你的使用场景，选择最合适的一条路径即可开始。

路径一：npm 快速启动

最快的方式，无需克隆仓库，一行命令启动 Web UI：

# 启动 Web UI 模式
npx @deepseek-ai/dsh web

# 启动后打开浏览器访问：
# http://127.0.0.1:3080

启动后的配置流程：

1. 在 Settings → Models 中配置 API Key
2. 选择你要使用的工作区目录
3. 在聊天框中输入任务，开始执行

路径二：源码构建

适合需要深度定制或参与开发的用户：

# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 安装依赖
pnpm install

# 构建
pnpm run build

# 启动
pnpm dsh web

路径三：Python SDK

适合在 Python 脚本或自动化流水线中集成：

pip install deepseek-harness-sdk

from pathlib import Path
from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run("Fix the failing tests.", session_id="example-001")
    print(result.final_response)

环境变量

什么是插件

插件是一个导出 apply 函数的 TypeScript 模块。框架在加载时调用 apply， 并传入 ctx 上下文对象。通过 ctx，插件可以注册服务、监听事件、声明依赖。

三种插件形式

第一个插件：hello-plugin

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

在 cordis.yml 中注册插件：

plugins:
  hello-plugin:
    path: ./hello-plugin.ts

使用 patch 方式加载运行：

pnpm dsh web --patch ./cordis.yml

工具开发：greet 工具

使用 defineTool 定义类型安全的工具：

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true }
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }]
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    }
  }))
}

关键概念

• inject：声明依赖的服务键，框架在服务就绪后自动注入
• defineTool：类型安全的工具定义辅助函数，提供参数/输出类型推导
• ctx.effect()：注册清理副作用，插件卸载时自动调用
• 自动清理：所有通过 ctx 注册的资源在插件卸载时自动回收

新行为的归属指南

掌握了基础概念和插件开发后，以下高级主题将帮助你更深入地发挥 Harness 的全部潜力。

Agent Presets

Agent Presets 是按会话作用域组合能力的机制。每个 preset 对应一个 cordis.yml， 挂载在 Agent 作用域下，为特定会话定制可用工具、模型和行为策略。

Skills 系统

ctx.skills 提供技能目录服务。tool-skill 插件将技能目录渲染为会话前缀， 让模型了解可用的技能集合。skill-filesystem 提供者从文件系统加载技能定义。

Goal Management

ctx.goals 从会话日志中折叠出带版本管理的目标状态。目标可以被 Agent 追踪、更新和完成， 为复杂任务提供结构化的进度追踪能力。

Workflow Engine

ctx.workflowEngine 提供工作流引擎。tool-workflow 和 tool-ralph 插件支持结构化工作流，允许定义多步骤、有状态的复杂任务执行流程。

LSP 集成

ctx.lsp 提供语言服务器协议（LSP）集成。lsp-local 提供者在本地运行语言服务器， 为 Agent 提供代码补全、诊断、定义跳转等能力，大幅提升编程辅助体验。

遥测

ctx.sessionTelemetry 支持 OpenTelemetry 标准的遥测导出。可以将会话指标、工具调用延迟、 模型请求耗时等数据导出到可观测性平台。

自修改系统

推荐学习路径

继续深入：

1. 探索能力接缝（Capability Seams）——尝试替换 ctx.fs 或 ctx.shell 提供者
2. 构建自定义 Profile 组合——用 --patch 挂载你的插件配置

资源链接