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

- 修改表格/图片知识库必须提供`--doc-id`的描述，更准确表达要求
- 调整CLI命令文档中过期或不准确信息，说明集合删除暂不支持
- 更新chunk添加命令中`--doc-id`的说明，强调对所有知识库类型均必需
- 精简chunk删除命令备注，明确批量操作自动分批处理
- 优化文档删除命令描述，强调删除异步传播及输出行为
- 修正文档状态命令中错误提示用词，更清晰表达
- 文件列表命令修改说明，明确默认分类ID不解析
- 知识库信息命令删除过时备注，突出索引设置不可变
- 服务删除命令简洁描述幂等性和权限要求
- 服务列表命令调整对场景参数的描述，明确必传要求

Author: clark-fc

docs/knowledge/chunk.md

@@ -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`。文档型知识库可选。
 
 **参数约束**
 

docs/knowledge/kb.md

@@ -110,7 +110,6 @@ json 模式：返回知识库完整配置 JSON。
 
 **注意事项**
 
-- CLI 通过 `index/list` 的 `pipeline_id` 参数精确过滤目标知识库，单次请求即可获取详情。
 - 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
 
 **示例**

docs/knowledge/knowledge-cli-guide.md

@@ -776,7 +776,7 @@ bl config set workspace_id ws-xxx
 
 **问题**：没有 `collection delete` 命令。
 
-**原因**：服务端无集合删除 API。
+**原因**：暂不支持通过 CLI 删除。
 
 **解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。
 

packages/commands/src/commands/knowledge/chunk-add.ts

@@ -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.",

packages/commands/src/commands/knowledge/chunk-delete.ts

@@ -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",

packages/commands/src/commands/knowledge/doc-delete.ts

@@ -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",

packages/commands/src/commands/knowledge/doc-status.ts

@@ -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",

packages/commands/src/commands/knowledge/file-list.ts

@@ -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: [

packages/commands/src/commands/knowledge/kb-info.ts

@@ -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;

packages/commands/src/commands/knowledge/service-delete.ts

@@ -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"],