# Handoff Document - SuperBizAgent-java 项目分析与学习

> **Session Date**: 2026-05-30  
> **Project**: SuperBizAgent-java (智能 OnCall 助手)  
> **Status**: 项目分析完成，学习路径已建立  
> **Next Agent**: 继续深度学习或开始功能开发

---

## 📋 Session Summary

本次会话完成了 **SuperBizAgent-java 项目的全面分析**，并建立了完整的学习体系。用户从零开始了解项目，现在已经掌握了核心架构和关键设计模式。

---

## ✅ Completed Work

### 1. 项目功能分析（Playwright + 代码分析）

**成果**：
- 使用 Playwright MCP 工具分析了 `localhost:9900` 站点
- 识别出 2 大核心功能：
  - **智能对话系统**：RAG 知识库检索、Prometheus 告警查询、腾讯云 CLS 日志查询
  - **AI Ops 自动化分析**：3-Agent 协同的告警根因分析（⭐️ 核心特色）

**产物**：
- `docs/功能分析报告.md` - 完整的功能分析、技术栈、使用场景

**关键发现**：
- AI Ops 使用了 **3-Agent 协同模式**（Planner + Executor + Supervisor）
- 后端：Spring AI + DeepSeek V4 Flash + SiliconFlow BGE-M3 + Zilliz Cloud Milvus
- 前端：SSE 流式响应 + Markdown 渲染

---

### 2. 日志配置（解决 Claude 无法分析日志的问题）

**问题**：项目启动后日志只输出到控制台，Claude 无法读取分析

**解决方案**：
- 创建 `src/main/resources/logback-spring.xml`（完整配置）
- 修改 `src/main/resources/application.yml`（添加 logging 部分）
- 配置特性：
  - 控制台 + 文件双输出
  - 按模块分文件（`application.log`, `aiops.log`, `chat.log`, `application-error.log`）
  - 异步写入（性能优化）
  - 自动滚动（10MB/文件，保留 30 天）

**产物**：
- `docs/日志配置与分析指南.md` - 详细的配置说明、分析场景、故障排查
- `docs/日志配置完成总结.md` - 快速参考总结
- `scripts/verify-logging.sh` 和 `scripts/verify-logging.bat` - 验证脚本

**验证命令**：
```bash
bash scripts/verify-logging.sh
```

---

### 3. 项目学习路径设计

**成果**：
- 设计了 **5 阶段学习路径**（从核心执行流到配置基础设施）
- 每个阶段包含：执行流程图、具体学习步骤、阶段总结、检查点清单
- 提供了 3 种学习节奏：快速（1小时）、标准（2小时）、深度（3小时）

**产物**：
- `docs/项目学习路径.md` - 完整的分阶段学习计划

**学习阶段**：
1. **阶段 1**：核心执行流理解（AI Ops + Chat 对话流程）⭐️ 从这里开始
2. **阶段 2**：RAG 知识库链路（文档上传 → 向量化 → 检索）
3. **阶段 3**：模型抽象与路由（ChatModel/EmbeddingModel 解耦）
4. **阶段 4**：Tools 工具集（Prometheus、CLS、RAG、DateTime）
5. **阶段 5**：配置与基础设施（application.yml、Milvus）

---

### 4. AI Ops 核心设计深度分析（/essence 技能）

**分析目标**：`/api/ai_ops` 接口的 3-Agent 协同架构

**成果**：
- 识别出 **3-Agent Collaborative Analysis Pattern**（核心设计模式）
- 完整的端到端调用链追踪（HTTP → Controller → Service → 3 Agents → Tools → SSE）
- 与其他方案的对比分析（单 Agent、2-Agent、静态工作流、ReAct Loop）
- 可迁移的代码示例（≤20 行）
- 5 个关键陷阱及避免方法

**产物**：
- `docs/learning/01-AI-Ops-核心设计-Essence报告.md`

**核心洞察**：
- **Planner**：制定计划 & 重新规划（承担 Replanner 角色）
- **Executor**：执行工具调用（只执行第一步）
- **Supervisor**：循环调度（直到 decision=FINISH）

**关键机制**：
- `outputKey` - Agent 状态共享的桥梁
- Prompt 中的 `{}` 占位符自动替换为 `state.value(key)`
- 循环编排：Planner → Executor → Planner（重新规划）→ ... → FINISH

---

### 5. outputKey 机制深度解析

**背景**：用户询问 outputKey 的作用

