# OncallAgent

**Repository Path**: yimazing/oncall-agent

## Basic Information

- **Project Name**: OncallAgent
- **Description**: 智能 OnCallAgent 系统，包含 chat、knowedge 和 ai_ops 三个主要 agent 模块
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SuperBizAgent

一个基于大语言模型的智能业务助手系统，集成了对话、知识库检索和智能运维等功能。

## 📋 项目简介

SuperBizAgent 是一个企业级 AI Agent 系统，提供智能对话、知识库管理和自动化运维分析能力。系统采用 RAG（检索增强生成）技术，结合多种工具调用能力，为企业提供智能化的业务支持。

## ✨ 功能特性

### 1. 智能对话（Chat）
- 基于 RAG 的智能对话系统
- 支持快速模式和流式输出
- 自动检索知识库相关内容
- 集成多种业务工具（Prometheus、MySQL 等）
- 使用 ReactAgent 架构，边思考边执行

### 2. 知识库管理（Knowledge）
- Markdown 文档自动索引
- 向量化存储和检索
- 支持文档增量更新
- 基于 Milvus 向量数据库

### 3. AI 运维分析（AI Ops）
- 一键自动化告警分析
- 使用 Plan-Execute-Replan 架构
- 自动查询 Prometheus 告警
- 智能匹配处理方案
- 生成结构化运维报告

### 4. 工具集成
- Prometheus 告警查询
- MySQL 数据库操作
- 腾讯云日志服务（MCP）
- 时间查询工具
- 内部文档查询

## 🛠 技术栈

### 后端
- **语言**：Go 1.24
- **框架**：GoFrame v2.7
- **AI 框架**：CloudWeGo Eino v0.6
- **向量数据库**：Milvus v2.4
- **数据库**：MySQL（通过 GORM）

### AI 能力
- **LLM**：DeepSeek V3（通过火山引擎）
- **Embedding**：阿里云 DashScope text-embedding-v4
- **Agent 架构**：ReactAgent、Plan-Execute-Replan
- **工具协议**：MCP（Model Context Protocol）

### 前端
- 原生 HTML/CSS/JavaScript
- Marked.js（Markdown 渲染）
- Highlight.js（代码高亮）


## 📁 项目结构

```
SuperBizAgent/
├── api/                          # API 定义
│   └── chat/v1/                  # Chat API v1
├── internal/                     # 内部实现
│   ├── controller/               # 控制器层
│   │   └── chat/                 # Chat 控制器
│   ├── ai/                       # AI 相关
│   │   ├── agent/                # Agent 实现
│   │   │   ├── chat_pipeline/    # 对话流水线（ReactAgent）
│   │   │   ├── knowledge_index_pipeline/  # 知识索引流水线
│   │   │   └── plan_execute_replan/       # 计划执行重规划（AI Ops）
│   │   ├── cmd/                  # 测试命令
│   │   │   ├── chat_cmd/         # 对话测试
│   │   │   ├── knowledge_cmd/    # 知识索引测试
│   │   │   ├── ai_ops_cmd/       # AI Ops 测试
│   │   │   └── recall_cmd/       # 检索测试
│   │   ├── embedder/             # Embedding 封装
│   │   ├── loader/               # 文档加载器
│   │   ├── retriever/            # 检索器
│   │   └── tools/                # 工具集
│   └── model/                    # 数据模型
├── utility/                      # 工具类
│   ├── client/                   # 客户端（Milvus）
│   ├── common/                   # 公共常量
│   ├── mem/                      # 内存管理
│   └── middleware/               # 中间件
├── manifest/config/              # 配置文件
│   └── config.yaml               # 统一配置
├── SuperBizAgentFrontend/        # 前端代码
│   ├── index.html                # 主页面
│   ├── app.js                    # 应用逻辑
│   └── styles.css                # 样式
├── main.go                       # 主服务入口
└── README.md                     # 项目文档
```

## 🚀 快速开始

### 前置要求

1. **Go 环境**：Go 1.24+
2. **Milvus**：向量数据库服务
3. **MySQL**：关系型数据库（可选）
4. **API Keys**：
   - DeepSeek API Key（火山引擎）
   - 阿里云 DashScope API Key

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd SuperBizAgent
```

2. **安装依赖**
```bash
go mod download
```

3. **配置文件**

编辑 `manifest/config/config.yaml`：

```yaml
# LLM 配置
ds_think_chat_model:
    api_key: "your-deepseek-api-key"
    base_url: "https://ark.cn-beijing.volces.com/api/v3"
    model: "deepseek-v3-1-terminus"

# Embedding 配置
doubao_embedding_model:
    api_key: "your-dashscope-api-key"
    base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    model: "text-embedding-v4"

# MCP 日志工具（可选）
mcp_url: "your-mcp-url"

# 文档目录
file_dir: "D:/Dev/SuperBizAgent/internal/ai/cmd/knowledge_cmd/docs"
```

4. **启动 Milvus**
```bash
# 使用 Docker
docker run -d --name milvus-standalone \
  -p 19530:19530 \
  -p 9091:9091 \
  milvusdb/milvus:latest
