RenatoMignone/inside-deepseek-harness

DeepSeek Harness 详解

🌐 在线交互式网站： renatomignone.github.io/inside-deepseek-harness
🔗 原始源代码仓库： deepseek-ai/deepseek-harness

[!NOTE]
技术性论断已对照上游 master 分支的 b150a55 提交（2026 年 8 月 21 日）进行核实。DeepSeek Harness 是一个开发者预览版，上游明确警告将会出现破坏兼容性的变更。

本仓库是对 DeepSeek Harness 的视觉化与技术性解读，并且更广泛地，是对当今最先进的智能体 harness 如何构建的解读。

[!TIP]
推荐的查看方式（交互式网页与 HTML）：
为获得最佳视觉体验，包括响应式卡片布局、增强排版和高分辨率图表缩放：
- 🌐 查看在线页面： renatomignone.github.io/inside-deepseek-harness
- 💻 或克隆到本地并打开：
git clone https://github.com/RenatoMignone/inside-deepseek-harness.git
cd inside-deepseek-harness
Open in browser
xdg-open index.html   # Linux
open index.html       # macOS
start index.html      # Windows

本指南的前提是读者已经了解什么是 LLM、工具和智能体。因此本指南并非从零开始。相反，它聚焦于使现代智能体 harness 强大的架构、抽象、执行模型和工程理念。

目录

1. 核心心智模型：模型 + Harness
2. 一切皆插件
3. 仓库的组织方式
4. 轮次 / 步骤智能体循环
5. 会话作为仅追加事件日志
6. 工具经过策略管道
7. 原生工具调用 vs Code Mode
8. 沙箱化执行
9. 子智能体、任务和工作流
10. 所使用的框架和技术
11. 这教会我们关于现代 harness 的什么
12. 仓库的实用阅读路径

1. 核心心智模型：模型 + Harness

思考 DeepSeek Harness 最有用的方式是：

现代编码智能体不仅仅是一个带有一些工具的 LLM。

它是模型加上 harness。
模型负责推理、规划、解释和语言生成。

harness 是模型周围的一切，使其在现实世界中真正有用：

- prompt 组装
- 工具暴露
- 执行
- 状态管理
- 策略检查
- 沙箱隔离
- 持久化
- 调度
- UI / API 集成
- 工作流与委托

换句话说：

- LLM 是大脑
- harness 是大脑周围的操作系统

现代编码 agent = 模型 + harness

为什么这很重要

早期的 agent 通常被设计为：

- 模型调用
- 也许一次工具调用
- 又一次模型调用
- 完成

现代 harness 要丰富得多。它们的行为更像应用运行时。它们具有结构化的工具接口、安全边界、持久状态、异步工作和可组合的子系统。

这是需要理解的第一个重要理念。

要在已安装 Node.js 的情况下尝试当前的 Web UI：

npx @deepseek-ai/dsh web

它默认启动于 http://127.0.0.1:3080。

2. 一切皆插件

DeepSeek Harness 围绕 Cordis 构建，后者充当运行时基底。插件向共享上下文贡献服务、类型化事件和可逆效果。甚至模型适配器、工具注册表、会话日志和默认 agent 循环也都是插件。

重要之处不仅在于“它使用了插件”。重要之处在于其设计哲学是：

一切重要的东西都被挂载到共享的运行时上下文中

这包括诸如以下内容：

- 模型提供方
- 工具注册表
- 会话
- 系统提示词组装
- 文件系统访问
- shell 执行
- 子 agent
- 任务
- Web UI
- 宿主集成

一切皆插件

为什么这是一种强大的架构

这为你带来：

- 依赖注入 - 服务可以干净地依赖其他服务
- 生命周期管理 - 插件可以被初始化、启动、停止和销毁
- 基于事件的集成 - 系统可以对运行时事件做出反应
- 可替换的提供方 - 你可以在稳定的抽象背后替换实现

因此，harness 不是一个巨大的硬编码单体。它更接近于一个模块化运行时平台，没有扩展必须打补丁的特权核心。

一个正在运行的 dsh 是一棵有序的插件树。Profiles 选择 bundles：dsh-base 提供共享运行时，而 dsh-web-app 和 dsh-headless 添加不同的产品界面。Profile、home 和命令行补丁层可以替换或插入配置行。

