Easel 架构课程 · 第 4 课

从哪里开始读：源码精读路线图

5 分钟读完路线 · 全程约 3 小时精读 · 本地代码都在你的机器上

答案先行：今天只读一站—— ~/Code/Projects/openclaw-src/packages/agent-core/src/agent-loop.ts 的 第 214–436 行（runLoop 主循环），约 200 行。别从头读文件，别读整个仓库； 带着第 3 课的七步骨架进去，出来能徒手写出 loop 伪代码，第一站就完成了。

三条读法原则（比路线更重要）

① 永远带着一个问题进去。每站只回答一个问题，答出来就走。
② 折叠所有不服务当下问题的东西。类型体操、hook 细节、错误分支——第一遍全部跳过， 第二遍自然读懂。
③ 任何一处卡超过 15 分钟就标记跳走。卡住说明缺前置知识，硬读是浪费； 后面某站会把它变简单。

五站路线（按依赖顺序，不按目录顺序）

站读什么（file:line 已核实）带进去的问题时长
1 openclaw-src/packages/agent-core/src/agent-loop.ts:214-436 七件事各在哪几行发生？hasMoreToolCalls 怎么算出来（:317）？ 60 min
2 同目录 agent-stream-response.ts:286-357 流式事件怎么变成工具执行？"流中执行"和"流后执行"差在哪？ 30 min
3 easel-repo/web/app.py:2051-2470 浏览器断开为什么 agent 还能跑完？runId 闩锁（:2361）怎么隔离并发会话？ 30 min
4 openclaw-src …/attempt-system-prompt-prepare.ts:244-301
＋ easel-repo/openclaw/workspace/AGENTS.md		 AGENTS.md/SOUL.md 在哪一行被拼进 system prompt？稳定前缀为什么放前面？ 45 min
5 openclaw-src …/run/attempt.ts:331-350
＋ agent-session-compaction.ts:490 起		 工具目录怎么装配？compaction 触发后历史发生了什么？ 弹性

第一站的操作细节（今天做这个）

  1. 开两个窗口：左边 agent-loop.ts 跳到 214 行；右边本课的骨架图（或第 3 课）
  2. 逐段往下读，在代码旁标注七件事的行号（① abort :218 → ② commit :191 → ③ stream :252 → ④ stopReason :281 → ⑤ 回填 :327 → ⑥ turn_end :332 → ⑦ steering :414）
  3. 读到 :317 停一下：hasMoreToolCalls 的三段式布尔表达式是全文件的"心脏"， 逐项弄懂 continuationRequired / endTurn===false / batch.terminate
  4. 读完 :436 出循环的 agent_end，合上笔记，手写 10 行伪代码—— 写不出来就说明还没读完，回去补

读完后回来检验