SuperBizAgent-java/docs/learning/00-项目学习路径.md

SuperBizAgent-java 项目学习路径

创建日期：2026-05-30
项目规模：58 文件，1528 符号，2828 关系，87 执行流
核心技术：Spring AI + DeepSeek V4 + BGE-M3 + Milvus + Agent 协同

---

📋 学习目标

通过本学习路径，你将掌握：

1. ✅ AI Ops 自动化分析的完整执行流程（3-Agent 协同架构）
2. ✅ Chat 对话系统的 RAG 知识库检索机制
3. ✅ 模型抽象与路由的解耦设计（ChatModel/EmbeddingModel）
4. ✅ Tools 工具集的设计模式（Prometheus/CLS/RAG）
5. ✅ 向量数据库的文档分块、向量化、检索全流程

预计总耗时：2-3 小时（可分多次完成）

---

🎯 学习路径（推荐顺序）

📍 阶段 1：核心执行流理解（30-40 分钟）⭐️ 从这里开始

目标：理解系统的 2 条主线执行流程

---

1.1 AI Ops 自动化分析流程 ⭐️⭐️⭐️

为什么从这里开始？

• 这是项目最核心、最有特色的功能
• 涉及 Agent 协同、工具调用、流式响应等关键技术
• 理解了它，其他模块会一通百通

执行流程图：

用户点击 "AI Ops" 按钮
    ↓
HTTP POST /api/ai_ops
    ↓
ChatController.aiOps()
    ↓
AiOpsService.executeAiOpsAnalysis()
    ↓
┌────────────────────────────────────────┐
│ Phase 1: Planner Agent 制定分析计划    │
│  - 输入：固定的规划 Prompt             │
│  - 输出：分析计划（要查哪些告警、日志）│
└────────────────────────────────────────┘
    ↓
┌────────────────────────────────────────┐
│ Phase 2: Executor Agent 执行工具调用   │
│  ├─ QueryMetricsTools.queryActiveAlerts()│
│  │   → Prometheus 告警（Mock 模式）    │
│  ├─ QueryLogsTools.queryLogs()         │
│  │   → 腾讯云 CLS 日志（Mock 模式）    │
│  └─ InternalDocsTools.queryInternalDocs()│
│      → RAG 知识库检索                   │
└────────────────────────────────────────┘
    ↓
┌────────────────────────────────────────┐
│ Phase 3: Supervisor Agent 生成报告     │
│  - 输入：Planner 计划 + Executor 数据  │
│  - 输出：结构化告警分析报告            │
│  - 格式：Markdown（表格、列表、代码块）│
└────────────────────────────────────────┘
    ↓
SSE 流式返回前端
    ↓
前端渲染 Markdown

学习步骤：

Step 1.1.1：阅读 Controller 入口

Read src/main/java/org/example/controller/ChatController.java

关注点：

• aiOps() 方法（第 106-117 行左右）
• 如何设置 SSE 响应头（text/event-stream）
• 如何调用 AiOpsService.executeAiOpsAnalysis()

预期收获：理解 HTTP 层如何触发 AI Ops 分析

---

Step 1.1.2：阅读核心 Service

Read src/main/java/org/example/service/AiOpsService.java

关注点：

• executeAiOpsAnalysis() 方法（核心入口）
• buildPlannerAgent() 方法（如何构建规划 Agent）
• buildExecutorAgent() 方法（如何构建执行 Agent）
• buildSupervisorSystemPrompt() 方法（如何构建最终报告生成 Prompt）
• 3 个 Agent 如何协同工作（chain 调用）

预期收获：理解 3-Agent 协同架构

---

Step 1.1.3：查看依赖图

在 Claude Code 中执行：
mcp__gitnexus__context({name: "AiOpsService", repo: "SuperBizAgent-java"})

关注点：

• outgoing.has_property：依赖了哪些 Tools
• incoming.imports：被谁调用（应该是 ChatController）

预期收获：理解 AiOpsService 的依赖关系

---

Step 1.1.4：如果要修改，先做影响分析

mcp__gitnexus__impact({
  target: "executeAiOpsAnalysis", 
  direction: "upstream", 
  repo: "SuperBizAgent-java"
})

预期收获：理解修改这个方法会影响哪些代码

---

🎓 阶段 1.1 总结：

完成后，你应该能回答：

1. AI Ops 分析为什么用 3 个 Agent 而不是 1 个？
2. Planner 和 Executor 的输入输出分别是什么？
3. 为什么要用 SSE 而不是普通的 HTTP 响应？
4. Mock 模式下，告警和日志数据从哪里来？

