skills/modelstudioai__cli
1
0
Fork 0
mirror of https://github.com/modelstudioai/cli.git synced 2026-09-14 19:49:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(knowledge): 添加知识库各类资源及操作命令手册

Browse Source 
- 新增 Chunk 管理命令手册，涵盖添加、列出、更新、删除操作详解
- 新增数据中心集合与分类命令文档，介绍集合创建、查看，分类增删查等功能
- 新增文档管理命令，包含文档上传、导入 OSS、状态查询、删除及标签管理
- 新增数据中心文件管理文档，涵盖文件列表、详情查看、删除等命令说明
- 新增知识库管理命令手册，包含知识库创建、查看、更新、删除和监控
- 各命令均详细说明参数、输出格式及多模式支持（text/quiet/json）
- 提供丰富示例及注意事项，帮助用户正确使用相关命令
This commit is contained in:
zeyu.fz
2026-08-11 01:02:49 +08:00
parent 12e7a22195
commit e292b20d4b
10 changed files with 3074 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/knowledge/chunk.md
+248
View File
@@ -0,0 +1,248 @@
# Chunk 管理命令手册
Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
---
#### `bl knowledge chunk add`
直接向知识库添加 chunk。
**用法**
```bash
bl knowledge chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------------- | ------ | ---- | ------------------------------------------------------------------------------------------- |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--doc-id <id>` | string | 否² | 所属文档 ID；表格/图片知识库必填，文档型可选 |
| `--content <text>` | string | 否¹ | Chunk 正文，最多 6000 字符（文档型）；与 `--content-file` 互斥 |
| `--content-file <path>` | string | 否¹ | 从 UTF-8 文本文件读取正文（`.md`/`.txt` 等）；与 `--content` 互斥 |
| `--title <text>` | string | 否 | Chunk 标题，最多 50 字符（文档型） |
| `--image-url <url>` | array | 否 | Chunk 图片 URL（可重复，最多 10 个；文档型） |
| `--field <key=value>` | array | 否¹ | 任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥 |
> ¹ `--content`/`--content-file`/`--title`/`--image-url` 与 `--field` 互斥，必须提供其一。
> ² 表格/图片知识库必须提供 `--doc-id`，服务端无此字段会返回 HTTP 500（`dataId不能为空`）。文档型知识库可选。
**参数约束**
- `--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
bl knowledge chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx
# 添加表格行（字段方式）
bl knowledge chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2
# 从文件读取内容
bl knowledge chunk add --index-id idx-xxx --content-file ./chunk.md --doc-id doc-xxx
```
---
#### `bl knowledge chunk list`
列出知识库中的 chunk，含内容和状态。
**用法**
```bash
bl knowledge chunk list --index-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ------------------- | ------ | ---- | ------------------------------ |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--doc-id <id>` | string | 否 | 只显示属于此文档的 chunk |
| `--page-number <n>` | number | 否 | 页码（默认：1） |
| `--page-size <n>` | 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
bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
# 只看某文档的 chunk
bl knowledge chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50
```
---
#### `bl knowledge chunk update`
更新 chunk 内容或切换其检索可见性。
**用法**
```bash
bl knowledge chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------------- | ------ | ---- | ------------------------------------------------------ |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--chunk-id <id>` | string | 是 | Chunk ID（`metadata._id`，来自 chunk list 输出） |
| `--doc-id <id>` | string | 是 | 所属文档 ID（`metadata.doc_id`，来自 chunk list 输出） |
| `--content <text>` | string | 否¹ | 新内容，10-6000 字符；与 `--content-file` 互斥 |
| `--content-file <path>` | string | 否¹ | 从 UTF-8 文本文件读取新内容 |
| `--title <text>` | 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
# 修改内容
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" --workspace-id ws-xxx
# 排除 chunk 不参与检索
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude
# 恢复检索
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include
```
---
#### `bl knowledge chunk delete`
从知识库中删除 chunk（不可逆）。
**用法**
```bash
bl knowledge chunk delete --index-id <id> --chunk-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ------------------------------------------------ |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--chunk-id <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
bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx
# 跳过确认
bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --yes
```
---
← [返回总览](../knowledge-cli-guide.md)
docs/knowledge/collection-category.md
+271
View File
@@ -0,0 +1,271 @@
# 数据中心集合与分类命令手册
集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
---
#### `bl knowledge collection create`
创建 FILE 数据集合。
**用法**
```bash
bl knowledge collection create --name <text> --description <text> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ---------------------- | ------ | ---- | ---------------------------------------------------------------- |
| `--name <text>` | string | 是 | 集合名称（1-20 字符） |
| `--description <text>` | string | 是 | 集合描述 |
| `--store-type <type>` | string | 否 | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） |
| `--oss-region <id>` | string | 否 | OSS region ID（`--store-type custom` 时必填） |
| `--oss-bucket <name>` | 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
# 创建平台托管的集合
bl knowledge collection create --name my-collection --description "team docs" --workspace-id ws-xxx
# 创建使用自有 OSS bucket 的集合
bl knowledge collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
```
---
#### `bl knowledge collection get`
查看数据集合详情。
**用法**
```bash
bl knowledge collection get (--collection-id <id> | --name <text>) [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ---------------------- | ------ | ---- | -------- |
| `--collection-id <id>` | string | 否¹ | 集合 ID |
| `--name <text>` | string | 否¹ | 集合名称 |
> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。
**参数约束**
- `--collection-id` 和 `--name` 互斥，必须提供其一
**输出**
text 模式：
```
id: conn-xxx
name: my-collection
description: team docs
storeType: PLATFORM
```
> 如果是 `CUSTOM` 存储，额外显示 `ossRegion` 和 `ossBucket`（注意：实测 getConnector 响应可能不返回 fileConnectorConfig，storeType 显示为 `-`）。
quiet 模式：输出集合 ID。
json 模式：返回 API 原始响应。
**注意事项**
- 无特殊注意事项。
**示例**
```bash
# 按 ID 查询
bl knowledge collection get --collection-id conn-xxx --workspace-id ws-xxx
# 按名称查询
bl knowledge collection get --name my-collection
```
---
#### `bl knowledge category list`
列出数据中心分类。
**用法**
```bash
bl knowledge category list [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ---------------------- | ------ | ---- | ------------------------------------------------------ |
| `--collection-id <id>` | string | 否 | 按集合 ID 过滤 |
| `--parent-id <id>` | string | 否 | 列出此分类的子分类 |
| `--name <text>` | string | 否 | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） |
| `--next-token <token>` | string | 否 | 游标分页令牌 |
| `--max-result <n>` | number | 否 | 每页条数（默认：20） |
**输出**
text 模式：
```
cate-xxx product-docs
cate-yyy system-docs [default]
next: --next-token eyJ...
```
> 标记 `[default]` 的是文件未指定分类时的默认归属。
quiet 模式：每行一个 `categoryId`。
json 模式：返回 API 原始响应。
**注意事项**
- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
**示例**
```bash
# 列出所有分类
bl knowledge category list --workspace-id ws-xxx
# 按名称过滤
bl knowledge category list --name my-category
# 翻页
bl knowledge category list --next-token eyJ...
```
---
#### `bl knowledge category add`
创建数据中心分类。
**用法**
```bash
bl knowledge category add --name <text> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ---------------------- | ------ | ---- | -------------------------------- |
| `--name <text>` | string | 是 | 分类名称（1-20 字符） |
| `--parent-id <id>` | string | 否 | 创建为指定分类的子分类 |
| `--collection-id <id>` | string | 否 | 创建在此集合下（默认：平台集合） |
**参数约束**
- `--name` 长度 1-20 字符
**输出**
text 模式：
```
created: cate-xxx (product-docs)
```
quiet 模式：输出分类 ID。
json 模式：返回 API 原始响应。
**注意事项**
- 用分类按业务域组织数据中心文件。
**示例**
```bash
# 创建分类
bl knowledge category add --name product-docs --workspace-id ws-xxx
# 创建子分类
bl knowledge category add --name sub --parent-id cate-xxx
```
---
#### `bl knowledge category delete`
删除数据中心分类。
**用法**
```bash
bl knowledge category delete --category-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| -------------------- | ------ | ---- | ------------ |
| `--category-id <id>` | string | 是 | 分类 ID |
| `--yes` | switch | 否 | 跳过确认提示 |
**输出**
text 模式：
```
deleted: cate-xxx
```
quiet 模式：无输出。
json 模式：返回 API 原始响应。
**注意事项**
- 含文件或子分类的分类的删除行为由服务端定义——服务端错误原样透传。
**示例**
```bash
# 删除分类（交互确认）
bl knowledge category delete --category-id cate-xxx --workspace-id ws-xxx
# 跳过确认
bl knowledge category delete --category-id cate-xxx --yes
```
---
← [返回总览](../knowledge-cli-guide.md)
docs/knowledge/doc.md
+344
View File
@@ -0,0 +1,344 @@
# 文档管理命令手册
文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
---
#### `bl knowledge doc list`
列出知识库中的文档及其解析/索引状态。
**用法**
```bash
bl knowledge doc list --index-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ------------------- | ------ | ---- | ------------------------------ |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--page-number <n>` | number | 否 | 页码（默认：1） |
| `--page-size <n>` | 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` 的关系：通过 `knowledge create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；通过 `knowledge doc upload --index-id` 导入的，`doc_id` 可能包含 workspace 后缀。
- 页大小默认 10（服务端默认），最大 100。
**示例**
```bash
# 列出文档
bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
# 每页 100 条
bl knowledge doc list --index-id idx-xxx --page-size 100
```
---
#### `bl knowledge doc status`
查看知识库导入任务状态。
**用法**
```bash
bl knowledge doc status --index-id <id> --job-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| --------------------------- | ------ | ---- | --------------------------------------------------- |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--job-id <id>` | string | 是 | 导入任务 ID（`ingestionId`，由 create/upload 返回） |
| `--page-number <n>` | number | 否 | 页码 |
| `--page-size <n>` | number | 否 | 每页条数 |
| `--wait` | switch | 否 | 轮询直到任务到达终态 |
| `--poll-interval <seconds>` | 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
# 查看任务状态
bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
# 轮询等待完成，10 秒间隔
bl knowledge doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10
```
---
#### `bl knowledge doc upload`
上传本地文件或目录到数据中心，可选导入到知识库。
**用法**
```bash
bl knowledge doc upload --file <path> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| --------------------------- | ------ | ---- | ---------------------------------------------------------------- |
| `--file <path>` | array | 是 | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 |
| `--index-id <id>` | string | 否 | 上传后导入到此知识库（所有文件合并为一个导入任务） |
| `--category-id <id>` | string | 否 | 目标数据中心分类（默认：工作区默认分类） |
| `--tag <text>` | array | 否 | 文件标签（可重复），应用到每个上传的文件 |
| `--wait` | switch | 否 | 轮询导入任务直到终态（需要 `--index-id`） |
| `--poll-interval <seconds>` | 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
# 上传单个文件
bl knowledge doc upload --file ./a.md --workspace-id ws-xxx
# 上传多个文件并导入到知识库，等待完成
bl knowledge doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait
# 上传整个目录
bl knowledge doc upload --file ./docs/ --workspace-id ws-xxx
# 干跑预览（查看将上传和跳过的文件）
bl knowledge doc upload --file ./docs/ --dry-run --verbose
```
---
#### `bl knowledge doc delete`
从知识库中删除文档及其 chunk。
**用法**
```bash
bl knowledge doc delete --index-id <id> --doc-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ----------------- |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--doc-id <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` 应从 `knowledge doc list --quiet` 获取，而非 `doc upload` 返回的 `fileId`。
- 删除是异步的：服务端立即返回 Success，但 `doc list` 中可能仍显示该文档（约 30 秒后传播完成）。
- 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。
**示例**
```bash
# 删除单个文档
bl knowledge doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx
# 批量删除，跳过确认
bl knowledge doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes
```
---
#### `bl knowledge doc tag`
批量更新数据中心文件的标签。
**用法**
```bash
bl knowledge doc tag --doc-id <id> --tag <text> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| --------------- | ------ | ---- | ------------------------------------------------------ |
| `--doc-id <id>` | array | 是 | 数据中心文件 ID（可重复，最多 20 个/次） |
| `--tag <text>` | array | 是 | 标签（可重复），应用到每个 `--doc-id` |
| `--mode <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
# 追加标签
bl knowledge doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx
# 覆盖标签
bl knowledge doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite
```
---
#### `bl knowledge doc import-oss`
从已授权的 OSS bucket 批量导入文件到数据中心。
**用法**
```bash
bl knowledge doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| -------------------- | ------ | ---- | ------------------------------------- |
| `--bucket <name>` | string | 是 | 已授权的 OSS bucket 名称 |
| `--region <id>` | string | 是 | OSS region ID（如 `cn-beijing`） |
| `--oss-key <key>` | array | 是 | OSS 对象 key（可重复，最多 10 个/次） |
| `--category-id <id>` | string | 否 | 目标数据中心分类（默认：默认分类） |
| `--tag <text>` | 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
# 导入单个文件
bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx
# 导入多个文件并覆盖
bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
```
---
← [返回总览](../knowledge-cli-guide.md)
docs/knowledge/file.md
+157
View File
@@ -0,0 +1,157 @@
# 数据中心文件管理命令手册
数据中心是知识库文件的存储层。文件通过 `doc upload` 或 `doc import-oss` 进入数据中心，再导入到知识库。数据中心文件可被多个知识库引用。
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
---
#### `bl knowledge file list`
列出数据中心分类下的文件。
**用法**
```bash
bl knowledge file list --category-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ---------------------- | ------ | ---- | -------------------------------------------------- |
| `--category-id <id>` | string | 是 | 分类 ID（通过 `category list` 或 `file get` 获取） |
| `--name <text>` | string | 否 | 按文件名过滤 |
| `--file-id <id>` | array | 否 | 按文件 ID 过滤（可重复） |
| `--next-token <token>` | string | 否 | 游标分页令牌（从上次输出获取） |
| `--max-result <n>` | 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 <token>` 继续翻页。
**示例**
```bash
# 列出分类下文件
bl knowledge file list --category-id cate-xxx --workspace-id ws-xxx
# 按名称过滤
bl knowledge file list --category-id cate-xxx --name report
# 翻页
bl knowledge file list --category-id cate-xxx --next-token eyJ...
```
---
#### `bl knowledge file get`
查看数据中心文件详情。
**用法**
```bash
bl knowledge file get --file-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ---------------- | ------ | ---- | --------------- |
| `--file-id <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
# 查看文件详情
bl knowledge file get --file-id file-xxx --workspace-id ws-xxx
```
---
#### `bl knowledge file delete`
从数据中心永久删除文件。
**用法**
```bash
bl knowledge file delete --file-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ---------------- | ------ | ---- | --------------- |
| `--file-id <id>` | string | 是 | 数据中心文件 ID |
| `--yes` | switch | 否 | 跳过确认提示 |
**输出**
text 模式：
```
deleted: file-xxx
```
quiet 模式：无输出。
json 模式：返回 API 原始响应。
**注意事项**
- **不可逆操作**：如果知识库引用了此文件，相关文档索引会失效。
- 与 `doc delete` 的区别：`doc delete` 只从单个知识库索引中移除文档，数据中心源文件保留；`file delete` 删除源文件本身，影响所有引用它的知识库。
**示例**
```bash
# 删除文件（交互确认）
bl knowledge file delete --file-id file-xxx --workspace-id ws-xxx
# 跳过确认
bl knowledge file delete --file-id file-xxx --yes
```
---
← [返回总览](../knowledge-cli-guide.md)
docs/knowledge/kb.md
+341
View File
@@ -0,0 +1,341 @@
# 知识库管理命令手册
知识库（Knowledge Base / pipeline / index）是 RAG 的核心载体，存储文档解析后的向量索引。本组命令覆盖知识库的创建、查看、更新、删除和监控。
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
---
#### `bl knowledge list`
列出工作区中的知识库。
**用法**
```bash
bl knowledge list [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ------------------- | ------ | ---- | --------------------------------- |
| `--name <text>` | string | 否 | 按知识库名称模糊过滤（1-20 字符） |
| `--page-number <n>` | number | 否 | 页码（默认：1） |
| `--page-size <n>` | 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
# 列出所有知识库
bl knowledge list --workspace-id ws-xxx
# 按名称过滤，第二页
bl knowledge list --name demo --page-number 2 --page-size 50
```
---
#### `bl knowledge info`
查看知识库配置详情。
**用法**
```bash
bl knowledge info --index-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | --------- |
| `--index-id <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。
**注意事项**
- 服务端无专用详情 API，CLI 通过分页遍历 `index/list`（每页 100 条，最多 10 页）查找目标知识库。
- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
**示例**
```bash
# 查看知识库详情
bl knowledge info --index-id idx-xxx --workspace-id ws-xxx
```
---
#### `bl knowledge create`
创建知识库并导入数据中心文件或分类。
**用法**
```bash
bl knowledge create --name <text> (--doc-id <id> | --category-id <id>) [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| --------------------------- | ------ | ---- | -------------------------------------------------------- |
| `--name <text>` | string | 是 | 知识库名称（1-20 字符，工作区内唯一） |
| `--doc-id <id>` | array | 否¹ | 数据中心文件 ID（可重复）；与 `--category-id` 互斥 |
| `--category-id <id>` | array | 否¹ | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 |
| `--embedding-model <name>` | string | 否 | 向量模型名称（默认：`text-embedding-v4`） |
| `--chunk-size <n>` | number | 否 | 切片大小，字符数（默认：600，建议 300-800） |
| `--wait` | switch | 否 | 轮询初始导入任务直到终态 |
| `--poll-interval <seconds>` | number | 否 | 轮询间隔秒数（默认：5） |
> ¹ `--doc-id` 和 `--category-id` 二选一，必须提供其一。
**参数约束**
- `--name` 长度 1-20 字符
- `--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
# 从指定文件创建知识库
bl knowledge create --name demo --doc-id file-xxx --workspace-id ws-xxx
# 从分类导入并等待导入完成
bl knowledge create --name demo --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 update`
更新知识库名称、描述或 rerank 阈值。
**用法**
```bash
bl knowledge update --index-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ---------------------------- | ------ | ---- | -------------------------------------------------------- |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--name <text>` | string | 否 | 新名称（1-20 字符） |
| `--description <text>` | string | 否 | 新描述 |
| `--rerank-min-score <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
# 更新描述
bl knowledge update --index-id idx-xxx --description "product docs v2" --workspace-id ws-xxx
# 调整 rerank 阈值
bl knowledge update --index-id idx-xxx --rerank-min-score 0.3
```
---
#### `bl knowledge delete`
删除知识库及其所有文档和 chunk。
**用法**
```bash
bl knowledge delete --index-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ------------ |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--yes` | switch | 否 | 跳过确认提示 |
**输出**
text 模式：
```
deleted: idx-xxx
```
quiet 模式：无输出。
json 模式：返回 API 原始响应。
**注意事项**
- **不可逆操作**：知识库及所有索引内容被永久删除。
- 数据中心中的源文件不受影响，仅删除知识库索引。
- 不带 `--yes` 时，CLI 会先查询知识库名称和文档数量作为确认摘要。
**示例**
```bash
# 删除（交互确认）
bl knowledge delete --index-id idx-xxx --workspace-id ws-xxx
# 跳过确认
bl knowledge delete --index-id idx-xxx --yes
```
---
#### `bl knowledge stats`
查看知识库存储和 QPS 监控数据。
**用法**
```bash
bl knowledge stats --index-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ----------------------------------------------- |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--start <time>` | string | 否 | 范围起始：Unix 秒或 ISO 日期（默认：24 小时前） |
| `--end <time>` | string | 否 | 范围结束：Unix 秒或 ISO 日期（默认：当前时间） |
**输出**
text 模式：
```
plan: ...
storage: 100 / 1000
peak qps: 5
qps windows: 24 data point(s)
```
quiet 模式：输出 json 格式。
json 模式：返回 API 原始响应，包含 `storageMonitorData` 和 `qpsMonitorData`。
**注意事项**
- 默认查询最近 24 小时数据。
- 时间戳自动转换为 epoch 秒（API 要求秒级字符串）。13 位毫秒时间戳会自动降为秒。
**示例**
```bash
# 查看最近 24 小时监控
bl knowledge stats --index-id idx-xxx --workspace-id ws-xxx
# 指定日期范围
bl knowledge stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31
```
---
← [返回总览](../knowledge-cli-guide.md)
docs/knowledge/knowledge-cli-guide.md
+822
View File
@@ -0,0 +1,822 @@
# `bl knowledge` 命令完整用法指南
> `bl knowledge` / `kscli` 知识库 CLI 命令总览，覆盖全部 34 个子命令。完整参数与示例请参阅各子域手册。
---
## 目录
1. [概述](#概述)
2. [核心概念与实体关系](#核心概念与实体关系)
3. [通用约定](#通用约定)
4. [典型工作流](#典型工作流)
5. [命令手册](#命令手册)
- [知识库管理](#知识库管理) → [完整手册](knowledge/kb.md)
- [文档管理](#文档管理) → [完整手册](knowledge/doc.md)
- [检索服务管理](#检索服务管理) → [完整手册](knowledge/service.md)
- [Chunk 管理](#chunk-管理) → [完整手册](knowledge/chunk.md)
- [数据中心文件管理](#数据中心文件管理) → [完整手册](knowledge/file.md)
- [数据中心集合与分类](#数据中心集合与分类) → [完整手册](knowledge/collection-category.md)
- [检索与对话](#检索与对话) → [完整手册](knowledge/search-chat.md)
6. [常见错误与排查](#常见错误与排查)
7. [附录：命令速查表](#附录命令速查表)
---
## 概述
`bl knowledge` 是阿里云百炼 CLI 的知识库命令组，覆盖 RAG（检索增强生成）全链路能力：
- **知识库全生命周期管理**：创建、查看、更新、删除、监控
- **文档管理**：上传本地文件、从 OSS 批量导入、查看解析状态、删除、打标签
- **Chunk 级运维**：直接增删改查知识库中的内容切片
- **检索服务管理**：创建/部署/复制/删除 Q&A 和检索服务（agent），管理 draft 与发布版本
- **数据中心管理**：文件、集合（connector）、分类的增删查
- **检索与对话**：语义检索（search）、多轮对话（chat）、兼容旧检索（retrieve）
共 34 个子命令，按功能域分为 7 组。所有命令均使用 DashScope API Key 鉴权。
---
## 核心概念与实体关系
```
┌─────────────────────────────────────────────────────────────┐
│ 数据中心 (Data Center) │
│ │
│ 集合 (Collection) ──┬── 分类 (Category) ── 文件 (File) │
│ │ "connector" 可多级嵌套 │
│ └── 默认分类 │
│ │
│ 文件来源：doc upload(本地上传) / doc import-oss(OSS导入) │
└──────────────────────────┬──────────────────────────────────┘
│ 导入 (import job)
▼
┌─────────────────────────────────────────────────────────────┐
│ 知识库 (Knowledge Base) │
│ │
│ 知识库 (KB / pipeline / index) │
│ ├── 文档 (Doc) ── 解析状态: PENDING/RUNNING/COMPLETED │
│ │ └── Chunk ── 内容切片，可增删改查、排除/恢复检索 │
│ └── 索引设置 (immutable): 向量模型、切片大小等 │
│ │
│ 知识库管理命令: create / list / info / update / delete / stats │
└──────────────────────────┬──────────────────────────────────┘
│ 绑定 (agent_config.kb_search_configs)
▼
┌─────────────────────────────────────────────────────────────┐
│ 检索服务 (Service / Agent) │
│ │
│ Service (agent) │
│ ├── scene: chat (Q&A) 或 search (检索) │
│ ├── 版本: beta (草稿) → 1, 2, 3... (已发布) │
│ ├── 状态: draft → deployed → edited → deleted │
│ └── 配置: 模型、温度、策略、rerank 等 │
│ │
│ 消费方式: search (语义检索) / chat (多轮对话) │
│ 管理命令: create / update / deploy / copy / delete / list / get │
└─────────────────────────────────────────────────────────────┘
```
**关键关系**：
- **数据中心文件 → 知识库**：通过 `knowledge create --doc-id` 或 `knowledge doc upload --index-id` 导入，文件解析后自动生成 chunk
- **知识库 → 检索服务**：一个服务可绑定多个知识库，服务配置中 `kb_search_configs` 指定关联的知识库 ID
- **检索服务 → 检索/对话**：`search` 和 `chat` 命令通过 `--agent-id` 指定服务来执行检索或对话
---
## 通用约定
### 鉴权
所有 `bl knowledge` 命令均使用 **DashScope API Key**（Bearer token）鉴权。获取方式：百炼控制台 API Key 页面。
优先级（高 → 低）：
1. `--api-key <key>` 命令行参数
2. `DASHSCOPE_API_KEY` 环境变量
3. 配置文件中的 `api_key`（`bl config set api_key <key>`）
### Workspace ID
知识库 API 使用 workspace 级域名（`{workspaceId}.cn-beijing.maas.aliyuncs.com`），因此 **几乎所有 knowledge 命令都需要 workspace ID**。
优先级（高 → 低）：
1. `--workspace-id <id>` 命令行参数
2. `BAILIAN_WORKSPACE_ID` 环境变量
3. 配置文件中的 `workspace_id`（`bl config set workspace_id <id>`）
缺失时报错：`Workspace ID is required.`
### 全局通用参数
以下参数在所有 `bl knowledge` 子命令中通用，后续命令手册中不再逐条列出：
| 参数 | 类型 | 说明 |
| --------------------- | ------ | ----------------------------------------------------------- |
| `--output <format>` | string | 输出格式：`text`（默认，人类友好）或 `json`（API 原始响应） |
| `--api-key <key>` | string | DashScope API Key |
| `--base-url <url>` | string | API 基地址（一般不需要指定） |
| `--timeout <seconds>` | number | 请求超时秒数 |
| `--quiet` | switch | 静默模式，只输出关键结果（如 ID 列表） |
| `--verbose` | switch | 详细模式，打印 HTTP 请求/响应详情到 stderr |
| `--dry-run` | switch | 干跑模式，预览将发送的请求结构，不实际调用 API |
| `--config <name>` | string | 使用指定配置 profile 执行命令 |
> **注意**：命令手册中每个命令的参数表只列出该命令**特有**的参数。上述全局参数对所有命令有效。
### 输出格式约定
- **text 模式**（默认）：人类友好的表格/结构化文本，适合终端查看。不同命令的输出格式见各命令的「输出」部分。
- **json 模式**（`--output json`）：返回 API 原始 JSON 响应，适合程序化处理和 agent 解析。
- **quiet 模式**（`--quiet`）：只输出最精简的结果（通常只有 ID），适合管道串联。
### 危险操作确认
涉及删除的命令（`kb delete`、`doc delete`、`chunk delete`、`file delete`、`category delete`、`service delete`、`service deploy`）在执行前会弹出二次确认提示。使用 `--yes` 可跳过确认，适用于自动化脚本。
### Dry-run 模式
`--dry-run` 模式下，命令会输出将发送的 endpoint 和 request body，但**不实际发起网络请求**。部分命令在 dry-run 下仍会执行本地校验（如文件扩展名检查、参数约束检查）。
---
## 典型工作流
### 场景 A：从零搭建知识库并检索
```bash
# 1. 上传本地文件到数据中心，同时导入到新知识库
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
# → 返回 index-id (pipelineId) 和导入任务状态
# 3. 创建检索服务（search 场景）
bl knowledge service create --name my-search --scene search --index-id idx-xxx --workspace-id ws-xxx
# → 返回 agent-id
# 4. 部署服务
bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx --yes
# 5. 执行检索
bl knowledge search --query "什么是RAG" --agent-id aid-xxx --workspace-id ws-xxx
```
### 场景 B：上传目录并导入到已有知识库
```bash
# 1. 上传整个目录到数据中心并直接导入到知识库（一步到位）
bl knowledge doc upload --file ./docs/ --index-id idx-xxx --workspace-id ws-xxx --wait
# → 文件逐个上传到 OSS → 注册到数据中心 → 创建合并导入任务 → 轮询到完成
# 2. 检查文档状态
bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
# → 查看 doc_id 和解析状态
# 3. 如果有文档解析失败，查看导入任务详情
bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
```
### 场景 C：创建并部署 Q&A 服务
```bash
# 1. 创建 chat 场景的检索服务
bl knowledge service create --name my-qa --scene chat --index-id idx-xxx --workspace-id ws-xxx
# → 初始状态: draft, 版本: beta
# 2. 调整配置（如修改模型、温度）
bl knowledge service update --agent-id aid-xxx --model qwen-max --temperature 0.7 --workspace-id ws-xxx
# 3. 用 beta 版本测试
bl knowledge chat --message "什么是RAG?" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
# 4. 测试通过后发布
bl knowledge service deploy --agent-id aid-xxx --version-desc "首版" --workspace-id ws-xxx --yes
```
### 场景 D：知识库内容运维
```bash
# 1. 查看 chunk 列表
bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
# → 返回 metadata._id (chunk id) 和 metadata.doc_id (document id)
# 2. 修改 chunk 内容
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --content "修正后的内容" --workspace-id ws-xxx
# 3. 排除某个 chunk 不参与检索（不删除内容）
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --exclude --workspace-id ws-xxx
# 4. 手动添加新 chunk
bl knowledge chunk add --index-id idx-xxx --content "新增的知识片段" --title "补充说明" --workspace-id ws-xxx
# 5. 删除 chunk（批量，自动分批每 10 个一组）
bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --yes --workspace-id ws-xxx
```
### 场景 E：服务迁移/复用
```bash
# 1. 复制现有服务为新草稿
bl knowledge service copy --agent-id aid-source --workspace-id ws-xxx
# → 返回新的 agent-id，名称加 copy_ 前缀
# 2. 修改新服务配置
bl knowledge service update --agent-id aid-new --name "改进版" --temperature 0.5 --workspace-id ws-xxx
# 3. 测试并发布
bl knowledge chat --message "测试" --agent-id aid-new --agent-version beta --workspace-id ws-xxx
bl knowledge service deploy --agent-id aid-new --workspace-id ws-xxx --yes
```
### 场景 F：从 OSS 批量导入文件
```bash
# 1. 从已授权的 OSS bucket 批量导入文件到数据中心
bl knowledge doc import-oss \
--bucket my-bucket --region cn-beijing \
--oss-key docs/a.pdf --oss-key docs/b.docx \
--workspace-id ws-xxx
# → 返回各文件的 fileId
# 2. 创建知识库并导入这些文件
bl knowledge create --name oss-kb --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
```
---
## 命令手册
以下按功能域分组，覆盖全部 34 个子命令。每个条目包含功能说明、用法签名（kscli 前缀）和详细手册链接。
> 完整参数表、参数约束、输出说明、注意事项与示例请参阅各子域手册。子域手册中的用法签名使用 `bl knowledge` 前缀。
---
### 知识库管理
> 📖 [完整手册](knowledge/kb.md) — 6 个命令
#### `kscli kb list`
列出工作区中的知识库。
```bash
kscli kb list [flags]
```
→ [完整参数与示例](knowledge/kb.md#bl-knowledge-list)
---
#### `kscli kb info`
查看知识库配置详情。
```bash
kscli kb info --index-id <id> [flags]
```
→ [完整参数与示例](knowledge/kb.md#bl-knowledge-info)
---
#### `kscli kb create`
创建知识库并导入数据中心文件或分类。
```bash
kscli kb create --name <text> (--doc-id <id> | --category-id <id>) [flags]
```
→ [完整参数与示例](knowledge/kb.md#bl-knowledge-create)
---
#### `kscli kb update`
更新知识库名称、描述或 rerank 阈值。
```bash
kscli kb update --index-id <id> [flags]
```
→ [完整参数与示例](knowledge/kb.md#bl-knowledge-update)
---
#### `kscli kb delete`
删除知识库及其所有文档和 chunk。
```bash
kscli kb delete --index-id <id> [flags]
```
→ [完整参数与示例](knowledge/kb.md#bl-knowledge-delete)
---
#### `kscli kb stats`
查看知识库存储和 QPS 监控数据。
```bash
kscli kb stats --index-id <id> [flags]
```
→ [完整参数与示例](knowledge/kb.md#bl-knowledge-stats)
---
### 文档管理
> 📖 [完整手册](knowledge/doc.md) — 6 个命令
#### `kscli doc list`
列出知识库中的文档及其解析/索引状态。
```bash
kscli doc list --index-id <id> [flags]
```
→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-list)
---
#### `kscli doc status`
查看知识库导入任务状态。
```bash
kscli doc status --index-id <id> --job-id <id> [flags]
```
→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-status)
---
#### `kscli doc upload`
上传本地文件或目录到数据中心，可选导入到知识库。
```bash
kscli doc upload --file <path> [flags]
```
→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-upload)
---
#### `kscli doc delete`
从知识库中删除文档及其 chunk。
```bash
kscli doc delete --index-id <id> --doc-id <id> [flags]
```
→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-delete)
---
#### `kscli doc tag`
批量更新数据中心文件的标签。
```bash
kscli doc tag --doc-id <id> --tag <text> [flags]
```
→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-tag)
---
#### `kscli doc import-oss`
从已授权的 OSS bucket 批量导入文件到数据中心。
```bash
kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
```
→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-import-oss)
---
### 检索服务管理
> 📖 [完整手册](knowledge/service.md) — 7 个命令
#### `kscli service list`
列出工作区中的检索/Q&A 服务。
```bash
kscli service list --scene <chat|search> [flags]
```
→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-list)
---
#### `kscli service get`
查看服务详情，含各版本配置。
```bash
kscli service get --agent-id <id> [flags]
```
→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-get)
---
#### `kscli service create`
创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
```bash
kscli service create --name <text> --scene <chat|search> [flags]
```
→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-create)
---
#### `kscli service update`
更新服务名称、描述或草稿配置。
```bash
kscli service update --agent-id <id> [flags]
```
→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-update)
---
#### `kscli service deploy`
发布 beta 草稿为新版本。
```bash
kscli service deploy --agent-id <id> [flags]
```
→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-deploy)
---
#### `kscli service delete`
删除检索/Q&A 服务（软删除，幂等）。
```bash
kscli service delete --agent-id <id> [flags]
```
→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-delete)
---
#### `kscli service copy`
复制服务为新草稿（名称自动加 `copy_` 前缀）。
```bash
kscli service copy --agent-id <id> [flags]
```
→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-copy)
---
### Chunk 管理
> 📖 [完整手册](knowledge/chunk.md) — 4 个命令
#### `kscli chunk add`
直接向知识库添加 chunk。
```bash
kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
```
→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-add)
---
#### `kscli chunk list`
列出知识库中的 chunk，含内容和状态。
```bash
kscli chunk list --index-id <id> [flags]
```
→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-list)
---
#### `kscli chunk update`
更新 chunk 内容或切换其检索可见性。
```bash
kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
```
→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-update)
---
#### `kscli chunk delete`
从知识库中删除 chunk（不可逆）。
```bash
kscli chunk delete --index-id <id> --chunk-id <id> [flags]
```
→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-delete)
---
### 数据中心文件管理
> 📖 [完整手册](knowledge/file.md) — 3 个命令
#### `kscli file list`
列出数据中心分类下的文件。
```bash
kscli file list --category-id <id> [flags]
```
→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-list)
---
#### `kscli file get`
查看数据中心文件详情。
```bash
kscli file get --file-id <id> [flags]
```
→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-get)
---
#### `kscli file delete`
从数据中心永久删除文件。
```bash
kscli file delete --file-id <id> [flags]
```
→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-delete)
---
### 数据中心集合与分类
> 📖 [完整手册](knowledge/collection-category.md) — 5 个命令
#### `kscli collection create`
创建 FILE 数据集合。
```bash
kscli collection create --name <text> --description <text> [flags]
```
→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-collection-create)
---
#### `kscli collection get`
查看数据集合详情。
```bash
kscli collection get (--collection-id <id> | --name <text>) [flags]
```
→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-collection-get)
---
#### `kscli category list`
列出数据中心分类。
```bash
kscli category list [flags]
```
→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-list)
---
#### `kscli category add`
创建数据中心分类。
```bash
kscli category add --name <text> [flags]
```
→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-add)
---
#### `kscli category delete`
删除数据中心分类。
```bash
kscli category delete --category-id <id> [flags]
```
→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-delete)
---
### 检索与对话
> 📖 [完整手册](knowledge/search-chat.md) — 3 个命令
#### `kscli retrieve`
从知识库检索（已废弃，请用 `search` 替代）。
```bash
kscli retrieve --index-id <id> --query <text> [flags]
```
→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-retrieve)
---
#### `kscli search`
对知识库执行语义检索（RAG 检索）。
```bash
kscli search --query <text> --agent-id <id> [flags]
```
→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-search)
---
#### `kscli chat`
与知识库进行 RAG 对话（流式输出）。
```bash
kscli chat --message <text> --agent-id <id> [flags]
```
→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-chat)
---
## 常见错误与排查
### Workspace ID 缺失
**报错**：`Workspace ID is required.`
**原因**：所有 knowledge 管理命令都需要 workspace ID 来构造 API 端点（`{workspaceId}.cn-beijing.maas.aliyuncs.com`）。
**解决**：
```bash
# 方式1：命令行参数
bl knowledge list --workspace-id ws-xxx
# 方式2：环境变量
export BAILIAN_WORKSPACE_ID=ws-xxx
# 方式3：配置文件
bl config set workspace_id ws-xxx
```
### 知识库 ID 不存在
**报错**：`Knowledge base not found: idx-xxx`
**原因**：`--index-id` 指定的知识库在当前 workspace 中不存在。
**解决**：先 `bl knowledge list` 确认知识库 ID。
### 导入任务 SystemError
**报错**：服务端返回 `SystemError`
**原因**：`doc status` 传入了不存在的 job ID，或知识库空闲无任务。
**解决**：检查 `doc list` 输出中的 `ingestionId`，或从 `doc upload`/`knowledge create` 的返回值获取。
### doc_id 与 fileId 混淆
**问题**：`doc delete` 时用了 `doc upload` 返回的 `fileId` 而非 `doc list` 返回的 `doc_id`。
**原因**：通过 `knowledge create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；但通过 `doc upload --index-id` 导入的，`doc_id` 可能含 workspace 后缀。
**解决**：始终用 `doc list --quiet` 获取 `doc_id`。
### retrieve 已废弃
**问题**：`retrieve` 命令输出废弃警告。
**解决**：改用 `search` 命令。`search` 通过 `--agent-id` 驱动检索策略，支持多知识库、路由、rerank 等高级特性。`retrieve` 直接操作 `--index-id`，功能受限且不再迭代。
### OSS 导入权限错误
**报错**：服务端返回权限相关错误。
**原因**：OSS bucket 未授权给平台服务角色。
**解决**：检查 RAM 控制台中的 `AliyunServiceRoleForBailian` 角色是否已正确授权。
### Chat SSE error
**报错**：`Chat API error` + API error code。
**原因**：流式对话过程中服务端返回 error 事件。
**解决**：检查 `--agent-id` 是否存在、服务是否已部署、API Key 是否有效。错误消息和 code 原样透传，不二次包装。
### file list 返回空
**问题**：`file list --category-id default` 返回空列表。
**原因**：与上传 API 不同，`file list` 不解析字面量 `default`，需要真实分类 ID。
**解决**：通过 `file get` 的 category 字段或 `category list` 获取真实分类 ID。
### 集合无法删除
**问题**：没有 `collection delete` 命令。
**原因**：服务端无集合删除 API。
**解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。
---
## 附录：命令速查表
| 命令 | 功能 | 关键参数 |
| ------------------------- | ------------ | ----------------------------------------------------------- |
| `kscli kb list` | 列出知识库 | `--name` |
| `kscli kb info` | 知识库详情 | `--index-id` |
| `kscli kb create` | 创建知识库 | `--name`, `--doc-id`/`--category-id` |
| `kscli kb update` | 更新知识库 | `--index-id`, `--name`/`--description`/`--rerank-min-score` |
| `kscli kb delete` | 删除知识库 | `--index-id`, `--yes` |
| `kscli kb stats` | 监控数据 | `--index-id`, `--start`/`--end` |
| `kscli doc list` | 文档列表 | `--index-id` |
| `kscli doc status` | 导入任务状态 | `--index-id`, `--job-id`, `--wait` |
| `kscli doc upload` | 上传文件 | `--file`, `--index-id`, `--wait` |
| `kscli doc delete` | 删除文档 | `--index-id`, `--doc-id` |
| `kscli doc tag` | 文件打标签 | `--doc-id`, `--tag`, `--mode` |
| `kscli doc import-oss` | OSS 导入 | `--bucket`, `--region`, `--oss-key` |
| `kscli service list` | 服务列表 | `--scene` |
| `kscli service get` | 服务详情 | `--agent-id` |
| `kscli service create` | 创建服务 | `--name`, `--scene`, `--index-id` |
| `kscli service update` | 更新服务 | `--agent-id`, 配置参数 |
| `kscli service deploy` | 发布服务 | `--agent-id`, `--yes` |
| `kscli service delete` | 删除服务 | `--agent-id`, `--yes` |
| `kscli service copy` | 复制服务 | `--agent-id` |
| `kscli chunk add` | 添加 chunk | `--index-id`, `--content`/`--field` |
| `kscli chunk list` | chunk 列表 | `--index-id`, `--doc-id` |
| `kscli chunk update` | 更新 chunk | `--index-id`, `--chunk-id`, `--doc-id` |
| `kscli chunk delete` | 删除 chunk | `--index-id`, `--chunk-id`, `--yes` |
| `kscli file list` | 文件列表 | `--category-id` |
| `kscli file get` | 文件详情 | `--file-id` |
| `kscli file delete` | 删除文件 | `--file-id`, `--yes` |
| `kscli collection create` | 创建集合 | `--name`, `--description` |
| `kscli collection get` | 集合详情 | `--collection-id`/`--name` |
| `kscli category list` | 分类列表 | `--collection-id`, `--parent-id` |
| `kscli category add` | 创建分类 | `--name`, `--parent-id` |
| `kscli category delete` | 删除分类 | `--category-id`, `--yes` |
| `kscli retrieve` | 检索（废弃） | `--index-id`, `--query` |
| `kscli search` | 语义检索 | `--query`, `--agent-id` |
| `kscli chat` | RAG 对话 | `--message`, `--agent-id` |
docs/knowledge/search-chat.md
+224
View File
@@ -0,0 +1,224 @@
# 检索与对话命令手册
以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。`retrieve` 已废弃。
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
---
#### `bl knowledge retrieve`
从知识库检索（已废弃，请用 `search` 替代）。
**用法**
```bash
bl knowledge retrieve --index-id <id> --query <text> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ------------------------------- | ------ | ---- | --------------------------------------------------- |
| `--index-id <id>` | string | 是 | 知识库 ID |
| `--query <text>` | string | 是 | 检索查询文本 |
| `--dense-similarity-top-k <n>` | number | 否 | 稠密检索 top K |
| `--sparse-similarity-top-k <n>` | number | 否 | 稀疏检索 top K |
| `--rerank` | switch | 否 | 启用 rerank |
| `--rerank-top-n <n>` | number | 否 | rerank 返回 top N 结果 |
| `--rerank-model <name>` | string | 否 | rerank 模型名，如 `qwen3-rerank-hybrid` |
| `--rerank-mode <mode>` | string | 否 | rerank 模式：`qa`、`similar` 或 `custom` |
| `--rerank-instruct <text>` | string | 否 | 自定义 rerank 指令（`--rerank-mode custom` 时使用） |
| `--top-k <n>` | number | 否 | 返回结果数（已废弃，用 `--rerank-top-n` 替代） |
**输出**
text/quiet 模式：
```
[1] (score: 0.9512)
检索到的文本内容...
[2] (score: 0.8734)
另一段文本内容...
```
> 无结果时输出 `No results found.`
json 模式：返回 API 原始响应。
**注意事项**
- **已废弃**，推荐使用 `search` 命令。`search` 通过 agent_id 驱动检索策略，支持更多高级特性。
- `--top-k` 已废弃，使用 `--rerank-top-n` 替代，传入 `--top-k` 会输出 stderr 警告。
- 此命令直接用 `--index-id` 检索，不需要创建检索服务。
**示例**
```bash
# 基础检索
bl knowledge retrieve --index-id idx-xxx --query "How to use Alibaba Cloud Bailian" --workspace-id ws-xxx
# 启用 rerank
bl knowledge retrieve --index-id idx-xxx --query "RAG retrieval" --rerank --rerank-model qwen3-rerank-hybrid
```
---
#### `bl knowledge search`
对知识库执行语义检索（RAG 检索）。
**用法**
```bash
bl knowledge search --query <text> --agent-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| --------------------------- | ------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `--query <text>` | string | 是 | 检索查询文本（不可为空） |
| `--agent-id <id>` | string | 是 | 检索服务 ID（在控制台知识检索页面获取，或通过 `service list` 查看） |
| `--agent-version <version>` | string | 否 | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本 |
| `--image <url>` | array | 否 | 图片 URL（可重复），用于多模态检索 |
| `--query-history <json>` | string | 否 | 用户对话历史 JSON，用于上下文理解和查询改写。格式：`[{"role":"user","content":"What is RAG"},{"role":"assistant","content":"RAG is..."}]` |
**参数约束**
- `--query` 不可为空（API 要求 `minLength: 1`）
- `--query-history` 必须是合法 JSON 数组
**输出**
text/quiet 模式：
```
[1] (score: 0.9512)
检索到的文本内容...
[2] (score: 0.8734)
另一段文本内容...
```
> 无结果时输出 `No results found.`
json 模式：返回 API 原始响应，`data.nodes[]` 包含检索结果。
**注意事项**
- 检索范围和策略（多知识库加权、路由、rerank 等）由 `--agent-id` 对应的服务配置驱动。只需 `--query` 和 `--agent-id` 即可调用。
- `--query-history` 传入前序对话轮次，服务端基于上下文改写查询以提升检索相关性。
- `--agent-version beta` 调用草稿配置进行调试，部署前验证效果。
- 与 `retrieve` 的区别：`search` 通过 agent_id 间接驱动检索策略（支持多知识库、路由、rerank 等），`retrieve` 直接操作 index_id 且功能较少。
**示例**
```bash
# 基础检索
bl knowledge search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
# 多模态检索（带图片）
bl knowledge search --query "describe this image" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg
# 带对话历史的多轮检索
bl knowledge search --query "How does it work" --agent-id aid-xxx --workspace-id ws-xxx --query-history '[{"role":"user","content":"What is RAG"},{"role":"assistant","content":"RAG is retrieval-augmented generation"}]'
# 调试草稿版本
bl knowledge search --query "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
```
---
#### `bl knowledge chat`
与知识库进行 RAG 对话（流式输出）。
**用法**
```bash
bl knowledge chat --message <text> --agent-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| --------------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--message <text>` | array | 是¹ | 消息文本（可重复）。支持 `role:content` 前缀设置角色（如 `user:hello`），默认角色为 `user`。也支持完整 JSON 对象传递结构化消息 |
| `--agent-id <id>` | string | 是 | Q&A 服务 ID（在控制台知识问答页面获取，或通过 `service list --scene chat` 查看） |
| `--agent-version <version>` | string | 否 | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本 |
| `--image <url>` | array | 否 | 图片 URL（可重复）。附加到最后一条 user 消息作为多模态内容 |
> ¹ `--message` 或 `--image` 至少提供其一。纯图片查询可以只传 `--image`（CLI 会自动创建空 user 消息承载图片）。
**参数约束**
- `--message` 或 `--image` 至少提供一个
- `--image` 不能与已包含 `image_url` 内容部分的消息同时使用
**输出**
**TTY text 模式**（实时流式）：
```
🔍 Retrieving...
✍️ Generating...
这是AI生成的回答内容，逐字流式输出...
```
> 进度标签由 SSE `step_change` 事件驱动：`tool_calling`（检索中）→ `plan_start`（规划中）→ `generation_start`（生成中）。
**非 TTY text 模式**（缓冲输出）：
```
完整的回答文本...
```
**json 模式**（`--output json`）：
```json
{
"answer": "完整的回答文本...",
"request_id": "xxx"
}
```
quiet 模式：输出完整的回答文本。
**注意事项**
- API 仅支持 SSE 流式响应。TTY 环境下实时打印 token；非 TTY 环境缓冲后输出完整文本。
- SSE 事件生命周期：`tool_calling` → `tool_return` → `plan_start` → `planning` → `plan_end` → `generation_start` → `generating` → `generation_end`。`tool_calling` → `tool_return` 可能循环多次。
- 多轮对话：用 `--message "user:..."` 和 `--message "assistant:..."` 传递对话历史。
- `--agent-version beta` 调用草稿配置进行调试。
- `--image` 附加到最后一条 user 消息上。如果消息中已包含 `image_url` 内容部分，则不能再用 `--image`。
- `--verbose` 模式下，所有 SSE 事件详情会输出到 stderr。
**示例**
```bash
# 单轮对话
bl knowledge chat --message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
# 多轮对话（带历史）
bl knowledge chat \
--message "user:What is RAG?" \
--message "assistant:RAG is retrieval-augmented generation..." \
--message "How does it work?" \
--agent-id aid-xxx --workspace-id ws-xxx
# 多模态对话（带图片）
bl knowledge chat \
--message "Describe these images" \
--image https://example.com/a.png \
--image https://example.com/b.png \
--agent-id aid-xxx --workspace-id ws-xxx
# 调试草稿版本
bl knowledge chat --message "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
```
---
← [返回总览](../knowledge-cli-guide.md)
docs/knowledge/service.md
+401
View File
@@ -0,0 +1,401 @@
# 检索服务管理命令手册
检索服务（也称 agent）是知识库的检索入口。通过 `--agent-id` 在 search/chat 命令中使用。服务有 `chat`（问答）和 `search`（检索）两种场景。
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
---
#### `bl knowledge service list`
列出工作区中的检索/Q&A 服务。
**用法**
```bash
bl knowledge service list --scene <chat|search> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ------------------------ | ------ | ---- | ------------------------------------------------------- |
| `--scene <chat\|search>` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） |
| `--status <status>` | string | 否 | 按状态过滤：`draft`、`deployed`（含 edited）、`deleted` |
| `--name <text>` | string | 否 | 按服务名称模糊过滤 |
| `--agent-id <id>` | string | 否 | 按精确 agent ID 过滤 |
| `--index-id <id>` | string | 否 | 按关联知识库 ID 过滤 |
| `--page-number <n>` | number | 否 | 页码（默认：1） |
| `--page-size <n>` | number | 否 | 每页条数（默认：10，最大 100） |
**参数约束**
- `--scene` 只能是 `chat` 或 `search`
- `--status` 只能是 `draft`、`deployed`、`deleted`
- `--page-size` 范围 1-100
**输出**
text 模式：
```
aid-xxx deployed 2 my-qa (kb: my-kb)
total: 1
Use an agent_id above with the knowledge chat command.
```
> 最后一行根据 scene 自动提示用 `search` 还是 `chat` 命令消费。
quiet 模式：每行一个 `agent_id`。
json 模式：返回 API 原始响应。
**注意事项**
- 服务端要求 `--scene` 必填，要查看两种场景的服务需分别执行。
**示例**
```bash
# 列出 chat 服务
bl knowledge service list --scene chat --workspace-id ws-xxx
# 只看已部署的检索服务
bl knowledge service list --scene search --status deployed
```
---
#### `bl knowledge service get`
查看服务详情，含各版本配置。
**用法**
```bash
bl knowledge service get --agent-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| --------------------------- | ------ | ---- | --------------------------------------------------------- |
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
| `--agent-version <version>` | string | 否 | 指定版本查看（`beta` 或已发布版本号）；不传则返回所有版本 |
**输出**
text 模式：
```
Basic:
id: aid-xxx
name: my-qa
desc: product Q&A
scene: chat
status: deployed
Version beta:
desc: draft
policy: turbo
model: qwen-max
temperature: 0.7
kb: idx-xxx (my-kb)
Version 1:
published: 2026-01-01
...
```
quiet 模式：输出 JSON 格式。
json 模式：返回 API 原始响应。
**注意事项**
- 不传 `--agent-version` 时返回所有版本（beta 草稿 + 已发布版本号）。
- 版本值原样传递，有效值集合由服务端维护。
**示例**
```bash
# 查看服务完整详情
bl knowledge service get --agent-id aid-xxx --workspace-id ws-xxx
# 只看 beta 草稿配置
bl knowledge service get --agent-id aid-xxx --agent-version beta
```
---
#### `bl knowledge service create`
创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
**用法**
```bash
bl knowledge service create --name <text> --scene <chat|search> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ------------------------ | ------ | ---- | ------------------------------------------------- |
| `--name <text>` | string | 是 | 服务名称（最多 200 字符，同一场景下工作区内唯一） |
| `--scene <chat\|search>` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） |
| `--description <text>` | string | 否 | 服务描述（最多 1000 字符） |
| `--index-id <id>` | string | 否 | 绑定此知识库；其他配置使用服务端默认值 |
**参数约束**
- `--name` 最多 200 字符
- `--scene` 只能是 `chat` 或 `search`
- `--description` 最多 1000 字符
**输出**
text 模式：
```
created: aid-xxx (status: draft, version: beta)
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
```
quiet 模式：输出 agent ID。
json 模式：返回 API 原始响应。
**注意事项**
- 不指定 `--index-id` 时，服务端使用默认 agent 配置。
- beta 草稿可通过 search/chat 的 `--agent-version beta` 测试，部署后才生效。
- 需要工作区的知识库创建权限。
**示例**
```bash
# 创建 Q&A 服务
bl knowledge service create --name my-qa --scene chat --workspace-id ws-xxx
# 创建检索服务并绑定知识库
bl knowledge service create --name my-search --scene search --index-id idx-xxx
```
---
#### `bl knowledge service update`
更新服务名称、描述或草稿配置。
**用法**
```bash
bl knowledge service update --agent-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ------------------------------ | ------ | ---- | ---------------------------------------------------------------------------------------- |
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
| `--name <text>` | string | 否 | 新名称（最多 200 字符） |
| `--description <text>` | string | 否 | 新描述（最多 1000 字符） |
| `--agent-version <version>` | string | 否 | 目标版本（默认：beta 草稿。已发布版本只接受 `--version-desc`） |
| `--version-desc <text>` | string | 否 | 版本描述 |
| `--policy <policy>` | string | 否 | Agent 策略：`turbo`（快速）或 `agentic`（多轮） |
| `--model <name>` | string | 否 | 生成模型代码（须在平台白名单中） |
| `--temperature <n>` | number | 否 | 采样温度，范围 0-2 |
| `--max-llm-calls <n>` | number | 否 | 单次请求最大 LLM 调用次数，范围 1-30 |
| `--enable-session-file <bool>` | string | 否 | 启用会话文件：`true` 或 `false` |
| `--enable-refusal <bool>` | string | 否 | 启用拒答：`true` 或 `false` |
| `--enable-anti-leak <bool>` | string | 否 | 启用防泄漏：`true` 或 `false` |
| `--enable-rich-text <bool>` | string | 否 | 启用富文本输出：`true` 或 `false` |
| `--enable-citation <bool>` | string | 否 | 启用引用标注：`true` 或 `false` |
| `--config-file <path>` | string | 否 | JSON 文件替换整个 `agent_config`（含嵌套设置如 `kb_search_configs`）；与标量配置参数互斥 |
**参数约束**
- 至少提供一个更新项（`--name`/`--description`/`--version-desc`/`--config-file`/标量配置参数），否则报错 "Nothing to update"
- `--config-file` 与标量配置参数（`--policy`/`--model`/`--temperature` 等）互斥
- 已发布版本 + 配置变更 → 报错（已发布版本只接受 `--version-desc`）
- `--name` 最多 200 字符；`--description` 最多 1000 字符
- `--policy` 只能是 `turbo` 或 `agentic`
- `--temperature` 范围 0-2
- `--max-llm-calls` 范围 1-30
- 布尔参数（`--enable-*`）只能是 `true` 或 `false`
**输出**
text 模式：
```
updated: aid-xxx
Draft config changed — verify with --agent-version beta, then deploy.
```
quiet 模式：无输出。
json 模式：返回 API 原始响应。
**注意事项**
- 配置变更只作用于 beta 草稿；已发布版本只接受 `--version-desc`。
- 标量配置参数采用 read-merge-write：CLI 先读取当前 beta 配置，再合并变更后整体提交（API 是整替换语义）。
- `--config-file` 替换整个配置，适合设置嵌套字段（如 `kb_search_configs`）。
- 修改草稿后用 `--agent-version beta` 在 search/chat 上测试，通过后 `service deploy` 发布。
**示例**
```bash
# 调整温度
bl knowledge service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
# 用 JSON 文件替换整个配置
bl knowledge service update --agent-id aid-xxx --config-file ./agent-config.json
# 给已发布版本 1 加描述
bl knowledge service update --agent-id aid-xxx --agent-version 1 --version-desc "first stable release"
```
---
#### `bl knowledge service deploy`
发布 beta 草稿为新版本。
**用法**
```bash
bl knowledge service deploy --agent-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------------- | ------ | ---- | ---------------- |
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
| `--version-desc <text>` | string | 否 | 新版本的描述说明 |
| `--yes` | switch | 否 | 跳过确认提示 |
**输出**
text 模式：
```
deployed: aid-xxx version 2
```
quiet 模式：输出新版本号。
json 模式：返回 API 原始响应。
**注意事项**
- 版本号自动递增，状态变为 `deployed`。
- 发布影响线上调用方，确认提示会警告。
- 如果当前状态为 `edited`（已发布后又改了草稿），确认提示会额外警告「发布会覆盖线上行为」。
- 需要工作区的知识库修改权限。
**示例**
```bash
# 发布（交互确认）
bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx
# 带描述并跳过确认
bl knowledge service deploy --agent-id aid-xxx --version-desc "tuned rerank params" --yes
```
---
#### `bl knowledge service delete`
删除检索/Q&A 服务（软删除，幂等）。
**用法**
```bash
bl knowledge service delete --agent-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | --------------- |
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
| `--yes` | switch | 否 | 跳过确认提示 |
**输出**
text 模式：
```
deleted: aid-xxx (status: deleted)
```
quiet 模式：无输出。
json 模式：返回 API 原始响应。
**注意事项**
- 删除不可撤销，`agent_id` 不再可用于 search/chat 调用。
- API 是幂等的：删除已删除的服务不会报错。
- 如果服务状态为 `deployed` 或 `edited`，确认提示会额外警告「此服务正在线上运行」。
- 需要工作区的知识库删除权限。
**示例**
```bash
# 删除（交互确认）
bl knowledge service delete --agent-id aid-xxx --workspace-id ws-xxx
# 跳过确认
bl knowledge service delete --agent-id aid-xxx --yes
```
---
#### `bl knowledge service copy`
复制服务为新草稿（名称自动加 `copy_` 前缀）。
**用法**
```bash
bl knowledge service copy --agent-id <id> [flags]
```
**参数**
| 参数 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ----------------- |
| `--agent-id <id>` | string | 是 | 源服务（agent）ID |
**输出**
text 模式：
```
new agent_id: aid-new (name: copy_my-qa, status: draft)
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
```
quiet 模式：输出新 agent ID。
json 模式：返回 API 原始响应。
**注意事项**
- 副本初始为 beta 草稿，测试后需 deploy 发布。
- 需要工作区的知识库创建权限。
**示例**
```bash
# 复制服务
bl knowledge service copy --agent-id aid-source --workspace-id ws-xxx
```
---
← [返回总览](../knowledge-cli-guide.md)