# agent

**Repository Path**: git4chen/agent

## Basic Information

- **Project Name**: agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Platform

企业级智能客服 Agent 平台：多轮对话、意图识别、知识库 RAG（检索增强生成）、混合检索与 SSE 流式回复。主用户为 C 端自助咨询；运营通过知识库页与意图页维护内容，无需在聊天首屏暴露技术参数。

产品体验原则见 [PRODUCT.md](PRODUCT.md)；操作说明见 [docs/使用手册.md](docs/使用手册.md)。

---

## 界面预览

基于 `agent-web`（React）的产品界面：C 端以对话为主，运营能力通过顶栏进入知识库与意图管理，不在聊天首屏暴露技术参数。

| 落地页 | 智能客服对话 |
|--------|----------------|
| [![落地页](docs/screenshots/landing.png)](docs/screenshots/landing.png) | [![对话页](docs/screenshots/chat.png)](docs/screenshots/chat.png) |
| 自助提问入口、常见话题引导 | 多轮对话、流式回复、知识库引用 |

| 知识库管理 | 意图管理 |
|------------|----------|
| [![知识库](docs/screenshots/knowledge-base.png)](docs/screenshots/knowledge-base.png) | [![意图管理](docs/screenshots/intent-admin.png)](docs/screenshots/intent-admin.png) |
| 文档上传、解析与向量化 | 意图识别与检索知识库路由配置 |

本地体验：启动 `agent-web` 开发服务，或访问 `agent-chat` / `agent-knowledge` 内置静态页（见下方「主要访问入口」）。

---

## 技术架构

### 技术栈

| 层次 | 选型 | 说明 |
|------|------|------|
| 语言 / 运行时 | Java 21 | 虚拟线程、Record |
| 应用框架 | Spring Boot 3.4 | Web、JPA、WebFlux（SSE） |
| LLM 集成 | LangChain4j | 对话、Embedding、提示词 |
| 大模型 | OpenAI 兼容 API | 默认 DeepSeek，环境变量可切换 |
| 向量与全文 | Elasticsearch 8 | kNN + BM25，混合融合（RRF 等） |
| 业务库 | MySQL 8 | 知识库元数据、会话、意图 |
| 缓存 | Redis | 会话、意图路由、话语分析缓存 |
| 对象存储 | MinIO（S3 兼容） | 原始文档，可切本地目录 |
| 服务治理 | Apache Dubbo 3 + Nacos | `agent-chat` ↔ `agent-knowledge` 检索 RPC |
| 网关 | Spring Cloud Gateway | 可选统一入口 |
| 文档解析 | MinerU（独立 Python 服务） | PDF / Office → Markdown |
| 前端（内置） | 静态 HTML | `chat.html` / `document.html` / `intent.html` |
| 前端（演进） | React + Vite（`agent-web/`） | 独立 SPA，未纳入 Maven 父工程 |

### 逻辑架构

```mermaid
flowchart TB
    subgraph Client["客户端"]
        U[终端用户 chat.html]
        O[运营 document.html / intent.html]
        W[agent-web 可选]
    end

    subgraph Gateway["api-gateway :9000 可选"]
        GW[路由 /api/v1/*]
    end

    subgraph ChatSvc["agent-chat :8082"]
        CC[Conversation / Chat API]
        IC[Intent 分类与执行]
        RP[RAG Pipeline]
        LLM[LLM 流式生成]
    end

    subgraph KnowSvc["agent-knowledge :8081"]
        KB[知识库 / 文档 API]
        JOB[异步解析管道]
        ES[(Elasticsearch)]
        HY[HybridSearch + Fusion]
        DUB[KnowledgeVector Dubbo]
    end

    subgraph Infra["基础设施"]
        MY[(MySQL)]
        RD[(Redis)]
        MI[MinIO]
        MU[MinerU API]
        NC[Nacos]
    end

    U --> CC
    O --> KB
    W --> GW
    GW --> CC
    GW --> KB
    CC --> IC
    IC --> RP
    RP -->|Dubbo retrieveWithTrace| DUB
    DUB --> HY
    HY --> ES
    RP --> LLM
    KB --> JOB
    JOB --> MI
    JOB --> MU
    JOB --> ES
    CC --> MY
    CC --> RD
    KB --> MY
    KnowSvc --> NC
    ChatSvc --> NC
```

