怎么读 Agent 源码 · 4 步法 + 8 维尺

装 + 跑通最小 hello-world

pip install / npm install，然后原封不动抄官方 README 的第一段 quickstart 跑一次。不要急着看代码。这一步的目的：

• 确认你能 reproduce 一次成功执行——避免后面读代码时把"环境配错"误诊成"代码理解错"；
• 知道 entry 函数具体叫什么（create_agent? Runner.run? agent.invoke?）以及它的典型调用形态；
• 留一份能反复跑的最小脚本——后面 trace 用得上。

反模式：跳过 quickstart 直接看源码——你会反复在"这个变量是用户传进来的、还是默认值、还是 magic 值"上卡壳。

Trace 一次执行 · 找出真正被踩到的 ≤ 5 个文件

在 entry 函数所在文件加 1 行打印（或用 sys.settrace / py-spy / IDE breakpoint），跑一次最小例子，记录"哪些文件按什么顺序被进入"。结果几乎总是 4–8 个文件——而仓库可能有 200 个 .py。

• 这 ≤ 5 个文件就是核心——读懂它们 = 读懂 80% 的设计；
• 其余 195 个是 adapters / integrations / examples / tests，只在用到时查；
• 记下每跳一次的"函数 → 文件:行"——这就是你的 call graph，比 ASCII art 强 10 倍。

反模式：从 README 引用的 import 链顺着读——你会读到一堆从来没被运行时调用过的 fallback / 兼容代码。

用 8 维尺填表 · 给每一维找出"它在哪里、长什么样"

下面那张 8 维表是这一章所有源码精读的统一坐标系。每读一家就把这 8 格填出来——不是写论文式答案，而是给出文件名 + 行号范围 + 一句话总结。

• 填表的 by-product 是你"被迫去找"——比起被动阅读，主动检索 4 个维度后你对仓库结构的认知会指数级提升；
• 3 家填完，差异自然浮现——不需要写比较文章；
• 遇到第 9、第 10 家框架时，沿用同一张表即可。

写"反向文档" · 合上代码用自己的话重写

这是最容易跳过、收益最大的一步。读完后关掉编辑器，用自己的话写一段："如何在这个框架里实现 X"——X 选一个略有难度的扩展场景（如"加一个会拒绝某类 tool 调用的 middleware"）。然后再打开官方文档对照：

• 你写得对的地方 → 真懂了；
• 你写错的地方 → 差距就是你需要补的那部分；
• 官方文档没写但你想到的地方 → 可能是别人也没意识到的 sharp edge。

下面有一个反向文档的实例对照（LangChain 中"自定义 state"），可以照葫芦画瓢做自己的练习。