docs(knowledge): 优化知识库文档内容及CLI说明

- 修改表格/图片知识库必须提供`--doc-id`的描述，更准确表达要求 - 调整CLI命令文档中过期或不准确信息，说明集合删除暂不支持 - 更新chunk添加命令中`--doc-id`的说明，强调对所有知识库类型均必需 - 精简chunk删除命令备注，明确批量操作自动分批处理 - 优化文档删除命令描述，强调删除异步传播及输出行为 - 修正文档状态命令中错误提示用词，更清晰表达 - 文件列表命令修改说明，明确默认分类ID不解析 - 知识库信息命令删除过时备注，突出索引设置不可变 - 服务删除命令简洁描述幂等性和权限要求 - 服务列表命令调整对场景参数的描述，明确必传要求
2026-09-14 19:49:23 +08:00 · 2026-08-14 13:40:08 +08:00
parent eb4f9af3e7
commit d5c4bd3572
12 changed files with 27 additions and 36 deletions
@@ -29,7 +29,7 @@ bl knowledge chunk add --index-id <id> (--content <text> | --field <k=v>) [flags
 | `--field <key=value>`   | array  | 否¹  | 任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥 |

 > ¹ `--content`/`--content-file`/`--title`/`--image-url` 与 `--field` 互斥，必须提供其一。
-> ² 表格/图片知识库必须提供 `--doc-id`，服务端无此字段会返回 HTTP 500（`dataId不能为空`）。文档型知识库可选。
+> ² 表格/图片知识库必须提供 `--doc-id`。文档型知识库可选。

 **参数约束**

@@ -110,7 +110,6 @@ json 模式：返回知识库完整配置 JSON。

 **注意事项**

- CLI 通过 `index/list` 的 `pipeline_id` 参数精确过滤目标知识库，单次请求即可获取详情。
 - 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。

 **示例**
@@ -776,7 +776,7 @@ bl config set workspace_id ws-xxx

 **问题**：没有 `collection delete` 命令。

-**原因**：服务端无集合删除 API。
+**原因**：暂不支持通过 CLI 删除。

 **解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。

@@ -23,7 +23,7 @@ const CHUNK_ADD_FLAGS = {
    type: "string",
    valueHint: "<id>",
    description:
-      "Owning document ID from the doc list command; required in practice — the server returns HTTP 500 (dataId不能为空) without it even for unstructured KBs",
+      "Owning document ID from the doc list command; required in practice for all knowledge base types",
  },
  content: {
    type: "string",
@@ -74,8 +74,8 @@ export default defineCommand({
  flags: CHUNK_ADD_FLAGS,
  notes: [
    "Document / table / image knowledge bases are supported; audio-video ones are not.",
-    "--doc-id is required in practice — verified live: even unstructured (document-type) KBs return HTTP 500 (dataId不能为空) without it. Use the document-level id from the doc list command; the per-row doc_id in chunk list metadata is rejected (Index.InvalidParameter).",
-    "Adding a text content chunk to an image-type document (jpg) triggers HTTP 500 (Index.SystemError) — the server does not support text chunks on image documents. Target a text-type document (docx/pdf/txt) instead.",
+    "--doc-id is required in practice for all knowledge base types. Use the document-level id from the doc list command; the per-row doc_id in chunk list output is not accepted.",
+    "Image-type documents do not support text chunks. Target a text-type document (docx/pdf/txt) instead.",
    "The API is idempotent but rate-limited to 10 calls per second — throttle batch scripts.",
    "The response carries no chunk id; list chunks afterwards to find the new one.",
    "For table/image knowledge bases use --field with Excel column headers as keys; values are passed through as strings.",
@@ -41,10 +41,7 @@ export default defineCommand({
  auth: "apiKey",
  usageArgs: "--index-id <id> --chunk-id <id> [flags]",
  flags: CHUNK_DELETE_FLAGS,
-  notes: [
-    "The server accepts at most 10 ids per call; larger sets are split into sequential batches automatically.",
-    "If a batch fails, the operation stops and already-deleted batches are listed in the error.",
-  ],
+  notes: ["Accepts at most 10 chunk ids per call; larger sets are batched automatically."],
  exampleArgs: [
    "--index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx",
    "--index-id idx-xxx --chunk-id chunk-a --yes",
@@ -43,8 +43,8 @@ export default defineCommand({
  notes: [
    "Removes documents from the knowledge base index only; the source files remain in the data center.",
    "Use the doc_id from `knowledge doc list --quiet`, not the fileId from `knowledge doc upload`. For documents created via `knowledge create --doc-id`, the doc_id equals the fileId; for documents imported via `knowledge doc upload --index-id`, the doc_id may include a workspace suffix.",
-    "Deletion is asynchronous: the server returns Success immediately, but the document may still appear in `knowledge doc list` for up to ~30s until the change propagates.",
-    "The output lists the ids actually deleted as reported by the server.",
+    "Deletion may take up to ~30s to propagate — the document may still appear in the doc list briefly.",
+    "The output lists the ids actually deleted.",
  ],
  exampleArgs: [
    "--index-id idx-xxx --doc-id file-xxx --workspace-id ws-xxx",
@@ -57,9 +57,9 @@ export default defineCommand({
  usageArgs: "--index-id <id> --job-id <id> [flags]",
  flags: DOC_STATUS_FLAGS,
  notes: [
-    "Both --index-id and --job-id are required by the server (passing only one returns SystemError).",
-    "If the server returns SystemError for an idle knowledge base, the job may not exist — check the ingestion id in the document list output.",
-    "Overall job states are PENDING / RUNNING / COMPLETED; per-document failures (for example PARSE_FAILED) exit non-zero with the server message passed through.",
+    "Both --index-id and --job-id are required (passing only one returns SystemError).",
+    "If you see a SystemError, the job may not exist — check the ingestion id in the document list output.",
+    "Overall job states are PENDING / RUNNING / COMPLETED; per-document failures (for example PARSE_FAILED) exit non-zero with the error message passed through.",
  ],
  exampleArgs: [
    "--index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx",
@@ -45,7 +45,7 @@ export default defineCommand({
  usageArgs: "--category-id <id> [flags]",
  flags: FILE_LIST_FLAGS,
  notes: [
-    "The server requires a real category id here — unlike upload APIs, the literal default is NOT resolved (returns an empty list). Find the id via file details of any uploaded file, or the category list command.",
+    "A real category id is required — the default value is not resolved here. Find the id via the category list command.",
    "Pagination is cursor-based: reuse the printed next token to continue.",
  ],
  exampleArgs: [
@@ -65,10 +65,7 @@ export default defineCommand({
  auth: "apiKey",
  usageArgs: "--index-id <id> [flags]",
  flags: KB_INFO_FLAGS,
-  notes: [
-    "Uses the index/list API with pipeline_id filtering to fetch a single knowledge base.",
-    "Indexing settings are immutable; changing them requires recreating the knowledge base.",
-  ],
+  notes: ["Indexing settings are immutable; changing them requires recreating the knowledge base."],
  exampleArgs: ["--index-id idx-xxx --workspace-id ws-xxx"],
  async run(ctx) {
    const { settings, flags } = ctx;
@@ -58,7 +58,7 @@ export default defineCommand({
  flags: SERVICE_DELETE_FLAGS,
  notes: [
    "Deletion cannot be undone; the agent_id becomes unusable for search and chat calls.",
-    "The API is idempotent — deleting an already-deleted service does not fail.",
+    "Idempotent — deleting an already-deleted service does not fail.",
    "Requires the knowledge-base delete permission in the workspace.",
  ],
  exampleArgs: ["--agent-id aid-xxx --workspace-id ws-xxx", "--agent-id aid-xxx --yes"],
@@ -49,7 +49,7 @@ export default defineCommand({
  usageArgs: "--scene <chat|search> [flags]",
  flags: SERVICE_LIST_FLAGS,
  notes: [
-    "The server requires a scene — run once per scene to see both chat and search services.",
+    "A scene (chat or search) is required — run once per scene to see both.",
    "Use the returned agent_id with the search or chat commands, or with service management commands.",
  ],
  exampleArgs: ["--scene chat --workspace-id ws-xxx", "--scene search --status deployed"],
@@ -211,7 +211,7 @@ bl knowledge chat --message "Describe these images" --image https://example.com/
 | Flag                    | Type   | Required | Description                                                                                                                                               |
 | ----------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--index-id <id>`       | string | yes      | Knowledge base ID                                                                                                                                         |
-| `--doc-id <id>`         | string | no       | Owning document ID from the doc list command; required in practice — the server returns HTTP 500 (dataId不能为空) without it even for unstructured KBs    |
+| `--doc-id <id>`         | string | no       | Owning document ID from the doc list command; required in practice for all knowledge base types                                                           |
 | `--content <text>`      | string | no       | Chunk body text, up to 6000 chars (document-type); alternative to --content-file                                                                          |
 | `--content-file <path>` | string | no       | Read chunk body from a UTF-8 plain text file (.md/.txt etc.)                                                                                              |
 | `--title <text>`        | string | no       | Chunk title, up to 50 chars (document-type)                                                                                                               |
@@ -224,8 +224,8 @@ bl knowledge chat --message "Describe these images" --image https://example.com/
 #### Notes

 - Document / table / image knowledge bases are supported; audio-video ones are not.
- --doc-id is required in practice — verified live: even unstructured (document-type) KBs return HTTP 500 (dataId不能为空) without it. Use the document-level id from the doc list command; the per-row doc_id in chunk list metadata is rejected (Index.InvalidParameter).
- Adding a text content chunk to an image-type document (jpg) triggers HTTP 500 (Index.SystemError) — the server does not support text chunks on image documents. Target a text-type document (docx/pdf/txt) instead.
+- --doc-id is required in practice for all knowledge base types. Use the document-level id from the doc list command; the per-row doc_id in chunk list output is not accepted.
+- Image-type documents do not support text chunks. Target a text-type document (docx/pdf/txt) instead.
 - The API is idempotent but rate-limited to 10 calls per second — throttle batch scripts.
 - The response carries no chunk id; list chunks afterwards to find the new one.
 - For table/image knowledge bases use --field with Excel column headers as keys; values are passed through as strings.
@@ -262,8 +262,7 @@ bl knowledge chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2

 #### Notes

- The server accepts at most 10 ids per call; larger sets are split into sequential batches automatically.
- If a batch fails, the operation stops and already-deleted batches are listed in the error.
+- Accepts at most 10 chunk ids per call; larger sets are batched automatically.

 #### Examples

@@ -517,8 +516,8 @@ bl knowledge delete --index-id idx-xxx --yes

 - Removes documents from the knowledge base index only; the source files remain in the data center.
 - Use the doc_id from `knowledge doc list --quiet`, not the fileId from `knowledge doc upload`. For documents created via `knowledge create --doc-id`, the doc_id equals the fileId; for documents imported via `knowledge doc upload --index-id`, the doc_id may include a workspace suffix.
- Deletion is asynchronous: the server returns Success immediately, but the document may still appear in `knowledge doc list` for up to ~30s until the change propagates.
- The output lists the ids actually deleted as reported by the server.
+- Deletion may take up to ~30s to propagate — the document may still appear in the doc list briefly.
+- The output lists the ids actually deleted.

 #### Examples

@@ -629,9 +628,9 @@ bl knowledge doc list --index-id idx-xxx --page-size 100

 #### Notes

- Both --index-id and --job-id are required by the server (passing only one returns SystemError).
- If the server returns SystemError for an idle knowledge base, the job may not exist — check the ingestion id in the document list output.
- Overall job states are PENDING / RUNNING / COMPLETED; per-document failures (for example PARSE_FAILED) exit non-zero with the server message passed through.
+- Both --index-id and --job-id are required (passing only one returns SystemError).
+- If you see a SystemError, the job may not exist — check the ingestion id in the document list output.
+- Overall job states are PENDING / RUNNING / COMPLETED; per-document failures (for example PARSE_FAILED) exit non-zero with the error message passed through.

 #### Examples

@@ -808,7 +807,7 @@ bl knowledge file get --file-id file-xxx --workspace-id ws-xxx

 #### Notes

- The server requires a real category id here — unlike upload APIs, the literal default is NOT resolved (returns an empty list). Find the id via file details of any uploaded file, or the category list command.
+- A real category id is required — the default value is not resolved here. Find the id via the category list command.
 - Pagination is cursor-based: reuse the printed next token to continue.

 #### Examples
@@ -841,7 +840,6 @@ bl knowledge file list --category-id cate-xxx --name report

 #### Notes

- Uses the index/list API with pipeline_id filtering to fetch a single knowledge base.
 - Indexing settings are immutable; changing them requires recreating the knowledge base.

 #### Examples
@@ -1048,7 +1046,7 @@ bl knowledge service create --name my-search --scene search --index-id idx-xxx
 #### Notes

 - Deletion cannot be undone; the agent_id becomes unusable for search and chat calls.
- The API is idempotent — deleting an already-deleted service does not fail.
+- Idempotent — deleting an already-deleted service does not fail.
 - Requires the knowledge-base delete permission in the workspace.

 #### Examples
@@ -1157,7 +1155,7 @@ bl knowledge service get --agent-id aid-xxx --agent-version beta

 #### Notes

- The server requires a scene — run once per scene to see both chat and search services.
+- A scene (chat or search) is required — run once per scene to see both.
 - Use the returned agent_id with the search or chat commands, or with service management commands.

 #### Examples