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 入口**

```bash
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**

```bash
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：查看依赖图**

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

**关注点**：
- `outgoing.has_property`：依赖了哪些 Tools
- `incoming.imports`：被谁调用（应该是 ChatController）

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

---

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

```bash
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**

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

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

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

---

**Step 1.2.2：查看 InternalDocsTools（RAG 核心）**

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

```bash
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**

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

**关注点**：
- `processAndStoreDocument()` 方法（完整流程）
- `queryRelevantDocs()` 方法（检索流程）
- 分块策略（`ChunkingStrategy`）

---

**Step 2.1.2：阅读 VectorEmbeddingService**

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

**关注点**：
- `generateEmbedding()` 单条向量化
- `generateEmbeddings()` 批量向量化
- 如何调用 `EmbeddingModel.embed()`

---

**Step 2.1.3：阅读 MilvusClientFactory**

```bash
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**

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

**关注点**：
- `routeChatModel()` 方法的匹配逻辑
- `routeEmbeddingModel()` 方法的匹配逻辑
- 为什么用 `List<ChatModel>` 而不是 `@Qualifier`？

---

**Step 3.1.2：阅读 SiliconFlowEmbeddingConfig**

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

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

---

**Step 3.1.3：阅读 application.yml**

```bash
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 类**

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

---

**Step 4.1.2：阅读 QueryMetricsTools（Mock 模式）**

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

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

---

**Step 4.1.3：阅读 QueryLogsTools（Mock 模式）**

```bash
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**

```bash
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**

```bash
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 协同模式

```bash
# 阅读 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. **缓存策略**：热点查询缓存

**推荐操作**：
```bash
# 查看向量化服务
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 |

---

## 🚀 开始学习

**推荐第一步**：

```bash
# 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` 更新索引。

---

**立即开始**：

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

祝学习愉快！🎉