flysheep-ai/learn_deepseek_harness

learn-agent-harness

一门关于 Agent Harness 内部机制的可运行课程。
从一个 60 行的脚本开始，一章一章地观察，一个现代
编码 agent 的 harness 是如何被真实问题逼出来的。

CI Python 3.11+ 23 chapters 22 tests passing offline demo deps License

English · 中文版 README.cn.md

一门可运行、循序渐进的agent harness 内部机制课程——讲述一个现代
编码 agent（Claude Code / DeepSeek Harness 风格）在底层是如何工作的，从
一个 60 行的 agent 循环到一个完整的可插拔 harness。23 章，每章一个概念，
每一章都是一个完整、自包含、可离线运行的 Python 文件
（python code.py --demo，无需 API key）。

agent-harness · llm-agents · tool-calling · ai-coding-agent · plugin-system · educational

这是什么

User ──▶ Agent Loop ──▶ LLM ──▶ Tool Calls ──▶ Filesystem / Shell / Sandbox
│  ▲
▼  │
Session (event log)

像 LangChain、LangGraph、Claude Code 和 DeepSeek Harness 这样的框架有
数万行代码——难以阅读，更难以修改。本课程讲授它们底层真正发生了什么：
agent 循环 / 工具注册表 / 会话事件日志 / 权限 / 上下文压缩 / 子 agent / 插件系统
/ 能力接缝 / 目标循环——以及那些让 deepseek-harness
真正新颖的部分：可回退的副作用、响应式依赖、惯性
生命周期，以及自我扩展。

适合：懂 Python、调用过 LLM API、用过工具
调用，但想理解 harness 实际如何工作的开发者。学完本
课程后，DeepSeek Harness 的 architecture.md 的每一页都能对应到这里的
某一章。

deepseek-harness 有何不同

一个通用的 harness 教程会讲授本课程开篇的那个 60 行循环——
while True: call the model, run its tools, append messages。它很少
讲授的是为什么一个工业级 harness 看起来完全不像那个循环。其中大部分
距离并非“更多功能”，而是一些被命名的结构性
决策——这才是本课程真正的主题：

| 独特决策 | 为什么它并不显而易见 | 章节 | 此处的最小形式 |
|---|---|---|---|
| 事件日志才是真相 | messages 看起来像是记忆，但它只是一个投影；实际存储的是一个仅追加的日志 | s05 | Session + derive_messages() |
| 轮次 / 步骤 / 回合 | “一次输入” ≠ “一次模型调用”；没有这些词，你就无法对预算、重放或被拒绝的轮次进行推理 | s06 → s17 | run_turn() + 内部步骤循环 |
| 权限是监听器，不是 if | 工具执行是一条瀑布流（pre → execute → post）；策略挂在其上，可在不触碰循环的情况下添加/移除 | s04 → s13 | 一个 6 行的 EventBus.waterfall |
| 能力接缝 | 定义 / 提供者 / 消费者——替换一个提供者，整个产品随之改变，无需分叉提供者 | s15 | FileSystem / Shell 协议 + Local / Memory / DryRun |
| 一切皆插件 | 不存在需要打补丁的特权核心；一个功能就是一个单元，整体挂载、整体卸载 | s14 | PluginContext + 逆序清理器 |
| 可逆效果 | 注册会返回其自身的逆操作，因此复合清理是自动的——这正是插件能够热卸载的原因 | s14 → s19 | on()/use()/register() 返回一个清理器 |
| 响应式辅助效果 | 依赖会在每一次上下文变化时重新求值；卸载会级联触发停止提供 → 守卫 → 撤回 | s20 | DependencyRuntime._reevaluate |
| 惯性生命周期 | 状态转换会运行至完成，然后才响应新的目标；失败先恢复，后记录 | s21 | 目标视图 vs 已提交视图 |
| 作用域 | 子代理的价值在于上下文隔离 + 受限的动作空间，而不是“多一次 LLM 调用” | s09 | registry.restricted() |
| 目标即持久状态 | 目标在终端之后依然存在，并由模型来评判，而不是由 while not done 来评判 | s17 → s22 | 事件日志之上的 GoalStore |
| 自我扩展 | 模型在会话中途检查并修改其自身的运行时 | s23 | harness_inspect/mount/unmount |

这些想法并非民间传说——它们扎根于一篇正式论文，Cordis
（可逆效果 + 响应式辅助效果）。本课程用一个 30 行的 EventBus + PluginContext 重新表达了
该论文的核心；
论文阅读笔记将
每一个 Cordis 概念映射回某一章，包括哪些内容被有意
没有移植。阅读路径：docs/。

学习路径

第 1 部分——代理如何运行

| | | |
|---|---|---|
| s01 agent_loop | 一个对话循环——以及为什么它还不是代理 |
| s02 tool_use | 第一个工具；内部步骤循环由此诞生 |
| s03 tool_registry | if/elif → Tool / Schema / Registry / Executor |
| s04 permission | pre → execute → post 流水线；权限位于 pre 中 |
| s05 session_event_log | 消息不再是真相；事件日志接管一切 |
| s06 turn_and_step | 一次用户输入 ≠ 一次模型调用 |
第 2 部分 — 智能体如何管理上下文、状态和任务

