知识库 API

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

基础路径

/projects/:projectId/kb

认证方式

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

权限说明

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

错误码约定

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

标签稳定 ID 机制（重要）

自 2026-06-14（issue #741）起，知识库标签的身份是稳定 id（key），不再是显示名（label）。

标签存储在 projects.config.kbFolder 树中，每个 file 类型节点有两个属性：

key：稳定 id（形如 tag-xxx），节点创建后永不改变，是标签的真实身份；
label：显示名，可随时重命名，仅用于展示。

为什么这样改：标签身份过去全链路以 label 字符串落地（kb_nodes.metadata.tag、KB Search 块、Schema 字段的 knowledgeBaseTag），重命名标签后已选 / 已入库的内容就和新名字失配。改用稳定 id 后，重命名只改 label，所有引用仍指向同一个 key，不再失配。

落地要点：

标签端点统一返回 { key, label }[]（GET / POST / PATCH / DELETE /kb/tags），不再返回 label[]；
重命名走 PATCH /kb/tags/:key（按 key 改 label，key 不变）；
删除优先按 key（DELETE /kb/tags/:tagName 先当 key 命中删除，未命中再回落按 label 删，兼容旧客户端）；
入库链路写双字段：节点 metadata 写 { tag: <label 快照>, tagId: <key> }（保留 tag 作 label 快照不删，新增 tagId 承载稳定 key）；
搜索三字段兜底：kb_search_similar RPC 对标签过滤做 metadata.tagId / metadata.tag / metadata.knowledgeBaseTag 三字段 OR 匹配——传 key 命中新数据的 tagId，迁移期传旧 label 仍能命中漏网旧节点的 tag / knowledgeBaseTag；
fail-loud：入库链路解析标签时，若传入值在项目 kbFolder 中既不是合法 key 也不是已知 label（孤儿 / 死引用）返回 KB_TAG_NOT_FOUND；若同名多 key（重名歧义）返回 KB_TAG_AMBIGUOUS。两者都同步返回 4xx，不静默吞。

一、节点管理

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	否	附加元数据。若含标签字段（`tag` / `tagId` / `knowledgeBaseTag` 任一），服务端会按项目 `kbFolder` 规范化成 `{ tag: <label 快照>, tagId: <稳定 key> }` 后入库（issue #741）

响应 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 缺失
400	`KB_TAG_NOT_FOUND`	metadata 标签在项目 kbFolder 中既非合法 key 也非已知 label（孤儿 / 死引用）
400	`KB_TAG_AMBIGUOUS`	metadata 标签为同名多 key（重名歧义），无法唯一解析
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
  }
}

标签稳定 ID（issue #741）：批量入库只读一次项目 kbFolder 建索引，逐行复用。某行 metadata 标签解析失败时，该行 error 为 KB_TAG_NOT_FOUND（孤儿 / 死引用）或 KB_TAG_AMBIGUOUS（重名歧义），不影响其它行。

错误码

状态码	错误码	说明
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

重新触发节点的知识库工作流。file 来源会按源文件路径重入；data 来源会回查源数据记录和字段配置，使用字段最新全文重建对应 KB 节点。

标签稳定 ID 数据安全（issue #741）：重入链路是「先软删旧节点，再触发重建」。为避免标签解析失败导致「删了又抛错 = 数据丢失」，所有待触发的标签会在任何软删之前先用项目 kbFolder 预校验，孤儿 / 歧义提前返回 4xx（KB_TAG_NOT_FOUND / KB_TAG_AMBIGUOUS），绝不删。

Path 参数

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

响应 200

json

{
  "success": true
}

错误码

