知识库 API

知识库系统 REST API，提供节点管理、向量操作、边操作、标签管理和搜索功能。知识库作为数据库和存储的"索引层"，通过分片和向量化实现语义搜索。

基础路径

/projects/:projectId/kb

认证方式

所有端点均需要 JWT Bearer Token 或 API Key 认证（combinedAuth 中间件）。

权限说明

请求者必须是项目所有者或项目所属团队的活跃成员。

错误码约定

知识库使用结构化错误码（如 KB_NODE_NOT_FOUND），便于前端国际化处理。

一、节点管理

1. 创建单个节点

POST /projects/:projectId/kb/nodes

创建一个知识库节点。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`source_type`	string	是	来源类型：`data` / `file`
`source_id`	string	是	来源 ID（指向 project_data 或 storage_files）
`level`	number	是	层级（0=文档, 1=章节, 2=段落, 3=句子）
`content`	string	是	文本内容
`parent_id`	string	否	父节点 ID
`content_type`	string	否	内容类型标识
`metadata`	object	否	附加元数据

响应 201

返回创建的节点对象。

错误码

状态码	错误码	说明
400	`KB_SOURCE_TYPE_REQUIRED`	source_type 缺失
400	`KB_SOURCE_ID_REQUIRED`	source_id 缺失
400	`KB_LEVEL_REQUIRED`	level 缺失
400	`KB_CONTENT_REQUIRED`	content 缺失
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_CREATE_NODE_FAILED`	创建节点失败

2. 批量创建节点

POST /projects/:projectId/kb/nodes/batch

批量创建节点。逐个处理，返回成功/失败列表（不回滚）。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`nodes`	array	是	节点数组，每项字段同「创建单个节点」

响应 200

json

{
  "results": [
    { "index": 0, "success": true, "node": { ... } },
    { "index": 1, "success": false, "error": "KB_CONTENT_REQUIRED" }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  }
}

错误码

状态码	错误码	说明
400	`KB_NODE_IDS_REQUIRED`	nodes 必须是非空数组
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问

3. 查询节点列表

GET /projects/:projectId/kb/nodes

分页查询节点列表，支持过滤条件。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Query 参数

参数	类型	必填	默认值	说明
`page`	number	否	`1`	页码
`pageSize`	number	否	`20`	每页条数（最大 100）
`source_type`	string	否	-	来源类型过滤：`data` / `file`
`source_id`	string	否	-	来源 ID 过滤
`status`	string	否	-	状态过滤：`pending` / `embedded` / `error`

响应 200

返回分页节点列表。

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_SEARCH_FAILED`	查询失败

4. 获取单个节点

GET /projects/:projectId/kb/nodes/:nodeId

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	节点 ID

响应 200

返回节点对象。

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在或不属于该项目
500	`KB_SEARCH_FAILED`	查询失败

5. 获取子节点

GET /projects/:projectId/kb/nodes/:nodeId/children

获取指定节点的直接子节点。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	父节点 ID

响应 200

json

{
  "data": [ ... ]
}

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
500	`KB_SEARCH_FAILED`	查询失败

6. 获取所有后代节点

GET /projects/:projectId/kb/nodes/:nodeId/descendants

递归获取指定节点的所有后代节点。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	祖先节点 ID

响应 200

json

{
  "data": [ ... ]
}

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
500	`KB_SEARCH_FAILED`	查询失败

7. 更新节点

PATCH /projects/:projectId/kb/nodes/:nodeId

更新节点的内容或状态。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	节点 ID

Body 参数（JSON）

参数	类型	必填	说明
`content`	string	否	新的文本内容
`content_type`	string	否	新的内容类型
`metadata`	object	否	新的元数据
`status`	string	否	新的状态：`pending` / `embedded` / `error`
`path`	string	否	新的路径

响应 200

返回更新后的节点对象。

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
500	`KB_UPDATE_NODE_FAILED`	更新失败

8. 删除节点

DELETE /projects/:projectId/kb/nodes/:nodeId

软删除节点，级联删除所有子节点。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	节点 ID

响应 200

json

{
  "success": true
}

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
500	`KB_DELETE_NODE_FAILED`	删除失败

