Spring AI Alibaba 源码学习 01：项目结构与模块分工

spring-ai-alibaba/
├── spring-ai-alibaba-bom/              # BOM 模块
├── spring-ai-alibaba-graph-core/       # Graph 核心运行时
├── spring-ai-alibaba-agent-framework/ # Agent 框架
├── spring-ai-alibaba-studio/           # Studio 应用
├── spring-boot-starters/               # Spring Boot Starters
│   ├── spring-ai-alibaba-starter-a2a-nacos/
│   └── spring-ai-alibaba-starter-config-nacos/
├── tools/                              # 工具目录
└── docs/                               # 文档目录

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>1.1.0.0-M4</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

public class StateGraph {

	/**
	 * Constant representing the END of the graph.
	 */
	public static final String END = "__END__";

	/**
	 * Constant representing the START of the graph.
	 */
	public static final String START = "__START__";

	/**
	 * Constant representing the ERROR of the graph.
	 */
	public static final String ERROR = "__ERROR__";

	/**
	 * Constant representing the NODE_BEFORE of the graph.
	 */
	public static final String NODE_BEFORE = "__NODE_BEFORE__";

```- **GraphRunner**：图执行引擎，负责执行编译后的图

```java
public class GraphRunner {

	private final CompiledGraph compiledGraph;

	private final RunnableConfig config;

	private final AtomicReference<Object> resultValue = new AtomicReference<>();

	// Handler for main execution flow - demonstrates encapsulation
	private final MainGraphExecutor mainGraphExecutor;

	public GraphRunner(CompiledGraph compiledGraph, RunnableConfig config) {
		this.compiledGraph = compiledGraph;
		this.config = config;
		// Initialize the main execution handler - demonstrates encapsulation
		this.mainGraphExecutor = new MainGraphExecutor();
	}

