SuperBizAgent-java/docs/analysis/explore-report.md

Explore Report: SuperBizAgent-java

生成时间: 2026-04-30
Project type: code repository
Phases completed: 4/4
Diagram included: yes
Core designs: 3
Status: complete

---

Phase 1: Positioning & Structure

这是什么项目

SuperBizAgent-java 是一个基于 Spring AI + Alibaba DashScope (Qwen) 的智能运维 AI Agent 平台。它将大语言模型、向量检索增强生成（RAG）和多智能体协作（Planner-Executor-Replanner）整合为一体，面向企业 IT 运维场景提供：

• 智能文档问答：上传运维知识库文档（Markdown/TXT），通过 RAG 管道实现向量化检索 + LLM 流式生成回答
• 告警分析自动化：多 Agent 协作分析 Prometheus 告警，结合日志查询（腾讯云 CLS）和内部知识库，生成结构化的告警分析报告
• MCP 协议集成：通过 Spring AI MCP Client 连接外部工具服务，扩展 Agent 能力边界

为什么值得研究

维度	价值
AI 框架落地	Spring AI Alibaba 生态的完整实践——ReactAgent、SupervisorAgent、Tool 注册、流式对话
多 Agent 协作	非玩具级的 Planner-Executor-Replanner 监督循环，实际解决告警分析这种开放性问题
RAG 工程化	完整的文档分块→向量化→Milvus 存储→语义检索→流式生成的端到端管道
MCP 协议	业界较早将 MCP (Model Context Protocol) 用于生产场景的 Java 案例

适合谁

• Spring Boot / Java 开发者学习 AI Agent 框架的落地模式
• AIOps / SRE 工程师了解智能运维 Agent 的架构设计
• 对 Spring AI Alibaba 生态感兴趣的技术决策者

项目规模

指标	数值
Java 源文件	~25 个
代码行数	~2500 行
API 端点	7 个
Agent 工具	4 个
知识库文档	5 篇

技术栈

应用层     Spring Boot 3.2 / Java 17
AI 层     Spring AI Alibaba 1.1.0 / Qwen3-Max / text-embedding-v4
存储层    Milvus 2.5 (向量库) / MinIO (对象存储)
集成层    MCP Client (WebFlux SSE) / Prometheus
部署      Docker Compose (Milvus + etcd + MinIO + Attu)

与替代方案的对比

方案	优势	劣势
本项目 (Spring AI Alibaba)	完整生态、国产模型、Java 原生	社区相对年轻
LangChain4j	社区活跃、模型支持广	多 Agent 模式需自行构建
Python LangChain	生态最丰富	非 Java 技术栈
纯 DashScope API	简单直接	缺乏 Agent 编排、工具调用框架

---

Phase 2: Flow

架构总览

graph TB
    subgraph 前端
        WEB[Web UI<br/>index.html + app.js]
    end

    subgraph 控制层
        CC[ChatController<br/>/api/chat /api/chat_stream]
        AO[AIOpsController<br/>/api/ai_ops]
        UP[FileUploadController<br/>/api/upload]
        HC[MilvusCheckController<br/>/milvus/health]
    end

    subgraph 服务层
        CS[ChatService<br/>ReactAgent 编排]
        AIS[AiOpsService<br/>多Agent 协作]
        RS[RagService<br/>RAG 流式问答]
        VIS[VectorIndexService<br/>文件索引管道]
        VSS[VectorSearchService<br/>向量相似搜索]
        VES[VectorEmbeddingService<br/>文本向量化]
        DCS[DocumentChunkService<br/>智能文档分块]
    end

    subgraph Agent工具
        DT[DateTimeTools]
        IDT[InternalDocsTools]
        QMT[QueryMetricsTools]
        QLT[QueryLogsTools]
    end

    subgraph 外部服务
        DS[DashScope API<br/>Qwen3-Max / Embedding]
        MV[Milvus<br/>向量数据库]
        PM[Prometheus<br/>监控告警]
        CLS[腾讯云CLS<br/>MCP SSE]
    end

    WEB --> CC
    WEB --> AO
    WEB --> UP
    WEB --> HC

    CC --> CS
    CC --> RS
    AO --> AIS
    UP --> VIS

    CS --> DT & IDT & QMT & QLT
    AIS --> DT & IDT & QMT & QLT

    CS --> DS
    RS --> DS
    RS --> VSS
    VIS --> DCS --> VES --> MV
    VSS --> MV
    QMT --> PM
    QLT --> CLS

    VES --> DS

