源码精读 Checklist

1. 读一个 package 的固定模板

1. 先读 README，不进 src。
2. 记录 ctx key、inject、public API。
3. 找 declaration merging：它向 Context/Events 增加了什么。
4. 找构造函数/插件入口：注册了哪些 effect。
5. 找 disposer/ownership：谁负责 teardown。
6. 找 tests：不变量通常比实现注释更稳定。

2. Agent Loop 精读断点

重点搜索这些概念而不是盲目滚文件：factory registration、setupAndPublish、driver wake、claim inbox、pre-step、prepareCall、stream assembler、tool group scheduler、turn-stopping、flush、cancel、dispose。

3. Session 精读断点

重点搜索：SessionEventMap、append、surfaceOp、sourceEventSeqs、deriveMessages、prepare/enter/announce、fork boundary、seed validation、unknown event handling、flush publication。

4. Tools 精读断点

重点搜索：ToolDefinition、defineTool schema DSL、register、visible schemas、restriction/scope、pre-execute/execute/post-execute、scheduler metadata、timeout、presentation。

5. LLM 精读断点

先读统一 vocabulary，再读 DeepSeek adapter。关注 request serialization、reasoning round-trip、SSE framing、StreamChunk、BlockAssembler、usage、finish reason、stable error codes、abort/idle timeout、dynamic credentials。

6. Boot 精读断点

关注 profile manifest、bundle patch、apply order、module resolution、Loader settle、assert loaded/activated、boot rollback、dump-config 与实际 mount 的一致性。

7. 每读完一条链，必须做逆向提问

• 如果删掉这个 service，谁会停？
• 如果 provider 被热替换，旧 effect 怎么撤销？
• 如果在这个 await 中取消，signal 到哪里？
• 如果进程此处崩溃，恢复时能知道发生过什么？
• 如果同时有两个 agent，这个注册是 global 还是 scoped？
• 如果一个 listener 抛错，谁负责隔离？

8. 源码笔记模板

Package:
Role: Definition / Provider / Consumer / Orchestrator
ctx key(s):
inject:
Events produced:
Events consumed:
Effects registered:
Scope behavior:
Durable state:
Cancellation path:
Teardown owner:
Failure boundary:
Key invariants:
Tests that prove them:
My reimplementation sketch: