第1章：开篇 —— DeepSeek Harness 是什么

第1章：开篇 —— DeepSeek Harness 是什么

本章不涉及源码细节，回答三个更根本的问题：dsh 是什么？它和你已经知道的那些 agent 工具有什么本质不同？为什么值得花时间读它的架构？读完这章，你会知道后面 12 章要拆的到底是个什么东西。

一、开场：一个反直觉的数字

先看一组对比。同样是「agent harness（智能体运行外壳）」这个品类：

185 比 4。如果你刚读完 Pi 教程第 1 章那套"做减法是一种竞争力"的论证，这个数字看起来像是走了完全相反的弯路。

但事情没那么简单。这 185 个包里，真正跑 agent 循环的只有 1 个，其余全是抽象接口、可换实现和插件。dsh 官方 README 里有一句话点破了这个设计：

这是 harness 中唯一包含具体循环逻辑的包。其他所有内容要么是抽象服务，要么是针对扩展点的插件：新行为应放入插件，而不是这里。 —— dsh-agent-loop/README.zh.md

换句话说，Pi 数的是"我做了多少功能"，dsh 数的是"我拆出了多少个可替换的位置"。两个数字不在同一个坐标系里。

这就是本教程要拆的东西：当你把 agent 运行时的每一个决策点都做成插件，会得到什么，又会付出什么。

二、dsh 是什么：一句话与一张图

一句话定义

DeepSeek Harness（简称 dsh）是 DeepSeek 开源的 agent 运行外壳，全部用 TypeScript 编写，架构上把 agent 运行时的每一项能力都拆成"抽象服务接缝 + 可替换实现"，并用一个叫 cordis 的依赖注入框架把它们组装起来。

拆开看：

• "agent 运行外壳" —— 它不是模型，也不是 SDK 库，而是让模型能读文件、跑命令、调工具、管会话的那一层运行时
• "每项能力都拆成接缝" —— 文件系统、Shell、进程、沙箱、后台任务、网络、存储、凭据、压缩、委派……每一项都是 ctx.xxx 抽象服务 + 至少一个具体实现包
• "cordis 组装" —— 一个 IoC（控制反转）容器，负责依赖注入、作用域、生命周期。整个 harness 就是一棵由 YAML 配置驱动的插件树
• "TypeScript" —— 发布为 npm 包，scope 是 @deepseek-ai/dsh-*

关键数字 [实测]

关于"185 个包"这个数字的诚实说明 这个数字容易造成误导，必须讲清楚三件事：