主要运行时流程

流程 A：RAG 智能问答（文档→检索→生成）

sequenceDiagram
    actor User
    participant Ctrl as FileUploadController
    participant VIS as VectorIndexService
    participant DCS as DocumentChunkService
    participant VES as VectorEmbeddingService
    participant MV as Milvus
    participant RS as RagService
    participant DS as DashScope

    Note over User,DS: === 索引阶段 ===
    User->>Ctrl: POST /api/upload (file.md)
    Ctrl->>VIS: indexSingleFile(file)
    VIS->>VIS: 删除旧向量(按source路径匹配)
    VIS->>DCS: chunkDocument(content)
    DCS-->>VIS: List<DocumentChunk>
    loop 每个分块
        VIS->>VES: generateEmbedding(chunk)
        VES->>DS: text-embedding-v4 API
        DS-->>VES: float[1024]
        VES-->>VIS: 向量
    end
    VIS->>MV: insert(向量 + 原文 + metadata)
    MV-->>VIS: OK

    Note over User,DS: === 问答阶段 ===
    User->>Ctrl: POST /api/chat (question)
    Ctrl->>RS: generateAnswerStream(question)
    RS->>VES: 向量化问题
    VES->>DS: text-embedding-v4
    DS-->>RS: query_vector[1024]
    RS->>MV: search(query_vector, topK=3)
    MV-->>RS: 3条最相似文档片段
    RS->>DS: Generation API (提示词 + 上下文 + 问题)
    DS-->>User: SSE 流式生成回答

流程 B：AIOps 多 Agent 告警分析

sequenceDiagram
    actor User
    participant Ctrl as ChatController
    participant AIS as AiOpsService
    participant Sup as SupervisorAgent
    participant P as PlannerAgent
    participant E as ExecutorAgent
    participant Tools as Agent Tools
    participant DS as DashScope

    User->>Ctrl: POST /api/ai_ops (告警信息)
    Ctrl->>AIS: executeAiOpsAnalysis(request)

    Note over AIS, DS: 启动监督循环
    AIS->>Sup: 启动，传入 Planner + Executor

    loop Planner-Executor-Replanner
        Sup->>P: 分析当前状态，决定下一步
        alt 需要制定/修订计划
            P-->>User: SSE: 📋 分析计划...
        else 需要执行步骤
            P-->>Sup: EXECUTE
            Sup->>E: 执行计划第一步
            E->>Tools: 调用工具收集证据
            Tools-->>E: 日志/告警/文档信息
            E-->>User: SSE: 🔍 执行结果...
            E-->>Sup: 反馈 + 证据
            Note over Sup: 将执行结果反馈给Planner
        else 分析完成
            P-->>Sup: FINISH
        end
    end

    Sup-->>User: SSE: ✅ Markdown 告警分析报告

---

Phase 3: Start Path

最小启动步骤

# 1. 启动基础设施（Milvus + etcd + MinIO）
cd D:\zhu\project\SuperBizAgent-java
docker compose -f vector-database.yml up -d

# 2. 设置 API Key 环境变量
export DASHSCOPE_API_KEY="your-dashscope-api-key"

# 3. 启动应用
mvn spring-boot:run
# 应用启动在 http://localhost:9900

# 4. 打开 Web 测试页面
# http://localhost:9900/index.html

学习起点

1. 第一入口：src/main/java/org/example/Main.java — Spring Boot 启动类，了解组件扫描范围
2. 核心对话：src/main/java/org/example/controller/ChatController.java — 所有 API 端点定义，理解请求路由
3. Agent 编排：src/main/java/org/example/service/ChatService.java — ReactAgent 如何注册工具、处理对话
4. 多 Agent 协作：src/main/java/org/example/service/AiOpsService.java — Planner-Executor-Replanner 模式完整实现
5. RAG 管道：按 VectorIndexService → DocumentChunkService → VectorEmbeddingService → RagService 顺序阅读

建议的第一个修改

在 QueryMetricsTools.java 的 queryPrometheusAlerts() 方法中添加一个 Mock 数据，观察 Agent 如何将新的工具输出整合到对话中。修改后重新提问相关问题即可看到效果。

---

Phase 4: Core Designs

设计一：Planner-Executor-Replanner 监督循环

