本项目是一个基于开源项目的学习型教程：在参考
spring-ai-alibaba/DataAgent的基础上，结合个人理解进行拆解、复现与讲解。
目标是帮助开发者从 0 到 1 系统掌握 StateGraph 图编排、双重 RAG 检索、自我纠错、HITL 人机协同 等 Text2SQL Agent 关键能力。
这个教程不是“只看概念”的介绍，而是围绕一个可运行项目，带你把 Text2SQL Agent 的关键能力拆开学透：
- 🧩 从流程到代码的完整映射：用 StateGraph 把问题理解、知识召回、规划、执行、纠错、报告串成清晰链路，知道每一步该放什么能力。
- 📚 结构化 + 非结构化的双通道检索：同时利用关系图谱信息与业务知识库，理解 Text2SQL 在真实业务里如何减少歧义和幻觉。
- 🛠️ 可落地的执行与纠错机制：掌握 SQL 生成与执行、错误回溯修复、Python Docker 沙盒分析的协作方式，而不是停留在“生成 SQL”这一步。
- 🤝 面向生产的交互设计：通过 HITL 人工确认、A2A 协议、SSE 流式反馈，学习高风险场景下可控、可观测的人机协同模式。
- 📖 可复现的学习路径：基于开源项目进行拆解与复现，提供从骨架搭建到核心编排的章节化路线，适合边读边跑、逐步进阶。
- 后端：
Kotlin+Spring Boot 3.x+Jimmer - AI 与编排：
Spring AI Alibaba Graph+Spring AI - 向量与存储：
PostgreSQL+pgvector - 前端：
Vue 3+TypeScript+Vite+A2UI
[用户自然语言提问]
└── A2A 协议流式请求
└── 路由意图识别
├── 知识召回（向量化业务词汇 + QA）
├── 关系图谱召回
├── 可行性评估与任务拆解（Planner）
├── 人工确认拦截（HITL）
├── SQL 生成与执行 + 自动纠错循环
├── Python Docker 沙盒执行与分析
└── 报告整理（Report Generation）
└── 前端流式打字机效果呈现（A2UI）
- 基础环境：
Java 21+、Node.js 20+、pnpm - 数据库：
PostgreSQL（默认localhost:5432/data_agent_tutorial） - 必装扩展：
pgvector
CREATE EXTENSION IF NOT EXISTS vector;首次初始化数据库（在项目根目录执行）：
psql -U postgres data_agent_tutorial -f data-agent-backend/src/main/resources/database.sql然后启动后端：
cd data-agent-backend
./gradlew bootRun出现 Tomcat started on port(s): 9933 即启动成功。
cd data-agent-frontend
pnpm install
pnpm dev默认地址：http://localhost:3500（自动代理 /api 到后端）。
打开浏览器输入自然语言问题，若看到前端卡片出现流式节点打字机效果，即最小 Agent 闭环已跑通。
本教程按章节组织，强烈建议切换到对应章节的 Git 分支对照阅读源码，效果翻倍！
- 🏗️ 00 项目骨架搭建
后端 Kotlin + Jimmer 初始化，前端 Vue3 接入 API 自动生成。 - 🔌 01 A2A 协议实战
跑通 Agent 服务发现与 JSON-RPC 流式事件。 - 🕸️ 02 Graph 编程基础
从单节点走向多分支路由，实现暂停 -> 人工确认 -> 续跑的 HITL 工作流。 - 🧠 03 Bird SQL 知识库基建
完成结构化表关联入库与 PGVector 向量化。 - 🔥 04 SQL Agent 核心编排（系列高潮）
逐个击破：知识召回、关系图谱、任务拆解、SQL 自纠错、Python 高阶计算、商业报告生成。
付费远程运行/安装/定制开发联系微信：ljc666max
其他关于程序运行安装报错请加QQ群：
- 416765656（满）
- 632067985