BettyXu2001/how-deepseek-harness-works

DeepSeek Harness 如何工作

DeepSeek Harness 源码教材：先阅读生产级 Harness 为什么这样设计，再从一次 LLM Call 开始，逐步搭出一个 Mini Harness。

阅读源码。亲手构建。理解产品决策。

核心认知是：

Agent = Model + Harness

Harness 负责循环、工具、状态、上下文、安全、扩展和复杂任务编排。这个项目用一套课程、两条学习轨道来讲清楚它：

- Source Track：以 DeepSeek Harness 的真实源码为依据。
- Build Track：通过 14 个累计式 Lab 从零实现同一组机制。
- Product Notes：直接写进每篇 Source Guide，解释设计原因和取舍。

学习路径

LLM Call
-> Architecture & Bootstrap
-> Agent Loop
-> Tool Calling
-> Bash / File / Search
-> Plugin System
-> Session & Context
-> Skills
-> Sandbox & Permissions
-> Planning
-> Subagents
-> Workflows
-> Mini Harness

| 部分 | 源码 / 理论 | Build Track |
|---|---|---|
| Part 0 · 基础 | 什么是 Agent Harness；架构概览 | Lab 00 |
| Part 1 · Agent 运行时 | 入口点与引导启动；Agent 循环 | Lab 01 |
| Part 2 · 工具 | 工具系统 | Labs 02–05 |
| Part 3 · 状态与可扩展性 | 插件系统；会话与上下文；技能 | Labs 06–08 |
| Part 4 · 安全且长时间运行的 Agent | 运行时、沙箱与权限；规划；子 Agent；工作流与调度器 | Labs 09–12 |
| Part 5 · 构建真正的 Harness | 系统组装 | Lab 13 |

参见完整课程、Source-to-Lab 映射和 Lab 索引。

交付规则

一次编写一个复习单元：

source/theory tutorial
-> related lab tutorial(s)
-> verification
-> review
-> next unit

一篇 Source Guide 可以支撑多个聚焦的 Lab。例如，工具系统映射到 Tool Calling、Bash、File 和 Search。持久化与压缩保留在会话与上下文中；权限保留在运行时与沙箱中。

项目结构

ADR/                    # research records and frozen implementation plan
docs/
00-overview/          # course overview and foundational article
01-source-track/      # DeepSeek Harness Source Guides
topics/               # review-unit and Source-to-Lab map
labs/
00-...13-.../         # active cumulative labs, each with src/
legacy/               # archived experiments from the former 10-lab outline
site/
chapters.json         # website navigation and display order
content/zh-CN/        # canonical Chinese website content
content/en-US/        # English counterpart
assets/                 # diagrams, images, and screenshots
references/             # source indexes and external references
scripts/                # validation and site helpers

Source Guide 的物理文件名保持稳定。课程和网站定义了推荐的阅读顺序。

网站

从仓库根目录预览：

node scripts/serve-site.mjs

然后打开打印出的本地 URL。该静态网站也可以通过 .github/workflows/deploy-pages.yml 部署。

中文是规范的内容来源。在教程按每次一个复习单元完成的过程中，保持英文页面在结构上对齐。
你将学到什么

到最后，你应该能够解释：

- 为什么一次 LLM 调用还不是一个 Agent。
- Turn、Step、工具调用和停止条件如何构成一个 Agent Loop。
- 为什么工具、插件和技能是不同的概念。
- 会话日志如何成为模型可见的上下文，并在长时间运行中存续。
- 沙箱、权限、防护和审批如何约束执行。
- 何时规划、子代理或确定性工作流是合适的。
- 各模块如何组装成一个连贯的教学级 Harness。

源基线

DeepSeek Harness 源声明与 ADR/RESEARCH.md 中记录的研究基线相关联。当前的写作和实现顺序已冻结在 ADR/PLAN.md 中。