状态码	错误码	说明
400	`KB_TAG_NOT_FOUND`	待触发标签在项目 kbFolder 中既非合法 key 也非已知 label（软删前预校验拦截）
400	`KB_TAG_AMBIGUOUS`	待触发标签为同名多 key（重名歧义，软删前预校验拦截）
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_NODE_NOT_FOUND`	节点不存在
404	`KB_SOURCE_NOT_FOUND`	源文件或源数据不存在
409	`KB_RETRIGGER_FIELD_NOT_FOUND`	无法定位 data 节点对应的数据字段
409	`KB_RETRIGGER_FIELD_AMBIGUOUS`	无法唯一定位 data 节点对应的数据字段
409	`KB_RETRIGGER_UNSUPPORTED`	当前 fallback 节点类型无法从源数据还原全文
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 类型节点表示。每个标签有稳定 id key（身份）和显示名 label，详见上文「标签稳定 ID 机制」。

返回形状变更（issue #741，2026-06-14）：标签端点统一返回 { key, label }[]，不再返回 label[]。

15. 获取标签列表

GET /projects/:projectId/kb/tags

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

Path 参数

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

响应 200

json

{
  "data": [
    { "key": "tag-a1b2c3d4", "label": "产品文档" },
    { "key": "tag-e5f6g7h8", "label": "技术资料" }
  ]
}

错误码

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

16. 创建标签

POST /projects/:projectId/kb/tags

创建一个新标签（在 kbFolder 根目录添加 file 节点，自动生成稳定 key）。

Path 参数

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

Body 参数（JSON）

参数	类型	必填	说明
`name`	string	是	标签显示名（label）。trim 后非空、长度 ≤200、不含控制字符（C0/DEL/C1）

响应 201

json

{
  "data": [
    { "key": "tag-a1b2c3d4", "label": "产品文档" },
    { "key": "tag-x9y8z7w6", "label": "新标签" }
  ]
}

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

并发安全（issue #741）：写入用 projects.updated_at 乐观锁 CAS，并发期间被改写返回 409 KB_TAG_CONFLICT_RETRY，不静默覆盖。

错误码

状态码	错误码	说明
400	`KB_TAG_NAME_REQUIRED`	name 缺失或为空
400	`KB_TAG_NAME_TOO_LONG`	name 超过 200 字符
400	`KB_TAG_NAME_INVALID`	name 含控制字符
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
409	`KB_TAG_DUPLICATE`	标签名已存在
409	`KB_TAG_CONFLICT_RETRY`	并发修改冲突，请重试
500	`KB_CREATE_TAG_FAILED`	创建标签失败

17. 重命名标签

PATCH /projects/:projectId/kb/tags/:key

按稳定 key 重命名标签：只改 label，key 不变。这是标签稳定 ID 根治的核心——重命名后已选 / 已入库内容的引用（指向 key）不失配。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`key`	string	是	标签稳定 id（URL 编码）

Body 参数（JSON）

参数	类型	必填	说明
`name`	string	是	新的显示名（label）。校验同「创建标签」：trim 非空、≤200、无控制字符。新名不能与其它 key 的标签同名（与自身同名是空操作，允许）

响应 200

json

{
  "data": [
    { "key": "tag-a1b2c3d4", "label": "产品文档（已改名）" }
  ]
}

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

并发安全（issue #741）：同「创建标签」走 projects.updated_at 乐观锁 CAS。

错误码

状态码	错误码	说明
400	`KB_TAG_NAME_REQUIRED`	name 缺失或为空
400	`KB_TAG_NAME_TOO_LONG`	name 超过 200 字符
400	`KB_TAG_NAME_INVALID`	name 含控制字符
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
404	`KB_TAG_NOT_FOUND`	指定 key 的标签不存在
409	`KB_TAG_DUPLICATE`	新名与其它标签重名
409	`KB_TAG_CONFLICT_RETRY`	并发修改冲突，请重试
500	`KB_RENAME_TAG_FAILED`	重命名失败

18. 删除标签

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

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

标签稳定 ID（issue #741）：路由参数名沿用 tagName 兼容旧客户端，但优先按稳定 key 删除；当作 key 未命中时再回落按 label 删除。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`tagName`	string	是	标签稳定 `key`（优先）或显示名 `label`（回落兼容），URL 编码

响应 200

json

{
  "data": [
    { "key": "tag-a1b2c3d4", "label": "产品文档" }
  ]
}

返回更新后的标签列表（{ key, label }[]）。

错误码

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

五、搜索

19. 向量相似度搜索

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	否	相似度阈值
`tags`	string[]	否	标签过滤。issue #741 起推荐传稳定标签 `key`，命中节点 `metadata.tagId`；迁移期传旧 `label` 仍可命中 `metadata.tag` / `metadata.knowledgeBaseTag`（RPC 三字段 OR 兜底）。多标签 OR；不传 = 不过滤。每项自动 trim 首尾空白后参与匹配；单项 ≤128 字符，数量 ≤50，不允许空串/纯空白

响应 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 缺失
400	`KB_TAGS_INVALID`	tags 非法（非字符串数组 / 含空串 / 超长 / 超量）
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_SEARCH_FAILED`	搜索失败

20. 文本搜索

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

基于文本的语义搜索。后端按当前 KB 配置的供应商、模型和维度生成 embedding，然后执行同一向量空间的搜索。

Path 参数

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

Body 参数（JSON）

参数	类型	必填	说明
`query`	string	是	搜索文本
`limit`	number	否	返回结果数量上限
`source_types`	string[]	否	来源类型过滤
`similarity_threshold`	number	否	相似度阈值
`tags`	string[]	否	标签过滤。issue #741 起推荐传稳定标签 `key`，命中节点 `metadata.tagId`；迁移期传旧 `label` 仍可命中 `metadata.tag` / `metadata.knowledgeBaseTag`（RPC 三字段 OR 兜底）。多标签 OR；不传 = 不过滤。每项自动 trim 首尾空白后参与匹配；单项 ≤128 字符，数量 ≤50，不允许空串/纯空白

响应 200

json

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

错误码

状态码	错误码	说明
400	`KB_QUERY_REQUIRED`	query 缺失或为空
400	`KB_TAGS_INVALID`	tags 非法（非字符串数组 / 含空串 / 超长 / 超量）
404	`KB_PROJECT_NOT_FOUND`	项目不存在或无权访问
500	`KB_SEARCH_FAILED`	搜索失败

21. 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
参考文档：知识库使用指南

补充端点

本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。

POST /projects/:projectId/kb/ingest

