【deepseek-harness】DeepSeek Harness 开源项目深度介绍

张忠琳

680人浏览 · 2026-08-19 06:27:27

张忠琳 · 2026-08-19 06:27:27 发布

DeepSeek Harness 开源项目深度介绍

1. What：这是什么项目

项目定位

DeepSeek Harness（简称 dsh）是由 DeepSeek AI 开发的开源智能体框架（Agent Harness），项目仓库位于 github.com/deepseek-ai/deepseek-harness，采用 MIT 许可证开源。

其核心定位是：一个以"一切皆插件"为架构原则的 AI Agent 运行时框架。它不是单一编码助手，而是一个可组装、可替换、可扩展的智能体基础设施，用于构建各类 LLM 驱动的自主任务执行系统。

框架底层由 Cordis 插件框架驱动，Cordis 的设计理念参见论文《A Programming Paradigm for Spatiotemporal Composability》。

核心能力与主要特性

全插件架构：模型适配器、工具注册表、会话日志、Agent 循环本身均为插件，所有组件均可通过配置替换，不存在特权核心。
多模型适配：内置 DeepSeek 模型适配器（支持 deepseek-v4-pro / deepseek-v4-flash），支持 OpenAI 兼容端点扩展，可配置多模型路由。
工具执行管道：结构化的工具调用流水线，支持前置策略拦截、沙箱守卫、审批流程、超时重试、结果规范化、后置处理等完整链路。
会话持久化：追加写入的 SessionEvent 日志模型，支持会话分叉（fork）、恢复（resume）、上下文压缩（compaction）和回放重放。
子代理委托：支持 spawn（全新子会话）和 fork（继承历史分叉）两种子代理模式，支持后台任务和工作流编排。
沙箱安全策略：文件系统写入隔离、进程执行限制、审批策略分级（workspace-write / read-only / danger-full-access）。
Web UI 与无头模式：内置浏览器交互界面（默认端口 3080），也支持 headless 一次性任务执行和 ACP（Agent Client Protocol）自动化服务。
** Capability Seam 设计**：每个能力由三角色构成——Service Definition（接口声明）、Service Provider（实现）、Consumer（消费方），角色可独立演进。
跨平台支持：POSIX 系统提供 bash 沙箱执行链，Windows 系统通过 ACL 受限令牌实现等价安全策略。
Python SDK：提供 Python SDK 和捆绑运行时，支持通过 Python 调用框架能力。

适用场景

编码助手平台搭建：构建可读写文件、执行命令、运行测试的 AI 编码智能体。
自动化任务编排：通过子代理委托和工作流引擎实现多步骤、多代理协作的复杂任务自动化。
LLM 应用基础设施：作为底层运行时，为上层 LLM 应用提供会话管理、工具调用、安全沙箱等基础设施。
Agent 协议对接：通过 ACP（Agent Client Protocol）JSON-RPC 接口，将 Agent 能力暴露为标准化服务。
插件生态开发：开发自定义工具、模型适配器、能力提供者，扩展框架功能边界。

2. Why：为什么选择这个项目

现存痛点与诞生背景

当前 AI Agent 领域面临几个核心痛点：

框架耦合严重：多数 Agent 框架将模型调用、工具执行、会话管理硬编码在核心循环中，扩展新能力需要修改框架本体，维护成本高。
能力替换困难：切换模型提供商、更换沙箱策略、替换文件系统实现时，往往需要 fork 框架或编写大量适配代码。
会话状态管理粗放：缺乏精确的会话事件日志，难以实现可靠的回放、分叉、上下文压缩等关键操作。
安全边界模糊：工具执行缺乏统一的安全策略管道，沙箱隔离与审批流程实现各自为政。
多代理协作缺乏基础设施：子代理委托、工作流编排等能力需要开发者从零构建。

DeepSeek Harness 正是为解决这些问题而生：通过 Cordis 插件框架的"一切皆插件"理念，将每个能力拆解为可独立替换的插件单元，同时提供完整的工具执行管道、会话日志模型和安全沙箱策略。

项目优势与差异点

对比维度	DeepSeek Harness	LangChain	AutoGPT	Claude Code
架构模式	全插件架构，无特权核心	链式调用，模块化	单体应用	封闭产品
能力替换	配置文件替换，零代码修改	需要编写适配代码	修改源码	不支持
会话模型	追加写入事件日志，可回放分叉	内存状态为主	简单持久化	封闭
安全策略	结构化沙箱管道，分级审批	无内置安全策略	无	内置但封闭
插件开发	Cordis 标准化插件协议	自由格式	无标准	不支持
子代理	spawn/fork 双模式	需自行实现	无	无
开源协议	MIT	MIT	MIT	闭源

