DeepSeek Harness 架构解析：从 Preset、Tool Pipeline 到 Agent Runtime

DeepSeek Harness（DSH）不是简单的模型聊天界面，也不只是又一个 Coding Agent。它把 Model Adapter、Tool Registry、Session、Agent Loop、Sandbox、Storage 和 UI 等能力放进插件组合，通过 Cordis 管理组件的加载、卸载、依赖与生命周期。

本文从工程角度介绍 DSH 的核心结构，并说明为什么需要从 Agent Runtime，而不只是从"模型加工具"的角度理解它。

版本说明 ：本文与《DeepSeek Harness 技术入门与架构原理》采用同一技术基线。冻结日期为 2026-08-24，DSH 版本为 0.1.1-rc.2，源码提交为 b150a551b8d465e31e418e1b2eaf5e79bbb7d28e。DSH 仍处于 Developer Preview，读者执行命令时应同时核对当前 README 与 --help 输出。

1. 从 `Model + Tools` 到 Agent Runtime

最小 Agent 经常被写成：

text 复制代码

Agent = Model + Tools

这个公式没有覆盖真实系统中的上下文、状态、循环、权限、执行环境、持久化和可观测性。更加接近工程现实的检查表是：

text 复制代码

Agent System = Model + Context + Tools + State + Loop
             + Execution Environment + Policy
             + Persistence + Observability

Harness 负责组织这些部分。

可以把一次 Agent 执行抽象成下面这条链路：

text 复制代码

用户输入
   ↓
Session / Context Projection
   ↓
Model Request
   ↓
Agent Loop
   ├─ 直接生成回答
   └─ 生成 Tool Call
          ↓
      Tool Pipeline
          ↓
      执行结果进入 Session
          ↓
      下一次 Model Request

模型只负责产生下一步候选输出。当前模型能看到哪些工具、Tool Call 是否允许执行、结果怎样保存并进入下一轮，都由 Harness 决定。

2. 快速运行 DeepSeek Harness

通过 npm 快速启动：

text 复制代码

npx @deepseek-ai/dsh web

冻结版本默认使用本地地址：

text 复制代码

http://127.0.0.1:3080

需要阅读和调试源码时，可以固定到本文使用的提交：

text 复制代码

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

冻结提交要求 Node.js ^22.19.0 || >=24.0.0，包管理器为 pnpm 11.7.0。以上命令仍应在目标环境中实际复测，尤其是 Node.js、pnpm 与操作系统组合。

3. Everything is a Plugin 到底是什么意思

DSH 的核心设计口号是 Everything is a Plugin。

这里的"Plugin"不是传统意义上只能增加几个外围功能的扩展。模型适配、工具注册、Agent Loop、Session、Sandbox 和存储等产品能力本身都可以由插件提供。

不过，这不代表 DSH 没有运行时内核。

Cordis 仍然负责一组稳定的组合语义：

Context：组件能够看到的能力环境；
Service：Provider 对外提供的能力；
Effect：受到生命周期跟踪的影响；
Fiber：一个插件实例对应的生命周期单位；
Loader：根据声明式配置加载和协调组件；
Dependency：决定 Consumer 在当前环境中能否成立。

更加准确的描述是：具体的 Agent 产品能力可以被替换和重新组合，Cordis 内核负责管理这些组件怎样进入和退出运行时。

4. 四套 Preset 不是四个独立 Agent

冻结版本提供四套预置 Agent Preset：

Preset	主要用途	能力呈现方式
Standard	日常完整 Agent	直接向模型呈现文件、Shell、搜索、Skill、Subagent 等能力
PTC / Code	多步工具编排	通过 Code Mode SDK，让模型用 TypeScript 程序组合多次工具操作
Minimal	最小化编码与 Benchmark	只保留持久 Shell 和文件编辑工具
Creative / Cordis	运行时实验与 Preset 创作	在标准能力之外提供运行时检查、插件实验和 Preset 创作指导

Preset 更接近 per-session composition，而不是四份完全独立的产品代码。

Host 可以持有共享的基础设施，当前 Session 则通过 Agent scope contribution 获得自己的能力组合。不同 Preset 还可能改变 Tool Presentation：底层能力相近，但模型看到和组织这些能力的方式不同。

因此，比较 Preset 时需要控制模型、任务和 Workspace 等变量。否则很难判断差异来自模型随机性，还是来自 Harness 组合。

5. Tool Call 不是一次普通函数调用

很多简单 Agent 框架把工具调用理解成：

text 复制代码

模型返回函数名和参数 → 查找函数 → 执行

真实产品需要更完整的执行边界。冻结版本中的主线可以简化成：

text 复制代码

tool/call
  → pre-execute
  → monotonic guards
  → approval
  → execute waterfall
  → post-execute
  → finalizeContent
  → tools/result
  → durable Session Event

这里有三个容易混淆的概念。

Guard