一个完整的能力接缝通常分隔三种角色：服务定义、提供方，以及面向模型的工具等消费者。正是这种分离让提供方可以将一项能力迁移到另一个执行环境，而无需重写其使用者。

3. 仓库是如何组织的

仓库结构反映了架构。

在高层次上，你可以将其视为：
- apps/ - 应用程序和 UI 入口点
- packages/ - 实际的能力模块和运行时服务
- docs/ - 架构和子系统说明
- examples/ - 示例项目和使用模式
- vendor/ - 供应商依赖
- python/ - Python 绑定 / 相关源码
- native/ - 原生组件
- scripts/ - 构建和实用脚本

仓库结构

最重要的文件夹：packages/

在 packages/ 内部，你会发现真正的构建块。

一种非常有用的心智分组方式是：

核心运行时主干

packages/core 拥有会话、系统提示词组装、工具、智能体服务、作用域和默认循环。llm、session 和 storage 添加了提供方适配器和持久化数据平面。

执行能力

fs、subprocess、shell、terminal、sandbox、code-runtime 和 lsp 定义了执行世界及其面向模型的消费者。

协调与集成

subagent、jobs、workflow、goal、schedule、skill、mcp、acp 和 sdk 涵盖委派、后台工作、可复用指令、调度和外部协议。boot、bundle 和 preset 负责组合；host 和 client 负责 Web 界面。

为什么这个结构很重要

这告诉了你一些更深层的东西：

DeepSeek Harness 是按能力接缝组织的，而不是按任意的工具文件夹组织的。这正是你在现代智能体运行时中所需要的。

4. 轮次 / 步骤智能体循环

DeepSeek Harness 围绕轮次和步骤来组织执行。

轮次
一个轮次包含零个或多个步骤。它在输入被接纳之前开启，并在不再有工具结果、排队的下一步输入或延续需要处理时关闭。因此，一个被拒绝的首次认领可能会留下一个持久的零步骤轮次。

步骤
一个步骤是：

- 一次模型请求
- 加上该模型请求发出的所有工具调用
- 加上这些工具调用的结果

轮次 / 步骤循环

为什么这很重要

这比简单地说“智能体在循环”要精确得多。

运行时现在可以清晰地定义：

- 一个步骤何时开始
- 究竟向模型发送了什么
- 在该步骤期间调用了哪些工具
- 返回了哪些结果
- 是否需要另一个步骤
- 轮次何时结束

这让 harness 能够对以下方面进行强有力的控制：

- 日志记录
- 重放
- 调度
- 取消
- 工具执行顺序
- 流式传输
- 延续

大致的循环是

1. 输入进入智能体的单一 FIFO 收件箱
2. 驱动器开启 turn/start 并认领下一步批次
3. agent/pre-step 可以重写、接纳或拒绝它
4. harness 推导历史记录，并组装提示词部分、动态上下文和工具 schema
5. 模型流式输出一个步骤；块和最终消息被记录
6. 请求的工具通过排序屏障和受保护的工具管道运行
7. 结果或新接纳的输入可能要求另一个步骤
8. agent/turn-stopping 在持久的 turn/end 之前运行
持久的 turn/、step/、消息和工具事件，与用于拦截、状态、引导和取消的实时 agent/ 控制事件是不同的。

这是智能体的运行主干。

5. 会话作为仅追加的事件日志

DeepSeek Harness 中最重要的技术理念之一是：会话并非被建模为简单的聊天记录。

相反，它们被建模为仅追加的事件日志。

会话作为事件日志

典型事件包括：

- turn/start
- step/start
- user/message
- assistant/chunk
- assistant/message
- tool/call
- tool/result
- step/end
- turn/end

为什么这很强大

因为现在系统可以从同一个底层真相中派生出多种视图：

- 人类可读的聊天记录
- 模型可见的消息历史
- 可重放的会话轨迹
- 调试 / 可观测性记录
- 跨多个会话的分析

这就是应用于智能体系统的事件溯源。

日志所提供的不只是消息历史。一个对话表面会折叠产生消息的事件，并支持替换操作；独立的会话投影派生出可供客户端使用的状态。压缩可以修剪庞大的工具结果，并用摘要替换一个平衡的表面范围，同时保留原始日志事实。