核心差异点：

Registration as Effect：所有注册（工具、提示段落、适配器、监听器）都是可逆副作用，插件卸载时自动回滚，保证干净的运行时状态。
Typed Events：通过 TypeScript 声明合并定义类型化事件，支持 emit / waterfall / parallel / serial 四种分发模式，事件契约即文档。
Capability Seam：每个能力由 Service Definition / Provider / Consumer 三角色构成完整链路，一个 Provider 替换即可改变整条能力链。
Model-Visible ⟺ Logged：任何到达模型请求的内容都必须可从会话日志重建，运行时不变量强制保证。

适合人群与不适合场景

适合：

需要构建可定制 AI Agent 平台的工程团队
对插件化架构和可组合性有要求的 LLM 应用开发者
需要精确控制工具执行安全策略的场景
希望基于 DeepSeek 模型构建 Agent 能力的开发者

不适合：

只需简单 LLM 问答、不需要工具调用的场景（过重）
对 TypeScript / Node.js 技术栈不熟悉的团队（框架基于 Node.js 22+ / TypeScript 6）
需要生产级稳定性的场景（项目目前处于 Developer Preview 阶段，明确声明会有破坏性变更）
需要接受外部 PR 贡献的开源协作者（项目当前不接受外部 Pull Request）

3. How：核心工作原理

DeepSeek Harness 的运行时由 Cordis 插件框架驱动，其核心工作原理可以归纳为以下几个层次：

插件与上下文

框架启动时，根据 Profile（配置组合）加载有序的 Bundle 层，构建插件树。每个插件是一个实现 Service 接口的对象，通过 apply(ctx) 方法挂载到共享上下文（Context）。插件通过 inject 声明依赖的服务键（如 ctx.tools、ctx.llm），框架按服务依赖关系自动排序加载，无需手动编排启动顺序。

事件驱动通信

插件间通信通过类型化事件完成。事件分为四种分发模式：

emit：观察型广播，监听者依次接收，无返回值。
waterfall：环绕中间件，监听者通过 next() 委托给下一个，可拦截或包装结果。
parallel：并行通知所有监听者。
serial：串行有序执行，有返回值。

分发模式是事件公共契约的一部分，在生成的目录中通过 @mode 标签声明并校验。

Agent 循环

Agent 的核心执行流程分为 Turn（轮次）和 Step（步骤）两个层级：

Turn：一次输入消费周期，从获取第一条输入开始，到模型和工具都停止或策略干预时结束。
Step：一次模型请求加其引发的工具调用，一个 Turn 包含零或多个 Step。

执行流程：用户输入 → turn/start → 声明待处理输入 → agent/pre-step（waterfall，可拒绝或改写）→ step/start → 组装系统提示和工具 schema → agent/request → llm/stream（模型流式响应）→ assistant/chunk* → assistant/message → tool/call* → 工具执行管道 → tool/result* → step/end → 判断是否需要下一步 → turn/end。

工具执行管道

工具调用经过结构化流水线：tools/pre-execute（前置策略、权限、沙箱）→ 单调守卫（deny/abstain）→ ctx.approval（一次性审批提示）→ tools/execute（超时、重试、指标）→ 工具执行体 → 文件系统守卫 → tools/post-execute（接受/阻止/替换/追加上下文）→ 结果规范化 → finalizeContent → tools/result（不可变结果通知）。

会话日志

会话日志是模型可见内容的唯一真相来源。deriveMessages() 从日志事件投影出模型历史。所有模型可见内容必须被记录（Model-Visible ⟺ Logged），这是运行时不变量强制保证的。分叉、恢复、压缩、遥测都从此事件流派生。

4. 总体架构

核心组件解析

ctx.llm（LLM 适配器）
模型调用抽象层。定义消息词汇表和流式响应接口，插件通过注册适配器接入不同模型提供商。内置 dsh-llm-deepseek 适配器支持 DeepSeek 系列模型，支持 thinking 模式和 reasoningEffort 调节。agent/request 和 llm/stream 两个 waterfall 事件允许插件拦截和包装模型请求与响应。

ctx.tools（工具注册表与执行管道）
管理所有模型可见工具的注册、schema 汇编和执行。工具注册时声明执行模式（并行/屏障）、UI 渲染意图（generic/terminal/diff）。执行管道串联 pre-execute → 守卫 → 审批 → execute → post-execute → finalize → result 全链路，每个环节可被插件拦截或增强。