```

5. **构建知识库**
```bash
cd internal/ai/cmd/knowledge_cmd
go run main.go
```

6. **启动服务**
```bash
# 回到项目根目录
cd ../../../../
go run main.go
```

7. **访问前端**

打开浏览器访问：`SuperBizAgentFrontend/index.html`


## 📡 API 文档

### 基础信息
- **Base URL**: `http://localhost:6872/api`
- **Content-Type**: `application/json`

### 接口列表

#### 1. 对话接口（快速模式）
```
POST /api/chat
```

**请求体**：
```json
{
  "Id": "user-session-id",
  "Question": "你好"
}
```

**响应**：
```json
{
  "message": "OK",
  "data": {
    "answer": "你好！我是智能助手..."
  }
}
```

#### 2. 流式对话接口
```
POST /api/chat_stream
```

**请求体**：同上

**响应**：Server-Sent Events (SSE) 流式输出

#### 3. AI 运维分析
```
POST /api/ai_ops
```

**请求体**：无需参数

**响应**：
```json
{
  "message": "OK",
  "data": {
    "result": "告警分析报告...",
    "detail": ["步骤1", "步骤2", ...]
  }
}
```

#### 4. 文件上传
```
POST /api/upload
```

**请求体**：multipart/form-data

**响应**：
```json
{
  "message": "OK",
  "data": {
    "fileName": "example.md",
    "filePath": "/path/to/file",
    "fileSize": 1024
  }
}
```


## ⚙️ 配置说明

### 配置文件位置
`manifest/config/config.yaml`

### 配置项说明

#### 服务配置
```yaml
server:
    address: ":8000"           # 服务监听端口
    openapiPath: "/api.json"   # OpenAPI 文档路径
    swaggerPath: "/swagger"    # Swagger UI 路径
```

#### 日志配置
```yaml
logger:
    level: "all"               # 日志级别
    stdout: true               # 输出到标准输出
```

#### LLM 配置
```yaml
ds_think_chat_model:           # 思考模型（复杂任务）
    api_key: "your-key"
    base_url: "https://ark.cn-beijing.volces.com/api/v3"
    model: "deepseek-v3-1-terminus"

ds_quick_chat_model:           # 快速模型（简单任务）
    api_key: "your-key"
    base_url: "https://ark.cn-beijing.volces.com/api/v3"
    model: "deepseek-v3-1-terminus"
```

#### Embedding 配置
```yaml
doubao_embedding_model:
    api_key: "your-key"
    base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    model: "text-embedding-v4"
```

#### MCP 工具配置
```yaml
mcp_url: "https://mcp-api.tencent-cloud.com/sse/your-id"
```

#### 文档目录
```yaml
file_dir: "/path/to/docs"      # 知识库文档目录
```


## 🔧 开发指南

### 添加新的 API 接口

1. **定义 API 结构**（`api/chat/v1/chat.go`）
```go
type YourReq struct {
    g.Meta `path:"/your-path" method:"post" summary:"描述"`
    Field  string
}

type YourRes struct {
    Result string `json:"result"`
}
```

2. **实现控制器**（`internal/controller/chat/chat_v1_your.go`）
```go
func (c *ControllerV1) Your(ctx context.Context, req *v1.YourReq) (res *v1.YourRes, err error) {
    // 业务逻辑
    return &v1.YourRes{Result: "success"}, nil
}
```

3. **无需修改路由**（自动绑定）

### 添加新的工具

在 `internal/ai/tools/` 目录创建新工具：

```go
func NewYourTool() tool.BaseTool {
    return tool.NewTool(
        "tool_name",
        "工具描述",
        yourToolFunc,
    )
}
```

在 `chat_pipeline/flow.go` 中注册：
```go
config.ToolsConfig.Tools = append(config.ToolsConfig.Tools, tools.NewYourTool())
```

### 测试命令

```bash
# 测试对话
cd internal/ai/cmd/chat_cmd && go run main.go

# 测试知识索引
cd internal/ai/cmd/knowledge_cmd && go run main.go

# 测试 AI Ops
cd internal/ai/cmd/ai_ops_cmd && go run main.go

# 测试检索
cd internal/ai/cmd/recall_cmd && go run main.go
```


## 🏗 架构说明

### Agent 架构

#### 1. ReactAgent（对话流水线）
```
用户输入 → RAG检索 → 对话模板 → ReactAgent → 工具调用 → 输出
```

**特点**：
- 边思考边执行
- 适合普通对话场景
- 自动调用工具获取信息

#### 2. Plan-Execute-Replan（AI Ops）
```
任务输入 → 规划 → 执行 → 评估 → 重新规划 → 最终输出
```

**特点**：
- 先规划后执行
- 适合复杂多步骤任务
- 可动态调整计划

### 数据流

```
前端 → API → Controller → Agent Pipeline → Tools → LLM → Response
                              ↓
                         Milvus (RAG)
```

## 📝 常见问题

### 1. Milvus 连接失败
确保 Milvus 服务已启动：
```bash
docker ps | grep milvus
```

### 2. 配置文件找不到
确保从项目根目录运行，或检查配置路径设置。

### 3. API Key 无效
检查 `manifest/config/config.yaml` 中的 API Key 是否正确。

### 4. 知识库检索无结果
先运行 `knowledge_cmd` 构建知识库索引。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**注意**：本项目仅供学习和研究使用。