### 模块依赖

```mermaid
flowchart LR
    GW[api-gateway]
    CH[agent-chat]
    KN[agent-knowledge]
    API[agent-dubbo-api]
    CM[agent-common]

    GW --> CH
    GW --> KN
    CH --> CM
    CH --> API
    KN --> CM
    KN --> API
    API --> CM
```

---

## 项目结构

```
agent-platform/                    # Maven 父工程 (pom.xml)
├── agent-common/                  # 公共库：实体、DTO、统一响应、异常、常量
├── agent-dubbo-api/               # Dubbo 接口与检索模型（HybridRetrievalTrace 等）
├── agent-knowledge/               # 知识库微服务 :8081
│   ├── controller/                # REST：知识库、文档、结构化查询
│   ├── service/
│   │   ├── parser/                # MinerU / CSV / MD 解析链
│   │   ├── job/                   # 异步管道：转换 → 分片 → 向量化
│   │   ├── vector/                # Elasticsearch 索引与写入
│   │   ├── retrieval/             # 混合检索、RRF 融合、父段解析
│   │   └── struct/                # 表格类 Text-to-SQL 数据路径
│   ├── dubbo/                     # KnowledgeVectorDubboServiceImpl
│   └── resources/static/
│       └── document.html          # 知识库管理页
│
├── agent-chat/                    # 对话微服务 :8082
│   ├── controller/                # 会话、聊天 SSE、意图管理 API
│   ├── service/
│   │   ├── intent/                # 意图分类、执行计划
│   │   ├── memory/                # 对话状态、槽位、摘要、话语分析
│   │   ├── rag/                   # RAG 编排、选库、引用格式化
│   │   ├── route/                 # 查询路由（语义 / 结构化 / 混合）
│   │   └── stream/                # 管道步骤与 SSE 事件
│   └── resources/static/
│       ├── chat.html              # 智能客服主界面
│       └── intent.html            # 意图运营页
│
├── api-gateway/                   # API 网关 :9000（可选）
│
├── agent-web/                     # React 前端（独立 npm 工程）
│
├── docs/                          # 设计文档、SQL、Docker、示例知识库
│   ├── architecture.md            # 架构详设
│   ├── chat-module.md             # 对话与 API
│   ├── knowledge-module.md        # 知识库详设
│   ├── message-pipeline.md        # 消息链路 / 路由链
│   ├── query-routing.md           # 查询路由与检索策略
│   ├── 使用手册.md                 # 用户与运营手册
│   ├── docker/                    # docker-compose 本地环境
│   └── sample-knowledge/          # 示例 Markdown + seed 脚本
│
├── PRODUCT.md                     # 产品定位与体验原则
└── openspec/                      # 变更提案与规格（OpenSpec 工作流）
```

### 各模块职责

| 模块 | 类型 | 职责 |
|------|------|------|
| **agent-common** | JAR | 跨服务共享的领域模型、`ApiResponse`、错误码、Mapper |
| **agent-dubbo-api** | JAR | 检索 RPC 契约；混合检索结果与追踪结构 |
| **agent-knowledge** | 可部署服务 | 知识库 CRUD、文档上传与异步解析、ES 向量/全文索引、混合检索 Dubbo 提供方 |
| **agent-chat** | 可部署服务 | 会话生命周期、意图识别与执行、RAG 调用、LLM 流式问答、管理端意图 API |
| **api-gateway** | 可部署服务 | 将 `/api/v1/knowledge-bases/**`、`/api/v1/chat/**` 等转发至对应服务 |
| **agent-web** | 前端 | 基于 React 的对话产品壳（开发中，生产可继续用静态页） |

