diff --git a/CHANGELOG.md b/CHANGELOG.md index 98f392884..4b14ba890 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and [中文版](CHANGELOG.zh.md) · [README](README.md) · [Contributing](CONTRIBUTING.md) +## [1.17.1] - 2026-08-22 + +### Fixed + +- **`knowledge create` now requires `--description`** — aligns with the server's required-description validation: the new `--description` flag is mandatory and its 1-500 character limit is checked locally before the request goes out. `bl knowledge create` / `kscli kb create` calls need to pass it. +- **`knowledge service update` warned about config fields the server itself returned** — updating the draft config through scalar flags such as `--policy` reads the full draft and merges before writing back; the draft's `user_system_prompt`, `anti_leak_prompt`, `refusal_prompt`, `credibility_prompt`, `session_file_parse_mode`, and `enable_thinking` / `enable_temperature` / `enable_credibility` / `enable_max_completion_tokens` were not recognized by the CLI, so every update printed a run of `unknown agent_config field passed through` warnings. The config itself was always written correctly; the spurious warnings are gone. + +### Added + +- **`bailian-web-search` routing skill** — `bl skill init` now also installs a dedicated web-search routing skill, so agents pick the right search entry point instead of guessing. +- **Knowledge Studio CLI command manual** — full `kscli` reference docs covering knowledge bases, documents, chunks, collections/categories, files, retrieval/Q&A services, and search/chat, with runnable examples for every command. + +### Changed + +- **Description flags explain what to write** — help text for the collection and service `--description` flags now states what the field is for (telling similar items apart in lists; for services, agents read it to pick the right one) rather than just repeating "required". +- **`knowledge retrieve --rerank-model` documents its precondition** — help now states that the target knowledge base must already have a rerank model configured, otherwise every value is rejected. + ## [1.17.0] - 2026-08-18 ### Added diff --git a/CHANGELOG.zh.md b/CHANGELOG.zh.md index 31a7d0124..4fb5c45b4 100644 --- a/CHANGELOG.zh.md +++ b/CHANGELOG.zh.md @@ -6,6 +6,23 @@ [English](CHANGELOG.md) · [README](README.zh.md) · [参与贡献](CONTRIBUTING.zh.md) +## [1.17.1] - 2026-08-22 + +### 修复 + +- **`knowledge create` 的 `--description` 更新为必填** —— 对齐服务端对知识库描述的必填校验：新增 `--description` 参数并设为必填，在发出请求前于本地校验 1–500 个字符的长度限制。`bl knowledge create` / `kscli kb create` 调用需带上该参数。 +- **`knowledge service update` 对服务端自己返回的配置字段误报警告** —— 通过 `--policy` 等标量参数更新草稿配置时，CLI 会先读取完整草稿再合并回写；草稿中的 `user_system_prompt`、`anti_leak_prompt`、`refusal_prompt`、`credibility_prompt`、`session_file_parse_mode` 以及 `enable_thinking` / `enable_temperature` / `enable_credibility` / `enable_max_completion_tokens` 此前不被 CLI 识别，导致每次更新都刷出一串 `unknown agent_config field passed through` 警告。配置本身始终被正确写入，现在不再误报。 + +### 新增 + +- **`bailian-web-search` 路由技能** —— `bl skill init` 现在会一并安装专门的联网搜索路由技能，让 agent 直接选中正确的搜索入口，不再靠猜。 +- **Knowledge Studio CLI 命令手册** —— 完整的 `kscli` 参考文档，覆盖知识库、文档、切片、集合/类目、文件、检索/问答服务以及 search/chat，每条命令均附可运行示例。 + +### 变更 + +- **描述类参数说明写清该填什么** —— 数据集合与服务的 `--description` 帮助文案现在会说明该字段的用途（在列表中区分同类项；服务描述供 agent 判断该调用哪个服务），不再只是重复「必填」。 +- **`knowledge retrieve --rerank-model` 补充前置条件说明** —— 帮助文案现在会说明目标知识库必须已配置重排序模型，否则任何取值都会被拒绝。 + ## [1.17.0] - 2026-08-18 ### 新增 diff --git a/docs/knowledge/kb.md b/docs/knowledge/kb.md index 25fcf5e1e..83fc10e5d 100644 --- a/docs/knowledge/kb.md +++ b/docs/knowledge/kb.md @@ -128,7 +128,7 @@ bl knowledge info --index-id idx-xxx --workspace-id ws-xxx **用法** ```bash -bl knowledge create --name (--doc-id | --category-id ) [flags] +bl knowledge create --name --description (--doc-id | --category-id ) [flags] ``` **参数** @@ -136,6 +136,7 @@ bl knowledge create --name (--doc-id | --category-id ) [flags] | 参数 | 类型 | 必填 | 说明 | | --------------------------- | ------ | ---- | -------------------------------------------------------- | | `--name ` | string | 是 | 知识库名称（1-20 字符，工作区内唯一） | +| `--description ` | string | 是 | 知识库装了什么内容、给谁用（1-500 字符） | | `--doc-id ` | array | 否¹ | 数据中心文件 ID（可重复）；与 `--category-id` 互斥 | | `--category-id ` | array | 否¹ | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 | | `--embedding-model ` | string | 否 | 向量模型名称（默认：`text-embedding-v4`） | @@ -148,6 +149,7 @@ bl knowledge create --name (--doc-id | --category-id ) [flags] **参数约束** - `--name` 长度 1-20 字符 +- `--description` 长度 1-500 字符，缺失或超长会在本地被拦截 - `--doc-id` 和 `--category-id` 互斥，必须提供其一 **输出** @@ -176,13 +178,13 @@ json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和 ```bash # 从指定文件创建知识库 -bl knowledge create --name demo --doc-id file-xxx --workspace-id ws-xxx +bl knowledge create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx # 从分类导入并等待导入完成 -bl knowledge create --name demo --category-id cate-xxx --wait +bl knowledge create --name demo --description '产品文档' --category-id cate-xxx --wait # 指定向量模型和切片大小 -bl knowledge create --name my-kb --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx +bl knowledge create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx ``` --- diff --git a/docs/knowledge/knowledge-cli-guide.md b/docs/knowledge/knowledge-cli-guide.md index 04ae6394f..5080938ff 100644 --- a/docs/knowledge/knowledge-cli-guide.md +++ b/docs/knowledge/knowledge-cli-guide.md @@ -153,7 +153,7 @@ bl knowledge doc upload --file ./docs/intro.md --workspace-id ws-xxx # → 返回 file-id # 2. 用文件创建知识库 -bl knowledge create --name my-kb --doc-id file-xxx --workspace-id ws-xxx --wait +bl knowledge create --name my-kb --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx --wait # → 返回 index-id (pipelineId) 和导入任务状态 # 3. 创建检索服务（search 场景） @@ -245,7 +245,7 @@ bl knowledge doc import-oss \ # → 返回各文件的 fileId # 2. 创建知识库并导入这些文件 -bl knowledge create --name oss-kb --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait +bl knowledge create --name oss-kb --description 'OSS 导入文档' --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait # 3. 检索 bl knowledge search --query "相关内容" --agent-id aid-xxx --workspace-id ws-xxx diff --git a/docs/knowledge/service.md b/docs/knowledge/service.md index d0d06372c..a4cb2d61d 100644 --- a/docs/knowledge/service.md +++ b/docs/knowledge/service.md @@ -142,14 +142,14 @@ bl knowledge service create --name --scene [flags] | ------------------------ | ------ | ---- | ------------------------------------------------- | | `--name ` | string | 是 | 服务名称（最多 200 字符，同一场景下工作区内唯一） | | `--scene ` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） | -| `--description ` | string | 否 | 服务描述（最多 1000 字符） | +| `--description ` | string | 建议 | 这个服务能回答什么、给谁用（最多 1000 字符） | | `--index-id ` | string | 否 | 绑定此知识库；其他配置使用服务端默认值 | **参数约束** - `--name` 最多 200 字符 - `--scene` 只能是 `chat` 或 `search` -- `--description` 最多 1000 字符 +- `--description` 最多 1000 字符；建议填写 —— agent 靠它判断该调用哪个服务 **输出** diff --git a/docs/kscli/chunk.md b/docs/kscli/chunk.md new file mode 100644 index 000000000..e75b8691a --- /dev/null +++ b/docs/kscli/chunk.md @@ -0,0 +1,248 @@ +# Chunk 管理命令手册 + +Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli chunk add` + +直接向知识库添加 chunk。 + +**用法** + +```bash +kscli chunk add --index-id (--content | --field ) [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------------- | ------ | ---- | ------------------------------------------------------------------------------------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--doc-id ` | string | 否² | 所属文档 ID；表格/图片知识库必填，文档型可选 | +| `--content ` | string | 否¹ | Chunk 正文，最多 6000 字符（文档型）；与 `--content-file` 互斥 | +| `--content-file ` | string | 否¹ | 从 UTF-8 文本文件读取正文（`.md`/`.txt` 等）；与 `--content` 互斥 | +| `--title ` | string | 否 | Chunk 标题，最多 50 字符（文档型） | +| `--image-url ` | array | 否 | Chunk 图片 URL（可重复，最多 10 个；文档型） | +| `--field ` | array | 否¹ | 任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥 | + +> ¹ `--content`/`--content-file`/`--title`/`--image-url` 与 `--field` 互斥，必须提供其一。 +> ² 表格/图片知识库必须提供 `--doc-id`。文档型知识库可选。 + +**参数约束** + +- `--field` 与 `--content`/`--content-file`/`--title`/`--image-url` 互斥 +- `--content` 与 `--content-file` 互斥 +- `--content` 最多 6000 字符 +- `--title` 最多 50 字符 +- `--image-url` 最多 10 个 + +**输出** + +text 模式： + +``` +chunk created (pipeline: idx-xxx) +List chunks to find the new chunk id. +``` + +quiet 模式：无输出（成功退出码 0）。 + +json 模式：返回 API 原始响应（不含 chunk ID）。 + +**注意事项** + +- 支持文档/表格/图片知识库；音视频知识库不支持。 +- API 响应不含 chunk ID，需用 `chunk list` 查找新 chunk。 +- API 幂等但限流 10 次/秒，批量脚本需自行节流。 +- 表格/图片知识库用 `--field`，键为 Excel 列名，值为字符串。 + +**示例** + +```bash +# 添加文本 chunk +kscli chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx + +# 添加表格行（字段方式） +kscli chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2 + +# 从文件读取内容 +kscli chunk add --index-id idx-xxx --content-file ./chunk.md --doc-id doc-xxx +``` + +--- + +#### `kscli chunk list` + +列出知识库中的 chunk，含内容和状态。 + +**用法** + +```bash +kscli chunk list --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ------------------- | ------ | ---- | ------------------------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--doc-id ` | string | 否 | 只显示属于此文档的 chunk | +| `--page-number ` | number | 否 | 页码（默认：1） | +| `--page-size ` | number | 否 | 每页条数（默认：20，最大 100） | + +**参数约束** + +- `--page-size` 范围 1-100 + +**输出** + +text 模式： + +``` +[chunk] chunk-xxx (doc: intro.md, doc_id: file-xxx) status: COMPLETED + chunk content preview (truncated at 200 chars)… +total: 1 +``` + +> 如果 chunk 被排除检索，行尾会显示 `[excluded from retrieval]`。 + +quiet 模式：每行一个 `metadata._id`（chunk ID），用于管道传给 update/delete。 + +json 模式：返回 API 原始响应，`data.nodes[]` 含完整 chunk 数据。 + +**注意事项** + +- 用 `metadata._id` 作为 chunk ID，`metadata.doc_id` 作为文档 ID，在 chunk update/delete 中使用。 +- 页大小默认 20，最大 100。 + +**示例** + +```bash +# 列出所有 chunk +kscli chunk list --index-id idx-xxx --workspace-id ws-xxx + +# 只看某文档的 chunk +kscli chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50 +``` + +--- + +#### `kscli chunk update` + +更新 chunk 内容或切换其检索可见性。 + +**用法** + +```bash +kscli chunk update --index-id --chunk-id --doc-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------------- | ------ | ---- | ------------------------------------------------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--chunk-id ` | string | 是 | Chunk ID（`metadata._id`，来自 chunk list 输出） | +| `--doc-id ` | string | 是 | 所属文档 ID（`metadata.doc_id`，来自 chunk list 输出） | +| `--content ` | string | 否¹ | 新内容，10-6000 字符；与 `--content-file` 互斥 | +| `--content-file ` | string | 否¹ | 从 UTF-8 文本文件读取新内容 | +| `--title ` | string | 否 | Chunk 标题，0-50 字符（空字符串清除标题；不传则不变） | +| `--exclude` | switch | 否² | 将此 chunk 排除出检索 | +| `--include` | switch | 否² | 将此 chunk 恢复检索（默认行为） | + +> ¹ `--content` 与 `--content-file` 互斥。 +> ² `--exclude` 与 `--include` 互斥。 + +**参数约束** + +- `--content` 与 `--content-file` 互斥 +- `--exclude` 与 `--include` 互斥 +- 至少提供一个更新项（`--content`/`--content-file`/`--title`/`--exclude`/`--include`） +- `--content` 长度 10-6000 字符 +- `--title` 最多 50 字符 + +**输出** + +text 模式： + +``` +updated: chunk-xxx +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 内容必须 10-6000 字符，且不超过知识库的 max chunk size。 +- `--content-file` 期望 UTF-8 纯文本文件，不解析 `.docx`/`.pdf` 等文档格式。 +- 仅切换 `--exclude`/`--include` 而不提供新内容时，CLI 自动读回当前内容并重新提交（API 要求 content 字段必填，CLI 隐藏了此限制）。 + +**示例** + +```bash +# 修改内容 +kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" --workspace-id ws-xxx + +# 排除 chunk 不参与检索 +kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude + +# 恢复检索 +kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include +``` + +--- + +#### `kscli chunk delete` + +从知识库中删除 chunk（不可逆）。 + +**用法** + +```bash +kscli chunk delete --index-id --chunk-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | ------------------------------------------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--chunk-id ` | array | 是 | Chunk ID（可重复，每批最多 10 个，超出自动分批） | +| `--yes` | switch | 否 | 跳过确认提示 | + +**输出** + +text 模式： + +``` +deleted: 2 chunk(s) in 1 batch(es) +``` + +quiet 模式：无输出。 + +json 模式：返回 `{ deleted_count, batches }`。 + +**注意事项** + +- 服务端每次最多接受 10 个 chunk ID，CLI 自动分批。 +- 如果某批失败，操作停止，已删除的批次会在错误 hint 中列出。 +- Chunk 被永久移除，不可恢复。 + +**示例** + +```bash +# 删除多个 chunk +kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx + +# 跳过确认 +kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --yes +``` + +--- + +← [返回总览](./kscli-cli-guide.md) diff --git a/docs/kscli/collection-category.md b/docs/kscli/collection-category.md new file mode 100644 index 000000000..b4061c49f --- /dev/null +++ b/docs/kscli/collection-category.md @@ -0,0 +1,268 @@ +# 数据中心集合与分类命令手册 + +集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli collection create` + +创建 FILE 数据集合。 + +**用法** + +```bash +kscli collection create --name --description [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | ---------------------------------------------------------------- | +| `--name ` | string | 是 | 集合名称（1-20 字符） | +| `--description ` | string | 是 | 集合描述 | +| `--store-type ` | string | 否 | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） | +| `--oss-region ` | string | 否 | OSS region ID（`--store-type custom` 时必填） | +| `--oss-bucket ` | string | 否 | OSS bucket 名称（`--store-type custom` 时必填） | + +**参数约束** + +- `--name` 长度 1-20 字符 +- `--store-type` 只能是 `platform` 或 `custom` +- `--store-type custom` 时 `--oss-region` 和 `--oss-bucket` 必填 + +**输出** + +text 模式： + +``` +created: conn-xxx (my-collection, PLATFORM) +``` + +quiet 模式：输出集合 ID。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- `platform` 使用平台托管存储；`custom` 使用已授权的 OSS bucket。 +- 自定义 bucket 必须携带标签 `bailian-connector-access=ReadAndWrite`（百炼的标签访问控制），否则服务端报 `setBucketCORS failed` 误导性错误。 +- **无集合删除 API**，创建需谨慎。 + +**示例** + +```bash +# 创建平台托管的集合 +kscli collection create --name my-collection --description "team docs" --workspace-id ws-xxx + +# 创建使用自有 OSS bucket 的集合 +kscli collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket +``` + +--- + +#### `kscli collection get` + +查看数据集合详情。 + +**用法** + +```bash +kscli collection get (--collection-id | --name ) [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | -------- | +| `--collection-id ` | string | 否¹ | 集合 ID | +| `--name ` | string | 否¹ | 集合名称 | + +> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。 + +**参数约束** + +- `--collection-id` 和 `--name` 互斥，必须提供其一 + +**输出** + +text 模式： + +``` +id: conn-xxx +name: my-collection +description: team docs +``` + +quiet 模式：输出集合 ID。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- getConnector 不返回 `fileConnectorConfig`（`storeType`/`regionId`/`bucketName`），这些字段仅在创建时通过请求体传入，查询时不可读回。 + +**示例** + +```bash +# 按 ID 查询 +kscli collection get --collection-id conn-xxx --workspace-id ws-xxx + +# 按名称查询 +kscli collection get --name my-collection +``` + +--- + +#### `kscli category list` + +列出数据中心分类。 + +**用法** + +```bash +kscli category list [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | ------------------------------------------------------ | +| `--collection-id ` | string | 否 | 按集合 ID 过滤 | +| `--parent-id ` | string | 否 | 列出此分类的子分类 | +| `--name ` | string | 否 | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） | +| `--next-token ` | string | 否 | 游标分页令牌 | +| `--max-result ` | number | 否 | 每页条数（默认：20） | + +**输出** + +text 模式： + +``` +cate-xxx product-docs +cate-yyy system-docs [default] +next: --next-token eyJ... +``` + +> 标记 `[default]` 的是文件未指定分类时的默认归属。 + +quiet 模式：每行一个 `categoryId`。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 分页是游标方式：使用输出的 `next: --next-token ` 继续翻页。 + +**示例** + +```bash +# 列出所有分类 +kscli category list --workspace-id ws-xxx + +# 按名称过滤 +kscli category list --name my-category + +# 翻页 +kscli category list --next-token eyJ... +``` + +--- + +#### `kscli category add` + +创建数据中心分类。 + +**用法** + +```bash +kscli category add --name [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | -------------------------------- | +| `--name ` | string | 是 | 分类名称（1-20 字符） | +| `--parent-id ` | string | 否 | 创建为指定分类的子分类 | +| `--collection-id ` | string | 否 | 创建在此集合下（默认：平台集合） | + +**参数约束** + +- `--name` 长度 1-20 字符 + +**输出** + +text 模式： + +``` +created: cate-xxx (product-docs) +``` + +quiet 模式：输出分类 ID。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 用分类按业务域组织数据中心文件。 + +**示例** + +```bash +# 创建分类 +kscli category add --name product-docs --workspace-id ws-xxx + +# 创建子分类 +kscli category add --name sub --parent-id cate-xxx +``` + +--- + +#### `kscli category delete` + +删除数据中心分类。 + +**用法** + +```bash +kscli category delete --category-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| -------------------- | ------ | ---- | ------------ | +| `--category-id ` | string | 是 | 分类 ID | +| `--yes` | switch | 否 | 跳过确认提示 | + +**输出** + +text 模式： + +``` +deleted: cate-xxx +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 含文件或子分类的分类的删除行为由服务端定义——服务端错误原样透传。 + +**示例** + +```bash +# 删除分类（交互确认） +kscli category delete --category-id cate-xxx --workspace-id ws-xxx + +# 跳过确认 +kscli category delete --category-id cate-xxx --yes +``` + +--- + +← [返回总览](./kscli-cli-guide.md) diff --git a/docs/kscli/doc.md b/docs/kscli/doc.md new file mode 100644 index 000000000..60cea6776 --- /dev/null +++ b/docs/kscli/doc.md @@ -0,0 +1,344 @@ +# 文档管理命令手册 + +文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli doc list` + +列出知识库中的文档及其解析/索引状态。 + +**用法** + +```bash +kscli doc list --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ------------------- | ------ | ---- | ------------------------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--page-number ` | number | 否 | 页码（默认：1） | +| `--page-size ` | number | 否 | 每页条数（默认：10，最大 100） | + +**参数约束** + +- `--page-size` 范围 1-100 + +**输出** + +text 模式：每行一个文档，`FAILED` 状态的文档红色高亮。 + +``` +doc-xxx COMPLETED intro.md md 1024 +total: 1 +``` + +quiet 模式：每行一个 `doc_id`。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- `doc_id` 与 `file_id` 的关系：通过 `kb create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；通过 `doc upload --index-id` 导入的，`doc_id` 可能包含 workspace 后缀。 +- 页大小默认 10（服务端默认），最大 100。 + +**示例** + +```bash +# 列出文档 +kscli doc list --index-id idx-xxx --workspace-id ws-xxx + +# 每页 100 条 +kscli doc list --index-id idx-xxx --page-size 100 +``` + +--- + +#### `kscli doc status` + +查看知识库导入任务状态。 + +**用法** + +```bash +kscli doc status --index-id --job-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| --------------------------- | ------ | ---- | --------------------------------------------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--job-id ` | string | 是 | 导入任务 ID（`ingestionId`，由 create/upload 返回） | +| `--page-number ` | number | 否 | 页码 | +| `--page-size ` | number | 否 | 每页条数 | +| `--wait` | switch | 否 | 轮询直到任务到达终态 | +| `--poll-interval ` | number | 否 | 轮询间隔秒数（默认：5） | + +**输出** + +text 模式： + +``` +status: COMPLETED + doc-xxx COMPLETED intro.md +``` + +quiet 模式：输出任务状态（`PENDING`/`RUNNING`/`COMPLETED`）。 + +json 模式：返回 API 原始响应，`data.rows[]` 包含每个文档的状态。 + +**注意事项** + +- `--index-id` 和 `--job-id` 服务端均要求必传，只传一个会返回 `SystemError`。 +- 整体任务状态为 `PENDING` / `RUNNING` / `COMPLETED`（无 `FAILED` 值）。 +- 单个文档可能解析失败（如 `PARSE_FAILED`），此时 CLI 以非零退出码报错，服务端消息原样透传。 +- 如果服务端对空闲知识库返回 `SystemError`，说明该 job 可能不存在。 + +**示例** + +```bash +# 查看任务状态 +kscli doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx + +# 轮询等待完成，10 秒间隔 +kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10 +``` + +--- + +#### `kscli doc upload` + +上传本地文件或目录到数据中心，可选导入到知识库。 + +**用法** + +```bash +kscli doc upload --file [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| --------------------------- | ------ | ---- | ---------------------------------------------------------------- | +| `--file ` | array | 是 | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 | +| `--index-id ` | string | 否 | 上传后导入到此知识库（所有文件合并为一个导入任务） | +| `--category-id ` | string | 否 | 目标数据中心分类（默认：工作区默认分类） | +| `--tag ` | array | 否 | 文件标签（可重复），应用到每个上传的文件 | +| `--wait` | switch | 否 | 轮询导入任务直到终态（需要 `--index-id`） | +| `--poll-interval ` | number | 否 | 轮询间隔秒数（默认：5） | + +**参数约束** + +- `--wait` 要求同时指定 `--index-id` + +**输出** + +text 模式： + +``` +intro.md file-xxx registered +job: job-xxx +status: COMPLETED + +Uploaded 1 file. +``` + +quiet 模式：每行一个 `fileId`。 + +json 模式：返回自定义结构，包含 `files`（路径和 fileId）、`skipped`、`index_id`、`ingestion_id`、`final_status`。 + +**注意事项** + +- 上传管道：申请 lease → PUT 到 OSS → 注册文件 →（可选）创建导入任务。 +- 目录递归扫描，`node_modules`、`.git` 等自动跳过。 +- 多文件按顺序处理（无并发），避免 OSS 限流。 +- 支持的文件格式：`.pdf .doc .docx .ppt .pptx .xls .xlsx .csv .md .txt .html .png .jpg .jpeg .bmp .gif` +- 部分文件上传失败时，已注册的 fileId 会在错误 hint 中列出。 + +**示例** + +```bash +# 上传单个文件 +kscli doc upload --file ./a.md --workspace-id ws-xxx + +# 上传多个文件并导入到知识库，等待完成 +kscli doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait + +# 上传整个目录 +kscli doc upload --file ./docs/ --workspace-id ws-xxx + +# 干跑预览（查看将上传和跳过的文件） +kscli doc upload --file ./docs/ --dry-run --verbose +``` + +--- + +#### `kscli doc delete` + +从知识库中删除文档及其 chunk。 + +**用法** + +```bash +kscli doc delete --index-id --doc-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | ----------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--doc-id ` | array | 是 | 文档 ID（可重复） | +| `--yes` | switch | 否 | 跳过确认提示 | + +**输出** + +text 模式： + +``` +deleted: 2 document(s) + doc-a + doc-b +``` + +quiet 模式：每行一个已删除的 `doc_id`。 + +json 模式：返回 API 原始响应，`data.deleted[]` 为实际删除的 ID 列表。 + +**注意事项** + +- 只从知识库索引中移除文档，数据中心源文件不受影响（用 `file delete` 删除源文件）。 +- `doc_id` 应从 `doc list --quiet` 获取，而非 `doc upload` 返回的 `fileId`。 +- 删除是异步的：服务端立即返回 Success，但 `doc list` 中可能仍显示该文档（约 30 秒后传播完成）。 +- 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。 + +**示例** + +```bash +# 删除单个文档 +kscli doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx + +# 批量删除，跳过确认 +kscli doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes +``` + +--- + +#### `kscli doc tag` + +批量更新数据中心文件的标签。 + +**用法** + +```bash +kscli doc tag --doc-id --tag [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| --------------- | ------ | ---- | ------------------------------------------------------ | +| `--doc-id ` | array | 是 | 数据中心文件 ID（可重复，最多 20 个/次） | +| `--tag ` | array | 是 | 标签（可重复），应用到每个 `--doc-id` | +| `--mode ` | string | 否 | 更新模式：`append`（默认，追加）或 `overwrite`（覆盖） | + +**参数约束** + +- `--doc-id` 最多 20 个/次 +- `--tag` 最多 100 个 +- 每个标签最多 32 字符 +- 标签总长度最多 700 字符 +- `--mode` 只能是 `append` 或 `overwrite` + +**输出** + +text 模式： + +``` +tagged: 2 file(s) with [project-a, draft] +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 同一组标签应用到所有 `--doc-id`；不同标签集需多次执行。 + +**示例** + +```bash +# 追加标签 +kscli doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx + +# 覆盖标签 +kscli doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite +``` + +--- + +#### `kscli doc import-oss` + +从已授权的 OSS bucket 批量导入文件到数据中心。 + +**用法** + +```bash +kscli doc import-oss --bucket --region --oss-key [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| -------------------- | ------ | ---- | ------------------------------------- | +| `--bucket ` | string | 是 | 已授权的 OSS bucket 名称 | +| `--region ` | string | 是 | OSS region ID（如 `cn-beijing`） | +| `--oss-key ` | array | 是 | OSS 对象 key（可重复，最多 10 个/次） | +| `--category-id ` | string | 否 | 目标数据中心分类（默认：默认分类） | +| `--tag ` | array | 否 | 文件标签（可重复，最多 10 个） | +| `--overwrite` | switch | 否 | 覆盖之前从相同 OSS key 导入的文件 | + +**参数约束** + +- `--oss-key` 最多 10 个/次 +- `--tag` 最多 10 个 + +**输出** + +text 模式： + +``` +imported: 2 file(s) + file-a SUCCESS docs/a.pdf + file-b SUCCESS docs/b.docx +``` + +quiet 模式：每行一个 `fileId`。 + +json 模式：返回 API 原始响应，`data.addFileResultList[]` 包含每个文件的 fileId、status 和 ossKey。 + +**注意事项** + +- bucket 必须事先授权给平台服务角色（RAM 中的 `AliyunServiceRoleForBailian`）。 +- 文件名取自 OSS key 的 basename。 +- `--overwrite` 会替换之前导入的文件并生成**新的 fileId**（旧 fileId 失效）。 + +**示例** + +```bash +# 导入单个文件 +kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx + +# 导入多个文件并覆盖 +kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite +``` + +--- + +← [返回总览](./kscli-cli-guide.md) diff --git a/docs/kscli/file.md b/docs/kscli/file.md new file mode 100644 index 000000000..e4edce0cd --- /dev/null +++ b/docs/kscli/file.md @@ -0,0 +1,157 @@ +# 数据中心文件管理命令手册 + +数据中心是知识库文件的存储层。文件通过 `doc upload` 或 `doc import-oss` 进入数据中心，再导入到知识库。数据中心文件可被多个知识库引用。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli file list` + +列出数据中心分类下的文件。 + +**用法** + +```bash +kscli file list --category-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | -------------------------------------------------- | +| `--category-id ` | string | 是 | 分类 ID（通过 `category list` 或 `file get` 获取） | +| `--name ` | string | 否 | 按文件名过滤 | +| `--file-id ` | array | 否 | 按文件 ID 过滤（可重复） | +| `--next-token ` | string | 否 | 游标分页令牌（从上次输出获取） | +| `--max-result ` | number | 否 | 每页条数 | + +**输出** + +text 模式： + +``` +file-xxx SUCCESS intro.md 1024 +next: --next-token eyJ... +``` + +quiet 模式：每行一个 `fileId`。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- `--category-id` 必须是真实的分类 ID。与上传 API 不同，字面量 `default` 在此不被解析，传入会返回空列表。通过 `file get` 的 category 字段或 `category list` 获取真实 ID。 +- 分页是游标方式：使用输出的 `next: --next-token ` 继续翻页。 + +**示例** + +```bash +# 列出分类下文件 +kscli file list --category-id cate-xxx --workspace-id ws-xxx + +# 按名称过滤 +kscli file list --category-id cate-xxx --name report + +# 翻页 +kscli file list --category-id cate-xxx --next-token eyJ... +``` + +--- + +#### `kscli file get` + +查看数据中心文件详情。 + +**用法** + +```bash +kscli file get --file-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------- | ------ | ---- | --------------- | +| `--file-id ` | string | 是 | 数据中心文件 ID | + +**输出** + +text 模式： + +``` +id: file-xxx +name: intro.md +type: md +size: 1024 +status: SUCCESS +parser: AUTO_SELECT +category: cate-xxx +uploaded: 2026-01-01T00:00:00Z +tags: project-a, draft +``` + +quiet 模式：输出 JSON 格式。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 无特殊注意事项。 + +**示例** + +```bash +# 查看文件详情 +kscli file get --file-id file-xxx --workspace-id ws-xxx +``` + +--- + +#### `kscli file delete` + +从数据中心永久删除文件。 + +**用法** + +```bash +kscli file delete --file-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------- | ------ | ---- | --------------- | +| `--file-id ` | string | 是 | 数据中心文件 ID | +| `--yes` | switch | 否 | 跳过确认提示 | + +**输出** + +text 模式： + +``` +deleted: file-xxx +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- **不可逆操作**：如果知识库引用了此文件，相关文档索引会失效。 +- 与 `doc delete` 的区别：`doc delete` 只从单个知识库索引中移除文档，数据中心源文件保留；`file delete` 删除源文件本身，影响所有引用它的知识库。 + +**示例** + +```bash +# 删除文件（交互确认） +kscli file delete --file-id file-xxx --workspace-id ws-xxx + +# 跳过确认 +kscli file delete --file-id file-xxx --yes +``` + +--- + +← [返回总览](./kscli-cli-guide.md) diff --git a/docs/kscli/kb.md b/docs/kscli/kb.md new file mode 100644 index 000000000..5fa4c34b8 --- /dev/null +++ b/docs/kscli/kb.md @@ -0,0 +1,342 @@ +# 知识库管理命令手册 + +知识库（Knowledge Base / pipeline / index）是 RAG 的核心载体，存储文档解析后的向量索引。本组命令覆盖知识库的创建、查看、更新、删除和监控。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli kb list` + +列出工作区中的知识库。 + +**用法** + +```bash +kscli kb list [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ------------------- | ------ | ---- | --------------------------------- | +| `--name ` | string | 否 | 按知识库名称模糊过滤（1-20 字符） | +| `--page-number ` | number | 否 | 页码（默认：1） | +| `--page-size ` | number | 否 | 每页条数（默认：20，最大 100） | + +**参数约束** + +- `--name` 长度 1-20 字符 +- `--page-size` 范围 1-100 + +**输出** + +text 模式：每行一个知识库，字段以双空格分隔，末尾显示总数。 + +``` +idx-xxx my-kb text-embedding-v4 600 product docs +total: 1 +``` + +quiet 模式：每行一个知识库 ID。 + +json 模式：返回 API 原始响应，`data.rows[]` 包含完整知识库信息。 + +**注意事项** + +- 返回的 `id` 字段作为后续命令的 `--index-id` 使用。 + +**示例** + +```bash +# 列出所有知识库 +kscli kb list --workspace-id ws-xxx + +# 按名称过滤，第二页 +kscli kb list --name demo --page-number 2 --page-size 50 +``` + +--- + +#### `kscli kb info` + +查看知识库配置详情。 + +**用法** + +```bash +kscli kb info --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | --------- | +| `--index-id ` | string | 是 | 知识库 ID | + +**输出** + +text 模式：按诊断维度分组展示。 + +``` +Basic: + id: idx-xxx + name: my-kb + description: product docs + dataType: ... +Indexing: [immutable — recreate required to change] + embeddingModelName: text-embedding-v4 + embeddingDimension: 1024 + chunkSize: 600 + overlapSize: ... + chunkMode: ... + separator: ... +Retrieval: + rerankModelName: ... + rerankMinScore: ... + rerankTopN: ... + rerankMode: ... + enableRewrite: ... + denseSimilarityTopK: ... + sparseSimilarityTopK: ... +Data: + sourceType: ... + connectorId: ... +``` + +quiet 模式：输出知识库 ID。 + +json 模式：返回知识库完整配置 JSON。 + +**注意事项** + +- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。 + +**示例** + +```bash +# 查看知识库详情 +kscli kb info --index-id idx-xxx --workspace-id ws-xxx +``` + +--- + +#### `kscli kb create` + +创建知识库并导入数据中心文件或分类。 + +**用法** + +```bash +kscli kb create --name --description (--doc-id | --category-id ) [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| --------------------------- | ------ | ---- | -------------------------------------------------------- | +| `--name ` | string | 是 | 知识库名称（1-20 字符，工作区内唯一） | +| `--description ` | string | 是 | 知识库装了什么内容、给谁用（1-500 字符） | +| `--doc-id ` | array | 否¹ | 数据中心文件 ID（可重复）；与 `--category-id` 互斥 | +| `--category-id ` | array | 否¹ | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 | +| `--embedding-model ` | string | 否 | 向量模型名称（默认：`text-embedding-v4`） | +| `--chunk-size ` | number | 否 | 切片大小，字符数（默认：600，建议 300-800） | +| `--wait` | switch | 否 | 轮询初始导入任务直到终态 | +| `--poll-interval ` | number | 否 | 轮询间隔秒数（默认：5） | + +> ¹ `--doc-id` 和 `--category-id` 二选一，必须提供其一。 + +**参数约束** + +- `--name` 长度 1-20 字符 +- `--description` 长度 1-500 字符，缺失或超长会在本地被拦截 +- `--doc-id` 和 `--category-id` 互斥，必须提供其一 + +**输出** + +text 模式： + +``` +index_id: idx-xxx +ingestion_id: job-xxx +status: COMPLETED +Next: check the import job status, then search against this knowledge base. +``` + +quiet 模式：只输出知识库 ID。 + +json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和 `ingestionId`（导入任务 ID）。`--wait` 时追加 `final_status` 字段。 + +**注意事项** + +- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。 +- 返回知识库 ID（`pipelineId`）和初始导入任务 ID（`ingestionId`）。 +- 使用 `doc status` 或 `--wait` 跟踪导入进度。 +- 如果 `--wait` 后部分文档解析失败，CLI 以非零退出码报错，知识库已创建成功的事实会在 hint 中提示。 + +**示例** + +```bash +# 从指定文件创建知识库 +kscli kb create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx + +# 从分类导入并等待导入完成 +kscli kb create --name demo --description '产品文档' --category-id cate-xxx --wait + +# 指定向量模型和切片大小 +kscli kb create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx +``` + +--- + +#### `kscli kb update` + +更新知识库名称、描述或 rerank 阈值。 + +**用法** + +```bash +kscli kb update --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------------- | ------ | ---- | -------------------------------------------------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--name ` | string | 否 | 新名称（1-20 字符） | +| `--description ` | string | 否 | 新描述 | +| `--rerank-min-score ` | number | 否 | rerank 最低分数阈值，范围 0-1（低于此分的 chunk 被过滤） | + +**参数约束** + +- 至少提供 `--name`、`--description`、`--rerank-min-score` 之一，否则报错 "Nothing to update" +- `--name` 长度 1-20 字符 +- `--rerank-min-score` 范围 0-1 + +**输出** + +text 模式： + +``` +updated: idx-xxx +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。 + +**示例** + +```bash +# 更新描述 +kscli kb update --index-id idx-xxx --description "product docs v2" --workspace-id ws-xxx + +# 调整 rerank 阈值 +kscli kb update --index-id idx-xxx --rerank-min-score 0.3 +``` + +--- + +#### `kscli kb delete` + +删除知识库及其所有文档和 chunk。 + +**用法** + +```bash +kscli kb delete --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | ------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--yes` | switch | 否 | 跳过确认提示 | + +**输出** + +text 模式： + +``` +deleted: idx-xxx +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- **不可逆操作**：知识库及所有索引内容被永久删除。 +- 数据中心中的源文件不受影响，仅删除知识库索引。 +- 不带 `--yes` 时，CLI 会先查询知识库名称和文档数量作为确认摘要。 + +**示例** + +```bash +# 删除（交互确认） +kscli kb delete --index-id idx-xxx --workspace-id ws-xxx + +# 跳过确认 +kscli kb delete --index-id idx-xxx --yes +``` + +--- + +#### `kscli kb stats` + +查看知识库存储和 QPS 监控数据。 + +**用法** + +```bash +kscli kb stats --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | ----------------------------------------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--start