# 知识库定义、引用和导出统计公共说明

知识库定义导入、向已有知识库导入条目、来源文件处理及任务统计是不同操作。先确认目标、请求形状和结果，再决定后续处理。

## 身份与变量

使用目标工作区个人访问令牌、`WORKSPACE_ID` 与相应模型创建/读取、智能体列表或导出统计权限。`MODEL_ID` 是正整数知识库 ID；API 路径可用该值的十进制字符串。短期任务身份也须由服务端校验，不能跨环境复用授权或资源。

批量定义例子从JSON 数组读取，设置 `MODELS_IMPORT_JSON` 为文件路径；每项是一个定义。单对象请求创建一个对象，数组请求批量创建，不能在客户端无条件按同一种响应形状解析。

## 定义、条目与文件分别处理

| 动作 | 输入与结果 | 不能据此判断 |
| --- | --- | --- |
| POST /semantic-models/import | 一个定义或非空定义数组；HTTP 201 返回新知识库或 items/total | 文件已上传、来源已解析、索引已完成，或图纸/分段历史等所有状态已恢复。 |
| POST /semantic-models/{model_id}/import | 向已有知识库导入语义条目，可有 append/overwrite、dry_run 等选项 | 创建了完整知识库。 |
| CLI semantic-model import/export/validate | 操作已有知识库的条目；export 与 validate 读取结果 | 三个命令都接受 JSON 输入或都修改内容。 |

定义请求中的 `tables` 为 `{db_name, table_names}` 对象数组，每项数据库名非空且表名列表非空；`files` 为 `{file_ids:[...]}`，引用既有文件，不包含文件字节。服务在写入前核对依赖。批次模型与条目创建在同一租户事务中，但结果未知或返回异常时仍需回查，不把任意 HTTP 错误等价为一定未写入。

条目的 `domain` 省略时当前归一化为 `nl2sql`；RAG 条目应显式设为 `rag`。`kind`、`key` 与 `spec` 须符合该领域；示例 `standard_qa` 的 spec 含 question/answer。表引用与知识库表集合要一致；历史停用标记条目在定义导入准备时可被跳过。条目全部联合类型、旧格式迁移与每项覆盖细节另需按现有语义条目规范逐项核对，这些接口三页不代替完整嵌套字段验收。

定义导入响应不提供条目逐项回执，也不证明后续解析/索引完成。保存新知识库 ID，再读取定义、条目、数据源和处理作业。当前定义字段不包含图纸专用配置、向量索引与分段历史；不要把此动作当作通用完整备份恢复。

## 引用查询的可见性与分页

引用查询先检查知识库读取，再读取当前身份可见的智能体有效绑定；合并工作区/系统定义及工作区覆盖后匹配引用，返回时排除归档智能体。它不是全局引用计数或删除前置检查的替代品。

正常分页默认 50，显式正整数超过 200 会取 200；当前权限投影完全没有可见候选时，早返回分支的结果 `limit` 可能为 0。以返回值为准，续页只由非空 `next_cursor` 决定，不因为 `items` 为空或少于页大小而提前停止。归档过滤在分页之后，也可能产生仍有下一游标的空页。

`NEXT_CURSOR` 第一页可不设置，后续从响应读取并保持原值；不能解码改写或移用于其他工作区、资源。响应没有 total，`knowledge_base_count` 是单个智能体的有效知识库绑定数，不是本资源的全局引用总数。

## 统计范围

导出统计没有任务 ID、分页或列表筛选参数。它统计当前工作区对应范围，排除生命周期未就绪或正在删除的记录；总数含已完成任务，因此 pending、running、failed 相加可以小于 total。统计不带每个任务本次运行的结果，操作判断应再读详情、文件和目标数据。

## 错误与环境

| 动作 | 已核对边界 | 处理 |
| --- | --- | --- |
| 定义导入 | 空请求/空数组、名称、来源或条目无效；依赖与权限校验；创建/响应阶段异常 | 读取 HTTP 与业务码，保存原输入，先回查，不能自动按“未创建”重复导入。 |
| 引用智能体 | 知识库读取先于引用列表；无效 limit/cursor 为参数错误，授权及服务不可用分别处理 | 保持同一模型与工作区；空页不代表全局无人引用。 |
| 导出统计 | 工作区/统计权限、存储读取及状态计数异常 | 按实际 HTTP 与业务码处理，不能将空/错误响应作为零任务。 |

Go/Python SDK 与 CLI 均有这些接口三个操作入口。普通条目导入方法只构造 entries 封装；Go 便捷方法与 CLI 未提供覆盖/预演选项。Python 另有 `import_entries_raw` 保留完整对象入口，因此不能写成 Python 完全没有相关能力。本次不修改产品实现或编造 CLI 参数。

CLI 的 validate 退出状态为 0 只说明调用成功，仍须明确检查结果 `valid: true` 并处理 errors。当前 CLI 输出中，false 的 valid 字段可能被省略，只留下 errors；缺少 valid 不能解释为校验通过。

工作区、模型、文件、任务与凭据不跨环境复用。