位置：src/main/java/org/example/service/AiOpsService.java

是什么：一个三层多 Agent 协作模式，用监督者控制循环来解决开放性的告警分析问题。

SupervisorAgent (监督者)
  ├── PlannerAgent (规划者)
  │     └── 决策三个状态: PLAN → 制定/修订计划
  │                      EXECUTE → 交给执行者
  │                      FINISH → 输出最终报告
  └── ExecutorAgent (执行者)
        └── 执行计划中的第一步
        └── 调用工具获取真实数据
        └── 返回反馈给 Planner 重新规划

为什么重要：

• 不是简单的单次 Agent 调用，而是通过循环反馈逐步逼近准确分析
• Planner 根据 Executor 返回的证据动态调整计划（即 Replan 机制）
• 通过 SSE 将每一步的中间结果实时推送给前端，用户体验好
• 工具调用是实际的：Prometheus 查询、日志搜索、知识库检索，不是 mock 玩具

关键实现细节：

// SupervisorAgent 创建并传入子 Agent
SupervisorAgent supervisor = SupervisorAgent.builder()
    .supervisorAgent(supervisor)
    .subAgents(plannerAgent, executorAgent)
    .build();

设计二：完整的 RAG 管道（5 级流水线）

位置：VectorIndexService → DocumentChunkService → VectorEmbeddingService → VectorSearchService → RagService

是什么：从原始文档到流式问答输出的完整 RAG 管道，涉及 5 个松耦合的服务组件。

阶段	组件	关键技术点
1. 智能分块	DocumentChunkService	按 Markdown 标题层级 + 段落边界分割，800 字符/块，100 字符重叠
2. 向量化	VectorEmbeddingService	DashScope text-embedding-v4，1024 维，支持批量
3. 向量存储	MilvusClientFactory	IVF_FLAT 索引，L2 距离，自动去重（按 source 路径）
4. 语义检索	VectorSearchService	Top-K 配置化（default 3），返回原文 + 相似度分数
5. 流式生成	RagService	DashScope Generation API，SSE 流式输出，支持 system prompt

为什么重要：

• 每个阶段独立可替换——可以换分块策略、换向量库、换 LLM
• 幂等上传：同一文件重新上传时，先删除旧向量再写入，保证数据一致性
• 分块策略考虑了 Markdown 的文档结构（标题层级），而不是简单的固定长度切割

设计三：工具即插即用的 Agent 工具系统

位置：src/main/java/org/example/agent/tool/*.java

是什么：基于 Spring AI @Tool 注解的工具系统，Agent 自动发现并可调用。

// 工具定义示例
@Component
public class DateTimeTools {
    @Tool(description = "获取当前日期和时间")
    public String getCurrentDateTime() { ... }
}

核心设计决策：

决策	做法	原因
Mock 开关	QueryMetricsTools 和 QueryLogsTools 都有 mockEnabled 配置	开发/演示时不需要真实 Prometheus/CLS 环境
MCP 优先	当 MCP Client 可用时，自动排除 QueryLogsTools	避免工具重复，MCP 提供更丰富的日志能力
JSON Schema 生成	使用 jsonschema-generator 为工具参数生成 schema	让 LLM 理解工具的参数类型和约束
工具注册	ChatService 和 AiOpsService 各自注册工具集	Agent 只获得需要的能力，避免干扰

ChatService 工具注册：

// 构建时注册所有可用工具
ReactAgent agent = ReactAgent.builder()
    .tools(dateTimeTools, internalDocsTools, 
           queryMetricsTools, queryLogsTools)
    .build();

为什么重要：

• Agent 工具系统是 AI Agent 的能力边界——定义了 Agent 能做什么
• Mock/Real 模式切换体现了开发友好性
• MCP 协议的集成展示了可扩展性——Agent 可以从外部获取新能力

---

总结

SuperBizAgent-java 是一个小而完整的 AI Agent 实践项目。它的三个核心竞争力是：

1. 多 Agent 协作（Planner-Executor-Replanner）——不是玩具，是真正解决问题的模式
2. 工程化的 RAG 管道——5 级流水线、幂等上传、智能分块
3. Spring AI 生态的完整实践——从 @Tool 注解到 MCP 协议，展示了 Java 生态做 AI Agent 的成熟路径

对于想将 AI Agent 引入企业运维场景的 Java 团队，这是一个很好的学习起点和脚手架。