	public Flux<GraphResponse<NodeOutput>> run(OverAllState initialState) {

```- **CompiledGraph**：编译后的可执行图
- **OverAllState**：全局状态对象，用于在节点间传递数据

**核心概念**：
- **Node**：工作流中的节点，封装特定操作或模型调用
- **Edge**：节点间的边，表示状态转换
- **OverAllState**：全局状态，携带整个流程的共享数据

### 3. spring-ai-alibaba-agent-framework

**职责**：Agent 框架，基于 Graph 核心运行时构建的高级 Agent 开发框架。提供 ReactAgent、SequentialAgent、ParallelAgent 等预构建的 Agent 类型，简化 Agent 开发。

**关键入口点**：
- **ReactAgent**：核心 Agent 类型，实现 ReAct（Reasoning + Acting）范式

```java
public class ReactAgent extends BaseAgent {
	private static final int DEFAULT_MAX_ITERATIONS = 10;

	private final AgentLlmNode llmNode;

	private final AgentToolNode toolNode;

	private CompiledGraph compiledGraph;

	private List<Hook> hooks;

	private List<ModelInterceptor> modelInterceptors;

	private List<ToolInterceptor> toolInterceptors;

	private int maxIterations;

	private int iterations = 0;

	private String instruction;

	private Function<OverAllState, Boolean> shouldContinueFunc;

	public ReactAgent(AgentLlmNode llmNode, AgentToolNode toolNode, CompileConfig compileConfig, Builder builder) throws GraphStateException {
		super(builder.name, builder.description, builder.includeContents, builder.returnReasoningContents, builder.outputKey, builder.outputKeyStrategy);
		this.instruction = builder.instruction;
		this.llmNode = llmNode;
		this.toolNode = toolNode;
		this.compileConfig = compileConfig;
		this.shouldContinueFunc = builder.shouldContinueFunc;
		this.hooks = builder.hooks;
		this.modelInterceptors = builder.modelInterceptors;
		this.toolInterceptors = builder.toolInterceptors;
		this.includeContents = builder.includeContents;
		this.inputSchema = builder.inputSchema;
		this.inputType = builder.inputType;
		this.outputSchema = builder.outputSchema;
		this.outputType = builder.outputType;
		this.maxIterations = builder.maxIterations <= 0 ? DEFAULT_MAX_ITERATIONS : builder.maxIterations;

		// Set interceptors to nodes
		if (this.modelInterceptors != null && !this.modelInterceptors.isEmpty()) {
			this.llmNode.setModelInterceptors(this.modelInterceptors);
		}
		if (this.toolInterceptors != null && !this.toolInterceptors.isEmpty()) {
			this.toolNode.setToolInterceptors(this.toolInterceptors);
		}
	}

	public static com.alibaba.cloud.ai.graph.agent.Builder builder() {
		return new DefaultAgentBuilderFactory().builder();
	}

```- **SequentialAgent**：顺序执行多个子 Agent 的工作流 Agent
- **ParallelAgent**：并行执行多个子 Agent 的工作流 Agent
- **LlmRoutingAgent**：基于 LLM 进行路由决策的工作流 Agent
- **LoopAgent**：循环执行的工作流 Agent

**核心特性**：
- Context Engineering：内置的上下文工程最佳实践
- Human In The Loop：人在回路支持
- Tool 调用：支持工具调用和 MCP 协议
- Hook 机制：支持在 Agent 执行的不同阶段插入自定义逻辑

### 4. spring-ai-alibaba-studio

**职责**：Studio 应用，提供可视化的 Agent 开发和管理界面。基于 Spring Boot 和 Next.js 构建，包含后端 API 和前端 Web UI。

**关键特性**：
- Agent 可视化界面
- 运行时追踪和监控
- Agent 配置管理
- 基于 CopilotKit 的 UI 组件

**技术栈**：
- 后端：Spring Boot + Spring AI Alibaba Agent Framework
- 前端：Next.js + TypeScript + CopilotKit

### 5. spring-boot-starters

**职责**：Spring Boot Starters，提供与 Spring Boot 的集成和自动配置。

#### 5.1 spring-ai-alibaba-starter-a2a-nacos

**职责**：提供 Agent-to-Agent (A2A) 通信的 Nacos 集成，支持分布式 Agent 协调和协作。

**关键特性**：
- 基于 Nacos 的服务发现
- A2A 通信协议支持
- 分布式 Agent 编排

#### 5.2 spring-ai-alibaba-starter-config-nacos

**职责**：提供基于 Nacos 的动态配置管理，支持 Agent 配置的动态更新。

**关键特性**：
- Nacos 配置中心集成
- 动态配置更新
- 配置热更新

## 模块依赖关系

下图展示了模块间的依赖关系：

![项目结构与模块分工关系图](images/a7442d82-d766-4fdf-9a78-b5de5dd56ce5.png)

*项目结构与模块分工关系图，沿用原材料配图。*

**依赖说明**：
- **graph-core** 是基础层，不依赖其他 Spring AI Alibaba 模块
- **agent-framework** 依赖 **graph-core**，提供高级 Agent 抽象
- **studio** 依赖 **agent-framework**，提供可视化界面
- **starters** 依赖 **agent-framework**，提供 Spring Boot 集成
- 所有模块都通过 **bom** 统一管理依赖版本

## 工具和辅助目录

### tools/

工具目录包含项目开发和维护所需的工具：
- **ci-config/**：CI/CD 配置文件
- **github-actions/**：GitHub Actions 工作流
- **linter/**：代码检查工具配置（checkstyle、markdownlint、yamllint 等）
- **make/**：Makefile 辅助脚本
- **scripts/**：Python 脚本（中文内容检查、换行检查等）
- **src/checkstyle/**：Checkstyle 配置文件

## 项目构建

项目使用 Maven 进行构建，主要命令：

```bash
# 编译项目
mvn clean compile

# 运行测试
mvn test

# 打包项目
mvn clean package

# 代码格式化
mvn spring-javaformat:apply

# 代码检查
mvn checkstyle:check