9. 重新触发工作流

POST /projects/:projectId/kb/nodes/:nodeId/retrigger

重新触发节点的知识库工作流。删除该 source_id 关联的所有旧节点和向量，然后重新触发分片/向量化工作流。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	节点 ID

响应 200

json

{
  "success": true
}

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
404	`KB_SOURCE_NOT_FOUND`	源文件不存在（仅 file 类型）
500	`KB_RETRIGGER_FAILED`	重新触发失败

二、向量管理

10. 设置节点向量

PUT /projects/:projectId/kb/nodes/:nodeId/vector

为节点设置 embedding 向量。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	节点 ID

Body 参数（JSON）

参数	类型	必填	说明
`embedding`	number[]	是	向量数组
`dimension`	number	是	向量维度

响应 200

json

{
  "success": true
}

错误码

状态码	错误码	说明
400	`KB_EMBEDDING_REQUIRED`	embedding 缺失
400	`KB_DIMENSION_REQUIRED`	dimension 缺失
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
500	`KB_UPDATE_NODE_FAILED`	设置向量失败

11. 删除节点向量

DELETE /projects/:projectId/kb/nodes/:nodeId/vector

删除节点的 embedding 向量。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	节点 ID

Query 参数

参数	类型	必填	说明
`dimension`	number	是	向量维度

响应 200

json

{
  "success": true
}

错误码

状态码	错误码	说明
400	`KB_DIMENSION_REQUIRED`	dimension 缺失
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
500	`KB_DELETE_NODE_FAILED`	删除向量失败

三、边管理

12. 创建边

POST /projects/:projectId/kb/edges

创建两个节点之间的关系边。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`source_id`	string	是	源节点 ID
`target_id`	string	是	目标节点 ID
`relation_type`	string	是	关系类型（如 `tag`、`reference`）
`weight`	number	否	关系权重
`metadata`	object	否	附加元数据

响应 201

返回创建的边对象。

错误码

状态码	错误码	说明
400	`KB_SOURCE_ID_REQUIRED`	source_id 或 target_id 缺失
400	`KB_SOURCE_TYPE_REQUIRED`	relation_type 缺失
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_CREATE_NODE_FAILED`	创建边失败

13. 获取节点的边

GET /projects/:projectId/kb/nodes/:nodeId/edges

获取指定节点的所有关联边。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`nodeId`	string	是	节点 ID

响应 200

json

{
  "data": [
    {
      "id": "uuid",
      "source_id": "uuid",
      "target_id": "uuid",
      "relation_type": "tag",
      "weight": 1.0,
      "metadata": {}
    }
  ]
}

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
500	`KB_SEARCH_FAILED`	查询失败

14. 删除边

DELETE /projects/:projectId/kb/edges/:edgeId

删除指定的关系边。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`edgeId`	string	是	边 ID

响应 200

json

{
  "success": true
}

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_DELETE_NODE_FAILED`	删除边失败

四、标签管理

标签存储在项目配置的 kbFolder 树中，以 file 类型节点的 label 表示。

15. 获取标签列表

GET /projects/:projectId/kb/tags

获取项目的所有知识库标签。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

响应 200

json

{
  "data": ["产品文档", "技术资料", "FAQ"]
}

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_SEARCH_FAILED`	获取标签失败

16. 创建标签

POST /projects/:projectId/kb/tags

创建一个新标签（在 kbFolder 根目录添加 file 节点）。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`name`	string	是	标签名称（不能为空）

响应 201

json

{
  "data": ["产品文档", "技术资料", "FAQ", "新标签"]
}

返回更新后的完整标签列表。

错误码

状态码	错误码	说明
400	`KB_TAG_NAME_REQUIRED`	name 缺失或为空
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
409	`KB_TAG_DUPLICATE`	标签名已存在
500	`KB_CREATE_TAG_FAILED`	创建标签失败

17. 删除标签

DELETE /projects/:projectId/kb/tags/:tagName

删除指定标签（从 kbFolder 中递归删除匹配的 file 节点）。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`tagName`	string	是	标签名称（URL 编码）

响应 200

json

{
  "data": ["产品文档", "FAQ"]
}

返回更新后的标签列表。

错误码

状态码	错误码	说明
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_DELETE_TAG_FAILED`	删除标签失败

