从零理解如何构建 AI Agent

Appearance

从零拆解 DeepSeek Harness ​

以 DeepSeek Harness 当前源码为分析基点，12 章主干 + 6 篇附录。教的是为什么这样拆，不是把官方架构文档再抄一遍。

全书按包名、事件名、符号名对照仓库 commit 47f943859b（2026-08-13）核实，正文不引用具体行号。仓库处于 developer preview，重构会让包名、事件名跟着漂移；对不上时以仓库当前源码和文档为准。

适合谁 / 不适合谁 ​

  • 适合：已经写过最小 Agent 循环，想看一套把循环、工具、会话、人和产品形态拆开的真实 harness。
  • 不适合：只想用 TypeScript 跟练最小闭环——请先 实践篇；OpenCode 主书概念入口见 什么是 AI Agent。

跨线入口 ​

本书特点 ​

循环不是核心：玩具 Agent 死掉的原因，从来不是循环写得不够优雅。贵的是三件事同时成立——换执行世界、从日志重建模型上下文、加人机能力时不准改循环。

四条主线：

  • 坐标系（00-01）：先认这不是又一个框架，再摸清仓库 spine / seam / 产品壳
  • 插件与循环（02-04）：可逆注册、Agent 接口与默认司机、一次 turn 的心跳
  • 日志与能力（05-07）：事件流投影、能力成套、工具系统边界
  • 世界与产品（08-11）：scope、启动时组合、人机平面、自己做时先抄哪五层

章节目录 ​

坐标系 ​

章节核心问题
第1章：这不是又一个 Agent 框架玩具 Agent 缺的不是循环，是可替换的能力边界
第2章：五分钟仓库地图先认 spine，再认 seam，最后才看 UI

插件与循环 ​

章节核心问题
第3章：核心必须消失注册是可逆 effect；不调 next() 就是短路
第4章：Agent 是接口，循环是实现依赖 agent-loop = 把可替换的司机焊死
第5章：一次 turn 是怎么跑完的followup / steer / inject 是同一条 inbox 的三种策略

日志与能力 ​

章节核心问题
第6章：模型看见的必须能从日志重建deriveMessages() 是投影，不是第二份真相
第7章：能力不是一个函数只加一个 tool 函数，换不了执行世界
第8章：工具系统才是工程地基政策、超时、沙箱都不进循环

世界与产品 ​

章节核心问题
第9章：每个 Agent 自己的世界可见性跟所有权必须是同一件事
第10章：组合发生在启动时换产品形态是叠层，不是 fork 代码
第11章：人机协作不在循环里slash command 不是模型消息
第12章：先抄这五层事件日志、接口/司机、能力成套、可逆注册、启动时组合

附录 ​

主线反复甩锅、又不打断主线的六块。建议读完第 6 章 / 第 9 章后再按需翻。

读完这一章，下一步做什么

本章行动任务