## 项目概述

该仓库是 Spring AI Alibaba 官方文档网站的源代码，基于 Docusaurus 构建，提供中英文双语文档。仓库内容主要涵盖 Spring AI Alibaba 框架的 Agent 框架、Graph 核心、RAG、多智能体协作、人工介入、记忆管理、沙箱运行时等高级主题，以及模型、消息、工具、结构化输出等基础教程。

## 核心功能

- **Agent 框架**：提供 ReactAgent 实现，支持 ReAct 范式、工具调用、多智能体协作（顺序、并行、路由、监督者模式）、人工介入（HITL）、上下文工程、记忆管理等。
- **Graph 核心**：提供底层工作流编排引擎，支持状态管理、节点/边定义、条件分支、并行执行、检查点持久化、时间旅行等。
- **RAG 支持**：涵盖两步 RAG、Agentic RAG、混合 RAG 的架构与实现，以及知识库构建、文档加载、向量存储等组件。
- **沙箱运行时**：提供隔离的代码执行和浏览器自动化环境，支持 Python、Shell 和浏览器操作。
- **技能系统**：支持技能的渐进式披露，通过 SkillRegistry 和 SkillsAgentHook 实现按需加载。
- **文档站点**：基于 Docusaurus 构建，支持中英文切换，提供 Markdown 文档和代码示例。

## 适用与不适用场景

**适用场景**：
- 需要构建生产级 AI Agent 应用的开发者，尤其是使用 Java/Spring 技术栈。
- 需要实现复杂多智能体协作、人工审批、长期记忆等高级功能的场景。
- 需要将 RAG 与 Agent 结合，构建知识库问答或研究助手。
- 需要隔离执行 Python/Shell/浏览器操作的场景。
- 需要学习 Spring AI Alibaba 框架的开发者。

**不适用场景**：
- 非 Java 技术栈的开发者（框架基于 Java/Spring）。
- 简单的单轮对话应用，无需 Agent 或工作流编排。
- 需要图形化低代码编排的场景（虽然支持 Dify DSL 导出，但主要面向代码开发）。
- 对实时性要求极高且不能容忍 LLM 调用延迟的场景。

## 技术架构与依赖

- **基础框架**：Spring AI Alibaba，基于 Spring AI 构建。
- **文档站点**：Docusaurus（React 静态站点生成器）。
- **核心组件**：
  - `spring-ai-alibaba-agent-framework`：Agent 框架，提供 ReactAgent、多智能体、Hook/Interceptor 等。
  - `spring-ai-alibaba-graph-core`：Graph 引擎，提供 StateGraph、节点/边、检查点等。
  - `spring-ai-alibaba-sandbox-tool`：沙箱工具，提供代码执行和浏览器自动化。
  - `spring-ai-alibaba-starter-dashscope`：DashScope 模型适配。
- **外部依赖**：Nacos（服务注册与发现）、Docker（沙箱容器）、Redis/PostgreSQL/MongoDB（检查点持久化）、向量数据库（Milvus、Pinecone、Redis、Elasticsearch 等）。
- **构建工具**：Make、npm。

## 安装与快速开始

仓库资料未提供具体的安装步骤，但根据 README 和文档，可以推断：

1. 确保本地安装 npm。
2. 克隆仓库后，运行 `make install && make preview` 启动中文文档站点。
3. 运行 `make preview-en` 启动英文文档站点。
4. 运行 `make build && make serve` 构建并服务站点。
5. 提交前运行 `make npm-lint && make markdown` 确保 CI 通过。

## 典型使用方法

仓库主要作为文档网站，典型使用是浏览文档学习框架。但文档中提供了大量代码示例，例如：

- 创建 ReactAgent：`ReactAgent.builder().name("agent").model(chatModel).tools(tool).build()`。
- 构建工作流：使用 `StateGraph` 添加节点和边，编译后执行。
- 实现 RAG：通过 Hook 或 Interceptor 在模型调用前检索文档。
- 多智能体协作：使用 `SequentialAgent`、`ParallelAgent`、`LlmRoutingAgent`、`SupervisorAgent`。
- 人工介入：配置 `HumanInTheLoopHook` 和检查点，实现工具调用审批。
- 沙箱执行：通过 `BaseSandbox` 和 `BrowserSandbox` 提供工具。

## 配置与部署要点

- **模型配置**：需要设置 DashScope API Key（环境变量 `AI_DASHSCOPE_API_KEY`）。
- **Nacos 配置**：A2A 场景需要配置 Nacos 地址、用户名、密码，并启用 registry/discovery。
- **沙箱配置**：需要配置 Docker socket 地址（`sandbox.docker.host`）和容器池大小。
- **检查点持久化**：生产环境建议使用 Redis、PostgreSQL 或 MongoDB 作为检查点存储。
- **文档站点部署**：使用 `make build` 生成静态文件，可部署到任意静态托管服务。

## 限制、风险与许可证

- **许可证**：Apache-2.0。
- **限制**：
  - 框架主要面向 Java/Spring 技术栈。
  - 沙箱依赖 Docker，需要 Docker 环境。
  - 部分功能（如 A2A）依赖 Nacos 3 及以上版本。
  - 结构化输出对部分模型依赖提示词增强，不保证严格格式。
- **风险**：
  - 沙箱执行代码存在安全风险，需确保容器隔离和资源限制。
  - 人工介入机制需要合理配置检查点，否则可能丢失状态。
  - 多智能体协作可能增加 LLM 调用成本，需合理设计。

## 官方链接

- GitHub 仓库：https://github.com/spring-ai-alibaba/website
- Spring AI Alibaba 主项目：https://github.com/alibaba/spring-ai-alibaba
- Docusaurus 文档：https://docusaurus.io/docs/markdown-features/react
- A2A 协议：https://a2a-protocol.org/latest/

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README 和文档内容。
- 分析时间：2025年4月。