# 查询知识库列表

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

分页查询当前调用方可见范围内的知识库，支持按名称关键词模糊搜索。API Key / OpenAPI 调用不传 scope 或传 app 时返回整个应用空间（X-App-Id）内的知识库；传 scope=principal 时，按当前 X-Principal-Id 查询 owner 知识库，并始终限制在当前 X-App-Id 内。用户控制台调用返回该用户自己创建的知识库，不受当前所在应用空间限制。可用 creatorType 按创建来源收窄。返回字段包含知识库 ID、名称、描述、文档数、创建时间、创建来源等摘要信息，不包含文档明细。适用于知识库管理页主列表展示。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentId | integer | 否 | 智能体ID（可选，传入后返回每条 enabled） |
| includeAgentGranted | boolean | 否 | 是否合并当前用户创建智能体所获的应用空间授权只读知识库 |
| keyword | string | 否 | 搜索关键词（匹配创建时登记的知识库名称，内核改名后需等同步） |
| creatorType | string | 否 | 创建来源过滤，可选值：user/apikey/app |
| scope | string | 否 | 查询范围，可选值：app/principal；principal 按当前 X-App-Id 和 X-Principal-Id 查询 |
| page | integer | 否 | 页码，从1开始 |
| pageSize | integer | 否 | 每页条数，取值范围1~100 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | PageResultKnowledgeLibraryItemVO | 响应数据 |
|     items | array | 数据列表 |
|         libraryId | integer | 知识库ID |
|         name | string | 知识库名称 |
|         description | string | 知识库描述 |
|         documentCount | integer | 知识库下的文档数 |
|         createdAt | string | 创建时间 |
|         enabled | boolean | 当前查询的智能体是否启用了该库（仅传入 agentId 时有意义） |
|         creatorType | string | 创建来源，可选值：user-用户在控制台创建、apikey-通过 API Key 创建、app-应用自身创建 |
|         creatorId | integer | 创建者ID，口径随 creatorType 变化：user 为用户ID、apikey 为 API Key 记录ID、app 为应用ID |
|         appId | integer | 该知识库所属的应用空间ID |
|         appName | string | 所属应用空间名称；应用记录缺失时为空，客户端应以 appId 回退 |
|         inCurrentApp | boolean | 该知识库是否归属当前请求所在的应用空间；由后端按 appId 判定 |
|         accessMode | string | 访问模式：owner-本人创建库，agent_granted-当前智能体的应用空间授权只读库 |
|         readOnly | boolean | 是否只读；true 时仅允许文档列表、摘要树和下载 |
|         grantingAgentId | integer | 授予只读访问的当前智能体ID；accessMode=agent_granted 时存在 |
|     total | integer | 总记录数 |
|     page | integer | 当前页码，从1开始 |
|     pageSize | integer | 每页大小 |
|     totalPages | integer | - |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |