知识库接口
本文介绍知识库相关的 8 个接口。以目录和页面组成的树组织心智模型,支持异步创建页面、混合搜索和 Markdown 导出。
调用说明
- 接入地址:
https://cloud.memory.bj.baidubce.com/api,下文路径直接拼接在该地址后。
- 请求头:
Authorization: Bearer <token> 必填;有 JSON 请求体时需携带 Content-Type: application/json。
- 错误码、异步操作和
operationId 的说明见 API 简介。
接口列表
| 接口 |
方法 |
路径 |
| 导出知识库 |
GET |
/v1/default/banks/{bank_id}/knowledge-base/export |
| 创建知识库目录 |
POST |
/v1/default/banks/{bank_id}/knowledge-base/folders |
| 更新知识库节点 |
PATCH |
/v1/default/banks/{bank_id}/knowledge-base/nodes/{node_id} |
| 删除知识库节点 |
DELETE |
/v1/default/banks/{bank_id}/knowledge-base/nodes/{node_id} |
| 创建知识库页面 |
POST |
/v1/default/banks/{bank_id}/knowledge-base/pages |
| 读取知识库页面 |
GET |
/v1/default/banks/{bank_id}/knowledge-base/pages/{page_id} |
| 搜索知识库页面 |
GET |
/v1/default/banks/{bank_id}/knowledge-base/search |
| 获取知识库树 |
GET |
/v1/default/banks/{bank_id}/knowledge-base/tree |
导出知识库
GET /v1/default/banks/{bank_id}/knowledge-base/export
返回可移植的 Markdown bundle:嵌套的 index.md、每个页面一个 .md,以及历史日志。
参数
| 名称 |
In |
类型 |
必填 |
说明 |
bank_id |
path |
string |
是 |
Bank 的唯一标识符。 |
请求头
| 名称 |
In |
类型 |
必填 |
说明 |
Authorization |
header |
string |
是 |
Bearer token。 |
响应
- 状态码:
200 — 成功响应
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
files |
array<KnowledgePageBundleFile> |
是 |
文件列表。 |
files[] · KnowledgePageBundleFile
数据结构 KnowledgePageBundleFile:
| 字段 |
类型 |
必填 |
说明 |
path |
string |
是 |
资源路径。 |
content |
string |
是 |
资源的正文内容;对 directive/page 等资源含其可编辑文本。 |
响应示例
1{
2 "files": [
3 {
4 "path": "string",
5 "content": "string"
6 }
7 ]
8}
响应
- 状态码:
422 — 校验错误
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
detail |
array<ValidationError> |
否 |
详细信息或校验错误列表。 |
detail[] · ValidationError
数据结构 ValidationError:
| 字段 |
类型 |
必填 |
说明 |
loc |
array<string \| integer> |
是 |
发生校验错误的位置路径;数组元素可以是字段名或索引。 |
msg |
string |
是 |
错误消息或状态消息。 |
type |
string |
是 |
对象或错误的类型。 |
input |
any |
否 |
触发校验的原始输入值。 |
ctx |
Context |
否 |
错误上下文信息。 |
响应示例
1{
2 "detail": [
3 {
4 "loc": [],
5 "msg": "string",
6 "type": "string",
7 "input": null,
8 "ctx": {}
9 }
10 ]
11}
operationId=export_knowledge_base
创建知识库目录
POST /v1/default/banks/{bank_id}/knowledge-base/folders
创建文件夹,可选择嵌套在父文件夹下。
参数
| 名称 |
In |
类型 |
必填 |
说明 |
bank_id |
path |
string |
是 |
Bank 的唯一标识符。 |
请求头
| 名称 |
In |
类型 |
必填 |
说明 |
Authorization |
header |
string |
是 |
Bearer token。 |
Content-Type |
header |
string |
是 |
固定application/json |
请求体
| 字段 |
类型 |
必填 |
说明 |
name |
string |
是 |
名称。 |
parent_id |
string? |
否 |
父节点的唯一标识符。 |
请求示例
1{
2 "name": "string",
3 "parent_id": "string"
4}
响应
- 状态码:
201 — 成功响应
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
id |
string |
是 |
资源的唯一标识符。 |
kind |
"folder" \| "page" |
是 |
节点类型:folder 或 page。 |
name |
string |
是 |
名称。 |
parent_id |
string? |
否 |
父节点的唯一标识符。 |
mental_model_id |
string? |
否 |
作为页面内容来源的 mental model ID(仅 page)。 |
managed |
boolean |
否 |
Client-set flag: true = system-owned, false = hand-authored;默认值:false |
description |
string? |
否 |
页面的 source query(即页面description)。 |
tags |
array<string> |
否 |
默认值:[] |
timestamp |
string? |
否 |
page 的最近刷新时间,或 folder 的最近更新时间。 |
is_stale |
boolean? |
否 |
仅适用于 page:scope 内存在比上次刷新更新的 memories(内容不同步)时为 true。由 tree 接口填充。 |
children |
array<KnowledgeNode> |
否 |
默认值:[] |
children[] · KnowledgeNode
数据结构 KnowledgeNode:
| 字段 |
类型 |
必填 |
说明 |
id |
string |
是 |
资源的唯一标识符。 |
kind |
"folder" \| "page" |
是 |
节点类型:folder 或 page。 |
name |
string |
是 |
名称。 |
parent_id |
string? |
否 |
父节点的唯一标识符。 |
mental_model_id |
string? |
否 |
作为页面内容来源的 mental model ID(仅 page)。 |
managed |
boolean |
否 |
Client-set flag: true = system-owned, false = hand-authored;默认值:false |
description |
string? |
否 |
页面的 source query(即页面description)。 |
tags |
array<string> |
否 |
默认值:[] |
timestamp |
string? |
否 |
page 的最近刷新时间,或 folder 的最近更新时间。 |
is_stale |
boolean? |
否 |
仅适用于 page:scope 内存在比上次刷新更新的 memories(内容不同步)时为 true。由 tree 接口填充。 |
children |
array<KnowledgeNode> |
否 |
默认值:[] |
嵌套 children[] → KnowledgeNode(已展开过,跳过)
响应示例
1{
2 "id": "string",
3 "kind": "folder",
4 "name": "string",
5 "parent_id": "string",
6 "mental_model_id": "string",
7 "managed": false,
8 "description": "string",
9 "tags": [],
10 "timestamp": "string",
11 "is_stale": false,
12 "children": []
13}
响应
- 状态码:
422 — 校验错误
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
detail |
array<ValidationError> |
否 |
详细信息或校验错误列表。 |
detail[] · ValidationError
数据结构 ValidationError:
| 字段 |
类型 |
必填 |
说明 |
loc |
array<string \| integer> |
是 |
发生校验错误的位置路径;数组元素可以是字段名或索引。 |
msg |
string |
是 |
错误消息或状态消息。 |
type |
string |
是 |
对象或错误的类型。 |
input |
any |
否 |
触发校验的原始输入值。 |
ctx |
Context |
否 |
错误上下文信息。 |
响应示例
1{
2 "detail": [
3 {
4 "loc": [],
5 "msg": "string",
6 "type": "string",
7 "input": null,
8 "ctx": {}
9 }
10 ]
11}
operationId=create_knowledge_folder
更新知识库节点
PATCH /v1/default/banks/{bank_id}/knowledge-base/nodes/{node_id}
重命名节点(设置 name)、将其移动到其他文件夹下(设置 parent_id,根节点使用 null),和/或更新页面选项(source_query、tags、max_tokens)。修改 source_query 会安排异步 refresh,使页面基于新问题重新构建。
参数
| 名称 |
In |
类型 |
必填 |
说明 |
bank_id |
path |
string |
是 |
Bank 的唯一标识符。 |
node_id |
path |
string |
是 |
节点的唯一 ID。 |
请求头
| 名称 |
In |
类型 |
必填 |
说明 |
Authorization |
header |
string |
是 |
Bearer token。 |
Content-Type |
header |
string |
是 |
固定application/json |
请求体
| 字段 |
类型 |
必填 |
说明 |
name |
string? |
否 |
名称。 |
parent_id |
string? |
否 |
父节点的唯一标识符。 |
source_query |
string? |
否 |
生成或刷新内容所使用的源查询。 |
tags |
array<string>? |
否 |
标签列表。 |
max_tokens |
integer? |
否 |
最大 token 数。 |
请求示例
1{
2 "name": "string",
3 "parent_id": "string",
4 "source_query": "string",
5 "tags": [
6 "string"
7 ],
8 "max_tokens": 0
9}
响应
- 状态码:
200 — 成功响应
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
id |
string |
是 |
资源的唯一标识符。 |
kind |
"folder" \| "page" |
是 |
节点类型:folder 或 page。 |
name |
string |
是 |
名称。 |
parent_id |
string? |
否 |
父节点的唯一标识符。 |
mental_model_id |
string? |
否 |
作为页面内容来源的 mental model ID(仅 page)。 |
managed |
boolean |
否 |
Client-set flag: true = system-owned, false = hand-authored;默认值:false |
description |
string? |
否 |
页面的 source query(即页面description)。 |
tags |
array<string> |
否 |
默认值:[] |
timestamp |
string? |
否 |
page 的最近刷新时间,或 folder 的最近更新时间。 |
is_stale |
boolean? |
否 |
仅适用于 page:scope 内存在比上次刷新更新的 memories(内容不同步)时为 true。由 tree 接口填充。 |
children |
array<KnowledgeNode> |
否 |
默认值:[] |
children[] · KnowledgeNode
数据结构 KnowledgeNode:
| 字段 |
类型 |
必填 |
说明 |
id |
string |
是 |
资源的唯一标识符。 |
kind |
"folder" \| "page" |
是 |
节点类型:folder 或 page。 |
name |
string |
是 |
名称。 |
parent_id |
string? |
否 |
父节点的唯一标识符。 |
mental_model_id |
string? |
否 |
作为页面内容来源的 mental model ID(仅 page)。 |
managed |
boolean |
否 |
Client-set flag: true = system-owned, false = hand-authored;默认值:false |
description |
string? |
否 |
页面的 source query(即页面description)。 |
tags |
array<string> |
否 |
默认值:[] |
timestamp |
string? |
否 |
page 的最近刷新时间,或 folder 的最近更新时间。 |
is_stale |
boolean? |
否 |
仅适用于 page:scope 内存在比上次刷新更新的 memories(内容不同步)时为 true。由 tree 接口填充。 |
children |
array<KnowledgeNode> |
否 |
默认值:[] |
嵌套 children[] → KnowledgeNode(已展开过,跳过)
响应示例
1{
2 "id": "string",
3 "kind": "folder",
4 "name": "string",
5 "parent_id": "string",
6 "mental_model_id": "string",
7 "managed": false,
8 "description": "string",
9 "tags": [],
10 "timestamp": "string",
11 "is_stale": false,
12 "children": []
13}
响应
- 状态码:
422 — 校验错误
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
detail |
array<ValidationError> |
否 |
详细信息或校验错误列表。 |
detail[] · ValidationError
数据结构 ValidationError:
| 字段 |
类型 |
必填 |
说明 |
loc |
array<string \| integer> |
是 |
发生校验错误的位置路径;数组元素可以是字段名或索引。 |
msg |
string |
是 |
错误消息或状态消息。 |
type |
string |
是 |
对象或错误的类型。 |
input |
any |
否 |
触发校验的原始输入值。 |
ctx |
Context |
否 |
错误上下文信息。 |
响应示例
1{
2 "detail": [
3 {
4 "loc": [],
5 "msg": "string",
6 "type": "string",
7 "input": null,
8 "ctx": {}
9 }
10 ]
11}
operationId=update_knowledge_node
删除知识库节点
DELETE /v1/default/banks/{bank_id}/knowledge-base/nodes/{node_id}
删除文件夹或页面及其整个子树(页面对应的 mental models 也会删除)。
参数
| 名称 |
In |
类型 |
必填 |
说明 |
bank_id |
path |
string |
是 |
Bank 的唯一标识符。 |
node_id |
path |
string |
是 |
节点的唯一 ID。 |
请求头
| 名称 |
In |
类型 |
必填 |
说明 |
Authorization |
header |
string |
是 |
Bearer token。 |
响应
- 状态码:
200 — 成功响应
- 格式:
application/json
无展开字段(标量、自由 object 或未声明 properties)
响应
- 状态码:
422 — 校验错误
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
detail |
array<ValidationError> |
否 |
详细信息或校验错误列表。 |
detail[] · ValidationError
数据结构 ValidationError:
| 字段 |
类型 |
必填 |
说明 |
loc |
array<string \| integer> |
是 |
发生校验错误的位置路径;数组元素可以是字段名或索引。 |
msg |
string |
是 |
错误消息或状态消息。 |
type |
string |
是 |
对象或错误的类型。 |
input |
any |
否 |
触发校验的原始输入值。 |
ctx |
Context |
否 |
错误上下文信息。 |
响应示例
1{
2 "detail": [
3 {
4 "loc": [],
5 "msg": "string",
6 "type": "string",
7 "input": null,
8 "ctx": {}
9 }
10 ]
11}
operationId=delete_knowledge_node
创建知识库页面
POST /v1/default/banks/{bank_id}/knowledge-base/pages
创建页面(一个 mental model 加一个树节点)。内容异步生成;使用返回的 operation_id 跟踪完成状态。
参数
| 名称 |
In |
类型 |
必填 |
说明 |
bank_id |
path |
string |
是 |
Bank 的唯一标识符。 |
请求头
| 名称 |
In |
类型 |
必填 |
说明 |
Authorization |
header |
string |
是 |
Bearer token。 |
Content-Type |
header |
string |
是 |
固定application/json |
请求体
| 字段 |
类型 |
必填 |
说明 |
name |
string |
是 |
名称。 |
source_query |
string |
是 |
生成或刷新 mental model/page 内容时使用的查询。 |
parent_id |
string? |
否 |
父节点的唯一标识符。 |
tags |
array<string>? |
否 |
标签列表。 |
max_tokens |
integer? |
否 |
最大 token 数。 |
trigger |
MentalModelTrigger-Input? |
否 |
触发方式或触发配置。 |
trigger · MentalModelTrigger-Input
数据结构 MentalModelTrigger-Input:
| 字段 |
类型 |
必填 |
说明 |
mode |
"full" \| "delta" |
否 |
刷新模式。full(默认)每次刷新都从头生成 mental model 内容;delta 在现有内容上进行局部编辑,逐字节保留未变化的章节,移除过时内容并加入新内容。如果 mental model 尚无内容,或 source_query 自上次刷新后发生变化,delta 会自动回退为完整生成;默认值:"full" |
response_schema |
object? |
否 |
用于结构化输出的可选 JSON Schema。设置后,每次刷新都会执行与 Reflectresponse_schema 相同的结构化抽取,并将解析结果存入 reflect_response.structured_output,同时保留 Markdown 内容。 |
keep_trace |
boolean |
否 |
为 true 时,记录 mental model 每次刷新的执行 trace,便于诊断定时或 consolidation 触发的刷新。仅保留最近一次 trace;工具输出会缩减为结果数量,以限制存储规模;默认值:false |
refresh_after_consolidation |
boolean |
否 |
为 true 时,在 observations consolidation 后刷新此 mental model(实时模式);默认值:false |
refresh_cron |
string? |
否 |
用于按固定计划刷新此 mental model 的 cron 表达式(UTC,标准 5 字段语法,例如0 3 * * * 表示每天 UTC 03:00)。与 refresh_after_consolidation 互斥:model 只能在 consolidation 后刷新或按 cron 刷新,不能同时启用。计划刷新仅在 model 已过期时执行(自上次刷新后 scope 内出现新 memories);没有变化时跳过,避免浪费 LLM 调用。null 表示不设置计划。 |
fact_types |
array<"world" \| "experience" \| "observation">? |
否 |
筛选 Reflect 时检索的 fact type。null 表示全部类型(world、experience、observation)。 |
exclude_mental_models |
boolean |
否 |
为 true 时,从 Reflect 循环中排除所有 mental models(跳过 search_mental_models 工具);默认值:false |
exclude_mental_model_ids |
array<string>? |
否 |
按 ID 从 Reflect 循环中排除指定 mental models。 |
tags_match |
"any" \| "all" \| "any_strict" \| "all_strict" \| "exact"? |
否 |
覆盖 refresh 时 model tags 筛选 memories 的方式。未设置时,有 tags 的 model 默认为 all_strict(用于安全隔离),无 tags 的 model 默认为 any。设置为 any 可在 refresh 时同时包含无标签和有标签 memories。 |
tag_groups |
array<TagGroupLeaf \| TagGroupAnd-Input \| TagGroupOr-Input \| TagGroupNot-Input>? |
否 |
Refresh 时使用的复合布尔 tag 表达式,用于替代 model 自身的 tags。设置后,这些 tag groups 会传给 Reflect,model 的扁平 tags 不再用于筛选。支持嵌套 and/or/not 表达式,以实现复杂的 tag scope。 |
include_chunks |
boolean? |
否 |
覆盖 refresh 内部 Recall 是否返回原始 chunk 文本。null 表示使用 Bank/全局 配置默认值(recall_include_chunks)。 |
recall_max_tokens |
integer? |
否 |
覆盖 refresh 内部 Recall 返回 facts 的 token budget。null 表示使用 Bank/全局 配置默认值(recall_max_tokens)。 |
recall_chunks_max_tokens |
integer? |
否 |
覆盖 refresh 内部 Recall 返回原始 chunks 的 token budget。null 表示使用 Bank/全局 配置默认值(recall_chunks_max_tokens)。 |
请求示例
1{
2 "name": "string",
3 "source_query": "string",
4 "parent_id": "string",
5 "tags": [
6 "string"
7 ],
8 "max_tokens": 0,
9 "trigger": {
10 "mode": "full",
11 "refresh_after_consolidation": false,
12 "refresh_cron": "string",
13 "fact_types": [
14 "world"
15 ],
16 "exclude_mental_models": false,
17 "exclude_mental_model_ids": [
18 "string"
19 ],
20 "tags_match": "any",
21 "tag_groups": [],
22 "include_chunks": false,
23 "recall_max_tokens": 0,
24 "recall_chunks_max_tokens": 0
25 }
26}
响应
- 状态码:
201 — 成功响应
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
page_id |
string |
是 |
页面的唯一标识符。 |
mental_model_id |
string |
是 |
Mental model 的唯一标识符。 |
operation_id |
string? |
否 |
异步操作 的唯一标识符。 |
响应示例
1{
2 "page_id": "string",
3 "mental_model_id": "string",
4 "operation_id": "string"
5}
响应
- 状态码:
422 — 校验错误
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
detail |
array<ValidationError> |
否 |
详细信息或校验错误列表。 |
detail[] · ValidationError
数据结构 ValidationError:
| 字段 |
类型 |
必填 |
说明 |
loc |
array<string \| integer> |
是 |
发生校验错误的位置路径;数组元素可以是字段名或索引。 |
msg |
string |
是 |
错误消息或状态消息。 |
type |
string |
是 |
对象或错误的类型。 |
input |
any |
否 |
触发校验的原始输入值。 |
ctx |
Context |
否 |
错误上下文信息。 |
响应示例
1{
2 "detail": [
3 {
4 "loc": [],
5 "msg": "string",
6 "type": "string",
7 "input": null,
8 "ctx": {}
9 }
10 ]
11}
operationId=create_knowledge_page
读取知识库页面
GET /v1/default/banks/{bank_id}/knowledge-base/pages/{page_id}
以 Markdown 文档(frontmatter + Markdown 正文)返回单个页面。
参数
| 名称 |
In |
类型 |
必填 |
说明 |
bank_id |
path |
string |
是 |
Bank 的唯一标识符。 |
page_id |
path |
string |
是 |
Page 的唯一 ID。 |
请求头
| 名称 |
In |
类型 |
必填 |
说明 |
Authorization |
header |
string |
是 |
Bearer token。 |
响应
- 状态码:
200 — 成功响应
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
id |
string |
是 |
资源的唯一标识符。 |
name |
string |
是 |
名称。 |
type |
string |
是 |
Page type;优先取 type: tag,否则为 knowledge-page。 |
description |
string? |
否 |
用于重建页面的 source query。 |
tags |
array<string> |
否 |
默认值:[] |
timestamp |
string? |
否 |
最近刷新时间;没有刷新记录时回退到创建时间。 |
body |
string? |
否 |
页面合成后的 Markdown 正文。 |
markdown |
string |
是 |
完整 Markdown 文档:YAML frontmatter + Markdown 正文。 |
响应示例
1{
2 "id": "string",
3 "name": "string",
4 "type": "string",
5 "markdown": "string",
6 "description": "string",
7 "tags": [],
8 "timestamp": "string",
9 "body": "string"
10}
响应
- 状态码:
422 — 校验错误
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
detail |
array<ValidationError> |
否 |
详细信息或校验错误列表。 |
detail[] · ValidationError
数据结构 ValidationError:
| 字段 |
类型 |
必填 |
说明 |
loc |
array<string \| integer> |
是 |
发生校验错误的位置路径;数组元素可以是字段名或索引。 |
msg |
string |
是 |
错误消息或状态消息。 |
type |
string |
是 |
对象或错误的类型。 |
input |
any |
否 |
触发校验的原始输入值。 |
ctx |
Context |
否 |
错误上下文信息。 |
响应示例
1{
2 "detail": [
3 {
4 "loc": [],
5 "msg": "string",
6 "type": "string",
7 "input": null,
8 "ctx": {}
9 }
10 ]
11}
operationId=get_knowledge_page
搜索知识库页面
GET /v1/default/banks/{bank_id}/knowledge-base/search
在 Bank knowledge pages 上执行 document 级混合搜索:融合 full-text(BM25)匹配和向量相似度匹配,使用 Reciprocal-Rank-Fusion 合并结果。不使用 reranker,以降低延迟。
参数
| 名称 |
In |
类型 |
必填 |
说明 |
bank_id |
path |
string |
是 |
Bank 的唯一标识符。 |
q |
query |
string |
是 |
搜索查询;minLen1 |
limit |
query |
integer |
否 |
返回结果的最大数量;默认值:10;取值范围:1–50 |
请求头
| 名称 |
In |
类型 |
必填 |
说明 |
Authorization |
header |
string |
是 |
Bearer token。 |
响应
- 状态码:
200 — 成功响应
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
results |
array<KnowledgePageSearchResult> |
是 |
结果列表。 |
total |
integer |
是 |
总数量。 |
results[] · KnowledgePageSearchResult
数据结构 KnowledgePageSearchResult:
| 字段 |
类型 |
必填 |
说明 |
id |
string |
是 |
资源的唯一标识符。 |
name |
string |
是 |
名称。 |
mental_model_id |
string? |
否 |
Mental model 的唯一标识符。 |
snippet |
string |
是 |
匹配内容摘要。 |
score |
number |
是 |
匹配或排序得分。 |
updated_at |
string? |
否 |
最后更新时间。 |
响应示例
1{
2 "results": [
3 {
4 "id": "string",
5 "name": "string",
6 "snippet": "string",
7 "score": 0,
8 "mental_model_id": "string",
9 "updated_at": "string"
10 }
11 ],
12 "total": 0
13}
响应
- 状态码:
422 — 校验错误
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
detail |
array<ValidationError> |
否 |
详细信息或校验错误列表。 |
detail[] · ValidationError
数据结构 ValidationError:
| 字段 |
类型 |
必填 |
说明 |
loc |
array<string \| integer> |
是 |
发生校验错误的位置路径;数组元素可以是字段名或索引。 |
msg |
string |
是 |
错误消息或状态消息。 |
type |
string |
是 |
对象或错误的类型。 |
input |
any |
否 |
触发校验的原始输入值。 |
ctx |
Context |
否 |
错误上下文信息。 |
响应示例
1{
2 "detail": [
3 {
4 "loc": [],
5 "msg": "string",
6 "type": "string",
7 "input": null,
8 "ctx": {}
9 }
10 ]
11}
operationId=search_knowledge_base
获取知识库树
GET /v1/default/banks/{bank_id}/knowledge-base/tree
以嵌套的文件夹和页面树返回 knowledge base。
参数
| 名称 |
In |
类型 |
必填 |
说明 |
bank_id |
path |
string |
是 |
Bank 的唯一标识符。 |
请求头
| 名称 |
In |
类型 |
必填 |
说明 |
Authorization |
header |
string |
是 |
Bearer token。 |
响应
- 状态码:
200 — 成功响应
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
roots |
array<KnowledgeNode> |
是 |
树的根节点列表。 |
roots[] · KnowledgeNode
数据结构 KnowledgeNode:
| 字段 |
类型 |
必填 |
说明 |
id |
string |
是 |
资源的唯一标识符。 |
kind |
"folder" \| "page" |
是 |
节点类型:folder 或 page。 |
name |
string |
是 |
名称。 |
parent_id |
string? |
否 |
父节点的唯一标识符。 |
mental_model_id |
string? |
否 |
作为页面内容来源的 mental model ID(仅 page)。 |
managed |
boolean |
否 |
Client-set flag: true = system-owned, false = hand-authored;默认值:false |
description |
string? |
否 |
页面的 source query(即页面description)。 |
tags |
array<string> |
否 |
默认值:[] |
timestamp |
string? |
否 |
page 的最近刷新时间,或 folder 的最近更新时间。 |
is_stale |
boolean? |
否 |
仅适用于 page:scope 内存在比上次刷新更新的 memories(内容不同步)时为 true。由 tree 接口填充。 |
children |
array<KnowledgeNode> |
否 |
默认值:[] |
嵌套 children[] → KnowledgeNode(已展开过,跳过)
响应示例
1{
2 "roots": [
3 {
4 "id": "string",
5 "kind": "folder",
6 "name": "string",
7 "parent_id": "string",
8 "mental_model_id": "string",
9 "managed": false,
10 "description": "string",
11 "tags": [],
12 "timestamp": "string",
13 "is_stale": false,
14 "children": []
15 }
16 ]
17}
响应
- 状态码:
422 — 校验错误
- 格式:
application/json
| 字段 |
类型 |
必填 |
说明 |
detail |
array<ValidationError> |
否 |
详细信息或校验错误列表。 |
detail[] · ValidationError
数据结构 ValidationError:
| 字段 |
类型 |
必填 |
说明 |
loc |
array<string \| integer> |
是 |
发生校验错误的位置路径;数组元素可以是字段名或索引。 |
msg |
string |
是 |
错误消息或状态消息。 |
type |
string |
是 |
对象或错误的类型。 |
input |
any |
否 |
触发校验的原始输入值。 |
ctx |
Context |
否 |
错误上下文信息。 |
响应示例
1{
2 "detail": [
3 {
4 "loc": [],
5 "msg": "string",
6 "type": "string",
7 "input": null,
8 "ctx": {}
9 }
10 ]
11}
operationId=get_knowledge_base_tree