**成果**：
- 详细解释了 outputKey 的共享内存模型
- 提供了 8 步完整时间线示例
- 回答了 3 个核心疑问：
  1. Prompt 中的 `{}` 占位符如何替换？
  2. 如果两个 Agent 用同一个 outputKey 会怎样？
  3. 如何在 Prompt 中读取多个 key？

**产物**：
- `docs/learning/02-outputKey-深度解析.md`
- `docs/learning/03-核心疑问解答.md`
- `docs/learning/README.md` - 学习报告索引

**核心概念**：
```
OverAllState = Map<String, Object>
- Planner 写入: state["planner_plan"]
- Executor 写入: state["executor_feedback"]
- Planner 读取: {executor_feedback} → state.get("executor_feedback")
```

---

## 📁 Key Artifacts

### 已创建的文档

| 文档 | 路径 | 用途 |
|------|------|------|
| **功能分析报告** | `docs/功能分析报告.md` | 项目功能、技术栈、AI Ops 案例 |
| **日志配置指南** | `docs/日志配置与分析指南.md` | 日志配置、分析场景、故障排查 |
| **日志配置总结** | `docs/日志配置完成总结.md` | 快速参考、调试技巧 |
| **项目学习路径** | `docs/项目学习路径.md` | 5 阶段学习计划 |
| **Essence 报告** | `docs/learning/01-AI-Ops-核心设计-Essence报告.md` | 3-Agent 协同架构深度分析 |
| **outputKey 解析** | `docs/learning/02-outputKey-深度解析.md` | 状态共享机制详解 |
| **疑问解答** | `docs/learning/03-核心疑问解答.md` | 3 个核心疑问的深度回答 |
| **学习索引** | `docs/learning/README.md` | 学习路径索引、检查点清单 |

### 已修改的配置

| 文件 | 修改内容 |
|------|---------|
| `src/main/resources/logback-spring.xml` | 新增完整日志配置（分模块、异步、滚动） |
| `src/main/resources/application.yml` | 新增 logging 配置段 |

### 核心源码文件（分析重点）

| 文件 | 关键行 | 作用 |
|------|--------|------|
| `ChatController.java` | 280-314 | `/api/ai_ops` HTTP 入口 + SSE 流式返回 |
| `AiOpsService.java` | 51-70 | 3-Agent 构建与编排核心逻辑 |
| `AiOpsService.java` | 100-124 | Planner & Executor Agent 构建 |
| `AiOpsService.java` | 144-257 | Agent Prompts（Planner、Executor、Supervisor） |
| `AiOpsService.java` | 79-94 | 最终报告提取逻辑 |

---

## 🎯 Current State

### 用户理解程度

**已掌握**：
- ✅ 项目整体功能和技术架构
- ✅ AI Ops 3-Agent 协同模式的工作原理
- ✅ outputKey 状态共享机制
- ✅ 完整的调用链（HTTP → Agents → Tools → SSE）
- ✅ 日志配置和分析方法

**待深入**（基于学习路径）：
- ⏳ 阶段 2：RAG 知识库链路（文档分块、向量化、检索）
- ⏳ 阶段 3：模型路由机制（ModelRoutingConfig、SiliconFlowEmbeddingConfig）
- ⏳ 阶段 4：Tools 工具集（QueryMetricsTools、QueryLogsTools 的实现细节）
- ⏳ 阶段 5：配置与基础设施（Milvus 连接、向量维度配置）

### 项目状态

- **GitNexus 索引**：已更新（1528 符号，2828 关系，87 执行流）
- **日志配置**：已完成，项目启动后会自动输出到 `logs/` 目录
- **学习体系**：已建立，文档齐全

---

## 🚀 Suggested Next Steps

### 选项 1：继续学习项目（推荐）

**按照学习路径继续**：

1. **阶段 2：RAG 知识库链路**（20 分钟）
   ```bash
   # 第一个命令
   Read src/main/java/org/example/service/RagService.java
   ```
   
   - 理解文档分块策略（ChunkingStrategy）
   - 掌握向量化流程（VectorEmbeddingService）
   - 了解 Milvus 检索机制

2. **阶段 3：模型路由机制**（15 分钟）
   ```bash
   Read src/main/java/org/example/config/ModelRoutingConfig.java
   ```
   
   - 理解 yml 驱动的模型路由
   - 掌握 ChatModel/EmbeddingModel 解耦设计
   - 了解如何切换模型（只改配置不改代码）

3. **实践验证**：
   - 启动项目：`mvn spring-boot:run`
   - 查看日志：`tail -f logs/application.log`
   - 访问 `http://localhost:9900`
   - 点击 "AI Ops" 观察 3-Agent 协同过程

---

### 选项 2：功能开发（需求驱动）

如果用户有具体需求，可以开始功能开发：

**常见需求方向**：
- 新增工具（如 K8s 事件查询）
- 新增 Agent（如根因分析专家 Agent）
- 接入真实的 Prometheus/CLS（关闭 Mock 模式）
- 优化 RAG 检索（调整分块策略、Top-K）
- 性能优化（Milvus 索引升级 IVF_FLAT → HNSW）

**开发前必做**：
```bash
# 影响分析（MUST）
mcp__gitnexus__impact({
  target: "要修改的类或方法", 
  direction: "upstream", 
  repo: "SuperBizAgent-java"
})

# 变更检测（MUST，修改后）
mcp__gitnexus__detect_changes({repo: "SuperBizAgent-java"})
```

---

### 选项 3：问题排查（如果遇到问题）

**常见问题**：
1. **项目启动失败**
   - 检查日志：`tail -f logs/application-error.log`
   - 查看配置：`Read src/main/resources/application.yml`
   - 验证 API Key：`spring.ai.deepseek.api-key`、`siliconflow.api-key`

2. **AI Ops 分析失败**
   - 查看 AI Ops 日志：`tail -f logs/aiops.log`
   - 检查 Mock 配置：`prometheus.mock-enabled: true`
   - 验证工具调用：查看是否有 `QueryMetricsTools` 的 DEBUG 日志

3. **RAG 检索无结果**
   - 检查 Milvus 连接：`logs/application.log` 中搜索 "Milvus"
   - 验证 Collection：是否创建了 `biz` collection
   - 查看向量维度：`milvus.vector-dim: 1024`（必须与 BGE-M3 一致）

---

## 💡 Suggested Skills

### 继续学习项目

```bash
# 如果要探索 RAG 知识库
/explore src/main/java/org/example/service/RagService.java

# 如果要深入某个设计模式
/essence 分析模型路由配置的设计

# 如果要理解工具集
/explore src/main/java/org/example/agent/tool/
```

### 功能开发

```bash
# 进入计划模式（修改前必做）
/plan

# 诊断问题
/diagnose [问题描述]

# 代码审查
/code-review
```

### 测试验证

```bash
# 验证功能
/verify

# 运行项目
/run
```

---

## 🔑 Key Insights

### 1. 3-Agent 协同是核心竞争力

这不是简单的 Agent 框架应用，而是一个**生产级的 AIOps 解决方案**：
- Planner 承担 Replanner 角色（动态调整策略）
- Executor 只执行"第一步"（避免规划执行混杂）
- Supervisor 循环调度（保证输出稳定性）

**与竞品对比**：
- 单 Agent 系统：无法重新规划
- 静态工作流：无法适应告警场景的不确定性
- ReAct Loop：规划与执行混杂，输出格式不稳定

### 2. outputKey 是状态共享的关键

没有 outputKey，3 个 Agent 无法协同：
```
state["planner_plan"] → Executor 读取
state["executor_feedback"] → Planner 读取并重新规划
```

### 3. Mock 模式便于开发调试

当前配置：
- `prometheus.mock-enabled: true`
- `cls.mock-enabled: true`

切换到生产环境只需改配置，无需改代码。

### 4. 模型可切换（yml 驱动）

```yaml
model-routing:
  chat: deepseek        # 改为 ollama 即可切换到本地模型
  embedding: siliconflow # 改为 openai 即可切换到 OpenAI
```

---

## 📊 Progress Tracking

### 学习进度

| 阶段 | 状态 | 完成度 |
|------|------|--------|
| **阶段 1：核心执行流** | ✅ 完成 | 100% |
| 阶段 2：RAG 知识库 | ⏳ 待学习 | 0% |
| 阶段 3：模型路由 | ⏳ 待学习 | 0% |
| 阶段 4：Tools 工具集 | ⏳ 待学习 | 0% |
| 阶段 5：配置基础设施 | ⏳ 待学习 | 0% |

### 学习检查点

**已能回答**：
- ✅ 为什么用 3 个 Agent 而不是 1 个？
- ✅ Planner 的 Replanner 角色是什么意思？
- ✅ Executor 为什么只执行"第一步"？
- ✅ Supervisor 如何知道该调用哪个 Agent？
- ✅ outputKey 的作用是什么？
- ✅ 如何从 state 中提取最终报告？

**待验证**（完成阶段 2 后）：
- ⏳ 文档分块为什么要有 overlap？
- ⏳ 为什么用 BGE-M3 而不是其他 Embedding 模型？
- ⏳ Milvus 的 IVF_FLAT 索引适合什么场景？

---

## 🔒 Context Not to Lose

### 重要的设计决策（来自 devflow）

参考 `devflow/projects/2026-05-29-chatmodel-abstraction/decisions.md`：

1. **L1**：Spring AI 1.1.0 的 OpenAiChatModel 不兼容 DeepSeek V4
   - 解决：升级到 1.1.7 + 使用原生 `spring-ai-starter-model-deepseek`

2. **L2**：`@Qualifier` Bean 名不要猜
   - 解决：用 `List<T>` 自检 + 类名筛选

3. **L3**：base-url 末尾不要带 `/v1`
   - 原因：Spring AI 自动追加 `/v1/embeddings`，会导致双重路径

4. **L4**：多 starter 并存需要 `@Primary` 路由
   - 解决：集中路由（ModelRoutingConfig）

5. **L6**：yml 驱动路由优于硬编码 @Qualifier
   - 目标：换模型只改 yml，不改 Java

### GitNexus 规范（CLAUDE.md）

**修改代码前 MUST**：
```bash
# 1. 影响分析
mcp__gitnexus__impact({target: "symbolName", direction: "upstream"})

# 2. 如果是 HIGH/CRITICAL 风险，警告用户

# 3. 修改代码...

# 4. 变更检测（提交前）
mcp__gitnexus__detect_changes()
```

### 关键配置项

| 配置项 | 当前值 | 修改影响 |
|--------|--------|---------|
| `milvus.vector-dim` | 1024 | 换 Embedding 模型时必须同步修改 |
| `model-routing.chat` | deepseek | 切换 Chat 模型 |
| `model-routing.embedding` | siliconflow | 切换 Embedding 模型 |
| `prometheus.mock-enabled` | true | 接入真实 Prometheus 时改为 false |
| `cls.mock-enabled` | true | 接入真实腾讯云 CLS 时改为 false |

---

## 📞 Handoff Notes

### For the Next Agent

1. **如果用户说"继续学习"**：
   - 从 `docs/项目学习路径.md` 的阶段 2 开始
   - 第一个命令：`Read src/main/java/org/example/service/RagService.java`

2. **如果用户说"启动项目试试"**：
   - 先验证日志配置：`bash scripts/verify-logging.sh`
   - 启动：`mvn spring-boot:run`
   - 查看日志：`tail -f logs/application.log`
   - 访问：`http://localhost:9900`

3. **如果用户提出新需求**：
   - 先问清楚具体需求
   - 进入计划模式：`/plan`
   - 影响分析：`mcp__gitnexus__impact`

4. **如果用户遇到问题**：
   - 先查看日志：`Read logs/application-error.log`
   - 使用 `/diagnose` 技能
   - 参考 `docs/日志配置与分析指南.md` 的故障排查部分

### 用户可能的下一步

基于对话趋势，用户最可能：
1. **继续学习**（60%）- 按照学习路径深入理解项目
2. **实践验证**（30%）- 启动项目，观察 AI Ops 运行
3. **提出新需求**（10%）- 基于理解后想扩展功能

---

## 🎓 Learning Resources Created

用户现在拥有完整的学习体系：

### 📖 入门文档
- `docs/功能分析报告.md` - 项目是什么、能做什么

### 🛠️ 实用指南
- `docs/日志配置与分析指南.md` - 如何调试
- `docs/项目学习路径.md` - 如何学习

### 🎯 深度分析
- `docs/learning/01-AI-Ops-核心设计-Essence报告.md` - 核心设计模式
- `docs/learning/02-outputKey-深度解析.md` - 关键机制详解
- `docs/learning/03-核心疑问解答.md` - 常见疑问
- `docs/learning/README.md` - 学习索引

### ✅ 学习检查点清单

每个阶段都有明确的检查点，用户可以自我验证理解程度。

---

**Session End Time**: 2026-05-30  
**Handoff Status**: ✅ Ready for next session  
**Estimated Next Session Duration**: 1-2 hours (depending on chosen path)

---

> 💡 **提示给下一个 Agent**：用户已经对项目有了深刻理解，可以直接进入实践或深度学习阶段。不需要从头解释项目，直接基于已有的文档和理解继续即可。