持久化也是一个接缝。随附的提供程序将会话存储为带校验和的压缩 JSONL 产物，或存储在可选的 SQLite 数据库中，而恢复过程可以平衡被中断的冷启动轮次，而无需重写已提交的事件。

为什么现代 harness 越来越多地采用这种做法

一旦智能体变得：

- 长时间运行
- 可恢复
- 多步骤
- 工具密集
- 可检查
- 面向生产

……一个简单的 messages[] 数组就不够用了。

事件日志要健壮得多。

6. 工具经过策略管道

一个严肃的智能体 harness 的标志是：工具调用不仅仅是一次回调调用。

在 DeepSeek Harness 中，工具调用会经过一个管道。

工具策略管道

当前的管道是：

1. 追加所请求的 tool/call
2. tools/pre-execute 返回允许、拒绝或询问；询问由一次性批准来解决
3. 单调递增的已注册守卫可以拒绝，但之后不能被削弱
4. tools/execute 包装器添加超时、重试或指标行为
5. 经过验证的工具实现运行
6. tools/post-execute 接受、替换、阻止或附加上下文
7. 注册表规范化输出，工具强制执行其最终内容不变量
8. tools/result 在持久的 tool/result 被追加之前观察冻结的结果

为什么这如此重要

这将一些在较弱系统中常常混在一起的问题分离开来：

- 模型被允许请求什么
- 运行时愿意执行什么
- 执行在操作层面如何被包装
- 结果如何被规范化和呈现
- 该操作如何被观察和记录
这意味着策略存在于执行框架中，而不是存在于每个单独的工具内部。

工具定义还声明了规范 JSON 输出、可重放的呈现方式、协作式取消，以及可选的并发分类。调用默认是独占的；只有显式的 isConcurrencySafe 结果才允许在循环的有界池中重叠执行。

这是最先进执行框架设计最清晰的标志之一。

7. 原生工具调用 vs 代码模式

这是该系统中最有趣的部分之一。

DeepSeek Harness 支持三种工具呈现模式：native（默认）、code 和 both。

原生工具
请求携带普通的函数 schema。一个助手响应可以发出一个或多个原生调用；它们的结果会为下一个模型步骤提供信息：

- 调用 read
- 检查结果
- 调用 grep
- 检查结果
- 调用 bash
- 检查结果
- 等等。

代码模式
请求携带保留的 run_code 传输通道，以及生成的类型化 tools SDK。模型编写一个异步 TypeScript 函数体，其中包含顶层 await 和 return。

原生工具 vs 代码模式

代码模式为何重要

它将确定性的编排移入一个程序中。

这意味着，你不必反复要求模型协调每一个微步骤，而是可以让代码处理确定性的工作流。

这可以改善：

- 延迟
- 往返次数
- token 效率
- 结构化的多步骤执行

重要的细微之处

代码模式不是一种绕过机制。

运行时程序仍然会桥接回同一个工具系统，并且每一次子分发都会重新进入完整的策略流水线。只有外层的 run_code 日志和返回值会进入模型上下文。

随附的 TypeScript 运行时为每次运行创建一个全新的 Node worker 线程，并带有时间、内存和输出限制以及强制终止。这是隔离，而不是安全边界：上游赋予它与 bash 等效的信任姿态，因此权限仍然归属于被桥接的工具及其提供方。

所以其价值不在于“原始的执行自由”。

其价值在于更好的编排界面。

8. 沙箱化执行

现代编码执行框架需要一个严肃的执行边界。

Shell 执行不能只是对 exec() 的朴素直接调用。

相反，DeepSeek Harness 将命令执行建模为多个层次。

沙箱化执行

这个栈大致是：

1. 面向模型的命令工具，例如 bash
2. 一个 shell 抽象
3. 一个子进程提供方
4. 一个沙箱策略
5. 一个沙箱后端
6. 操作系统边界

为什么这种分层很重要

它允许执行框架区分：

- 模型想要运行的命令
- 它可以在其下运行所依据的策略
- 用于隔离它的后端
- 实际执行工作的操作系统强制机制

平台特定的后端

示例包括：

- Linux：bubblewrap、Landlock
- macOS：Seatbelt
- Windows：受限令牌 + 基于 ACL 的控制
沙箱模式有 read-only、workspace-write 和 danger-full-access。一个受限模式如果没有可用的后端，会以 SANDBOX_UNAVAILABLE 失败关闭；它绝不会静默地退化为不受限的执行。