| | | |
|---|---|---|
| s07 prompt_assembly | 系统提示词是运行时产物，而非常量 |
| s08 skill_loading | 渐进式披露：目录始终存在，正文按需加载 |
| s09 subagent | 上下文隔离 + 受限动作空间 |
| s10 context_compaction | 压缩遮蔽的是投影，而非日志 |
| s11 task_system | 任务是 harness 状态，而非模型记忆 |
| s12 background_jobs | 同步工具调用 vs 异步作业 |

第 3 部分 — 为什么工业级 harness 需要 Event / Plugin / Capability

| | | |
|---|---|---|
| s13 event_bus | 权限/日志/指标从循环中移出，交给监听器 |
| s14 plugin_system | Context / Registry / Plugin — 一切皆插件 |
| s15 capability_seams | Definition / Provider / Consumer — 换掉提供者，就换掉整个世界 |
| s16 agent_team | spawn / send / receive / status；策略属于模型 |
| s17 goal_loop | 目标是持久状态，而非 while not done |
| s18 full_harness | 集成，通过自主修复失败的测试来验证 |

第 4 部分 — deepseek-harness 的独特机制（进阶）

| | | |
|---|---|---|
| s19 revertible_effects | 注册返回其逆操作：track / accumulator / LIFO / independence |
| s20 reactive_coeffects | 依赖在每次上下文变化时重新求值；三阶段级联 |
| s21 inertial_lifecycle | 目标视图 vs 已提交视图驱动一切；惯性；失败时优先恢复 |
| s22 session_lifecycle | 会话/结束种子边界、分叉、目标激活（armed/disarmed）、派生缓存 |
| s23 self_extending | inspect / mount / unmount — 模型修改自己的运行时 |

每一章结尾都会指出下一章存在是为了修复的痛点。
对比相邻两章的差异，你就能得到“这一章添加了什么”的确切答案。

快速开始

pip install -r requirements.txt        # one dependency: httpx

python s01_agent_loop/code.py --demo                 # any chapter runs offline
python s18_full_harness/code.py --demo --debug       # trace the inside of a turn
python s23_self_extending/code.py --demo             # the model modifies its own runtime

real model (OpenAI-compatible API or Anthropic)
cp .env.example .env          # LLM_API_KEY / LLM_BASE_URL / LLM_MODEL
python s18_full_harness/code.py
Help me find out why the tests are failing and fix them.

python3 -m unittest discover tests                    # 22 deterministic tests
学习无需密钥——每一章的 --demo 都在离线的脚本化模型（ScriptedProvider）上运行。环境变量见 .env.example。

两条铁律

1. 模型可见即被记录（在 s05 中形式化）。
任何进入模型请求的内容都必须能从事件日志中重建。messages 是一种投影，绝不是真相。
2. 模型决策。框架赋能（在 s02 中形式化，在 s18 中检验）。
框架构建一个由工具、上下文、状态和权限组成的可操作世界——它从不脚本化模型的思考。测试套件会扫描核心代码中形如 if task_type == "research" 的分支：零命中。

仓库布局

learn-agent-harness/
├── README.md / README.cn.md   ← 双语入口
├── DESIGN.md                  ← 研究发现 + 课程设计决策
├── harness_llm.py             ← 唯一共享文件：模型访问层
│                                （不包含任何框架逻辑）
├── tests/                     ← 每章的冒烟测试 + 确定性机制测试
├── docs/                      ← Cordis 论文笔记 + 阅读索引
├── s01_agent_loop/ … s23_self_extending/
│     每一章：code.py + README.md（中文）+ README.en.md

为什么每章一个 code.py，而不是共享的 src/？
因为 from src.agent import Agent 会隐藏学习过程——你永远看不到 Agent 是如何成长的。本项目倾向于重复：每一章都展示完整、最小、可运行的实现。唯一的例外是 harness_llm.py——HTTP 传输不属于框架机制。

与参考项目的关系

- shareAI-lab/learn-claude-code
——借鉴了其教学方法：每章一个概念，README 从痛点出发，代码内标注“新增 / 未变”，愿意重复。
- deepseek-ai/deepseek-harness
——吸收了其工业级设计：会话事件日志、Turn/Step 术语、工具流水线、能力接缝、一切皆插件、自我扩展。不是它的 Cordis 框架——相同的理念在这里用 30 行的 EventBus + PluginContext 表达。参见概念 → 章节映射 上文。

本项目不是这两个仓库的 fork、翻译或重写。设计决策见：DESIGN.md。

延伸阅读

- docs/README.md ——索引和建议阅读路径。
- Cordis 论文笔记（中文）
——对 deepseek-harness 的 Cordis 框架所依据的 88 页形式化论文的阅读指南，将每个概念映射到某一章（最好在 s14–s23 之后阅读）。

贡献

欢迎贡献——代码或文字的修正、新练习、更好的解释、翻译或测试覆盖。

- 阅读 CONTRIBUTING.md 了解工作流程和内部规则。
- 所有参与者都应遵守行为准则。
- 在开始大型更改之前，请先创建一个 issue，以便我们能够就方向达成一致。

安全

请私下报告漏洞，而不是创建公开的 issue。
请参阅 SECURITY.md。

支持

如有问题、想法和讨论，请参阅 SUPPORT.md。

许可证

MIT © 2026 flysheep-ai