ctx.sessions（会话事件日志）
追加写入的事件日志存储，是整个系统的真相来源。SessionEvent 包含 user/message、assistant/chunk、assistant/message、tool/call、tool/result、turn/start、turn/end、step/start、step/end 等类型。deriveMessages() 从日志投影模型历史，保证回放一致性。支持 zstd 压缩存储。

ctx.agentLoop（Agent 驱动器）
实现 Agent 接口的默认驱动器，执行 Turn/Step 循环。通过 agent/pre-step waterfall 决定模型可见内容，agent/turn-stopping serial 事件提供终止检查点。支持输入队列、上下文注入、目标轮次（goal round）等机制。

ctx.systemPrompt（系统提示组装）
负责在每次 Step 前组装系统提示段落和工具 schema。插件通过注册提示段落贡献者（prompt section contributor）向系统提示注入内容，工具 schema 在组装时自动汇总已注册工具。

ctx.fs / ctx.shell / ctx.sandbox（执行能力三件套）
文件系统、Shell 执行和沙箱策略构成工具执行的物理能力层。三者共享同一沙箱策略：workspace-write 限制写入到工作区和临时目录，read-only 禁止写入，danger-full-access 放开限制。文件系统守卫在 fs/write-intent 和 fs/edit-intent 事件上实施写前检查。

ctx.subagent（子代理能力）
提供 spawn（全新子会话）和 fork（继承已完成历史分叉）两种子代理模式。spawn 模式子代理不继承父会话上下文，通过共享工作区和结构化报告（Ralph handoff）传递状态。fork 模式继承会话历史，适合延续性任务。

ctx.approval（审批服务）
工具执行前的交互式审批机制。在 tools/pre-execute 之后、单调守卫之前触发，支持 one-shot 审批提示。策略可配置为 never（不审批）或 ask（逐次询问）。

数据流转流程

用户输入 → 进入 Agent inbox 队列
Turn 启动 → 驱动器声明待处理输入，触发 turn/start 事件
Pre-step 拦截 → agent/pre-step waterfall 链处理，可拒绝或改写消息
Step 启动 → 写入 user/message 事件，组装系统提示和工具 schema
模型请求 → agent/request → llm/stream waterfall → 模型流式响应 → assistant/chunk* → assistant/message 事件
工具调用 → 模型响应中包含 tool-call → tool/call 事件 → 工具执行管道 → tool/result 事件
Step 结束 → 判断是否需要下一步（工具欠请求 or 新输入到达）
Turn 结束 → turn/end 事件 → Agent 状态转为 idle
持久化 → 全程事件写入 JSONL 日志，支持回放、分叉、压缩

5. 部署与安装

前置环境要求

依赖	版本要求	说明
Node.js	^22.19.0 或 >=24.0.0	CI 覆盖 22.19、24、26 版本
pnpm	11.7.0	通过 Corepack 启用：`corepack enable`
Git	>=2.26	支持 worktree 特定配置扩展
DEEPSEEK_API_KEY	可选	Web UI、headless、ACP demo 和真实 API e2e 测试需要

方式一：通过 npx 快速启动（推荐新手）

# 安装 Node.js 22+ 后直接运行，无需克隆源码
npx @deepseek-ai/dsh web

# 该命令会自动安装并启动 Web UI，默认地址 http://127.0.0.1:3080
# 首次启动后在 Settings → Models 中配置 DeepSeek API Key

方式二：从源码构建运行

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

# 2. 启用 Corepack 并安装依赖
corepack enable
pnpm install
# postinstall 会自动配置 Lefthook Git hooks

# 3. 构建项目（tsc 类型检查 → tsdown 打包 → Web 前端构建）
pnpm run build

# 4. 启动 Web UI
pnpm dsh web
# 默认地址 http://127.0.0.1:3080

# 5. 启动 Headless 一次性任务（需要 API Key）
export DEEPSEEK_API_KEY=sk-your-key-here
pnpm dsh --profile headless "summarize this workspace"

# 6. 启动 ACP 自动化服务（需要 API Key）
pnpm run demo:acp

方式三：开发模式

# 克隆并安装依赖后，运行类型检查确认环境就绪
pnpm run typecheck

# 开发模式启动 Web UI（热更新）
pnpm run dev:web

# 运行单元测试
pnpm run test

# 运行覆盖率测试（CI 标准：每个文件 100%）
pnpm run test:coverage

# 运行 e2e 测试（需要 DEEPSEEK_API_KEY，无 Key 自动跳过）
pnpm run test:e2e

# 代码检查
pnpm run lint

# 完整检查套件
pnpm run check:all

方式四：Python SDK

