DeepSeek Harness 全景技术解析-Day23

一、项目概述与定位

DeepSeek Harness （命令行名 dsh）是 DeepSeek AI 于 2026 年 8 月 13 日正式开源的 Agent 运行时框架。它并非一个新的基础模型，也不是简单的 API 客户端，而是位于大语言模型与真实世界执行环境之间的基础设施层。官方给出的定义极为简洁：

Model + Harness = Agent

模型负责思考与推理，Harness 负责调度工具、管理任务、执行闭环、记录轨迹------相当于 AI 的"执行操作系统"。

属性	内容
项目名称	DeepSeek Harness (`dsh`)
当前版本	v0.1 Developer Preview
开源协议	MIT
技术栈	TypeScript / Node.js / pnpm Monorepo
底层框架	Cordis（时空调度可组合元框架）
核心设计	Everything is a Plugin（一切皆插件）
快速启动	`npx @deepseek-ai/dsh web`（默认端口 3080）
Node 要求	`^22.19

项目当前处于开发者预览阶段 ，官方明确警告会有破坏兼容性的变更（compatibility-breaking changes），因此适合用于评估、插件开发和内部试验，不建议直接作为唯一生产工具。

二、核心架构哲学："一切皆插件"

DeepSeek Harness 最激进的设计决策是：没有任何特权内核需要打补丁。模型适配器、工具注册表、会话日志、Agent 循环本身------全部都是插件，每一项都可以被替换、组合或扩展。

这种设计与传统 Agent 框架形成鲜明对比：

维度	传统 Agent 框架	DeepSeek Harness
扩展方式	Fork 源码 → 修改核心 → 提 PR	写插件 → 挂载到配置树 → 生效
Agent Loop	固定在内核中，不可替换	只是一个插件（`dsh-agent-loop`）
工具注册	静态列表挂载	动态服务注册 + 事件拦截
模型适配	硬编码或有限扩展	完全可替换的 Provider 插件
沙箱/Shell	与工具耦合	通过 Capability Seam 整体替换

实现这一哲学的底层是 Cordis------一个"时空调度可组合"（Spatiotemporal Composability）的元框架。

三、底层框架：Cordis

3.1 Cordis 是什么？

Cordis 是由北京大学与 DeepSeek 研究人员共同设计的元框架，其理论基础发表于论文 A Programming Paradigm for Spatiotemporal Composability。

Cordis 解决的核心问题是动态组合（Dynamic Composition）------现代软件系统（尤其是 Agent 系统）需要能够在运行时添加、移除、替换组件，同时保证：

时间可组合性（Temporal Composability）：组件移除时，其所有副作用可被完全回滚
空间可组合性（Spatial Composability）：组件可以声明依赖关系，运行时自动解析

Cordis 通过两个核心机制实现：

可逆效果（Revertible Effects）：每次上下文变换都携带逆操作，运行时跟踪管理
反应式协效（Reactive Coeffects）：上下文变化时，按组件的协效规范通知相关方

3.2 Cordis 在 Harness 中的角色

在 DeepSeek Harness 中，Cordis 提供：

共享上下文 （ctx）：服务注册表，如 ctx.llm、ctx.tools、ctx.sessions
类型化事件（Typed Events）：插件间通信的扩展点
依赖注入与生命周期管理：插件按依赖图自动激活/卸载
配置叠加与热替换：通过 Patch Layer 动态重组

值得注意的是，DeepSeek Harness 将 Cordis 源码内嵌 （vendored）到 vendor/ 目录，并重命名为 @deepseek-ai/cordis 作用域，以确保框架层完全可控、可审计、可补丁。

四、项目结构与仓库体系

4.1 官方仓库

仓库	地址	作用
主仓库	`deepseek-ai/deepseek-harness`	Harness 核心代码、插件、文档
Cordis 框架	`cordiverse/cordis`	元框架源码（TypeScript）
Cordis 论文	`cordiverse/paper`	时空调度可组合性理论预印本

4.2 Monorepo 目录结构

DeepSeek Harness 采用 pnpm workspace 管理的 Monorepo 结构，核心目录如下：

复制代码

deepseek-harness/
├── apps/
│   ├── cli/                    # CLI 入口与预设配置
│   │   └── config/agent-presets/  # 四种官方预设（standard/minimal/code/cordis）
│   └── web/                    # Web UI 应用
├── packages/
│   ├── core/                   # 产品 API 脊柱
│   │   ├── session/            # 事件溯源会话日志 (ctx.sessions)
│   │   ├── system-prompt/      # 提示词组装 (ctx.systemPrompt)
│   │   ├── tools/              # 工具注册与执行流水线 (ctx.tools)
│   │   ├── agent/              # Agent 接口与事件词汇 (ctx.agents)
│   │   └── agent-loop/         # 默认 Agent 驱动 (ctx.agentLoop)
│   ├── llm/                    # LLM 能力族（抽象服务 + 适配器）
│   ├── shell/                  # Bash 能力族（执行器接缝）
│   ├── terminal/               # 持久 PTY 能力族
│   ├── fs/                     # 文件系统能力族
│   ├── subprocess/             # 子进程能力族
│   ├── sandbox/                # 进程隔离（bwrap/Landlock/Seatbelt）
│   ├── subagent/               # 子 Agent 委托能力族
│   ├── skill/                  # Skill 能力族（注册表 + 本地 Provider）
│   ├── web/                    # Web 搜索/获取能力族
│   ├── workflow/               # 工作流引擎
│   ├── jobs/                   # 后台作业运行时
│   ├── session/                # 持久化会话数据平面
│   ├── preset/                 # 每会话 Agent 组合
│   ├── client/                 # Web GUI 浏览器端
│   ├── host/                   # Web GUI 服务端
│   ├── sdk/                    # 进程外运行时 SDK（JSON-RPC）
│   ├── acp/                    # Agent Client Protocol 服务器
│   └── ...                     # 其他能力族（goal, plan, guard, compaction 等）
├── vendor/                     # 内嵌 Cordis 框架及其基础库
├── docs/                       # 架构文档、开发指南、子系统参考
├── .agents/skills/             # 官方内置 Skill（工程规范、文档标准等）
└── examples/                   # 示例组合（如 agent-spine-demo）

4.3 核心包职责对照表

包名	职责	`ctx` 键
`core/session`	追加只写会话日志与内存存储	`ctx.sessions`
`core/system-prompt`	Prompt 段落与工具 Schema 组装	`ctx.systemPrompt`
`core/tools`	作用域工具注册表与守卫执行流水线	`ctx.tools`
`core/agent`	Agent 接口、实时注册表、`agent/*` 事件	`ctx.agents`
`core/agent-loop`	默认具体 Agent 驱动	`ctx.agentLoop`
`llm/llm`	消息与流式词汇 + 适配器接缝	`ctx.llm`

五、核心机制深度解析

5.1 Profile & Bundle：组合即配置

DeepSeek Harness 的启动过程是按顺序叠加出一棵插件树。理解这一机制需要掌握三个概念：

Plugin：一个具体能力单元
Bundle：一套能力组合包（npm 包 + Cordis 配置）
Profile：决定本次启动使用哪些 Bundle 的命名组合

默认 web profile 的两个主要 Bundle：

dsh-base：模型、Agent Loop、会话、工具、Shell、审批、沙箱等基础配置（约 78 行）
dsh-web-app：Web Server、API、浏览器模块和 UI 插件（约 51 行）

叠加顺序（越往后优先级越高）：

Profile 列出的 Bundle（按顺序）
Profile 的 cordis.patch.yml
机器级 cordis.patch.yml
命令行 --patch 覆盖

你可以通过以下命令查看实际启动的插件树：

bash 复制代码

dsh --profile web --dump-config

关键设计 ：Patch 按 id 定位条目，替换整个 config，而非深度合并。这意味着配置是显式且可预测的。

5.2 Capability Seam：真正的可插拔

"可插拔"最容易停留在接口层。DeepSeek Harness 更进一步，将每项能力拆分为三个角色，构成能力接缝（Capability Seam）：

角色	职责	示例
Service Definition	声明能力契约	`ShellService`
Service Provider	提供具体实现	`bash-local`、`bash-sandbox`、`pwsh-local`
Consumer	使用能力（通常是面向模型的 Tool）	`tool-bash`

只有当 Definition、Provider、Consumer 三者齐全时，才构成真正的 Seam。更换 Provider 时（如将本地 Bash 换成远程沙箱），Tool 和 Agent Loop 都无需产生平台分支。

5.3 Session Log：模型上下文不是 messages 数组

与传统 Agent 原型在内存中维护 messages 数组不同，DeepSeek Harness 采用事件溯源（Event Sourcing）设计：

核心原则 ：Model-visible means logged（模型可见 = 已记录）
存储形式 ：追加只写的 SessionEvent 日志（JSONL）
投影机制 ：deriveMessages() 按 Surface 规则从日志投影出模型历史

同一份日志可生成：

持久化 JSONL 文件
Web 实时事件
Fork（分叉）、Resume（恢复）、Replay（回放）
Transcript（转录）、Telemetry（遥测）、Compact（压缩）

这种设计的优势在于可观测性：任何进入模型请求的内容，都必须能从日志重建。如果 Agent 在 Step 40 偏离轨道，你可以在 Step 39 处 Fork 并重试，且完全可见模型当时看到了什么。

5.4 Turn / Step 状态机

DeepSeek Harness 严格区分 Turn 与 Step：

Step：一次模型请求 + 该请求发起的 Tool Call
Turn：零个或多个 Step，从领取输入开始，直到没有后续工作为止

一次完整 Turn 的七步流转：

复制代码

turn/start
  ├─ 从 Inbox 领取输入，写入 turn/start
  ├─ systemPrompt.assemble() 汇总 Prompt 段落、变量和 Tool Schema
  ├─ agent/pre-step 事件（插件可改写输入或拒绝）
  ├─ step/start + user/message
  ├─ 从 Session Log 投影模型历史
  ├─ llm.prepareCall() → 流式请求 → assistant/chunk* → assistant/message
  ├─ 若存在 ToolCall → Tool Pipeline → tool/result → 下一 Step
  └─ agent/turn-stopping → turn/end

关键设计：Loop 只维护状态机和持久化顺序，策略决策（是否批准工具、如何改请求、Prompt 追加内容、工具结果裁剪）全部由事件监听器或 Service Plugin 完成。

六、四种运行模式

Harness 内置四种预设模式，每种对应一棵不同的插件树：

模式	核心能力	适用场景
Standard（标准）	完整编程 Agent：文件编辑、Shell、搜索、Skill、计划、目标、子 Agent、工作流	通用开发任务，对标 Claude Code / Codex
PTC / Code（编程工具调用）	Standard 全部能力，但工具通过 TypeScript SDK 暴露，模型写程序编排多步操作	自动化流水线、多步工具链、省 Token
Minimal（极简）	仅两个工具：持久 `bash` + `str_replace_editor`，无上下文压缩	模型基准测试、极简环境
Creator（创造）	Standard + 运行时自省、内存插件实验、预设编写指导	插件开发者、自定义模式

6.1 PTC 模式详解

PTC（Programmatic Tool Calling）是 Harness 的差异化能力之一。传统模式下，模型需要 5 轮 Tool Call 才能完成的操作，在 PTC 模式下可以写成一段 TypeScript 程序，一次 run_code 执行即可：

typescript 复制代码

// 模型生成的 PTC 程序示例
const files = await tools.list_files({ path: "./src" });
for (const f of files) {
  if (f.endsWith(".test.ts")) {
    await tools.run_command({ command: `npx jest ${f}` });
  }
}

中间数据留在执行环境中，不进入上下文，显著节省 Token。

6.2 Minimal 模式的特殊意义

Minimal 不仅是"精简版"，更是 DeepSeek 官方用于模型基准测试 的 RL 对齐配置。其 agent.cordis.yml 将 system prompt 固定为 You are a helpful software engineer assistant.，设置 complete: true 和 includeRuntimeContext: false，屏蔽所有 harness 身份、工具指导、沙箱上下文。

七、扩展点与插件开发

7.1 官方扩展点地图

目标	机制
添加模型 Provider	在 `ctx.llm` 注册适配器
添加模型可见能力	在 `ctx.tools` 注册，Schema 自动加入 Prompt 组装
添加 Shell 执行	注册 `ctx.shell` 后端
添加文件系统策略	注册 `ctx.fs` Provider 或监听 `fs/*` 事件
拦截请求/工具/Turn	使用 `agent/` 或 `tools/` 事件
添加 UI 节点	注册 `ConversationNodeDefinition` + 渲染器
添加持久化状态	扩展 `SessionEventMap`，从日志渲染与回放

7.2 开发一个自定义 Preset

Preset 是 DeepSeek Harness 中最轻量的扩展方式。一个 Preset 是一个目录，包含：

复制代码

my-preset/
├── agent.cordis.yml    # 核心组合配置
├── preset.yml          # 元数据（名称、描述）
└── skills/             # 可选 Skill 文件
    └── my-skill/
        └── SKILL.md

将 Preset 放入 ~/.dsh/.agent-presets/<name>/，即可在 Web UI 中选择。例如，基于 Standard 添加自定义工具的 agent.cordis.yml：

yaml 复制代码

# 继承 standard 的能力
- id: my-custom-tool
  name: '@my-org/dsh-tool-custom'
  config:
    apiEndpoint: https://api.example.com

社区已出现大量 Preset 创新，如：

两阶段锚定（Anchored Standard）：首轮使用 Minimal 的 RL 对齐 prompt，之后自动晋升到 Standard 工具集，实测可将 Project2 基准从 91 分提升至 98/99 分
任务感知路由（Router Standard）：根据任务类型自动选择 reasoning mode 和工具集

八、快速上手指南

8.1 一行命令体验

bash 复制代码

# 前提：Node.js ^22.19 || >=24
npx @deepseek-ai/dsh web
# 打开 http://127.0.0.1:3080

8.2 从源码构建

bash 复制代码

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

8.3 关键配置文件

文件	作用
`~/.dsh/settings.yaml`	用户设置、Provider 配置
`~/.dsh/.credentials.yaml`	API Key（只写存储）
`~/.dsh/profiles/<name>/cordis.yml`	Profile 插件树
`~/.dsh/profiles/<name>/cordis.patch.yml`	用户自定义 Patch
`~/.dsh/.agent-presets/<name>/agent.cordis.yml`	自定义 Preset

8.4 配置自定义 Provider（以 OpenAI-compatible 为例）

yaml 复制代码

# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    my-gateway:
      displayName: My Gateway
      api: openai-completions
      baseURL: https://api.mygateway.com/v1
      apiKeyEnv: MY_API_KEY
      compat:
        thinkingFormat: deepseek
      defaultContextWindow: 1048576
      defaultMaxTokens: 32768
      models:
        - id: deepseek-v4-pro
          contextWindow: 1048576

九、生态体系与社区

9.1 官方 Skill 工程规范

Harness 仓库的 .agents/skills/ 目录包含 11 个 Skill 文件，实际上是 DeepSeek 内部真实的工程规范，包括：

dsh-code-review：接口契约、生命周期、并发安全审查标准
dsh-pre-push-checks：根据改动范围选择最小但足够的检查集
dsh-doc-standards：文档层级、预算控制、slop 检查清单

9.2 社区生态

项目	描述
`awesome-deepseek-harness`	精选插件、Skill、MCP 服务器合集
`dsh-TUI`	社区终端 UI 替代方案
`dsh-plugin-market`	插件市场（发现、审查、安装）
`deepseek-harness-desktop`	Tauri 封装的桌面端（约 5MB）
`codewhale`	社区驱动的 Rust 实现，支持 DSH 集成

社区插件通过 GitHub Topic dsh-plugin 被发现。官方明确：主仓库里的包并不比社区的包更重要。

十、总结与前瞻

DeepSeek Harness 的架构可以浓缩为一句话：架构的中心不是 Agent Loop，而是可组合、可替换、可回放的能力网络。

它的真正价值在于：

解耦：将模型、工具、执行环境、观测系统彻底解耦
可组合：通过 Cordis 的配置叠加机制，无需 Fork 即可重组任意能力
可观测：追加只写的 Session Log 为调试、审计、回放提供单一事实来源
可进化：Creator 模式允许模型在运行时自省和修改自身组合

当前限制也很明确：Developer Preview 的兼容性承诺、暂不接收外部 PR 的治理策略、以及部分机制（如 Preset 代际回收）仍在完善中。但对于希望深度定制 Agent 运行时 的开发者而言，Harness 提供了一个前所未有的开放底座------它不是"DeepSeek 版的 Claude Code"，而是Agent 时代的 Android。