<span id="知识库定义引用和导出统计公共说明"></span>

# Knowledge base definitions, references, and export statistics

Importing knowledge base definitions, importing entries into existing knowledge bases, processing source files, and task statistics are separate operations. Confirm target, request shape, and result before proceeding.

<span id="身份与变量"></span>

## Identity and variables

Use a personal access token, `WORKSPACE_ID`, and model creation/read, agent-list, or export-statistics privileges for the target workspace. `MODEL_ID` is a positive integer knowledge base ID; paths accept its decimal string. Short-lived task identities still require server validation. Never reuse authorization or resources across environments.

Batch definition examples read a JSON array from the path in `MODELS_IMPORT_JSON`, one definition per item. A single-object request creates one object; an array creates in batch. Clients must not unconditionally parse both response shapes identically.

<span id="定义条目与文件分别处理"></span>

## Handle definitions, entries, and files separately

| Operation | Input and result | Does not establish |
| --- | --- | --- |
| POST /semantic-models/import | One definition or nonempty definition array. HTTP 201 returns a new knowledge base or items/total | Files uploaded, sources parsed, indexes completed, or all drawing/chunk history restored. |
| POST /semantic-models/{model_id}/import | Import semantic entries into an existing knowledge base, with options such as append/overwrite and dry_run | Creation of a complete knowledge base. |
| CLI semantic-model import/export/validate | Operate on existing knowledge base entries; export/validate read results | That all three accept JSON input or modify content. |

Definition `tables` is an array of `{db_name, table_names}` objects, each with a nonempty database name and table-name list. `files` is `{file_ids:[...]}`, referencing existing files without file bytes. The service checks dependencies before writing. Batch models/entries are created in one tenant transaction, but unknown outcomes/errors still require rereading. An HTTP error does not always mean nothing was written.

Omitted entry `domain` currently normalizes to `nl2sql`; explicitly set `rag` for RAG entries. `kind`, `key`, and `spec` must match the domain. Example `standard_qa` spec contains question/answer. Table references must match the knowledge base table set. Historically disabled entries may be skipped during import preparation. Full union types, legacy migrations, and per-item overwrite behavior require the semantic-entry specification; these three pages do not replace full nested-field acceptance checks.

Definition import provides no item-level entry receipts or proof of completed parsing/indexing. Save new knowledge base IDs and read definitions, entries, sources, and processing jobs. Current definition fields exclude drawing-specific configuration, vector indexes, and chunk history. This is not complete general backup/recovery.

<span id="引用查询的可见性与分页"></span>

## Reference visibility and pagination

Reference queries first check knowledge base read access, then visible effective agent bindings. They combine workspace/system definitions and workspace overrides before matching references and exclude archived agents in results. This is not a global reference count or substitute for deletion prechecks.

Normal page size defaults to 50; explicit positive integers above 200 are capped at 200. With no visible candidates in the permission projection, an early return may yield `limit` of 0. Follow returned values. Continue solely according to nonempty `next_cursor`; empty/short `items` do not establish completion. Archival filtering occurs after pagination and can produce an empty page with a next cursor.

`NEXT_CURSOR` may be unset initially; later copy the response unchanged. Do not decode, rewrite, or reuse it for another workspace/resource. There is no total. `knowledge_base_count` counts effective knowledge base bindings for one agent, not this resource's global reference count.

<span id="统计范围"></span>

## Statistics scope

Export statistics accept no task ID, pagination, or list filters. They count corresponding current-workspace records excluding lifecycle-not-ready/deleting records. Totals include completed tasks, so pending+running+failed may be below total. Statistics lack each task run's result; read details, files, and target data for operational decisions.

<span id="错误与环境"></span>

## Errors and environments

| Operation | Verified boundary | Handling |
| --- | --- | --- |
| Definition import | Empty request/array, invalid names/sources/entries, dependency/privilege checks, or creation/response exceptions | Inspect HTTP/business codes and retain input. Read again before repeating; do not automatically assume nothing was created. |
| Referencing agents | Knowledge base read precedes listing. Invalid limit/cursor causes parameter errors; distinguish authorization and service unavailability | Retain the same model/workspace. Empty pages do not mean no global references. |
| Export statistics | Workspace/statistics privileges, storage reads, or state-counting failures | Follow actual HTTP/business codes. Empty/error responses do not mean zero tasks. |

Go/Python SDKs and CLI expose all three operations. Regular entry-import methods construct only entries envelopes. Go helpers and CLI lack overwrite/preview options. Python additionally provides `import_entries_raw` for complete objects, so it does not wholly lack this capability. This review changes no implementation or invents CLI parameters.

CLI validate exit0 means the call succeeded only. Explicitly check `valid: true` and handle errors. Current CLI output may omit false valid and retain errors alone; missing valid does not mean validation passed.

Do not reuse workspace, model, file, task, or credential values across environments.