边界被刻意收窄：这些模式仅约束文件系统效果。网络访问和进程可见性不在这一词汇范围内，而 Windows ACL 或较旧的 Landlock 强制执行可能会被报告为部分执行。容器、microVM 和远程执行不是本地沙箱后端——它们为另一个执行世界替换了连贯的文件系统、子进程和 shell 提供程序。

更大的教训

最好的 harness 将能力暴露与执行隔离分开。

这是超越 DeepSeek Harness 本身的一条重要架构原则。

9. 子代理、作业和工作流

现代代理日益成为协同工作的系统，而不仅仅是单线程循环。

DeepSeek Harness 通过支持以下内容反映了这一点：

- 子代理
- 作业
- 工作流

子代理、作业、工作流

子代理
父代理可以将任务委托给子代理。

这对于以下方面很有用：

- 专业化
- 分解
- 并行探索
- 隔离的子问题

命名提供程序可以共存，包括进程内 spawn/fork、ACP、Codex、Claude Code 和 dsh SDK 提供程序。能力检查涵盖结构化输出、人设、工具过滤和委托深度。可继续的子代理使用持久的子会话，并可以在冷恢复后接受后续的 FIFO 轮次。

作业
长时间运行的工作可以作为作业来管理。

典型的控制包括：

- job_list
- job_output
- job_kill

通用的按所有者作用域注册表目前涵盖 bash 和子代理作业。完成通知可以唤醒空闲的所有者，或加入忙碌所有者的下一步收件箱。

工作流
工作流在工作线程中执行模型编写的 JavaScript 主体。该脚本可以使用有界的 agent()、parallel() 和 pipeline() 原语，通过同一子代理接缝启动子代理；父会话会收到持久的工作流显示记录。

为什么这很重要

这是向能够管理以下内容的 harness 更广泛转变的一部分：

- 并行工作
- 异步工作
- 后台执行
- 结构化编排

这正是高级代理系统的发展方向。

10. 使用的框架和技术

理解不仅是理念，还有具体的技术选择，是很有帮助的。

使用的框架和技术

关键技术及其作用

Cordis
用作插件运行时和服务组合层。

用途：

- 依赖注入
- 服务注册表
- 生命周期处理
- 事件集成

TypeScript + Node.js
用作主要实现语言和运行时。

用途：

- 强类型实现
- 一致的服务器/运行时环境
- worker/线程/进程支持
pnpm monorepo
用于包管理和工作区组织。

用途：

- monorepo 包协调
- 快速安装
- 清晰的工作区边界

React + Vite
用于 Web 界面和前端工具链。

用途：

- UI 组合
- 快速开发工作流
- 浏览器端运行时集成

运行时 schema / 验证工具
用于配置和运行时验证。

用途：

- 更安全的配置处理
- 经过验证的服务输入
- 可预测的契约

Worker Threads
用于 TypeScript Code Mode 和工作流脚本执行。

用途：

- 为生成程序提供每次运行的全新隔离环境
- 有界的执行资源
- 结构化的宿主/程序交互

这种隔离本身并不是安全边界。

沙箱后端
用于同世界进程限制。

用途：

- 管控所生成命令的文件系统影响
- 应用最小权限
- 使用操作系统支持的隔离机制

ripgrep
作为打包二进制文件使用，以支持快速源代码搜索能力。

用途：

- 高效搜索
- 类似 grep/glob 的行为
- 代码库探索

OpenTelemetry
用于可选的追踪 / 可观测性。

用途：

- 遥测
- 诊断
- 对运行时行为的分布式可见性

ACP / SDK / JSON-RPC 集成接口
用于客户端和外部集成。

用途：

- 编程式访问
- 进程间集成
- 编辑器 / 宿主 / 工具链连接

MCP
用于发现外部工具服务器，并通过普通工具注册表注册其 schema 和执行器。

JSONL / SQLite 持久化
用作可互换的持久会话后端：默认使用独立的压缩 JSONL 产物，或选择启用共享 SQLite 数据库。

为什么这些选择很重要

它们强化了四项核心特质：

- 模块化
- 安全性
- 性能
- 可观测性

