X-Agents/team-require/api/knowledge-api.md

# 知识库 API

## 基础信息

| 项目 | 说明 |
|------|------|
| 基础URL | `http://localhost:8082` |

## 接口列表

### 1. 创建知识库

**请求**

```
POST /api/knowledge/create
Content-Type: application/json
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | 是 | 知识库名称 |
| description | String | 否 | 知识库描述 |
| llm_model_id | String | 是 | LLM 模型 ID |
| embedding_model_id | String | 是 | Embedding 模型 ID |
| parsing_config | Object | 是 | 解析配置 |
| - engine | String | 是 | 解析引擎：markitdown / docling |
| - docling_url | String | 条件 | Docling URL（engine=docling 时必填） |
| - enable_pdf | Boolean | 否 | 是否启用 PDF 解析 |
| - pandoc | Boolean | 否 | 是否启用 Pandoc |
| storage_config | Object | 否 | 存储配置，不传则使用全局配置 |
| - type | String | 否 | 存储模式：local / minio |
| - endpoint | String | 否 | MinIO endpoint |
| - bucket | String | 否 | MinIO bucket |
| - access_key | String | 否 | MinIO access key |
| - secret_key | String | 否 | MinIO secret key |
| - use_ssl | Boolean | 否 | MinIO 是否使用 SSL |

**响应**

```json
{
  "success": true,
  "id": "kb_xxx",
  "message": "Knowledge base created successfully"
}
```

---

### 2. 获取知识库列表

**请求**

```
GET /api/knowledge/list
```

**响应**

```json
{
  "success": true,
  "data": [
    {
      "id": "kb_001",
      "name": "产品文档知识库",
      "description": "用于存储产品手册",
      "llm_model_id": "model_001",
      "embedding_model_id": "model_002",
      "status": "active",
      "document_count": 15,
      "chunk_count": 156,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

---

### 3. 获取知识库详情

**请求**

```
GET /api/knowledge/:id
```

**响应**

```json
{
  "success": true,
  "data": {
    "id": "kb_001",
    "name": "产品文档知识库",
    "description": "用于存储产品手册",
    "llm_model_id": "model_001",
    "embedding_model_id": "model_002",
    "parsing_config": {
      "engine": "markitdown",
      "enable_pdf": true,
      "pandoc": true
    },
    "status": "active",
    "document_count": 15,
    "chunk_count": 156,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

---

### 4. 删除知识库

**请求**

```
DELETE /api/knowledge/:id
```

**响应**

```json
{
  "success": true,
  "message": "Knowledge base deleted"
}
```

---

### 5. 获取知识库下的文档列表

**请求**

```
GET /api/knowledge/:id/documents
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | String | 否 | 过滤状态：all / parsed / parsing / failed |

**响应**

```json
{
  "success": true,
  "data": [
    {
      "id": "doc_001",
      "knowledge_base_id": "kb_001",
      "name": "产品手册_v2.0.pdf",
      "file_key": "abc123.pdf",
      "file_url": "http://localhost:8082/files/abc123.pdf",
      "file_size": 2516582,
      "status": "parsed",
      "chunk_count": 156,
      "uploaded_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

---

### 6. 上传文档到知识库

**请求**

```
POST /api/knowledge/:id/documents
Content-Type: multipart/form-data
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | File | 是 | 要上传的文件 |

**响应**

```json
{
  "success": true,
  "id": "doc_001",
  "url": "http://localhost:8082/files/abc123.pdf",
  "document": {
    "id": "doc_001",
    "knowledge_base_id": "kb_001",
    "name": "产品手册_v2.0.pdf",
    "file_size": 2516582,
    "status": "parsing",
    "chunk_count": 0,
    "uploaded_at": "2024-01-15T10:30:00Z"
  },
  "message": "Document uploaded"
}
```

---

### 7. 删除知识库文档

**请求**

```
DELETE /api/knowledge/:id/documents/:doc_id
```

**响应**

```json
{
  "success": true,
  "message": "Document deleted"
}
```

---

### 8. 重新解析文档

**请求**

```
POST /api/knowledge/:id/documents/:doc_id/reparse
```

**响应**

```json
{
  "success": true,
  "message": "Document reparse started"
}
```

---

### 9. 获取文档预览内容

**请求**

```
GET /api/knowledge/:id/documents/:doc_id/preview
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | Number | 否 | 页码（默认 1） |

**响应**

```json
{
  "success": true,
  "data": {
    "total_pages": 3,
    "current_page": 1,
    "content": "第一章 产品介绍..."
  }
}
```