Agent 框架源码教程 JiauZhang/deepseek-harness-from-scratch

DeepSeek Harness 从零入门到精通

构建你自己的 AI Agent 编排框架

教程目录

本教程从源码层面对 DeepSeek Harness 进行了全面深入的剖析，共 11 章，涵盖框架基础、核心模块、高级主题和实战构建。

第一部分：基础入门

| 章节 | 内容 | 关键主题 |
| 第 1 章：开篇 | 项目简介、设计哲学、架构总览 | 一切皆插件、事件溯源、Seam 架构 |
| 第 2 章：Cordis 插件框架深度解析 | Context/Fiber/Events/Plugin 源码分析 | 上下文、四种事件模式、Effect 系统 |

第二部分：核心模块

| 章节 | 内容 | 关键主题 |
| 第 3 章：Agent 系统 | Agent 接口、Inbox 机制、生命周期 | followup/steer/inject、轮次和步骤 |
| 第 4 章：Session 会话系统 | 事件溯源、事件类型、消息派生 | 模型可见即已记录、分支与恢复 |
| 第 5 章：工具系统 | 工具注册、执行管线、Code Mode | defineTool、守卫、并发控制 |
| 第 6 章：LLM 适配器体系 | 适配器模式、StreamChunk 协议 | 流式协议、重试策略 |

第三部分：进阶主题

| 章节 | 内容 | 关键主题 |
| 第 7 章：作用域系统 | 隔离机制、作用域链、事件过滤 | 作用域隔离、ScopedLayers |
| 第 8 章：Goal 目标与 Jobs 任务系统 | 目标状态机、后台任务管理 | 事件派生、AbortController |
| 第 9 章：Seam 架构与能力替换 | 文件系统/Shell/沙箱/子代理 Seam | 可替换能力、isolate 模式 |

第四部分：实战

| 章节 | 内容 | 关键主题 |
| 第 10 章：实战：构建完整 Harness | 完整可运行示例 | LLM 适配器、4 个工具、交互式聊天 |
| 第 11 章：附录 | 术语表、类型速查、事件速查表 | 学习路径 |

核心架构图

graph TB
subgraph "用户界面层"
CLI[CLI App]
WEB[Web App]
API[ACP API]
end

subgraph "编排层"
AL[Agent Loop]
TR[Tool Registry]
SS[Session Store]
LLM[LLM Service]
SP[System Prompt]
end

subgraph "能力层"
FS[Filesystem]
SH[Shell]
SUB[Subprocess]
LSP[LSP]
WB[Web]
end

subgraph "基础设施层"
C[Cordis Framework]
EV[Events]
FB[Fiber]
CTX[Context]
SC[Scope]
end

CLI --> AL
WEB --> AL
API --> AL

AL --> TR
AL --> SS
AL --> LLM
AL --> SP

TR --> FS
TR --> SH
TR --> SUB
TR --> LSP
TR --> WB

C --> EV
C --> FB
C --> CTX
C --> SC

核心设计理念

- 一切皆插件：产品中的每一部分都是插件，每一部分都可以从配置替换
- 模型可见即已记录：任何到达模型的内容都必须能从会话日志重建
- 事件是扩展点：事件就是扩展点，选对事件域是大多数改动的第一个决定
- Seam 架构：以可替换能力接口设计，替换一个 Provider 就能改变整个产品行为

学习建议

1. 按章节顺序阅读，从 Cordis 基础开始
2. 每章都包含真实源码片段和 Mermaid 图表
3. 第 10 章提供完整可运行的示例代码
4. 遇到不熟悉的术语可查阅第 11 章附录

本教程由 DeepSeek Harness 源码分析整理而成。

Sponsor

公众号

AliPay
WeChatPay