知识库 API

文档上传、管理与语义检索（向量 + BM25 混合检索）。

版本说明：文档 CRUD、检索、对话挖掘两者都提供。建知识库、上传入库、知识库列表为个人版独有（/api/v1/knowledge/create、/:kb_id/upload、/list）。个人版下该组未挂载鉴权，仅做租户兜底 default。

---

GET /api/v1/knowledge/documents

获取知识库文档列表（分页）。

查询参数： page（默认 1）、page_size（默认 20）、status（processing/completed/failed）。

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "doc_abc123",
        "filename": "产品需求文档.pdf",
        "file_size": 2048576,
        "file_type": "pdf",
        "status": "completed",
        "chunk_count": 45,
        "created_at": "2026-08-05T09:00:00Z"
      }
    ],
    "total": 15,
    "page": 1,
    "page_size": 10
  },
  "message": "ok",
  "request_id": "req_abc123"
}

---

POST /api/v1/knowledge/documents

创建文档（上传并入库）。multipart/form-data。

字段	类型	必填	说明
file	file	✅	上传文件
description	string	-	文档描述

支持格式（白名单）： .txt、.json、.pdf、.csv、.xls、.xlsx。 不支持 .md / .docx / .doc / 图片 / 音视频。单文件上限 50MB（个人版上传上限配置为 2048MB，但文档向量化通道单文件仍受格式与大小约束）。

curl -X POST http://localhost:19824/api/v1/knowledge/documents \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/document.pdf" \
  -F "description=产品需求文档"

上传后状态为 processing，系统自动分块、向量化与 BM25 索引；可用 GET /api/v1/knowledge/documents 轮询 status。

---

DELETE /api/v1/knowledge/documents/:id

删除文档（含向量与索引）。

---

POST /api/v1/knowledge/search

语义检索，返回最相关的文档片段（finalScore 由向量得分与 BM25 得分加权，k1=1.5）。

请求：

{ "query": "产品的核心功能有哪些", "top_k": 5 }

字段	类型	必填	说明
query	string	✅	检索文本
top_k	int	-	返回数量，默认 5，最大 20

响应：

{
  "code": 0,
  "data": {
    "results": [
      {
        "content": "核心功能包括：多智能体协作、知识库管理、工作流编排...",
        "source": "产品需求文档.pdf",
        "document_id": "doc_abc123",
        "score": 0.92,
        "metadata": { "page": 3, "chunk_index": 7 }
      }
    ],
    "total": 5
  },
  "message": "ok",
  "request_id": "req_abc123"
}

---

对话挖掘（mining）

两者都提供。从对话中自动挖掘可沉淀为知识的内容，需人工确认/拒绝。

方法	路径	说明
GET	/api/v1/knowledge/mining	挖掘候选列表
POST	/api/v1/knowledge/mining	触发一次挖掘
GET	/api/v1/knowledge/mining/stats	挖掘统计
POST	/api/v1/knowledge/mining/:id/confirm	确认采纳
POST	/api/v1/knowledge/mining/:id/reject	拒绝

---

个人版独有：知识库管理

方法	路径	说明
POST	/api/v1/knowledge/create	新建一个知识库
POST	/api/v1/knowledge/:kb_id/upload	向指定知识库上传文档
GET	/api/v1/knowledge/list	知识库列表

---

错误码

场景	code	message
文件格式不支持	40001	不支持的文件格式
文件过大	40001	文件大小超过限制
文档不存在	40400	文档不存在
检索查询为空	40001	查询内容不能为空