# 参考 docs/user/guide/python-sdk.md 安装 Python SDK
# 项目包含 python/ 目录，提供 Python SDK 和捆绑运行时
cd python/
# 具体安装步骤参见 python/README.md

环境变量配置

# 必需：DeepSeek API Key（Web/headless/ACP demo 使用）
export DEEPSEEK_API_KEY=sk-your-key-here

# 可选：自定义 API 端点（默认为官方 API）
export DEEPSEEK_BASE_URL=https://api.deepseek.com

# 可选：权限模式覆盖（默认 workspace-write）
export DSH_PERMISSION_MODE=danger-full-access

# 也可在仓库根目录创建 .env 文件（已被 .gitignore 忽略）
# .env 内容示例：
# DEEPSEEK_API_KEY=sk-your-key-here
# DEEPSEEK_BASE_URL=https://api.deepseek.com

部署后验证

# 1. 验证 Web UI 启动：浏览器访问 http://127.0.0.1:3080
#    应看到会话界面，进入 Settings → Models 配置 API Key

# 2. 验证 Headless 模式：
pnpm dsh --profile headless "echo hello"
# 应输出模型对任务的响应

# 3. 验证构建完整性：
pnpm run typecheck  # TypeScript 类型检查通过
pnpm run build      # 完整构建通过

# 4. 查看实际加载的插件树：
pnpm dsh --profile web --dump-config
# 输出当前 profile 组合的所有插件行及其配置

6. 快速上手使用实战

实战一：Web UI 编码助手

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

启动后操作步骤：

打开浏览器访问 http://127.0.0.1:3080
进入 Settings → Models，输入 DeepSeek API Key 并保存
点击 Choose workspace，添加并选择你的项目目录
新建会话，输入任务指令，例如：

总结这个仓库并识别主要包结构

Agent 将能够读写工作区文件、执行命令、运行测试、委托子任务，在需要审批的操作前会询问用户。

实战二：Headless 一次性任务

# 设置 API Key
export DEEPSEEK_API_KEY=sk-your-key-here

# 在项目目录中执行一次性编码任务
pnpm dsh --profile headless "read package.json and list all workspace packages"

# 输出直接打印到 stdout，适合脚本集成

实战三：ACP 自动化服务

ACP（Agent Client Protocol）通过 JSON-RPC stdio 暴露 Agent 能力，适合与编辑器或 CI 集成。

# 启动 ACP 服务
pnpm run demo:acp

# 服务通过 stdio 接收 JSON-RPC 请求，创建并管理 Agent 会话

关键配置文件示例

Profile 配置（cordis.yml）

以下是一个完整的 headless agent 配置示例（基于 examples/headless-agent/cordis.yml）：

# DeepSeek 模型适配器配置
- id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
  config:
    thinking: enabled          # 启用思考模式
    reasoningEffort: max       # 推理强度：max
    models:
      - id: deepseek-v4-pro
        contextWindow: 128000
      - id: deepseek-v4-flash
        contextWindow: 128000

# 子进程管理（bash 执行器底层依赖）
- id: subprocess
  name: '@deepseek-ai/dsh-subprocess-local'

# Bash 执行器
- id: bash
  name: '@deepseek-ai/dsh-bash-local'
  config:
    timeoutMs: 60000           # 命令超时 60 秒

# Agent 骨架配置
- id: agent-spine
  name: '@deepseek-ai/dsh-agent-spine-demo'
  config:
    agents:
      - id: main
        provider: deepseek-official
        model: deepseek-v4-flash
        cwd: !!js process.cwd()
    workspaceContext:
      maxBytes: 65536           # 工作区上下文最大 64KB
    persona: |
      You are a coding assistant powered by the {{model}} model.
      Verify your work by running the code or tests. Keep answers brief.

# 会话持久化
- id: persistence
  name: '@deepseek-ai/dsh-session-persistence-jsonl'
  config:
    root: './.sessions'
    compression: zstd           # zstd 压缩存储

# 上下文压缩
- id: compaction-basic
  name: '@deepseek-ai/dsh-compaction-basic'
  config:
    thresholdRatio: 0.8         # 上下文窗口使用达 80% 触发压缩
    retainRatio: 0.16           # 保留最近 16% 内容
    maxTokens: 8192             # 压缩摘要最大 token 数
    compactionRetries: 1        # 压缩失败重试次数

# 子代理能力
- id: subagent
  name: '@deepseek-ai/dsh-subagent'
- id: subagent-spawn-in-process
  name: '@deepseek-ai/dsh-subagent-spawn-in-process'
  config:
    providerName: spawn