五、搜索

18. 向量相似度搜索

POST /projects/:projectId/kb/search

基于 embedding 向量进行相似度搜索。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`query_embedding`	number[]	是	查询向量
`dimension`	number	是	向量维度
`limit`	number	否	返回结果数量上限
`source_types`	string[]	否	来源类型过滤：`["data"]` / `["file"]`
`source_ids`	string[]	否	来源 ID 过滤
`level_filter`	number[]	否	层级过滤
`similarity_threshold`	number	否	相似度阈值

响应 200

json

{
  "data": [
    {
      "id": "uuid",
      "content": "匹配的文本内容",
      "similarity": 0.92,
      "source_type": "data",
      "source_id": "uuid",
      "level": 2,
      "metadata": {}
    }
  ]
}

错误码

状态码	错误码	说明
400	`KB_QUERY_EMBEDDING_REQUIRED`	query_embedding 缺失
400	`KB_DIMENSION_REQUIRED`	dimension 缺失
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_SEARCH_FAILED`	搜索失败

19. 文本搜索

POST /projects/:projectId/kb/text-search

基于文本的语义搜索。后端自动生成 embedding（维度 1536），然后执行向量搜索。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`query`	string	是	搜索文本
`limit`	number	否	返回结果数量上限
`source_types`	string[]	否	来源类型过滤
`similarity_threshold`	number	否	相似度阈值

响应 200

json

{
  "data": [
    {
      "id": "uuid",
      "content": "匹配的文本内容",
      "similarity": 0.89,
      "source_type": "file",
      "source_id": "uuid"
    }
  ]
}

错误码

状态码	错误码	说明
400	`KB_QUERY_REQUIRED`	query 缺失或为空
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_SEARCH_FAILED`	搜索失败

20. Tag 扩展搜索

POST /projects/:projectId/kb/expand

基于已知节点，通过边关系扩展搜索关联节点。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`node_ids`	string[]	是	起始节点 ID 列表（非空数组）
`relation_types`	string[]	否	关系类型过滤
`max_depth`	number	否	最大遍历深度
`limit`	number	否	返回结果数量上限

响应 200

json

{
  "data": [ ... ]
}

错误码

状态码	错误码	说明
400	`KB_NODE_IDS_REQUIRED`	node_ids 缺失或为空
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_SEARCH_FAILED`	搜索失败

源码

路由：apps/backend/src/routes/knowledge-base.ts
服务：apps/backend/src/services/knowledge-base.ts
参考文档：知识库使用指南

知识库 API ​

基础路径 ​

认证方式 ​

权限说明 ​

错误码约定 ​

一、节点管理 ​

1. 创建单个节点 ​

2. 批量创建节点 ​

3. 查询节点列表 ​

4. 获取单个节点 ​

5. 获取子节点 ​

6. 获取所有后代节点 ​

7. 更新节点 ​

8. 删除节点 ​

9. 重新触发工作流 ​

二、向量管理 ​

10. 设置节点向量 ​

11. 删除节点向量 ​

三、边管理 ​

12. 创建边 ​

13. 获取节点的边 ​

14. 删除边 ​

四、标签管理 ​

15. 获取标签列表 ​

16. 创建标签 ​

17. 删除标签 ​

五、搜索 ​

18. 向量相似度搜索 ​

19. 文本搜索 ​

20. Tag 扩展搜索 ​

源码 ​

知识库 API

基础路径

认证方式

权限说明

错误码约定

一、节点管理

1. 创建单个节点

2. 批量创建节点

3. 查询节点列表

4. 获取单个节点

5. 获取子节点

6. 获取所有后代节点

7. 更新节点

8. 删除节点

9. 重新触发工作流

二、向量管理

10. 设置节点向量

11. 删除节点向量

三、边管理

12. 创建边

13. 获取节点的边

14. 删除边

四、标签管理

15. 获取标签列表

16. 创建标签

17. 删除标签

五、搜索

18. 向量相似度搜索

19. 文本搜索

20. Tag 扩展搜索

源码