Guard 根据策略阻止不允许发生的调用。所谓 monotonic，强调后续处理不能把已经拒绝的调用重新变成允许状态。

Approval

Approval 决定当前这一次操作是否需要用户批准。它不是永久权限，也不改变 Sandbox 的影响范围。

Sandbox

Sandbox 控制工具在哪个执行环境中运行，以及它最多能够影响哪些资源。操作获得批准，不意味着它可以跳出执行边界。

因此：

text 复制代码

Guard    → 规则是否允许
Approval → 这一次是否放行
Sandbox  → 最多能影响哪里

Code Mode 也必须回到完整 Tool Pipeline。它改变的是工具调用的编排方式，不应该成为绕过 Guard、Approval 或 Sandbox 的旁路。

6. Cordis 如何管理动态组合

动态插件系统至少要处理两类不同问题。

Temporal Composability

组件从 mount 到 active，再到 unloading 和 disposed，Runtime 必须知道它产生过哪些受管理的影响。

监听器、定时器、Service 注册和子 Fiber 等 Effect 应归属于具体生命周期。当插件被卸载时，Runtime 才能沿所有权关系执行清理。

这不等于 Cordis 能够自动回滚所有外部副作用。数据库写入、网络请求或已经启动的外部进程仍需要组件自己定义补偿或清理方式。

Spatial Composability

组件是否能够运行，还取决于当前 Context 中是否存在它需要的 Service。

当 required Service 消失时，依赖它的 Consumer 可以卸载；新的 Provider 出现后，Consumer 再在新的依赖环境中重新加载。

这比让 Consumer 长期持有一个被静默替换的全局对象引用更容易推理，也为声明式配置和 HMR 提供了统一的生命周期基础。

7. Session 为什么不能只是聊天数组

普通聊天应用可能只保存：

text 复制代码

user message
assistant message
user message
assistant message

Agent 还需要保存 Tool Call、Tool Result、状态变化和运行统计等事件。

DSH 区分能够持久化的 Session Event 与仅用于当前运行过程的 live Agent Event。持久事件可以派生出不同 projection，例如模型消息、Transcript、统计信息和会话查询结果。

这套设计的价值不是保证外部世界能够被完全复现，而是让系统能够回答：模型当时看到了什么，工具返回了什么，以及下一次请求是怎样构造出来的。

Event Log 改善的是可重建性和可解释性，不是对真实世界确定性的承诺。

8. Code Mode 与 Subagent 说明了什么

Code Mode 让模型生成一段程序来编排工具。它适合处理循环、过滤、聚合和多步骤依赖，可以减少模型与 Harness 之间反复往返的次数。

但 Code Mode 并不必然更便宜或更可靠。启动 Runtime、生成程序、处理错误和传输结果都有固定成本。任务很短时，直接 Tool Call 可能更加合适。

Subagent 则把"由谁完成子任务"也抽象成 Provider。一个可靠的委派至少要明确四件事：

Task：子代理要完成什么；
Context：它能够看到哪些信息；
Authority：它拥有哪些工具和权限；
Return：它应该返回什么格式的结果。

Workspace 共享也不等于上下文、权限和会话状态全部共享。这些边界必须分别设计。

9. 关于《DeepSeek Harness 技术入门与架构原理》

为了把上面的概念连成完整学习路径，我写了《DeepSeek Harness 技术入门与架构原理：从第一个插件到 Agent Runtime》。它属于 DSH 开源后首批系统性中文技术电子书之一。

全书包括八章正文和四个附录，按照下面的顺序展开：

text 复制代码

运行 DSH
  → 比较四套 Preset
  → 理解 Everything is a Plugin
  → 编写 Skill、Tool 与 Hook
  → 进入 Cordis 生命周期
  → 还原 Agent Loop 与 Session
  → 分析 Code Mode 与 Subagent
  → 设计自己的 Harness

这本书不会把 DSH 宣传成行业标准，也不把 Developer Preview 的 API 写成长期稳定承诺。它选择 DSH，是因为这个项目提供了一个足够公开的 Agent Runtime 样本。

电子书地址：https://jdread-api.jd.com/h5/p_book_detail_share?s=1\&ebookId=30981809

官方项目：https://github.com/deepseek-ai/deepseek-harness

技术冻结提交：https://github.com/deepseek-ai/deepseek-harness/commit/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e

总结

研究 DeepSeek Harness 时，最值得关注的不是某个按钮或某条命令，而是它怎样回答下面这些问题：

Agent 能力怎样进入当前 Session？
Tool Call 怎样经过策略、批准和执行环境？
插件怎样随依赖变化而加载和卸载？
Session 怎样记录模型真正看到的内容？
Code Mode 和 Subagent 怎样复用同一套能力边界？

这些问题不会随着某个 API 改名而消失。它们共同构成了 Agent Runtime 的工程基础。

DeepSeek Harness 架构解析：从 Preset、Tool Pipeline 到 Agent Runtime