332 lines
9.4 KiB
Markdown
332 lines
9.4 KiB
Markdown
# 学习报告索引
|
||
|
||
> 创建日期：2026-05-30
|
||
> 主题：AI Ops 3-Agent 协同架构深度分析
|
||
> 学习路径：从核心设计 → outputKey 机制 → 疑难解答
|
||
|
||
---
|
||
|
||
## 📚 学习报告清单
|
||
|
||
### 01. [AI Ops 核心设计 - Essence 报告](./01-AI-Ops-核心设计-Essence报告.md)
|
||
|
||
**内容**：
|
||
- 3-Agent 协同分析模式详解
|
||
- 完整调用链（HTTP → Service → Agents → Tools → SSE）
|
||
- 设计模式对比与权衡分析
|
||
- 迁移示例与关键陷阱
|
||
|
||
**适合**：
|
||
- 第一次学习 AI Ops 架构
|
||
- 需要理解"为什么用 3 个 Agent"
|
||
- 准备在自己的项目中应用这个模式
|
||
|
||
**关键收获**：
|
||
- ✅ 理解 Planner、Executor、Supervisor 的职责
|
||
- ✅ 掌握 Agent 协同的执行流程
|
||
- ✅ 学会避免常见的陷阱
|
||
|
||
---
|
||
|
||
### 02. [outputKey 深度解析](./02-outputKey-深度解析.md)
|
||
|
||
**内容**：
|
||
- outputKey 的核心机制（共享内存模型）
|
||
- 完整时间线示例（8 个步骤）
|
||
- Prompt 占位符替换原理
|
||
- 调试技巧与实践建议
|
||
|
||
**适合**：
|
||
- 已理解 3-Agent 架构，想深入了解状态传递机制
|
||
- 遇到 Agent 间通信问题
|
||
- 想知道如何在 Prompt 中引用其他 Agent 的输出
|
||
|
||
**关键收获**：
|
||
- ✅ 理解 `OverAllState` 的工作原理
|
||
- ✅ 掌握 outputKey 的命名规范
|
||
- ✅ 学会在 Prompt 中正确引用 state
|
||
|
||
---
|
||
|
||
### 03. [3个核心疑问解答](./03-核心疑问解答.md)
|
||
|
||
**内容**：
|
||
- 疑问 1：Prompt 中的 `{}` 占位符如何替换？
|
||
- 疑问 2：如果两个 Agent 用同一个 outputKey 会怎样？
|
||
- 疑问 3：如何在 Prompt 中读取多个 key？
|
||
|
||
**适合**：
|
||
- 对特定机制有疑问
|
||
- 遇到实际问题需要快速查阅
|
||
- 想了解边界情况的处理
|
||
|
||
**关键收获**：
|
||
- ✅ 掌握 Prompt 模板引擎的替换规则
|
||
- ✅ 避免 outputKey 冲突导致的数据丢失
|
||
- ✅ 学会在 Prompt 中读取多个 state 值
|
||
|
||
---
|
||
|
||
### 04. [RAG 分块策略 - Essence 报告](./04-RAG-分块策略-Essence报告.md)
|
||
|
||
**内容**：
|
||
- Token 感知的智能分块机制
|
||
- 结构保护（Markdown 标题、列表、代码块）
|
||
- 软硬双重限制防止失控
|
||
- 重叠机制保证上下文连续性
|
||
- 与 LangChain 等方案的对比
|
||
|
||
**适合**：
|
||
- 需要理解 RAG 链路中的文档处理流程
|
||
- 想了解如何切分文档而不破坏语义
|
||
- 准备优化自己项目的文档分块策略
|
||
|
||
**关键收获**：
|
||
- ✅ 理解为什么用 Token 估算而不是字符计数
|
||
- ✅ 掌握不可中断上下文的检测逻辑
|
||
- ✅ 学会软硬双重限制的设计哲学
|
||
- ✅ 理解重叠机制如何提升检索准确率
|
||
|
||
---
|
||
|
||
### 05. [文件上传自动索引 - Essence 报告](./05-文件上传自动索引-Essence报告.md)
|
||
|
||
**内容**：
|
||
- 上传即索引的自动化流程
|
||
- 基于文件名的覆盖更新策略
|
||
- 原子化的删除-索引流程
|
||
- 同步 vs. 异步的权衡分析
|
||
- 一致性保证的设计思路
|
||
|
||
**适合**：
|
||
- 需要理解 RAG 系统的文件管理机制
|
||
- 想了解如何保证文件系统与向量库的一致性
|
||
- 准备构建自己的文档上传功能
|
||
|
||
**关键收获**：
|
||
- ✅ 理解为什么上传成功后立即触发索引
|
||
- ✅ 掌握基于文件名的覆盖更新策略
|
||
- ✅ 学会同步索引 vs. 异步队列的权衡
|
||
- ✅ 理解索引失败不阻塞上传的设计哲学
|
||
|
||
---
|
||
|
||
### 06. [RAG 查询流程 - Essence 报告](./06-RAG查询流程-Essence报告.md) ⭐ 新增
|
||
|
||
**内容**：
|
||
- Tool-Driven RAG 架构
|
||
- ReactAgent 智能路由机制
|
||
- 向量检索 + LLM 综合答案
|
||
- Tool-as-Service 松耦合设计
|
||
- JSON 返回格式与 Agent 契约
|
||
|
||
**适合**：
|
||
- 需要理解查询如何触发 RAG
|
||
- 想了解 ReactAgent 的工作原理
|
||
- 准备构建多功能 AI 助手（不只是文档问答）
|
||
|
||
**关键收获**：
|
||
- ✅ 理解为什么用 ReactAgent 而不是直接调用 RAG
|
||
- ✅ 掌握 Tool-as-Service 架构的优势
|
||
- ✅ 学会系统提示词如何引导 Agent 选择工具
|
||
- ✅ 理解 Top-K = 3 的设计依据
|
||
|
||
---
|
||
|
||
## 🎯 推荐学习顺序
|
||
|
||
### 快速模式（30 分钟）
|
||
|
||
```
|
||
01-AI-Ops-核心设计-Essence报告.md
|
||
↓ (只看"核心洞察"、"完整调用链"、"迁移示例")
|
||
完成 ✅
|
||
```
|
||
|
||
### 标准模式（1 小时）
|
||
|
||
```
|
||
01-AI-Ops-核心设计-Essence报告.md
|
||
↓ (完整阅读)
|
||
02-outputKey-深度解析.md
|
||
↓ (重点看"完整时间线示例")
|
||
03-核心疑问解答.md
|
||
↓ (按需查阅)
|
||
完成 ✅
|
||
```
|
||
|
||
### 深度模式（2 小时）
|
||
|
||
```
|
||
01-AI-Ops-核心设计-Essence报告.md
|
||
↓ (完整阅读 + 对照源码验证)
|
||
02-outputKey-深度解析.md
|
||
↓ (完整阅读 + 自己画时间线图)
|
||
03-核心疑问解答.md
|
||
↓ (完整阅读 + 尝试回答扩展问题)
|
||
实践：修改 AiOpsService 添加新的 Agent
|
||
↓
|
||
完成 ✅
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 学习检查点
|
||
|
||
### 完成 01 后，你应该能回答：
|
||
|
||
- [ ] 为什么用 3 个 Agent 而不是 1 个？
|
||
- [ ] Planner 的 Replanner 角色是什么意思？
|
||
- [ ] Executor 为什么只执行"第一步"？
|
||
- [ ] Supervisor 如何知道该调用哪个 Agent？
|
||
- [ ] 如果 Executor 执行失败会发生什么？
|
||
|
||
### 完成 02 后，你应该能回答：
|
||
|
||
- [ ] outputKey 的本质是什么？
|
||
- [ ] Prompt 中的 `{executor_feedback}` 如何被替换？
|
||
- [ ] 如何从 state 中提取最终报告？
|
||
- [ ] 如何调试 Agent 间的状态传递？
|
||
|
||
### 完成 03 后，你应该能回答：
|
||
|
||
- [ ] 如果两个 Agent 使用同一个 outputKey 会发生什么？
|
||
- [ ] 如何在 Prompt 中同时读取 3 个 key？
|
||
- [ ] 模板引擎是如何工作的？
|
||
|
||
### 完成 04 后，你应该能回答：
|
||
|
||
- [ ] 为什么用 Token 估算而不是字符计数？
|
||
- [ ] 什么是"不可中断的上下文"？举例说明。
|
||
- [ ] 软限制和硬限制的区别是什么？
|
||
- [ ] 重叠机制如何提升检索准确率？
|
||
- [ ] 这个设计与 LangChain 的切分器有什么不同？
|
||
- [ ] 在什么情况下会在列表中间强制切断？
|
||
|
||
### 完成 05 后，你应该能回答：
|
||
|
||
- [ ] 为什么上传成功后要立即触发索引？
|
||
- [ ] 为什么使用原始文件名而不是 UUID？
|
||
- [ ] 索引失败为什么不影响上传？这个设计的利弊是什么？
|
||
- [ ] 如何保证文件更新时，向量库中的旧数据被删除？
|
||
- [ ] 这个设计在什么场景下会出现问题？
|
||
- [ ] 如何改造为异步索引？
|
||
|
||
### 完成 06 后，你应该能回答：
|
||
|
||
- [ ] 为什么用 ReactAgent 而不是直接调用 RAG？
|
||
- [ ] InternalDocsTools 的 `@Tool` 注解是如何被 ReactAgent 发现的？
|
||
- [ ] 工具返回为什么必须是 JSON 格式？
|
||
- [ ] Top-K = 3 的设计依据是什么？
|
||
- [ ] L2 距离和余弦相似度的区别？何时该换？
|
||
- [ ] 如果要添加一个新工具（如查 GitHub Issues），需要改哪些文件？
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
### 项目文档
|
||
|
||
- [项目学习路径](../项目学习路径.md) - 完整的项目学习计划
|
||
- [功能分析报告](../功能分析报告.md) - 项目整体功能分析
|
||
- [日志配置与分析指南](../日志配置与分析指南.md) - 日志配置与调试
|
||
|
||
### 源码文件
|
||
|
||
| 文件 | 关键行 | 说明 |
|
||
|------|--------|------|
|
||
| `AiOpsService.java` | 51-70 | 3-Agent 构建与编排 |
|
||
| `AiOpsService.java` | 100-124 | Planner & Executor 构建 |
|
||
| `AiOpsService.java` | 144-257 | Agent Prompts |
|
||
| `ChatController.java` | 280-314 | HTTP 入口 + SSE 返回 |
|
||
| `DocumentChunkService.java` | 104-202 | RAG 分块核心逻辑 ⭐ |
|
||
| `DocumentChunkService.java` | 279-297 | Token 估算算法 |
|
||
| `DocumentChunkService.java` | 307-336 | 不可中断上下文检测 |
|
||
| `VectorIndexService.java` | 124-168 | 文档索引流程 |
|
||
| `RagService.java` | 55-83 | RAG 查询编排 |
|
||
| `FileUploadController.java` | 35-103 | 文件上传接口 ⭐ |
|
||
| `FileUploadController.java` | 72-80 | 自动索引触发（核心设计） |
|
||
| `VectorIndexService.java` | 173-215 | 删除旧数据（覆盖更新） |
|
||
| `ChatController.java` | 140-274 | ReactAgent 对话接口 ⭐ |
|
||
| `ChatService.java` | 59-96 | 系统提示词构建 |
|
||
| `InternalDocsTools.java` | 49-78 | RAG 工具封装 |
|
||
| `VectorSearchService.java` | 42-94 | 向量检索 |
|
||
|
||
---
|
||
|
||
## 🚀 下一步
|
||
|
||
### 实践练习
|
||
|
||
1. **修改 Planner Prompt**
|
||
- 调整 `buildPlannerPrompt()` 中的指令
|
||
- 观察 Agent 行为变化
|
||
- 记录你的发现
|
||
|
||
2. **添加新的 Agent**
|
||
- 在 Planner 和 Executor 之间添加一个 Validator Agent
|
||
- 验证 Planner 的计划是否合理
|
||
- 实现 3-Agent → 4-Agent 升级
|
||
|
||
3. **调试工具失败场景**
|
||
- 故意让某个工具返回失败
|
||
- 观察 Executor 如何反馈给 Planner
|
||
- 验证 Planner 的重新规划逻辑
|
||
|
||
---
|
||
|
||
## 📝 学习笔记模板
|
||
|
||
你可以在这个文件夹创建自己的学习笔记：
|
||
|
||
```markdown
|
||
# 我的学习笔记 - [日期]
|
||
|
||
## 今日学习
|
||
|
||
- 阅读文档：[文档名]
|
||
- 学习时长：[X小时]
|
||
- 完成练习：[练习名]
|
||
|
||
## 关键收获
|
||
|
||
1.
|
||
2.
|
||
3.
|
||
|
||
## 疑问
|
||
|
||
1.
|
||
2.
|
||
|
||
## 下一步计划
|
||
|
||
- [ ]
|
||
- [ ]
|
||
```
|
||
|
||
---
|
||
|
||
## 🎓 扩展阅读
|
||
|
||
### Spring AI 官方文档
|
||
|
||
- [Agent Framework](https://docs.spring.io/spring-ai/) - Spring AI Agent 官方文档
|
||
- [Tool Use](https://docs.spring.io/spring-ai/reference/api/tool.html) - 工具使用指南
|
||
|
||
### 相关设计模式
|
||
|
||
- **Chain of Responsibility**（责任链模式）- Supervisor 调度模式的基础
|
||
- **Strategy Pattern**（策略模式）- Planner 的多策略规划
|
||
- **Observer Pattern**（观察者模式）- Agent 间的状态通知
|
||
|
||
---
|
||
|
||
> 💡 **提示**：这个学习报告文件夹会持续更新。当你遇到新的问题或有新的发现时，可以创建新的 Markdown 文件添加到这里。
|
||
|
||
---
|
||
|
||
**创建日期**：2026-05-30
|
||
**最后更新**：2026-05-31
|
||
**版本**：v1.3 (新增 RAG 查询流程报告，完成 RAG 全链路分析)
|