# agent-scope-java2

**Repository Path**: ctllin/agent-scope-java2

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent-Scope Java 2.0

AI 知识库平台：基于 Spring Boot 3 后端 + Vue 3 前端，集成大模型对话（GLM）、RAG 知识库检索（Milvus 向量库）、本地 ONNX 模型推理（中文向量化 / OCR / 离线 TTS），支持文档上传、解析、分块、向量化与全文/语义检索。

---

## 目录

- [功能总览](#功能总览)
- [技术栈](#技术栈)
- [环境要求](#环境要求)
- [快速启动](#快速启动)
- [配置说明](#配置说明)
- [项目结构](#项目结构)
- [API 接口一览](#api-接口一览)
- [前端路由](#前端路由)
- [核心架构](#核心架构)
- [RAG 流水线](#rag-流水线)
- [外部服务集成](#外部服务集成)
- [部署指南](#部署指南)
- [常见问题](#常见问题)

---

## 功能总览

| 模块 | 功能 |
|------|------|
| 用户认证 | JWT 登录、快捷登录开关、用户/角色/菜单权限管理 |
| AI 对话 | 多模型路由（GLM / Ollama 本地）、多会话管理、流式输出、对话历史持久化 |
| 知识库 | 创建/删除知识库、文档上传（PDF/Word/TXT/图片）、文本解析与分块 |
| 向量检索 | 本地 ONNX 文本向量化 → Milvus 入库 → 语义 Top-K 检索（RAG） |
| OCR 识别 | 基于 RapidOCR 的图片/PDF 页面文字识别，支持单页与批量 |
| TTS 朗读 | 文档内容朗读，支持 Edge-TTS 在线合成与 sherpa-onnx 本地离线合成 |
| ASR 语音识别 | 基于 Vosk 的离线语音识别，支持文件上传与实时识别 |
| 文档解析 | 集成 MinerU，支持 PDF/Word/Excel 高精度解析，输出 Markdown/JSON |
| 文档编辑 | 分页浏览、逐行编辑、行合并/删除/移动、页级编辑 |
| 文档预览 | 支持 PDF、Word、Excel、PPT 在线预览（@vue-office/*） |

---

## 技术栈

### 后端

| 分类 | 技术 | 版本 |
|------|------|------|
| 框架 | Spring Boot | 3.5.16 |
| JDK | Java | 21+ |
| 构建 | Maven | 3.8+ |
| 数据库 | MongoDB | 4.4+（spring-data-mongodb） |
| 向量库 | Milvus | 2.x（milvus-sdk-java 3.0.5） |
| AI 编排 | AgentScope Harness | 2.0.1 |
| LLM 接口 | OpenAI 兼容（智谱 GLM） | agentscope-extensions-model-openai |
| 本地推理 | DJL + ONNX Runtime | 0.36.0 / 1.16.3 |
| 分词器 | HuggingFace Tokenizers（DJL） | 0.36.0 |
| OCR | RapidOCR | 0.0.7（ONNX Runtime 推理） |
| 语音识别 | Vosk | 0.3.45 |
| 语音合成 | sherpa-onnx JVM | v1.13.6 |
| 文档解析 | Apache PDFBox / Apache POI | 3.0.2 / 5.2.5 |
| 认证 | JJWT | 0.12.6 |
| 事件总线 | LMAX Disruptor | 3.4.4 |
| 文件存储 | x-file-storage | 2.2.1 |
| 缓存 | Caffeine | Spring Boot 管理 |
| 工具库 | Hutool | 5.8.46 |
| 序列化 | Jackson（含 JSR310 时间支持） | Spring Boot 管理 |
| WebSocket | spring-boot-starter-websocket | 3.5.16 |
| 代码简化 | Lombok | 1.18.34 |

### 前端

| 分类 | 技术 | 版本 |
|------|------|------|
| 框架 | Vue 3 + TypeScript | 3.4+ / 5.3+ |
| 构建 | Vite | 5.0+ |
| UI | Element Plus + @element-plus/icons-vue | 2.4.4 |
| 状态管理 | Pinia | 2.1.7 |
| 路由 | Vue Router 4 | 4.2.5 |
| HTTP | Axios（统一拦截器） | 1.6.2 |
| Markdown | markdown-it | 15.0.1 |
| 文档预览 | @vue-office/docx / excel / pdf / pptx | 多版本 |
| 样式 | Sass | 1.69.5 |
| 类型检查 | vue-tsc | 2.0+ |

### 使用的模型

| 用途 | 模型 | 说明 |
|------|------|------|
| 对话 LLM | GLM `glm-4-flash`（智谱AI） | OpenAI 兼容接口，可通过环境变量切换 base-url/model |
| 本地对话 LLM | Qwen2.5-3B / Qwen3-8B（Ollama） | 本地部署，通过 Ollama API 调用 |
| 文本向量化 | `Xenova/bge-small-zh-v1.5` | 本地 ONNX 推理，512 维，归一化输出 |
| OCR | RapidOCR ONNX | 中英文图片文字识别 |
| 离线 TTS | sherpa-onnx `vits-melo-tts-zh_en` / `supertonic-3-int8` | 本地语音合成（中英混读） |
| 在线 TTS | Edge-TTS | 可选，依赖系统安装 `edge-tts` 命令 |
| 语音识别 | Vosk（中文/英文模型） | 离线识别，需下载模型到 `sherpa-onnx/` |

---

## 环境要求

| 组件 | 版本/要求 | 说明 |
|------|-----------|------|
| JDK | 21+ | 后端编译运行 |
| Maven | 3.8+ | 后端构建 |
| Node.js | 18+（建议 20/22） | 前端构建运行 |
| MongoDB | 4.4+，默认 `127.0.0.1:27017` | 业务数据存储，库名 `test` |
| Milvus | 2.x，默认 `localhost:19530` | 向量检索；不需要时可设 `milvus.enabled=false` |
| GLM API Key | 必需 | 环境变量 `GLM_API_KEY` |
| 本地 Embedding 模型 | `/data/software/AI/Xenova/bge-small-zh-v1.5/` | 需包含 `tokenizer.json` + `onnx/model.onnx` |
| Vosk 模型 | `sherpa-onnx/` 目录 | 语音识别模型，可通过脚本下载 |
| 磁盘目录 | `/data/agent-scope/files`、`/data/agent-scope/tts-cache` 等 | 需可写权限 |
| ffmpeg | 系统 PATH 中 | ASR 音频格式转换所需 |
| MinerU（可选） | `mineru-api --port 8000` | 高精度文档解析，需独立启动 |

> **Docker 快速启动 MongoDB / Milvus：**
> ```bash
> docker run -d -p 27017:27017 --name mongodb mongo:latest
> docker run -d -p 19530:19530 --name milvus milvusdb/milvus:latest milvus run standalone
> ```

---

## 快速启动

### 方式一：一键脚本（推荐）

```bash
# 根目录启动脚本，自动检查 MongoDB 连接与 API Key
./start.sh
```

> `start.sh` 会检查 MongoDB 是否运行、`GLM_API_KEY` 是否设置，然后在后台启动后端。

### 方式二：手动启动

**启动后端：**

```bash
cd backend
mvn spring-boot:run        # 开发模式启动（8080 端口）
```

**启动前端（新终端）：**

```bash
cd frontend
npm ci                     # 首次安装（使用已提交的 package-lock.json）
npm run dev                # 开发模式（5173 端口，/api 自动代理到 8080）
```

### 访问

| 地址 | 说明 |
|------|------|
| `http://localhost:5173` | 前端页面（Vite 开发服务器） |
| `http://localhost:8080/api/*` | 后端 API |
| `http://localhost:8080/files/**` | 静态文件访问（x-file-storage 存储） |

### 登录

- 默认账号：`root / 123456`
- 快捷登录：在登录页**双击空白区域**触发（需 `app.quick-login.enabled=true`）
- 启动时 `DataInitConfig` 会自动创建 root 用户（若不存在）

---

## 配置说明

所有后端配置集中在 `backend/src/main/resources/application.yml`，无多环境 profile。

### 核心配置项

```yaml
server:
  port: 8080

# MongoDB
spring.data.mongodb:
  uri: mongodb://127.0.0.1:27017/test?authSource=admin&retryWrites=false

# GLM 大模型（环境变量优先，yml 中有 fallback 默认值）
glm:
  api-key: ${GLM_API_KEY:your-fallback-key}
  base-url: ${GLM_BASE_URL:https://open.bigmodel.cn/api/paas/v4}
  model: ${GLM_MODEL:glm-4-flash}

# 本地 Embedding 模型
embedding:
  tokenizer-uri: file:/data/software/AI/Xenova/bge-small-zh-v1.5/tokenizer.json
  onnx-model-uri: file:/data/software/AI/Xenova/bge-small-zh-v1.5/onnx/model.onnx
  max-sequence-length: 512

# Milvus（禁用时设为 false）
milvus:
  enabled: true
  host: localhost
  port: 19530
  collection-prefix: kb_
  dimension: 512

# RAG 检索参数
rag:
  chunk-size: 500
  overlap-ratio: 0.15
  top-k: 3
  similarity-threshold: 0.5

# 文件存储
file.storage.base-path: /data/agent-scope/files

# 快捷登录
app.quick-login:
  enabled: true
  username: root
  password: "123456"

# TTS
app.tts:
  edge-command: edge-tts
  audio-dir: /data/agent-scope/tts-cache
  use-offline: false

# ASR（Vosk）
app.asr:
  audio-dir: /data/agent-scope/asr
  ffmpeg-path: ffmpeg

# MinerU 文档解析（需独立启动 mineru-api）
app.mineru:
  url: http://127.0.0.1:8000
  parse-timeout-ms: 600000

# 多模型路由
app.ai-models.models:
  - name: GLM-4-Flash
    model: glm-4-flash
    base-url: https://open.bigmodel.cn/api/paas/v4
  - name: Qwen2.5-3B (本地)
    model: qwen2.5:3b
    base-url: http://127.0.0.1:9081/ollama
    api-key: ollama
  - name: Qwen3-8B (本地)
    model: qwen3:8b
    base-url: http://127.0.0.1:9081/ollama
    api-key: ollama

# 事件总线
app.events:
  type: disruptor
  ring-buffer-size: 1024
```

### 环境变量

```bash
# 必需
export GLM_API_KEY=你的智谱APIKey

# AgentScope harness 要求（即使使用 GLM 也需设置）
export OPENAI_API_KEY=dummy

# 可选（覆盖 yml 中的默认值）
export GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
export GLM_MODEL=glm-4-flash
export AMAP_API_KEY=你的高德Web服务密钥
```

---

## 项目结构

```
agent-scope-java2/
├── backend/                          # Spring Boot 后端
│   ├── pom.xml                       # Maven 依赖配置（Spring Boot 3.5.16）
│   ├── start.sh                      # 生产环境启动脚本
│   └── src/main/
│       ├── java/com/agentscope/
│       │   ├── AgentScopeApplication.java   # 入口类（@EnableFileStorage @EnableAsync @EnableScheduling）
│       │   ├── controller/           # REST 控制器（10 个）
│       │   │   ├── AuthController.java        # /api/auth — 登录/快捷登录/当前用户
│       │   │   ├── ChatController.java        # /api/chat — 会话管理/发送消息/模型列表/高德配置
│       │   │   ├── KnowledgeBaseController.java # /api/knowledge-bases — CRUD/上传/分块/向量化/搜索/OCR
│       │   │   ├── UserController.java        # /api/users — 用户 CRUD/密码修改
│       │   │   ├── RoleController.java        # 角色管理
│       │   │   ├── MenuController.java        # 菜单管理
│       │   │   ├── AsrController.java         # /api/asr — 语音识别上传/识别/批量操作
│       │   │   ├── TtsController.java         # /api/tts — 语音合成/缓存管理
│       │   │   ├── TtsRecordController.java   # /api/tts-records — 合成记录/音频播放
│       │   │   └── ParseController.java       # /api/parse — MinerU 文档解析
│       │   ├── service/              # 业务层（18 个 Service + 实现）
│       │   │   ├── ChatService.java           # 对话核心逻辑
│       │   │   ├── EmbeddingService.java      # 本地 ONNX 向量化
│       │   │   ├── MilvusService.java         # Milvus 向量库操作
│       │   │   ├── KnowledgeBaseService.java  # 知识库业务
│       │   │   ├── OcrService.java            # RapidOCR 调用
│       │   │   ├── TtsService.java            # TTS 合成
│       │   │   ├── AsrService.java            # Vosk 语音识别
│       │   │   ├── ParseService.java          # MinerU 文档解析
│       │   │   ├── ModelRouter.java           # 多模型路由
│       │   │   ├── AmapTool.java              # 高德地图工具
│       │   │   ├── AmapRestClient.java        # 高德 API 客户端
│       │   │   ├── AuthService.java           # 认证逻辑
│       │   │   ├── UserService.java           # 用户管理
│       │   │   ├── RoleService.java           # 角色管理
│       │   │   ├── MenuService.java           # 菜单管理
│       │   │   ├── TtsRecordService.java      # 合成记录管理
│       │   │   ├── XFileStorageService.java   # 文件存储
│       │   │   └── EmbeddingCacheService.java # Embedding 缓存
│       │   ├── repository/           # MongoDB 数据访问（13 个 Repository）
│       │   ├── model/
│       │   │   ├── entity/            # 实体类（14 个）
│       │   │   ├── dto/               # 请求 DTO（13 个）
│       │   │   └── vo/                # 响应 VO（11 个）
│       │   ├── config/               # 配置类（21 个）
│       │   │   ├── MilvusConfig.java          # Milvus 条件装配（@ConditionalOnProperty + @Lazy）
│       │   │   ├── EmbeddingConfig.java       # Embedding 模型加载
│       │   │   ├── DataInitConfig.java        # 启动时自动创建 root 用户
│       │   │   ├── TraceContextFilter.java    # 链路追踪（@Order HIGHEST_PRECEDENCE）
│       │   │   ├── JwtConfig.java             # JWT 认证拦截器
│       │   │   ├── AiModelConfig.java         # 多模型路由配置
│       │   │   ├── AgentScopeConfig.java      # AgentScope 框架配置
│       │   │   ├── QuickLoginConfig.java      # 快捷登录配置
│       │   │   ├── TtsConfig.java             # TTS 配置
│       │   │   ├── AsrConfig.java             # ASR 配置
│       │   │   ├── MineruConfig.java          # MinerU 配置
│       │   │   ├── RagConfig.java             # RAG 参数配置
│       │   │   ├── AmapConfig.java            # 高德地图配置
│       │   │   ├── FileStorageConfig.java     # 文件存储配置
│       │   │   └── ThreadPoolConfig.java      # 线程池配置
│       │   ├── events/               # Disruptor 事件总线
│       │   │   ├── BizEvent.java              # 事件定义
│       │   │   ├── BizEventType.java          # 事件类型枚举（OCR/ASR/EMBED/TTS）
│       │   │   ├── BizEventHandler.java       # 事件处理接口
│       │   │   ├── BizEventHandlerRegistry.java # 处理器注册
│       │   │   ├── DisruptorEventConfig.java  # Disruptor 配置
│       │   │   └── EventPublisher.java        # 事件发布器
│       │   ├── interceptor/
│       │   │   └── RequestIdInterceptor.java  # 请求 ID 拦截器
│       │   ├── common/
│       │   │   ├── Response.java              # 统一响应封装
│       │   │   ├── ResultCode.java            # 错误码枚举
│       │   │   ├── RequestContext.java        # 请求上下文
│       │   │   ├── Request.java               # 请求工具
│       │   │   ├── enums/                     # 枚举（10 个：ChatMode/DocumentType/SplitStrategy 等）
│       │   │   └── exceptions/                # 自定义异常
│       │   └── util/                 # 工具类（10 个：JWT/OCR/TTS/ASR/Snowflake 等）
│       └── resources/
│           └── application.yml       # 单一配置文件（无 profile）
├── frontend/                         # Vue 3 前端
│   ├── package.json                  # 依赖声明（npm）
│   ├── vite.config.ts                # Vite 配置（端口 5173，代理 /api → 8080，构建输出到 backend）
│   ├── tsconfig.json                 # TypeScript 配置
│   └── src/
│       ├── main.ts                   # Vue 入口（创建 App，挂载 Pinia/Router/Element Plus）
│       ├── App.vue                   # 根组件
│       ├── api/
│       │   ├── index.ts              # 全部 API 函数（60+ 个，涵盖所有接口）
│       │   └── auth.ts               # 认证专用 API
│       ├── views/                    # 页面组件
│       │   ├── login/index.vue       # 登录页（双击快捷登录）
│       │   ├── dashboard/index.vue   # 首页
│       │   ├── chat/index.vue        # AI 对话
│       │   ├── knowledge-base/
│       │   │   ├── index.vue         # 知识库列表
│       │   │   └── detail.vue        # 知识库详情（文档管理/分块编辑/OCR）
│       │   ├── asr/index.vue         # 语音识别
│       │   ├── tts/index.vue         # 语音合成
│       │   ├── mineru/index.vue      # 文档解析（MinerU）
│       │   └── user/index.vue        # 用户管理
│       ├── components/               # 公共组件
│       │   ├── PdfViewer.vue         # PDF 预览
│       │   ├── TextViewer.vue        # 文本预览/编辑
│       │   ├── TtsToolbar.vue        # TTS 工具栏
│       │   ├── ManualSplitDialog.vue # 手动分块对话框
│       │   └── AmapMap.vue           # 高德地图
│       ├── layout/index.vue          # 主布局（侧边栏 + 顶栏 + 内容区）
│       ├── router/index.ts           # 路由定义与守卫
│       ├── store/user.ts             # Pinia 用户状态管理
│       ├── types/index.ts            # TypeScript 类型定义（214 行，20+ 接口/枚举）
│       ├── utils/
│       │   ├── request.ts            # Axios 实例（baseURL /api，拦截器处理 token/错误）
│       │   ├── amapLoader.ts         # 高德地图 JS API 加载器
│       │   └── markdown.ts           # Markdown 渲染工具
│       └── composables/
│           └── useTTS.ts             # TTS 组合式函数
├── docs/                             # 项目文档
│   ├── mineru.md                     # MinerU 使用说明
│   └── res.md                        # 资源下载与环境配置备忘
├── scripts/                          # 辅助脚本
│   ├── download-melo-onnx.sh         # 下载 MeloTTS ONNX 模型
│   ├── download-supertonic.sh        # 下载 Supertonic TTS 模型
│   ├── download-vosk-model.sh        # 下载 Vosk ASR 模型
│   ├── requirement.txt               # Python 依赖（vosk/edge-tts/mineru）
│   └── vosk-asr.py                   # Vosk ASR 测试脚本
├── sherpa-onnx/                      # 本地 TTS/ASR 运行库与模型（.gitignore）
├── start.sh                          # 根目录一键启动脚本
├── clear-git-log.sh                  # Gitee Git 历史重置
├── clear-github-log.sh               # GitHub Git 历史重置
├── README.md                         # 本文件
├── STARTUP.md                        # 启动说明（中文）
└── AGENTS.md                         # AI Agent 工作指引
```

---

## API 接口一览

所有接口统一返回 `Response<T>` 格式：

```json
{
  "requestId": "a1b2c3...",
  "timestamp": 1700000000000,
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

### 认证 `/api/auth`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 用户名密码登录 |
| POST | `/api/auth/quick-login` | 快捷登录（root 账号） |
| GET | `/api/auth/current` | 获取当前登录用户信息 |

### 用户 `/api/users`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/users` | 用户列表（分页 + 关键词搜索） |
| GET | `/api/users/{id}` | 获取用户详情 |
| POST | `/api/users` | 创建用户 |
| PUT | `/api/users/{id}` | 更新用户 |
| DELETE | `/api/users/{id}` | 删除用户 |
| PUT | `/api/users/{id}/password` | 修改密码 |

### AI 对话 `/api/chat`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/chat/models` | 获取可用模型列表 |
| GET | `/api/chat/amap-config` | 获取高德地图前端配置 |
| POST | `/api/chat/sessions` | 创建对话会话 |
| GET | `/api/chat/sessions` | 获取会话列表 |
| GET | `/api/chat/sessions/{id}` | 获取会话详情 |
| DELETE | `/api/chat/sessions/{id}` | 删除会话 |
| POST | `/api/chat/messages` | 发送消息（返回用户消息 + AI 回复） |
| GET | `/api/chat/sessions/{id}/messages` | 获取会话消息历史 |

### 知识库 `/api/knowledge-bases`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/knowledge-bases` | 知识库列表 |
| GET | `/api/knowledge-bases/{id}` | 知识库详情 |
| POST | `/api/knowledge-bases` | 创建知识库 |
| DELETE | `/api/knowledge-bases/{id}` | 删除知识库 |
| POST | `/api/knowledge-bases/{id}/documents` | 上传文档 |
| GET | `/api/knowledge-bases/{id}/documents` | 文档列表（分页） |
| DELETE | `/api/knowledge-bases/documents/{id}` | 删除文档 |
| DELETE | `/api/knowledge-bases/documents/batch` | 批量删除文档 |
| POST | `/api/knowledge-bases/documents/batch-split` | 批量分块 |
| POST | `/api/knowledge-bases/documents/batch-embed` | 批量向量化 |
| POST | `/api/knowledge-bases/documents/{id}/split` | 单文档分块 |
| GET | `/api/knowledge-bases/documents/{id}/chunks` | 获取文档分块 |
| GET | `/api/knowledge-bases/documents/{id}/content` | 获取文档内容 |
| POST | `/api/knowledge-bases/documents/{id}/embed` | 单文档向量化 |
| POST | `/api/knowledge-bases/documents/{id}/download` | 下载文档 |
| POST | `/api/knowledge-bases/{id}/search` | 语义搜索（Top-K） |

### 分块管理 `/api/knowledge-bases/chunks`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/knowledge-bases/chunks/batch-embed` | 批量向量化分块 |
| POST | `/knowledge-bases/chunks/delete-vectors` | 删除分块向量 |
| POST | `/knowledge-bases/chunks/batch-delete` | 批量删除分块 |
| POST | `/knowledge-bases/chunks/merge` | 合并分块 |
| POST | `/knowledge-bases/chunks/manual` | 手动创建分块 |
| PUT | `/knowledge-bases/chunks/{id}` | 更新分块内容 |
| PUT | `/knowledge-bases/chunks/reorder` | 分块排序 |
| POST | `/knowledge-bases/chunks/manual-batch` | 批量手动分块 |

### OCR `/api/knowledge-bases/documents/{id}/ocr`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/knowledge-bases/documents/{id}/ocr` | 触发 OCR 识别 |
| GET | `/knowledge-bases/documents/{id}/ocr-status` | 轮询 OCR 状态 |
| POST | `/knowledge-bases/documents/{id}/ocr/{pageIndex}` | 单页 OCR |
| GET | `/knowledge-bases/documents/{id}/pages` | 获取页面内容 |
| GET | `/knowledge-bases/documents/{id}/page-count` | 获取总页数 |

### 语音识别 `/api/asr`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/asr/upload` | 上传音频文件 |
| GET | `/api/asr/records` | 识别记录列表（分页） |
| POST | `/api/asr/records/{id}/recognize` | 单条识别 |
| POST | `/api/asr/records/batch-recognize` | 批量识别 |
| DELETE | `/api/asr/records/{id}` | 删除记录 |
| POST | `/api/asr/records/batch-delete` | 批量删除 |

### 语音合成 `/api/tts` & `/api/tts-records`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/tts/speak` | 语音合成 |
| DELETE | `/api/tts/cache` | 清理 TTS 缓存 |
| GET | `/api/tts/cache/stats` | 缓存统计 |
| POST | `/api/tts-records` | 创建合成记录 |
| GET | `/api/tts-records` | 合成记录列表（分页） |
| GET | `/api/tts-records/{id}` | 合成记录详情 |
| DELETE | `/api/tts-records/{id}` | 删除记录 |
| GET | `/api/tts-records/{id}/audio` | 播放合成音频 |

### 文档解析 `/api/parse`（MinerU）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/parse/upload` | 上传文件解析 |
| GET | `/api/parse/records` | 解析记录列表（分页） |
| GET | `/api/parse/records/{id}` | 解析记录详情 |
| POST | `/api/parse/records/{id}/reparse` | 重新解析 |
| POST | `/api/parse/records/batch-reparse` | 批量重新解析 |
| DELETE | `/api/parse/records/{id}` | 删除记录 |
| GET | `/api/parse/records/{id}/download` | 下载 Markdown |
| GET | `/api/parse/records/{id}/download-json` | 下载 JSON |

---

## 前端路由

| 路径 | 页面 | 说明 |
|------|------|------|
| `/login` | 登录页 | 双击空白区域触发快捷登录 |
| `/dashboard` | 首页 | 默认路由重定向 |
| `/chat` | AI 对话 | 多模型多会话对话 |
| `/knowledge-base` | 知识库列表 | 创建/管理知识库 |
| `/knowledge-base/:id` | 知识库详情 | 文档管理/分块编辑/OCR/搜索 |
| `/asr` | 语音识别 | 音频上传/识别/管理 |
| `/tts` | 语音合成 | 文本转语音/缓存管理 |
| `/mineru` | 文档解析 | MinerU 高精度文档解析 |
| `/user` | 用户管理 | 需 root 权限 |

路由守卫：所有页面需登录（`requiresAuth: true`），token 存储在 `localStorage`。

---

## 核心架构

### 后端架构

```
请求 → TraceContextFilter（链路追踪，最高优先级）
     → JwtConfig 拦截器（认证检查）
     → RequestIdInterceptor（请求 ID 注入）
     → Controller → Service → Repository（MongoDB）
                               → MilvusService（向量库）
                               → EmbeddingService（本地 ONNX）
                               → EventPublisher → Disruptor 事件总线
```

### 事件驱动（Disruptor）

耗时操作通过 Disruptor 事件总线异步处理，避免阻塞主线程：

| 事件类型 | 处理内容 |
|----------|----------|
| OCR | PDF/图片页面文字识别 |
| EMBED | 文本向量化并写入 Milvus |
| ASR | 语音识别 |
| TTS | 语音合成 |

配置：`app.events.type=disruptor`，环形缓冲区大小 1024。

### 前端架构

```
Vue 3 App
├── Element Plus（UI 组件库）
├── Pinia（状态管理：user store）
├── Vue Router（路由 + 守卫）
├── Axios（HTTP：/api 代理到 8080，拦截器处理 token/错误）
└── Views → Components → API Layer → Backend
```

---

## RAG 流水线

```
文档上传 → 文本解析（PDFBox/POI）
         → 文本分块（chunk-size=500, overlap=15%）
         → 本地 ONNX 向量化（bge-small-zh-v1.5, 512维）
         → Milvus 入库（collection: kb_{知识库ID}）
         → 语义搜索（Top-K=3, similarity≥0.5）
         → 拼接上下文 → LLM 对话
```

### 分块策略

- 默认：按 `chunk-size=500` 字符分块，重叠率 `overlap-ratio=0.15`
- 支持手动分块、合并、排序
- 分块状态：`UPLOADED` → `SPLIT` → `EMBEDDED`

### 向量库

- Milvus collection 命名：`kb_{knowledgeBaseId}`
- 向量维度：512（与 bge-small-zh-v1.5 匹配）
- 条件装配：`milvus.enabled=false` 时完全禁用，纯对话仍可用
- 懒加载：首次使用时连接

---

## 外部服务集成

### 智谱 GLM

- 接口：OpenAI 兼容（`https://open.bigmodel.cn/api/paas/v4`）
- 默认模型：`glm-4-flash`
- 通过 `GLM_API_KEY` 环境变量配置

### Ollama 本地模型

- Qwen2.5-3B / Qwen3-8B 通过 Ollama API 调用
- 默认地址：`http://127.0.0.1:9081/ollama`
- 安装：`ollama pull qwen2.5:3b && ollama pull qwen3:8b`

### MinerU 文档解析

- 需独立启动：`mineru-api --host 0.0.0.0 --port 8000`
- 支持 PDF/Word/Excel/PPT 高精度解析
- 输出 Markdown 和 JSON 格式
- 接口文档：`http://127.0.0.1:8000/docs`

### Vosk 语音识别

- 离线识别，需下载模型到 `sherpa-onnx/` 目录
- 支持中文/英文
- 音频格式转换依赖 ffmpeg

### 高德地图

- Web 服务密钥：`AMAP_API_KEY`
- JS API 密钥：`AMAP_WEB_KEY`
- 用于导航功能（驾车路线规划、地理编码）

---

## 部署指南

### 生产构建

```bash
# 1. 构建前端（输出到 backend/src/main/resources/static/）
cd frontend && npm run build

# 2. 构建后端 JAR
cd backend && mvn clean package

# 3. 运行
java -jar backend/target/agent-scope-java2-1.0.0-SNAPSHOT.jar
```

> `npm run build` 会先执行 `vue-tsc --noEmit` 类型检查，再执行 `vite build`，输出目录为 `backend/src/main/resources/static/`，被打进 Spring Boot JAR。

### 生产环境注意事项

- 关闭快捷登录：`app.quick-login.enabled=false`
- 替换 JWT 密钥：`app.jwt.secret`（当前为默认值）
- 替换 GLM API Key：使用环境变量，不要硬编码在 yml 中
- 确保 `/data/agent-scope/` 目录存在且可写
- MongoDB 建议开启认证
- Milvus 建议部署为集群模式（生产环境）

### 磁盘目录规划

| 目录 | 用途 |
|------|------|
| `/data/agent-scope/files/` | 知识库文件存储 |
| `/data/agent-scope/storage/` | x-file-storage 静态文件 |
| `/data/agent-scope/tts-cache/` | TTS 合成缓存 |
| `/data/agent-scope/tts-records/` | TTS 合成记录音频 |
| `/data/agent-scope/asr/` | ASR 音频文件 |
| `/data/agent-scope/logs/` | 应用日志（滚动，100MB 上限，14 天保留） |
| `/home/software/AI/Xenova/bge-small-zh-v1.5/` | Embedding ONNX 模型 |
| `sherpa-onnx/` | TTS/ASR 本地原生库与模型 |

---

## 常见问题

### MongoDB 连接失败

```
MongoSocketOpenException: Exception opening socket
```

- 确认 MongoDB 已启动：`mongosh --eval "db.version()" --quiet`
- 确认地址为 `127.0.0.1:27017`，URI 带 `authSource=admin`
- Docker 启动：`docker run -d -p 27017:27017 --name mongodb mongo:latest`

### GLM 模型配置错误

```
Cannot resolve model: "openai:null"
```

- 设置环境变量：`export GLM_API_KEY=你的APIKey`
- 或检查 `application.yml` 中 `glm.api-key` 配置

### Milvus 未启用

- `application.yml` 中 `milvus.enabled=false` 时向量功能整体关闭
- 纯对话功能仍可正常使用
- 需要向量检索时改为 `true` 并确保 Milvus 服务运行

### Embedding 加载失败

- 检查模型目录路径是否正确（`embedding.tokenizer-uri` / `embedding.onnx-model-uri`）
- 确认目录下存在 `tokenizer.json` 和 `onnx/model.onnx`
- 可在 yml 中修改指向自己的 bge 模型路径

### TTS 无声音

- 离线模式：依赖 `sherpa-onnx/` 下原生库（Linux x64）
- 在线模式：需系统安装 `edge-tts`（`pip install edge-tts`）
- 检查 `app.tts.use-offline` 配置

### ASR 识别失败

- 确认 Vosk 模型已下载到 `sherpa-onnx/` 目录
- 运行 `scripts/download-vosk-model.sh` 下载模型
- 确认 ffmpeg 已安装并在 PATH 中

### 文件上传失败

- 确认 `/data/agent-scope/files` 目录存在且应用有写权限
- 检查 `spring.servlet.multipart.max-file-size`（默认 50MB）

### MinerU 解析失败

- 确认 MinerU API 服务已启动：`mineru-api --host 0.0.0.0 --port 8000`
- 检查 `app.mineru.url` 配置
- 接口文档：`http://127.0.0.1:8000/docs`

### 端口被占用

```bash
# 查找占用端口的进程
lsof -i :8080
# 终止进程
kill -9 <PID>
```

### 后端构建警告

- `package-lock.json` 在 `.gitignore` 中但已提交到仓库 → 使用 `npm ci` 保证一致性
- `start.sh` 中有硬编码路径 → 仅用于特定部署环境
- `application.yml` 中有 fallback 默认 API Key → 生产环境务必使用环境变量覆盖