---

## 核心业务流程

### 1. 知识入库（运营侧）

从文档上传到可被检索，全程异步，不阻塞上传接口。

```mermaid
sequenceDiagram
    participant Op as 运营 / document.html
    participant KB as agent-knowledge
    participant S3 as MinIO
    participant MU as MinerU
    participant Job as 解析管道
    participant ES as Elasticsearch
    participant DB as MySQL

    Op->>KB: 上传文件 + kbId
    KB->>S3: 存储原始文件
    KB->>DB: 文档记录 PENDING
    KB-->>Op: 返回 docId（异步）

    Job->>S3: 读取文件
    alt PDF/DOCX/XLSX/PPTX
        Job->>MU: 解析为 Markdown
    else MD/TXT/CSV
        Job->>Job: 内置 Parser
    end
    Job->>Job: 分片 parent-child / 语义块
    Job->>ES: Embedding + 索引（向量 + 全文）
    opt 表格类知识
        Job->>DB: 结构化表元数据 + 动态表
    end
    Job->>DB: 状态 DONE / FAIL
    Op->>KB: 轮询或刷新列表
```

**要点**

- 仅状态为 **可用（DONE）** 的文档参与 RAG。
- 默认 **parent-child 分片**：检索命中子段后可解析为父段上下文（`ParentSegmentRetrievalResolver`）。
- 混合检索在知识库服务内完成：`kNN` + 全文 → `HybridScoreFusion`（如 RRF）→ Top-N。

### 2. 智能问答（用户侧）

用户只需在 `chat.html` 提问；系统完成意图、选库、检索与生成。

```mermaid
sequenceDiagram
    participant U as 用户
    participant UI as chat.html
    participant Chat as agent-chat
    participant Intent as 意图 / 话语分析
    participant RAG as RagPipeline
    participant Dubbo as Dubbo 检索
    participant Know as agent-knowledge
    participant LLM as 大模型

    U->>UI: 发送消息
    UI->>Chat: POST bootstrap / stream
    Chat->>Chat: 校验会话与 userId
    Chat->>Intent: 话语分析 + 意图分类
    Intent-->>Chat: ExecutionPlan（是否 RAG、目标 kbId）
    alt 需要 RAG
        Chat->>RAG: 查询改写（可选）
        RAG->>Dubbo: retrieveWithTrace(query, topK, kbId)
        Dubbo->>Know: 混合检索 ES
        Know-->>RAG: 片段 + HybridRetrievalTrace
        RAG->>RAG: 组装 System + 历史 + 引用
    end
    Chat->>LLM: 流式生成
    LLM-->>UI: SSE 逐 token
    Chat->>Chat: 落库消息与引用 metadata
```

**路由与执行（概念层）**

| 阶段 | 说明 |
|------|------|
| 话语分析 | 问候、元问题、话题切换等快捷路径，减少误触发 RAG |
| 意图识别 | 匹配 `chat_intent`（退货、物流、知识问答等） |
| 知识库路由 | 按意图 `handler_config` 或 LLM 选库（`KnowledgeBaseResolver`） |
| 存储类型 | 向量检索 / Text-to-SQL / 混合（见 `ChatQueryRouter`） |
| RAG 组装 | 检索片段 + 会话窗口 + 知识库 system prompt |
| 响应 | 固定话术或 LLM；SSE 推送管道步骤（可选） |

更细的链路见 [docs/message-pipeline.md](docs/message-pipeline.md)。

### 3. 意图与检索绑定（运营侧）

