第 13 章：源码阅读路线，别把框架读成散装零件

这套教程到这里先收个口。最后一章不讲新 API，而是给一条后续阅读路线。读框架源码失败，很多时候不是因为 Java 看不懂，而是入口选错：一上来钻工具类、配置类、泛型细节，最后像在仓库里数螺丝。

本章边界

本章只讲“以后怎么继续读、遇到问题怎么定位”。它不替代前面章节，也不鼓励你把全部源码从头到尾读一遍。

1. 生活类比：参观工厂要按生产线走

参观工厂不要从仓库角落的螺丝盒开始。先看原料入口，再看生产线，再看质检，再看出货。

Spring AI Alibaba 的生产线可以这样走：

这张图比文件列表重要。文件只是入口，生产线才是理解框架的方式。

2. 三轮阅读法

第一轮：只看主干，不看细节。

目标是回答：一个用户输入如何进入 Agent，如何经过模型和工具，再返回结果。

第二轮：看 Graph 和 State。

目标是回答：流程怎么分支、状态怎么传递、记忆怎么恢复、中断怎么继续。

第三轮：看扩展和工程化。

目标是回答：Hook、Interceptor、多 Agent、Studio、Starters 如何围绕主干扩展。

不要试图第一轮就读完所有类。第一轮读得太细，很容易把框架读成散装零件。

3. 遇到问题怎么定位

问题	先问自己	定位方向
Agent 没调用工具	工具描述清楚吗，模型有没有产生 tool call	模型节点、工具节点、工具描述
多轮对话没记住	threadId 是否一致，Saver 是否可用	RunnableConfig、Saver、状态恢复
输出字段读不到	outputKey 是否正确，输出是否进入 state	结构化输出、state key
Hook 没生效	Hook 挂在哪个位置，是否进入图	Hook 位置、图边连接
Graph 没走到预期节点	条件边读的 key 是否正确	条件边、节点输出
多 Agent 输出被覆盖	outputKey 是否冲突，合并策略是什么	子 Agent 输出 key、MergeStrategy

这个表比“去搜哪个文件”更重要。先把问题翻译成框架概念，再去找源码入口。

4. 生产化检查清单

读源码最终不是为了背实现，而是为了能落地。上线前至少问六个问题：

维度	必问问题
配置管理	模型 Key、模型名、Prompt、工具开关放在哪里，能否按环境切换
异常处理	模型失败、工具失败、解析失败、中断恢复失败怎么兜底
日志观测	能否按 threadId 查到模型、工具、节点、边的耗时和错误
测试策略	是否有无模型单测、工具假实现、Graph 路由测试、集成测试
安全边界	Shell、Python、文件、MCP 工具权限是否被限制
成本与限流	循环 Agent、并行 Agent、模型调用上限是否可控

不要只问“能不能跑”。还要问：失败时能不能解释，出事时能不能追踪，权限是否关得住。

5. 待验证清单

这些点适合后续写进阶篇时继续实测：

1. 不同 example 的运行命令和依赖矩阵，需要逐个验证。
2. A2A / Nacos 需要真实 Nacos 和服务发现环境。
3. Redis、Mongo、JDBC、File Saver 需要分别跑集成测试。
4. Voice、Multimodal、DeepResearch 需要模型能力、API Key、网络和依赖环境配齐。
5. Admin 模块依赖前后端和部署资源，适合单独开工程化专题。

6. 本章小结

整套教程的主线就是：

例子跑起来 -> Agent 组起来 -> Graph 跑起来 -> 状态接起来 -> 多 Agent 编排起来 -> 工程化落下来

走到这里，你应该已经有一张能继续深入的地图。后面无论学 RAG、MCP、A2A，还是自己封装生产工具，都可以沿着这张图往外扩。

7. 练习题

1. 任选一个线上问题，按“现象 -> 框架概念 -> 定位方向 -> 验证方式”写一个排查计划。
2. 把 ReactAgent 调用链画成自己的版本，要求包含 Builder、Graph、LLM Node、Tool Node。
3. 选一个还没跑过的 example，先只读 README 和入口说明，写出它可能需要哪些外部依赖。
4. 用“配置、异常、日志、测试、安全、成本”六个维度，审查你准备上线的一个 Agent。

课后源码索引：按三轮阅读法打开

第一轮主干：

1. examples/chatbot/src/main/java/com/alibaba/cloud/ai/examples/chatbot/ChatbotApplication.java
2. examples/chatbot/src/main/java/com/alibaba/cloud/ai/examples/chatbot/ChatbotAgent.java
3. spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/ReactAgent.java
4. spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/DefaultBuilder.java
5. spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/node/AgentLlmNode.java
6. spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/node/AgentToolNode.java

第二轮 Graph 和 State：

1. spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/StateGraph.java
2. spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/CompiledGraph.java
3. spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/OverAllState.java
4. spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/CompileConfig.java
5. examples/documentation/src/main/java/com/alibaba/cloud/ai/examples/documentation/graph/QuickStartExample.java

第三轮扩展和工程化：

1. examples/documentation/src/main/java/com/alibaba/cloud/ai/examples/documentation/framework/tutorials/HooksExample.java
2. examples/multiagent-patterns/pipeline/src/main/java/com/alibaba/cloud/ai/examples/multiagents/pipeline/sequential/SequentialPipelineConfig.java
3. examples/multiagent-patterns/routing/src/main/java/com/alibaba/cloud/ai/examples/multiagents/routing/simple/RoutingConfig.java
4. spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/controller/GraphExecutionController.java