---

1.2 Chat 对话流程

执行流程图：

用户输入消息 → 点击发送
    ↓
HTTP POST /api/chat
    ↓
ChatController.chat()
    ↓
ChatService.executeChat(userMessage, sessionId)
    ↓
createReactAgent(ChatModel, tools)
    ├─ InternalDocsTools (RAG 检索)
    ├─ DateTimeTools (时间查询)
    ├─ QueryMetricsTools (告警查询)
    └─ QueryLogsTools (日志查询)
    ↓
ReactAgent.stream(userMessage)
    ↓
根据用户问题，自动选择调用哪些 Tools
    ↓
SSE 流式返回
    ↓
前端渲染

学习步骤：

Step 1.2.1：阅读 ChatService

Read src/main/java/org/example/service/ChatService.java

关注点：

• executeChat() 方法
• createReactAgent() 方法（如何注册 Tools）
• buildSystemPrompt() 方法（系统提示词）
• getToolCallbacks() 方法（MCP 工具回调，可选）

预期收获：理解 ReactAgent 如何工作

---

Step 1.2.2：查看 InternalDocsTools（RAG 核心）

Read src/main/java/org/example/tools/InternalDocsTools.java

mcp__gitnexus__context({name: "InternalDocsTools", repo: "SuperBizAgent-java"})

关注点：

• queryInternalDocs() 方法
• 如何调用 RagService.queryRelevantDocs()
• 返回值结构

预期收获：理解 RAG 如何嵌入到 Agent 工具链

---

🎓 阶段 1.2 总结：

完成后，你应该能回答：

1. ReactAgent 如何决定调用哪个 Tool？
2. Chat 和 AI Ops 使用的 Agent 有什么区别？
3. 为什么 Chat 需要 sessionId 而 AI Ops 不需要？

---

📍 阶段 2：RAG 知识库链路（20 分钟）

目标：理解文档上传 → 向量化 → 检索的完整链路

---

2.1 文档上传与向量化

执行流程图：

用户上传文档 (txt/md)
    ↓
HTTP POST /api/upload
    ↓
FileUploadController.upload()
    ↓
RagService.processAndStoreDocument()
    ├─ 文档分块
    │   └─ ChunkingStrategy.splitByParagraphs()
    │       ├─ 段落识别（\n\n）
    │       ├─ Token 估算（estimateTokens）
    │       └─ 重叠策略（overlap=100）
    ├─ 向量化
    │   └─ VectorEmbeddingService.generateEmbeddings()
    │       └─ SiliconFlow BGE-M3 (1024 维)
    └─ 存储到 Milvus
        └─ MilvusClientFactory.insert()

学习步骤：

Step 2.1.1：阅读 RagService

Read src/main/java/org/example/service/RagService.java

关注点：

• processAndStoreDocument() 方法（完整流程）
• queryRelevantDocs() 方法（检索流程）
• 分块策略（ChunkingStrategy）

---

Step 2.1.2：阅读 VectorEmbeddingService

Read src/main/java/org/example/service/VectorEmbeddingService.java

关注点：

• generateEmbedding() 单条向量化
• generateEmbeddings() 批量向量化
• 如何调用 EmbeddingModel.embed()

---

Step 2.1.3：阅读 MilvusClientFactory

Read src/main/java/org/example/client/MilvusClientFactory.java

关注点：

• createClient() 方法（Zilliz Cloud 连接）
• Collection 创建逻辑
• 索引类型（IVF_FLAT）
• loadCollection() 调用（重要！搜索前必须 load）

---

🎓 阶段 2 总结：

完成后，你应该能回答：

1. 文档分块为什么要有 overlap？overlap=100 的意义是什么？
2. 为什么用 BGE-M3 而不是其他 Embedding 模型？
3. Milvus 的 IVF_FLAT 索引适合什么场景？什么时候需要换 HNSW？
4. 为什么 Collection 创建后要手动 loadCollection()？

---

📍 阶段 3：模型抽象与路由（15 分钟）

目标：理解 ChatModel/EmbeddingModel 如何解耦和路由

背景：这是 2026-05-29 重构的核心成果（见 devflow/projects/2026-05-29-chatmodel-abstraction/）

---

3.1 模型路由机制

架构图：

application.yml
    ├─ model-routing.chat: deepseek
    └─ model-routing.embedding: siliconflow
         ↓
ModelRoutingConfig.java
    ├─ routeChatModel()
    │   └─ List<ChatModel> → 匹配 "deepseek" → @Primary
    └─ routeEmbeddingModel()
        └─ Map<String, EmbeddingModel> → 匹配 "siliconflow" → @Primary
             ↓
Spring 容器注入
    ├─ ChatService @Autowired ChatModel → DeepSeek V4 Flash
    └─ VectorEmbeddingService @Autowired EmbeddingModel → SiliconFlow BGE-M3

学习步骤：

Step 3.1.1：阅读 ModelRoutingConfig

Read src/main/java/org/example/config/ModelRoutingConfig.java

关注点：

• routeChatModel() 方法的匹配逻辑
• routeEmbeddingModel() 方法的匹配逻辑
• 为什么用 List<ChatModel> 而不是 @Qualifier？

---

Step 3.1.2：阅读 SiliconFlowEmbeddingConfig

Read src/main/java/org/example/config/SiliconFlowEmbeddingConfig.java

关注点：

• 如何创建独立的 OpenAiApi
• 为什么 base-url 不能带 /v1 后缀？（参考 decisions.md L3）

---

Step 3.1.3：阅读 application.yml

Read src/main/resources/application.yml

关注点（第 23-62 行）：

• model-routing 配置
• spring.ai.deepseek 配置
• siliconflow 配置
• 为什么 spring.ai.openai.api-key: unused？

---

🎓 阶段 3 总结：

完成后，你应该能回答：

1. 如果要换成 Ollama 本地模型，需要改哪些配置？
2. 为什么 @Qualifier 方案会失败？（参考 decisions.md L2）
3. Spring AI 1.1.0 为什么不能用 OpenAI 兼容模式调 DeepSeek？（参考 decisions.md L1）

---

📍 阶段 4：Tools 工具集（20 分钟）

目标：理解 Agent 可调用的所有工具

---

4.1 工具清单

工具类	功能	核心方法	文件路径
InternalDocsTools	RAG 知识库检索	queryInternalDocs()	tools/InternalDocsTools.java
DateTimeTools	获取当前时间	getCurrentDateTime()	tools/DateTimeTools.java
QueryMetricsTools	Prometheus 告警查询	queryActiveAlerts()	tools/QueryMetricsTools.java
QueryLogsTools	腾讯云 CLS 日志查询	queryLogs()	tools/QueryLogsTools.java

---

学习步骤：

Step 4.1.1：查看所有 Tool 类

Glob pattern="**/tools/*.java"

---

Step 4.1.2：阅读 QueryMetricsTools（Mock 模式）

Read src/main/java/org/example/tools/QueryMetricsTools.java

关注点：

• @Tool 注解（Spring AI 的工具注册机制）
• mockEnabled 配置的作用
• Mock 数据结构（模拟 Prometheus 告警）

---

Step 4.1.3：阅读 QueryLogsTools（Mock 模式）

Read src/main/java/org/example/tools/QueryLogsTools.java

关注点：

• 如何根据告警名称返回关联的日志
• Mock 数据如何与 AI Ops 分析报告对应

---

🎓 阶段 4 总结：

完成后，你应该能回答：

1. 如果要新增一个工具（如 K8s 事件查询），需要做什么？
2. Mock 模式的数据是否可以通过配置文件管理？
3. 为什么 Tool 方法要返回 String 而不是复杂对象？

---

📍 阶段 5：配置与基础设施（10 分钟）

目标：理解配置项和基础设施

---

Step 5.1：阅读 application.yml

Read src/main/resources/application.yml

关注清单：

配置项	作用	默认值	修改场景
milvus.host	Zilliz Cloud 地址	in03-xxx.cloud.zilliz.com	换集群
milvus.vector-dim	向量维度	1024 (BGE-M3)	换模型
model-routing.chat	Chat 模型路由	deepseek	换模型
model-routing.embedding	Embedding 路由	siliconflow	换模型
document.chunk.max-size	分块最大 Token	800	优化检索
rag.top-k	检索返回数	3	优化检索
prometheus.mock-enabled	Prometheus Mock	true	接入真实 Prometheus
cls.mock-enabled	CLS Mock	true	接入真实腾讯云 CLS

---

Step 5.2：阅读 MilvusProperties

Read src/main/java/org/example/config/MilvusProperties.java

关注点：

• @ConfigurationProperties(prefix = "milvus")
• 为什么 vectorDim 要从配置读取？（参考 brief.md）

---

🎓 阶段 5 总结：

完成后，你应该能回答：

1. 如果 Embedding 模型从 BGE-M3 (1024维) 换成 text-embedding-ada-002 (1536维)，需要改哪些配置？
2. Mock 模式如何切换到真实环境？

---

📊 学习检查点

完成每个阶段后，勾选对应的检查点：

✅ 阶段 1 检查点

• 我能画出 AI Ops 的完整执行流程图
• 我理解了 Planner、Executor、Supervisor 的职责
• 我知道如何修改 Planner 的分析策略
• 我能解释 SSE 流式响应的优势

✅ 阶段 2 检查点

• 我能画出文档上传到向量存储的完整流程
• 我理解了文档分块策略的 overlap 参数
• 我知道如何调整 top-k 影响检索结果
• 我能解释为什么 Collection 需要 load

✅ 阶段 3 检查点

• 我理解了 @Primary 路由的原理
• 我能通过修改 yml 切换模型
• 我知道为什么不用 @Qualifier
• 我能添加新的模型提供商（如 Ollama）

✅ 阶段 4 检查点

• 我理解了 @Tool 注解的作用
• 我能新增一个自定义工具
• 我知道 Mock 模式的数据结构
• 我能对接真实的 Prometheus/CLS

✅ 阶段 5 检查点

• 我理解了所有关键配置项
• 我能修改配置优化 RAG 检索
• 我知道如何切换到生产环境配置

---

🎯 进阶学习路径

完成基础学习后，可以尝试：

进阶 1：深入 Agent 协同模式

# 阅读 Spring AI Agent Framework 源码
Read pom.xml  # 查看 spring-ai-alibaba-starter-agent 版本

研究方向：

• ReactAgent 的 Tool 选择算法
• Agent 链式调用的状态传递
• Agent 的异常处理机制

---

进阶 2：性能优化

优化点：

1. Milvus 索引优化：IVF_FLAT → HNSW
2. 分块策略优化：调整 max-size 和 overlap
3. 批量向量化：优化 generateEmbeddings() 批量大小
4. 缓存策略：热点查询缓存

推荐操作：

# 查看向量化服务
Read src/main/java/org/example/service/VectorEmbeddingService.java

# 查看 Milvus 客户端
Read src/main/java/org/example/client/MilvusClientFactory.java

---

进阶 3：功能扩展

扩展方向：

1. 新增工具：

   • K8s 事件查询工具
   • Grafana Dashboard 查询工具
   • Jira Issue 创建工具

2. 新增 Agent：

   • 根因分析专家 Agent
   • 修复建议生成 Agent
   • 历史告警对比 Agent

3. 新增模型支持：

   • Ollama 本地模型
   • Azure OpenAI
   • Anthropic Claude

---

📚 参考文档

项目文档

文档	用途
docs/功能分析报告.md	项目功能概览、技术栈、分析案例
docs/日志配置与分析指南.md	日志配置、分析场景、故障排查
devflow/projects/2026-05-29-chatmodel-abstraction/	ChatModel 重构的完整记录
CLAUDE.md	GitNexus 使用规范（影响分析、变更检测）

技术文档

技术	官方文档
Spring AI	https://docs.spring.io/spring-ai/
Milvus	https://milvus.io/docs
DeepSeek API	https://platform.deepseek.com/docs
SiliconFlow	https://siliconflow.cn/docs

---

🚀 开始学习

推荐第一步：

# 1. 阅读 AI Ops 核心 Service
Read src/main/java/org/example/service/AiOpsService.java

# 2. 查看依赖图
mcp__gitnexus__context({name: "AiOpsService", repo: "SuperBizAgent-java"})

# 3. 如果打算修改，先做影响分析
mcp__gitnexus__impact({target: "AiOpsService", direction: "upstream", repo: "SuperBizAgent-java"})

学习节奏建议：

• 快速模式（1 小时）：只完成阶段 1 + 阶段 3
• 标准模式（2 小时）：完成阶段 1-4
• 深度模式（3 小时）：完成全部 5 个阶段 + 进阶路径

---

🎓 学习产出建议

学习过程中，建议你输出以下文档（保存到 docs/learning/）：

文档	内容
AI-Ops-执行流.md	手绘执行流程图 + 关键代码片段
RAG-知识库设计.md	文档分块策略、向量化、检索全流程
模型路由机制.md	ChatModel/EmbeddingModel 路由源码分析
Tools-工具集.md	所有工具的作用、参数、返回值、扩展方案
学习笔记.md	每个阶段的收获、疑问、TODO

---

💡 提示：这个学习路径是基于项目当前状态（2026-05-30）设计的。如果项目有重大更新，请重新执行 npx gitnexus analyze 更新索引。

---

立即开始：

# Step 1: 从 AI Ops 开始
Read src/main/java/org/example/service/AiOpsService.java

祝学习愉快！🎉