第 1 章 DeepSeek Harness 是什么
1.1 一句话定位
DeepSeek Harness（简称 dsh） 是 DeepSeek 官方开源的 AI Agent 运行框架（harness）。它把一个完整的 agent 产品拆解为一棵插件树：模型适配器、工具注册表、会话日志、审批策略、沙箱，甚至 agent loop（智能体循环）本身，都是挂载在共享上下文上的插件。
这意味着：
没有任何特权内核。不存在"必须打补丁才能改"的核心代码。
一切皆可替换。想换掉文件系统访问方式？换掉 shell 执行后端？把整个执行世界搬到远程沙箱？都只需替换对应的服务提供方（Provider），消费方代码一行不改。
扩展方式是"挂载插件"，而不是 fork 仓库改源码。
官方文档站：https://deepseek-harness.github.io/deepseek-harness/ 源码仓库：https://github.com/deepseek-ai/deepseek-harness
1.2 与同类工具的关系
如果你用过 Claude Code、OpenClaw 这类 coding agent，可以把 dsh 理解为同类的 agent harness，但它的架构哲学更加彻底：
| 维度 | 传统 agent 框架 | DeepSeek Harness |
|---|---|---|
| 扩展模型 | 继承基类 / 实现 hook | 挂载 Cordis 插件，注册服务 + 监听事件 |
| 内核 | 特权核心，扩展围绕它 | 无特权内核，agent loop 也是插件 |
| 替换能力 | 部分可配置 | 每个能力都是一个 seam（接缝），替换 Provider 即替换能力 |
| 配置 | 单一配置文件 | profile（具名组装）+ 有序 patch 层叠加 |
| 副作用管理 | 手工清理 | 注册即副作用（effect），插件卸载时自动撤销 |
1.3 底层框架：Cordis
dsh 构建在 Cordis 之上——一个以 vendor 方式引入的轻量插件框架。Cordis 提供三件东西：
Context（上下文）：服务的容器，所有能力以稳定 key 暴露在
ctx上（如ctx.tools、ctx.llm）。插件生命周期：
apply(ctx)→ 注册副作用 → 卸载时自动回卷。类型化事件系统：
emitwaterfallparallelserialbail五种分发模式，是 dsh 的主要扩展点。
学习 dsh，Cordis 是第一课。本知识库第 3～6 章会用官方 Cordis 教程的 7 个动手实验带你从零掌握它。
1.4 核心术语速查
| 术语 | 含义 |
|---|---|
Context (ctx) | 服务容器；插件通过 ctx.<key> 互相发现 |
| Plugin（插件） | 实现 Service 的对象（函数 对象 Service 子类） |
| Service（服务） | 插件提供的具名能力，占据一个 ctx.<key> |
| inject | 插件声明依赖的服务名列表，服务就绪后插件才启动 |
| Effect | 可逆副作用：注册的监听器、子插件、工具等，卸载时自动撤销 |
| Fiber | 已加载插件实例的运行时句柄，带状态机（PENDING/LOADING/ACTIVE/…） |
| Seam（接缝） | 可替换能力：Service Definition + Provider + Consumer 三角色 |
| Profile | 存放在 Harness home 中的具名插件组装 |
| 组合包（Bundle） | Cordis 配置项及挂载代码的分发格式 |
| Session Event | 追加式会话日志事件，是"模型可见即已记录"的持久事实 |
| Turn（轮次） | 一次完整交互，含零或多个 step |
| Step（步骤） | 一次模型请求 + 它调用的工具 |
1.5 本知识库的学习路径
第 2 章：安装运行，认识 profile 与组合包。
第 3 章：Cordis 五大核心概念与分发模式。
第 4 章：动手写第一个插件，理解生命周期与 effect。
第 5 章：服务（
ctx、inject、依赖驱动加载）。第 6 章：事件系统与 waterfall 短路语义。
第 7 章：配置校验、组合与 HMR 热重载、PENDING 诊断。
第 8 章：接入真实 harness，注册一个模型可调用的工具。
第 9 章：dsh 架构全景（启动层叠、核心包、轮次流程、会话日志）。
第 10 章：扩展实战——新行为该挂在哪个扩展点。
第 11 章：常见问题与排错手册。
官方教程要求克隆仓库并 pnpm install，但不需要任何 API 密钥——所有示例都能在无密钥环境中运行。
本章内容依据官方文档 Architecture 与 Cordis Tutorial 整理。