```mermaid
flowchart LR
    A[用户话术] --> B[IntentClassifier]
    B --> C{意图命中}
    C --> D[IntentExecutor]
    D --> E{handler: RAG?}
    E -->|是| F[解析 kbId / kbIds]
    F --> G[Dubbo 混合检索]
    G --> H[LLM 生成 + 引用]
    E -->|否| I[直连 LLM / 固定回复 / 工具]
```

意图配置在 **intent.html** 或 `docs/sql/chat-intent-seed.sql`；示例数据脚本见 `docs/sample-knowledge/`。

---

## 数据与存储

| 数据 | 存储 | 说明 |
|------|------|------|
| 知识库、文档、分片元数据 | MySQL | `knowledge_base`、`knowledge_document`、`knowledge_segment` 等 |
| 向量与全文索引 | Elasticsearch | 索引名默认 `knowledge_segment_v1` |
| 原始文件 | MinIO / 本地目录 | `knowledge.storage.type` |
| 会话与消息 | MySQL | `chat_conversation`、`chat_message` |
| 意图定义 | MySQL | `chat_intent`、`chat_intent_relation` |
| 热点缓存 | Redis | 意图表、路由结果、话语分析 |

表结构见 [docs/sql/schema.sql](docs/sql/schema.sql)。

---

## 快速开始

### 1. 启动基础设施

```bash
docker compose -f docs/docker/docker-compose.yml up -d
mysql -h127.0.0.1 -P3306 -uagent -pagent agent < docs/sql/schema.sql
mysql -h127.0.0.1 -P3306 -uagent -pagent agent < docs/sql/chat-intent-seed.sql
```

### 2. 配置 LLM

`~/.agent/secrets.yml` 或环境变量：

```yaml
llm:
  api-key: ${LLM_API_KEY}
  base-url: https://api.deepseek.com/v1
  model: deepseek-chat
```

### 3. 启动服务

```bash
mvn -pl agent-knowledge -am spring-boot:run    # :8081
mvn -pl agent-chat -am spring-boot:run         # :8082
# 可选
mvn -pl api-gateway -am spring-boot:run        # :9000
```

### 4. 导入示例并体验

```bash
bash docs/sample-knowledge/seed-demo.sh
# 等待 document.html 中文档「可用」后，打开 chat.html 提问
```

MinerU、密钥与排障见 [docs/docker/README.md](docs/docker/README.md)、[docs/使用手册.md](docs/使用手册.md)。

---

## 主要访问入口

| 入口 | URL |
|------|-----|
| 智能客服 | http://localhost:8082/chat.html |
| 知识库管理 | http://localhost:8081/document.html |
| 意图管理 | http://localhost:8082/intent.html |
| 知识库健康检查 | http://localhost:8081/actuator/health |
| 对话健康检查 | http://localhost:8082/actuator/health |

---

## 文档索引

| 文档 | 内容 |
|------|------|
| [docs/使用手册.md](docs/使用手册.md) | 终端用户与运营操作 |
| [docs/architecture.md](docs/architecture.md) | 架构详设、数据模型、可观测性 |
| [docs/chat-module.md](docs/chat-module.md) | 会话 API、意图、SSE |
| [docs/knowledge-module.md](docs/knowledge-module.md) | 上传、分片、向量化 |
| [docs/message-pipeline.md](docs/message-pipeline.md) | 消息链路四层路由 |
| [docs/query-routing.md](docs/query-routing.md) | 语义 / 结构化 / 混合查询 |
| [docs/document-parsing.md](docs/document-parsing.md) | MinerU 集成 |
| [PRODUCT.md](PRODUCT.md) | 产品定位与品牌气质 |

---

## 构建要求

- JDK 21+
- Maven 3.9+
- Docker（本地 MySQL / Redis / ES / MinIO / Nacos）
- 可选：Python 3.10+（MinerU）、Node.js 20+（`agent-web`）

```bash
mvn clean package -DskipTests
```

---

## 许可证

见仓库根目录 LICENSE（若尚未添加，以团队约定为准）。