知识摄入

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`projectId`	项目 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

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

整体更新知识库节点内容或元数据。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`projectId`	项目 ID
`nodeId`	知识节点 ID

请求：请求体为 JSON，表示该资源的目标配置或完整更新内容。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /projects/:projectId/kb/process

触发知识库节点处理、解析或向量化任务。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`projectId`	项目 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回任务触发结果、运行状态或同步摘要；长任务可能只表示已入队。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

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

批量软删除知识库节点。请求体提供节点 ID 列表；调用方必须具有项目写权限，响应返回实际删除数量。

OAuth 知识库向量费用（#1495）

OAuth project:kb:write 的入库、PUT 内容重向量化，以及 project:kb:read 的文本检索，会对实际 embedding 调用按模型 Token 用量计费；不产生 Flow 运行费。读取节点与传入现成向量的搜索不调用 embedding。JWT/API Key 原有费用路径保持兼容。

调用人只取服务端已验证 OAuth 身份；使用该用户默认账户的隐藏计费 Key 与付款团队。访问共享项目不会改用项目所有者的余额，body 不能指定付款人。
OAuth 同步调用优先使用 KB 配置中的 publicModelId，并固定 provider/model/dimension。旧配置没有公开 ID 时，只在该供应存在唯一已发布 embedding 映射时兼容解析；别名歧义要求管理员明确选择，不能随机选择价格。供应检查复用公共发布库、启用 variant、协议路由与凭据，不要求 embedding 探针新鲜度。零价和小数价有效，缺价不作为免费；不会自动切换向量空间。
外呼前检查余额或模型订阅权益、冻结报价并写入现有消费意图；每次实际调用独立计量，不新增固定运行费。传 Idempotency-Key 后，同一调用重放返回 409；改项目、内容或模型不会借用旧账单。
只接受供应商真实 prompt_tokens / total_tokens；缺用量、超时或响应异常记为待核对，不补造零用量、不自动重试供应商。余额不足在外呼前拒绝；PUT / text-search 返回对应错误。ingest 已创建节点时继续返回 207 和 status:error，供调用方查询节点状态。
返回 X-Wainao-Request-Id 可关联现有消费回执。X-Wainao-Billing-State: pending 表示真实用量已持久化但结算待恢复，已生成向量可以使用；若用量证据本身无法落库则拒绝交付，不应盲目重发。向量格式无效但供应商已经报告用量时，实际消耗仍计费。

OAuth embedding HTTP 与以上三个 KB 同步路径使用同一执行服务：外呼前创建持久计量意图，真实供应商 usage 入账后交付向量。缺失用量或超时标记未知，不补造 0；结算暂未完成但证据已保存时返回 X-Wainao-Billing-State: pending。支持 Idempotency-Key，已接受的重复请求返回 409，不重发供应商调用。

旧 JWT/API Key、工作流与数据写入触发的异步索引继续使用已有 provider/model/dimension 配置与收费方式；共用 HTTP 传输不意味着新增 OAuth 模型账单。向量搜索及纯元数据 CRUD 不产生模型调用费。

知识库 API ​

基础路径 ​

认证方式 ​

权限说明 ​

错误码约定 ​

标签稳定 ID 机制（重要） ​

一、节点管理 ​

1. 创建单个节点 ​

2. 批量创建节点 ​

3. 查询节点列表 ​

4. 获取单个节点 ​

5. 获取子节点 ​

6. 获取所有后代节点 ​

7. 更新节点 ​

8. 删除节点 ​

9. 重新触发工作流 ​

二、向量管理 ​

10. 设置节点向量 ​

11. 删除节点向量 ​

三、边管理 ​

12. 创建边 ​

13. 获取节点的边 ​

14. 删除边 ​

四、标签管理 ​

15. 获取标签列表 ​

16. 创建标签 ​

17. 重命名标签 ​

18. 删除标签 ​

五、搜索 ​

19. 向量相似度搜索 ​

20. 文本搜索 ​

21. Tag 扩展搜索 ​

源码 ​

补充端点 ​

POST /projects/:projectId/kb/ingest ​

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

POST /projects/:projectId/kb/process ​

POST /projects/:projectId/kb/nodes/batch-delete ​

OAuth 知识库向量费用（#1495） ​

知识库 API

基础路径

认证方式

权限说明

错误码约定

标签稳定 ID 机制（重要）

一、节点管理

1. 创建单个节点

2. 批量创建节点

3. 查询节点列表

4. 获取单个节点

5. 获取子节点

6. 获取所有后代节点

7. 更新节点

8. 删除节点

9. 重新触发工作流

二、向量管理

10. 设置节点向量

11. 删除节点向量

三、边管理

12. 创建边

13. 获取节点的边

14. 删除边

四、标签管理

15. 获取标签列表

16. 创建标签

17. 重命名标签

18. 删除标签

五、搜索

19. 向量相似度搜索

20. 文本搜索

21. Tag 扩展搜索

源码

补充端点

POST /projects/:projectId/kb/ingest

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

POST /projects/:projectId/kb/process

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

OAuth 知识库向量费用（#1495）