源码地图：从哪里开始读

把 23,000+ 行核心实现压缩为一条可执行的阅读路线，并标出关键符号与依赖。

先读 12 个文件

第一站：消息与 provider 边界

packages/ai/src/types.ts 定义 Message、Tool、Context、stream event、Model 与 provider options。先建立这套数据语言，才能看懂上层为何需要转换。

models.ts 则把 provider 注册、认证解析、模型目录与 stream 组合在一起。上层依赖 Models 接口，不需要知道每个 API 的 payload 细节。

第二站：真正的 agent loop

1. agent/src/types.ts：阅读 AgentLoopConfig、AgentTool、AgentState、AgentEvent。
2. agent/src/agent-loop.ts：阅读 runLoop()、streamAssistantResponse()、tool batch。
3. agent/src/agent.ts：理解 stateful wrapper、subscribe、prompt、continue、abort、queue。

第三站：session 与 app runtime

先读 session-manager.ts 的 entry types 和 context building，再读 agent-session-runtime.ts 的服务装配。最后进入 agent-session.ts：此时你已知道它桥接的两端是什么。

第四站：横切系统

• core/resource-loader.ts：settings、context、skills、prompts、extensions 如何发现。
• core/system-prompt.ts：工具、guidelines、项目 context 如何组成 prompt。
• core/extensions/：extension API 与 hooks。
• modes/：interactive/print/json/rpc 如何消费同一 session。
• packages/tui/src/：终端差分渲染与组件。

一条完整调用追踪

main()
→ createAgentSessionRuntime()
→ createAgentSession()
→ AgentSession.prompt()
→ Agent.prompt()
→ agentLoop()
→ runLoop()
→ streamAssistantResponse()
→ executeToolCalls()
→ AgentSession event listener
→ SessionManager.appendMessage()
→ active mode renders/emits

风险热点

• Context overflow：摘要边界、retry 与旧 session 兼容。
• Tool concurrency：共享写入、交互 UI 与顺序保证。
• Extension collision：同名资源、hook 组合与可信代码。
• Provider drift：不同 API 对 tool call、thinking、cache 的兼容转换。
• Session migration：损坏行、版本演进、active branch 投影。

这些不是泛泛的“可能有 bug”，而是代码中已经有专门类型、测试或防护的摩擦点。