11. 这让我们对现代 harness 有何认识

DeepSeek Harness 只是一种实现，但作为观察该领域更广泛方向的透镜，它很有用。

有用的教训并不是每个 agent 都必须复制这个包图。而是状态、策略、组合、执行和呈现需要稳定的归属边界。

1. 它们是模块化的
它们由稳定的能力接缝构建，而不仅仅是临时辅助工具。

2. 它们具有结构化执行
工具被强描述、被中介、被包装并被观测。

3. 它们将状态视为持久基础设施
会话是事件流，而不仅仅是文本历史。

4. 它们将提示词视为一个子系统
提示词构建不是事后补充。它是一个正式的组装过程。

5. 它们区分能力与隔离
暴露一个命令工具，与决定如何或在何处安全执行它，并不是同一回事。

6. 它们支持更丰富的编排模型
子 agent、作业和基于代码的编排正日益成为标准。

7. 它们是为运维而构建，而不仅仅是为了演示
可观测性、重放、取消和可恢复性都很重要。

架构对比：原型 vs. 现代 Harness 运行时

| 维度 | 传统原型 Agent | DeepSeek Harness 架构 |
| :--- | :--- | :--- |
| 运行时内核 | 带有硬编码胶水的单体脚本 | 由 Profile 组合的 Cordis 插件树，具备类型化事件和可逆效果 |
| 状态与内存 | 短暂的进程内消息数组（messages[]） | 仅追加事件、派生投影、JSONL/SQLite 持久化、重放与恢复 |
| 工具治理 | 直接无防护的回调执行 | 类型化 I/O、审批、单调守卫、包装器、终结与观察 |
| 编排 | 仅由聊天驱动的循环 | 原生/代码/两者兼具的呈现方式、Subagent、Job 和 Workflow 脚本 |
| 执行边界 | 原始 exec() / 直接宿主 shell | 故障关闭的文件系统隔离；远程世界取代一致的 provider 接缝 |
| 并发 | 单线程同步流程 | 可选的并行调用、按所有者划分的 Job、子 Agent 和由 worker 支持的脚本 |

简版

成熟的 harness 将模型输出转化为持久、可观测、可扩展且受策略治理的工作——并且每个安全边界都被精确地陈述。

12. 仓库的实用阅读路径

如果有人想高效地理解这个代码库，一条好的路径是：

1. 阅读 docs/architecture.md、Cordis 入门指南和能力接缝图
2. 用 dsh --profile web --dump-config 检查实际的组合
3. 跟随 dsh-base，然后是 Web 或无头 bundle 以及 profile 补丁层
4. 追踪一个请求经过 core/agent-loop、提示词组装、ctx.llm 和会话事件的过程
5. 研究完整的工具流水线，并将持久的 session/ 事实与实时的 agent/* 控制分开
6. 跟随会话持久化、投影和压缩
7. 检查 Code Mode 及其 worker 线程 provider
8. 一起检查文件系统、shell、子进程以及确切的沙箱边界
9. 检查 subagent、jobs、workflow、goal、schedule 和 skill 系统
10. 只有到那时，才跟随宿主/客户端投影进入 Web UI 或 ACP/SDK 传输层

简而言之

如果你理解这六件事，你就理解了仓库的大部分内容：

- 插件运行时
- profile、bundle 和限定作用域的组合
- agent 循环
- 工具流水线
- 会话事件日志
- 能力接缝及其确切的执行边界

上游包含生成的模块、事件、服务、持久化和工具目录。由于项目处于开发者预览阶段，当细节冲突时，请优先参考这些目录和包 README，而非第三方摘要。

最终要点

DeepSeek Harness 之所以有趣，不仅在于它实现了什么，还在于它清晰地展示了现代 harness 现在必须成为什么样子。

仅仅拥有以下内容已经不够了：

- 一个模型
- 几个工具
- 一个 ReAct 循环

现代形态更接近于：

- 一个可组合的运行时
- 一个持久的执行模型
- 策略中介的工具
- 明确的执行边界
- 结构化的编排接口
- 强大的可观测性与重放能力

这就是这个仓库背后真正的启示。

作者与维护者

由 Renato Mignone 策划与维护。
- GitHub: @RenatoMignone
- 项目网站: renatomignone.github.io/inside-deepseek-harness