1 · 认识 DeepSeek Harness
2026-08-21 11:39
5
0
本篇目标：建立对 dsh 的心智模型，搞懂「它是什么、为什么这么设计、几个必须先记住的概念」。
1. 一句话定位
DeepSeek Harness（代号 dsh）是 DeepSeek AI 开源的一个 Agent 运行时（agent harness）。
它和普通的「AI SDK」不一样：你不是去「调用」它，而是写一个插件，挂进它的运行时；运行时在每一轮对话里反过来调用你的插件。
💡 心智转变：你不是主控方，你是扩展方。这是小白最大的坎——后面所有接口都是「在运行时旁边挂东西」。
当前它处于 developer preview（开发者预览），官方明确会说有破坏性更新。所以本次培训里所有命令以 0.1.0-rc 版本为准，升级时要重看文档。
2. 为什么是「运行时」而不是「SDK」
| 对比 | SDK | Harness（dsh） |
|---|---|---|
| 你扮演的角色 | 主控方，主动调用库 | 扩展方，写插件挂进运行时 |
| 模型 / 工具 / 循环 | 通常要你自己编排 | 全是插件，装上去就行 |
| 改一个能力 | 改业务代码 | 改/加一个配置层或插件 |
如图：模型负责「想」，Harness 负责「在真实环境里干成」。Harness 的内核是 Cordis——它只管加载、卸载、依赖关系，本身不含任何 Agent 能力。模型适配器、工具注册表、会话日志、Agent Loop、系统提示词……每一项都是一个插件，挂在内核旁边，卸载时自动撤销。
3. 必须先建立的 5 个认知
| 认知 | 一句话结论 |
|---|---|
| ① Agent = 模型 + Harness | 模型负责想，Harness 负责在真实环境干成 |
| ② 一切皆插件 | 内核只管加载/卸载/依赖，不含任何 Agent 能力 |
| ③ 配置树 + 层叠 | profile → bundle → patch 逐层叠加；改能力不碰源码 |
| ④ 会话日志 append-only | 模型看到的一切都写进事件日志：「模型可见即已记录」 |
| ⑤ 轮次与步骤 | 一个 step = 一次模型请求 + 它调的工具；一个 turn = 0..N 个 step |
⚠️ 第 ④ 条是运行时不变量：任何「模型能看到的新输入」都必须由一条新的会话事件产生，否则框架会断言失败。新增模型可见输入 = 新增会话事件。
4. 轮次与步骤流水线
讲后面每个接口时，都要指一下它在下面这条流水线上的位置——能省掉一半提问。
关键记点：
agent/pre-step、agent/request、llm/stream、三个tools/*是 waterfall（瀑布）事件：监听器必须调next()才能往下走，不调就等于否决整条链。agent/turn-stopping是 serial（串行）事件，没有next()，可以停止整轮。
5. 关键概念速览（术语）
| 术语 | 含义 |
|---|---|
| Cordis | 底层插件框架，管加载/卸载/依赖/事件 |
| profile（档案） | $DSH_HOME/profiles/<name> 下的可启动组合 |
| bundle（组合包） | 一个带配置层的 npm 包，声明「我贡献什么插件」 |
| patch（配置层） | 一个 YAML 条目数组，按 id 插入或覆盖插件行 |
| seam（能力接缝） | 可替换能力 = Service Definition + Provider + Consumer 三件套 |
| session log（会话日志） | 模型上下文的唯一真源，append-only |
本篇小结
- dsh = 开源 Agent 运行时，内核 Cordis「一切皆插件」。
- 五个认知里，②一切皆插件和④模型可见即已记录是后面所有内容的总纲。
- 流水线图记住 waterfall 必须
next()，下一篇开始逐个接口往上挂。
下一篇：02-安装与环境准备
全部评论