# 子代理委托工具
- id: tool-subagent
  name: '@deepseek-ai/dsh-tool-subagent'
  config:
    provider: spawn
    toolName: subagent
    backgroundMode: continuable  # 可继续的后台子代理
    maxDepth: 1                  # 最大委托深度

# 文件系统
- id: fs-local
  name: '@deepseek-ai/dsh-fs-local'
  config:
    cwd: !!js process.cwd()

- id: fs-observation-policy
  name: '@deepseek-ai/dsh-fs-observation-policy'

- id: tool-fs
  name: '@deepseek-ai/dsh-tool-fs'

常用命令

# 查看当前 profile 的插件组合树
pnpm dsh --profile web --dump-config

# 运行自引用 Cordis demo（Agent 可检查和修改自己的运行时插件）
pnpm run demo:cordis

# 运行 mock LLM 服务器（测试用）
pnpm run mock:llm

# 生成文档站点
pnpm run docs:build

# 清理构建产物
pnpm run clean

常见踩坑点

Node.js 版本不匹配：框架要求 Node.js 22.19+ 或 24+，使用 Node 20 或更低版本会报错。通过 node --version 确认。
pnpm 版本错误：仓库锁定 pnpm@11.7.0，未通过 Corepack 启用可能导致版本不一致。运行 corepack enable 后再 pnpm install。
API Key 未配置：Web UI 启动后如果未在 Settings → Models 中配置 Key，模型请求会失败。Headless 模式需要设置 DEEPSEEK_API_KEY 环境变量或根目录 .env 文件。
沙箱权限不足：默认 workspace-write 模式限制写入到工作区目录，如果 Agent 需要操作工作区外文件会收到 [sandbox: file access denied] 错误。这是策略行为而非 bug，可通过 DSH_PERMISSION_MODE 环境变量调整。
Windows 平台 bash 不可用：bash 执行链在 Windows 上自动禁用（disabled: !!js process.platform === 'win32'），改用 pwsh 执行链。如需在 Windows 上使用 bash，需在 profile patch 中同时禁用 pwsh 行和启用 bash 行。
插件冲突：同时挂载 dsh-fs-local 和 dsh-fs-sandbox 会因 ctx.fs 重复注册导致加载失败。框架设计为 fail-loud，会在启动时报错而非静默降级。
会话格式不兼容：项目处于 Developer Preview 阶段，SESSION_FORMAT_VERSION 保持为 0，不承诺向后兼容。升级版本后旧的会话日志可能无法加载。
cordis.yml 中的 !!js 语法：仅 config 字段和 disabled 字段支持 !!js 表达式插值，其他元数据保持字面量。条件组合应使用 overlay 而非在非支持字段中使用表达式。

7. 总结与展望

项目价值总结

DeepSeek Harness 的核心价值在于提出了一种全插件化的 AI Agent 运行时范式：

架构层面：通过 Cordis 框架的 Service/Context/Event 模型，将 Agent 的每个能力拆解为可独立替换的插件单元，消除了传统框架中的核心耦合问题。
工程层面：结构化的工具执行管道、追加写入的会话事件日志、分级沙箱策略、类型化事件契约等设计，为构建生产级 Agent 系统提供了扎实的工程基础。
生态层面：Capability Seam 的三角色设计（Definition / Provider / Consumer）为插件生态提供了清晰的扩展契约，社区开发者可以针对任一角色贡献实现。

项目当前版本为 0.1.0-rc.5，处于 Developer Preview 阶段，由 DeepSeek AI 团队维护。

社区信息

GitHub：github.com/deepseek-ai/deepseek-harness
许可证：MIT
社区讨论：GitHub Discussions
Discord 社区：DeepSeek Harness Discord
插件生态：GitHub 话题 dsh-plugin 标记插件仓库
贡献说明：项目当前不接受外部 PR，但鼓励通过插件开发、bug 报告、博客文章等方式参与社区

版本与后续发展方向

当前状态：Developer Preview（v0.1.0-rc.5），快速迭代中，明确声明会有破坏性兼容性变更
会话格式：SESSION_FORMAT_VERSION 保持 0，无兼容性承诺
后续方向（基于项目文档和架构推断）：
- 稳定会话格式版本，提供向后兼容保证
- 扩展模型适配器支持（更多 OpenAI 兼容端点）
- 完善 Windows 平台支持（当前通过 ACL 实现沙箱）
- 开放外部贡献通道
- 丰富插件生态（社区插件通过 dsh-plugin 话题发现）
- Python SDK 功能完善
- 沙箱策略增强（E2B 远程沙箱 POC 已在 packages/e2b 中）