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

在当前身份主体下创建一个新的知识库容器。知识库是文档的逻辑分组单位，后续上传的文档需指定归属知识库。名称在同一主体内不强制唯一，但建议保持业务可识别性；删除知识库会级联软删除其下所有文档。

对知识库下所有文档发起语义树重建任务。当文档解析逻辑、提示词模板或LLM 模型升级后，可通过此接口批量重新生成语义树以应用新效果。API Key / OpenAPI 调用可重建整个应用空间（X-App-Id）内的知识库，用户控制台调用可重建该用户自己创建的知识库；越出范围返回 403。重建是异步任务，调用立即返回；过程中文档查询仍可访问旧版语义树。

软删除指定知识库及其下所有文档（设置 deleted_at 时间戳，不物理删除）。API Key / OpenAPI 调用可删除整个应用空间（X-App-Id）内的知识库，用户控制台调用可删除该用户自己创建的知识库；越出范围返回 403。删除后该知识库及其文档不再出现在任何查询接口中，已建立的语义树和向量索引会被异步清理。force=false 且库正被智能体引用时返回 409，data.agents 列出全部引用方（含不在本应用空间的，会带 appName 标注）。该操作不可撤销，调用前请二次确认。

分页查询指定知识库下的文档列表，支持按文件名关键词模糊搜索。API Key / OpenAPI 调用可查整个应用空间（X-App-Id）内的知识库，用户控制台调用可查该用户自己创建的知识库；越出范围返回 403。返回字段包含文档 ID、文件名、文件大小、解析状态、创建时间等摘要，不包含语义树明细。适用于知识库详情页文档列表。

获取指定文档的完整语义树节点结构，包含每个节点的标题、层级、摘要、原文片段引用等。只能读取当前调用方可见范围内的文档：API Key / OpenAPI 调用可读整个应用空间（X-App-Id）内知识库的文档，用户控制台调用可读该用户自己创建的知识库的文档；文档不存在或越出范围均返回 403（两者不可区分，避免泄露文档是否存在）。语义树由 dianjin-agent 内核异步生成，若文档尚处于解析状态会返回空结构；前端应根据状态字段做空态展示。

按 nodeIds 批量提取指定文档语义树节点的原文正文内容。node_id 取自 knowledgeDocumentGetTree 返回的真实节点ID（4位数字，如 0001）；API Key / OpenAPI 调用可读整个应用空间（X-App-Id）内知识库的文档，用户控制台调用可读该用户自己创建的知识库的文档，越出范围返回 403；同时校验文档归属该知识库；单次最多 50 个节点，超限报错；未命中的节点返回 status=not_found 占位。

校验调用方对该文档的访问权限后，生成 OSS 预签名 URL 并以 HTTP 302 重定向到该 URL，由浏览器原生触发下载。API Key / OpenAPI 调用可下载整个应用空间（X-App-Id）内知识库的文档，用户控制台调用可下载该用户自己创建的知识库的文档；文档不存在或越出范围均返回 403（两者不可区分，避免泄露文档是否存在）。预签名 URL 有短期有效期（默认数分钟），过期需重新调用本接口。响应头不附带任何业务数据，请通过 documentId 查询接口获取文件名等元信息。

前端通过 multipart/form-data 直传文件到后端，由后端代为上传至 OSS，返回 ossKey 后调用方再调用 /document/import 或 /document/importTable 进入解析链路。API Key / OpenAPI 调用可向整个应用空间（X-App-Id）内的知识库上传，用户控制台调用可向该用户自己创建的知识库上传；越出范围返回 403。单文件大小上限 100 MB，支持的扩展名：.pdf/.doc/.docx/.txt/.md/.markdown/.jpg/.jpeg/.png/.xlsx/.xls/.csv。

读取已上传的 Excel/CSV 文件的列名和示例数据，作为后续配置导入映射的依据。预分析可能调用模型推断列映射，会产生知识编译用量，但不触发文档导入或语义树生成。新上传文件仅需ossKey，知识库、原始文件名及稳定文档用量身份由后端恢复。兼容显式libraryId/documentUsageId，提供时必须与上传记录一致；fileName不覆盖上传记录。升级前无上传记录的文件启用计费时仍需提供libraryId，或重新上传。表头行号 headerRow 默认 1、数据起始行号 dataStartRow 默认 2，适用于绝大多数标准模板。

将已通过 /document/upload 上传到 OSS 的文件导入指定知识库，触发后台解析与语义树生成流程。入参中的 ossKey 必须由本系统的上传接口返回，不接受外部直传的 OSS 路径。API Key / OpenAPI 调用可导入整个应用空间（X-App-Id）内的知识库，用户控制台调用可导入该用户自己创建的知识库；越出范围返回 403。导入是异步流程，文档解析状态可通过列表接口查询。

将已上传的 Excel/CSV 表格文件按用户配置的列映射规则导入知识库，基于表头行号、数据起始行号、列到语义层级（一/二/三级标题/正文）的映射，生成结构化的语义树。导入前应先通过 /document/parseTableStructure 读取列名作为映射依据。API Key / OpenAPI 调用可导入整个应用空间（X-App-Id）内的知识库，用户控制台调用可导入该用户自己创建的知识库；越出范围返回 403。新上传文件的libraryId、fileName、fileSize、documentUsageId由后端上传记录恢复，客户端可省略；显式知识库或用量身份与记录不符时拒绝。升级前无记录的文件仍兼容原有参数。导入是异步流程。

对单个文档重新生成语义树。当文档解析逻辑或 LLM 模型升级后，可针对个别文档重建以验证新效果，或在文档导入失败后重试。API Key / OpenAPI 调用可重建整个应用空间（X-App-Id）内知识库的文档，用户控制台调用可重建该用户自己创建的知识库的文档；文档不存在或越出范围均返回 403（两者不可区分，避免泄露文档是否存在）。重建是异步任务，调用立即返回；过程中查询接口仍返回旧版语义树。

软删除指定文档（设置 deleted_at 时间戳，不物理删除文件）。API Key / OpenAPI 调用可删除整个应用空间（X-App-Id）内知识库的文档，用户控制台调用可删除该用户自己创建的知识库的文档；文档不存在或越出范围均返回 403（两者不可区分，避免泄露文档是否存在）。文档对应的语义树和向量索引会被异步清理。OSS 上的原始文件保留，便于后续审计追溯；如需彻底清除原文件请联系管理员。

更新知识库的名称和描述。API Key / OpenAPI 调用可更新整个应用空间（X-App-Id）内的知识库，用户控制台调用可更新该用户自己创建的知识库；越出范围返回 403。改名会在本次请求内同步刷新列表搜索用的名称；同步失败时列表仍按旧名可搜，不影响改名本身。