1. 它统计的是本机 profile 实际安装的 @deepseek-ai/* 包，不等于官方仓库的包总数（可能更多，也可能含未安装的）
2. 其中约 34 个是 Web 前端 UI 插件（dsh-client-ui-*），跟 agent 内核无关
3. 很多包极小 —— dsh-brand 只导出一个类型、dsh-timeout 只有几个纯函数。包数量衡量的是拆分粒度，不是代码规模

后面每次用到"185"，都是在讨论拆分粒度这件事，不是在夸功能多。

一张图看清分层

配图说明：dsh 的五层架构。自上而下：前端 UI 插件（约 34 个，一人一块）、Host 宿主层（进程级）、Agent 平面（唯一循环实现 + 模型可见工具，由 preset 决定）、能力 Seam 层（20+ 组抽象+实现）、cordis 内核。关键在每一层内部的东西都是可插拔的——把 dsh-tool-pwsh 从配置里删掉一行，模型就没有 shell 了，不需要改任何代码。

┌─────────────────────────────────────────────────────────┐
│  Web 前端插件（34 个 dsh-client-*）                        │
│  一个插件一块 UI：侧边栏 / 对话流 / 工具树 / 设置 / 主题…      │
├─────────────────────────────────────────────────────────┤
│  Host 宿主层（webserver / apiproxy / typert / …）          │
│  HTTP 路由、Remote 分发、前端静态资源                        │
├─────────────────────────────────────────────────────────┤
│  Agent 平面                                              │
│  ┌───────────────┐  ┌──────────────────────────────┐    │
│  │ dsh-agent-loop│  │ 模型可见工具（tool-* 共 20 个）  │    │
│  │ 唯一的循环实现  │  │ pwsh / read / write / edit /… │    │
│  └───────────────┘  └──────────────────────────────┘    │
│  ┌──────────────────────────────────────────────────┐   │
│  │ 横切策略插件：超时 / 溢出 / 压缩 / 检查点 / 重复提醒    │   │
│  └──────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────┤
│  能力 Seam 层（20+ 组「抽象接口 + 可换实现」）               │
│  fs · shell · subprocess · sandbox · jobs · web · spill  │
│  storage · settings · credentials · compaction · …       │
├─────────────────────────────────────────────────────────┤
│  cordis 内核                                             │
│  Context · Service · Plugin · Fiber · inject · dispose   │
└─────────────────────────────────────────────────────────┘

这张图的关键不在层数，而在每一层内部的东西都是可插拔的。第 3 章会展示：把 dsh-tool-pwsh 从配置里删掉一行，模型就没有 shell 了；换成 dsh-bash-local，它就跑在 bash 上。不需要改一行代码。

三、三个身份

和 Pi 一样，dsh 也可以从三个视角来看，但内容完全不同。

3.1 作为产品：一个可以直接用的 agent

dsh web 起一个本地 Web GUI，dsh --profile headless "跑测试" 做一次性任务。本机实测跑的就是 Web 形态，监听 127.0.0.1 的随机端口。

作为产品它的特点：

• 多模型：本机实测接了三个自定义 provider（企业网关 / 聚合网关 / 自建代理），单个 provider 下挂多个模型，会话中可以随时 /model 切换
• 权限预设：workspace-write（工作区可写 + 询问审批）和 danger-full-access 两档打包好，一个下拉切换
• 委派：内置 subagent、fork、workflow 编排、ralph 循环四种多 agent 机制
• 目标续跑：create_goal 后可以跨多轮自动继续，直到目标达成或阻塞

但产品成熟度不是它现在的卖点 —— 版本号还是 0.1.0-rc.6，官方 README 直说 rc 之间会破坏兼容。如果你只想找个顺手的编码 agent，Claude Code 或 Pi 都更稳。

3.2 作为架构参考：一份"能力接缝"清单

这是本教程认为 dsh 最大的价值。

任何人做 agent 运行时都会面对同一批问题：文件怎么读写、命令怎么跑、结果太长怎么办、上下文满了怎么办、多个 agent 怎么协作、危险操作怎么拦。dsh 的做法是把每个问题都定义成一个抽象接缝，然后给出至少一个实现。

于是它变成了一份清单：如果你要做 agent 运行时，这 20 多个位置你迟早要做决定。清单本身比它的任何一个具体实现都有价值 —— 哪怕你一行 dsh 代码都不用。

第 4 章会把这份清单完整摊开。

3.3 作为插件运行时：自己给自己加能力

dsh 的扩展方式不是"写扩展文件"，而是"往插件树里加一行"。本机实测的用户配置里就有 8 行第三方插件（一个叫 dsh-toolbelt 的社区包），提供了跨 agent 记忆、Windows 编码守护、图像生成等能力。

更极端的是，它装了一个叫 dsh-tool-cordis 的包 —— 让模型自己检查运行时、挂载自己写的插件。这个包本机没启用，但它的存在说明了设计意图：插件系统是给模型也准备的。

四、与三个同类的对照

理解一个 harness 最快的方式，是看它在什么地方和别人做了不同的选择。

4.1 vs Pi：减法 vs 拆分

有意思的是：Pi 明确列为"不做"的三件事（子 Agent、权限弹窗、计划模式），dsh 全做了，而且都做成了可以整体拔掉的插件。这不是"dsh 比 Pi 功能多"，而是两种应对同一矛盾的方式 —— Pi 说"我不做，你自己加"，dsh 说"我做了，你不要就删配置"。

代价也不同：Pi 的代价是缺功能时要自己写；dsh 的代价是理解成本 —— 你得先懂 cordis、懂 patch 分层，才能改动任何东西。

4.2 vs Claude Code：黑箱 vs 白箱

Claude Code 是闭源产品，系统提示词不公开、工具集固定、扩展点由官方定义（hooks / skills / MCP）。

dsh 是开源运行时，每一段系统提示词都能追到是哪个插件贡献的（第 9 章会逐段拆解本机实测的 9927 字符），每个工具的完整 schema 都在会话日志里躺着。

这不是优劣 —— 产品化程度和可观测性通常是反比。但如果你的目标是学 agent 运行时怎么做，白箱是唯一选项。

4.3 vs LangChain 类框架：运行时 vs 库

LangChain / LangGraph 是库：你在自己的应用里 import 它，控制流在你手上。

dsh 是运行时：它启动进程、管生命周期、拥有配置树，你的代码作为插件被它加载。

这个区别决定了很多设计。比如 dsh 的每个插件都必须能被 dispose() 干净卸载（第 2 章会讲 cordis 的 fiber 机制），因为运行时要支持热重载和会话级作用域；而库不需要操心这个。

五、这个项目的成熟度：必须说清楚的话

本教程写作时（2026 年 8 月），dsh 的状态是：

• 版本 0.1.0-rc.6，developer preview
• 官方 README 明示：rc 版本之间会有破坏兼容性的变更
• 部分包的 README 里带着 TODO(...) 标记和"已知限制与暂缓事项"小节，坦承哪些设计还没落地
• 本机安装的 runtime-seed-dsh 用的是精确 pin（"0.1.0-rc.6" 而非 ^0.1.0-rc.6），包描述里直接写明原因是"dsh 是 developer preview，README 承诺 rc 构建之间会有破坏性变更" [实测]

所以：

不要把本教程当作生产选型依据 本教程的价值在于拆解架构思路。如果你要在生产环境选一个 agent 运行时，dsh 现在的版本状态不适合。等它到 1.0 再说。

但架构思路不会因为版本号而失效 —— 第 13 章总结的十条设计判断，你可以直接用在自己的项目上。

另一个必须说清楚的：本教程有一处天然盲区。所有素材来自本机安装的包（打包后的 lib/*.js + README），不是官方仓库的原始 TypeScript 源码。这意味着：

• 能看到：完整的运行时行为、类型定义、官方文档、真实会话日志
• 看不到：源码里的注释细节、测试用例、未安装包的实现、官方设计文档（README 里大量引用的 .agents/notes/ 目录本机没有）

凡是受这个盲区影响的结论，正文里会明确标注。

六、每一章要回答什么

七、动手复核

本章的关键数字，你可以这样验证（PowerShell）：

# 1. 官方包总数
(Get-ChildItem "$env:DSH_HOME\profiles\node_modules\@deepseek-ai" -Directory).Count

# 2. 官方文档规模
$md = Get-ChildItem "$env:DSH_HOME\profiles\node_modules\@deepseek-ai" -Recurse -File -Include *.md
"$($md.Count) 篇 / $([math]::Round(($md | Measure-Object Length -Sum).Sum/1MB,2)) MB"

# 3. 版本号
(Get-Content "$env:DSH_HOME\profiles\node_modules\@deepseek-ai\dsh-base\package.json" -Raw |
  ConvertFrom-Json).version

# 4. 唯一的循环实现有多少行
(Get-Content "$env:DSH_HOME\profiles\node_modules\@deepseek-ai\dsh-agent-loop\lib\index.js").Count

# 5. 当前会话的运行时事实
Get-ChildItem env: | Where-Object Name -like 'DSH_*'

第 3 章会给出读取会话事件日志的完整方法 —— 系统提示词、工具 schema、事件流都在那个文件里。

八、总结

DeepSeek Harness 是一次把"可替换性"推到极致的架构实验：

1. 作为产品：能用，但版本状态（0.1.0-rc.6，明示破坏性变更）决定了它现在不适合生产
2. 作为架构参考：它交出了一份 20 多项的"agent 运行时能力接缝清单"，这份清单比任何具体实现都有价值
3. 作为插件运行时：连 agent loop 本身都是配置里的一行，扩展的边界远超一般框架

它和 Pi 构成了同一道题的两个极端答案。Pi 问"最少需要什么"，dsh 问"最多能拆成什么"。两个问题都值得问 —— 而只有把两个答案都看过，你才知道自己的项目该站在哪个位置。

下一章我们从地基开始：cordis 到底是什么，为什么一个 agent 运行时会选一个聊天机器人框架的 IoC 容器当底座。

Related Documents

• README-教程总览
• 第2章-cordis底座-一切皆插件的地基
• Pi 教程第 1 章 —— 减法哲学的对照
• DeepSeek Harness 研究摘要