diff --git a/docs/knowledge/chunk.md b/docs/knowledge/chunk.md
index 83c4fdb..378ee80 100644
--- a/docs/knowledge/chunk.md
+++ b/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`。文档型知识库可选。
 
 **参数约束**
 
diff --git a/docs/knowledge/kb.md b/docs/knowledge/kb.md
index 54147ea..25fcf5e 100644
--- a/docs/knowledge/kb.md
+++ b/docs/knowledge/kb.md
@@ -110,7 +110,6 @@ json 模式：返回知识库完整配置 JSON。
 
 **注意事项**
 
-- CLI 通过 `index/list` 的 `pipeline_id` 参数精确过滤目标知识库，单次请求即可获取详情。
 - 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
 
 **示例**
diff --git a/docs/knowledge/knowledge-cli-guide.md b/docs/knowledge/knowledge-cli-guide.md
index 1ce8c61..04ae639 100644
--- a/docs/knowledge/knowledge-cli-guide.md
+++ b/docs/knowledge/knowledge-cli-guide.md
@@ -776,7 +776,7 @@ bl config set workspace_id ws-xxx
 
 **问题**：没有 `collection delete` 命令。
 
-**原因**：服务端无集合删除 API。
+**原因**：暂不支持通过 CLI 删除。
 
 **解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。
 
diff --git a/packages/commands/src/commands/knowledge/chunk-add.ts b/packages/commands/src/commands/knowledge/chunk-add.ts
index 4c0dc3d..de4eb50 100644
--- a/packages/commands/src/commands/knowledge/chunk-add.ts
+++ b/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.",
diff --git a/packages/commands/src/commands/knowledge/chunk-delete.ts b/packages/commands/src/commands/knowledge/chunk-delete.ts
index 83433f0..36f70ae 100644
--- a/packages/commands/src/commands/knowledge/chunk-delete.ts
+++ b/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",
diff --git a/packages/commands/src/commands/knowledge/doc-delete.ts b/packages/commands/src/commands/knowledge/doc-delete.ts
index 1b8681a..356399a 100644
--- a/packages/commands/src/commands/knowledge/doc-delete.ts
+++ b/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",
diff --git a/packages/commands/src/commands/knowledge/doc-status.ts b/packages/commands/src/commands/knowledge/doc-status.ts
index 08e7a6d..c48fa7e 100644
--- a/packages/commands/src/commands/knowledge/doc-status.ts
+++ b/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",
diff --git a/packages/commands/src/commands/knowledge/file-list.ts b/packages/commands/src/commands/knowledge/file-list.ts
index af40e65..0b41d88 100644
--- a/packages/commands/src/commands/knowledge/file-list.ts
+++ b/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: [
diff --git a/packages/commands/src/commands/knowledge/kb-info.ts b/packages/commands/src/commands/knowledge/kb-info.ts
index cc62b6c..cbb1dc1 100644
--- a/packages/commands/src/commands/knowledge/kb-info.ts
+++ b/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;
diff --git a/packages/commands/src/commands/knowledge/service-delete.ts b/packages/commands/src/commands/knowledge/service-delete.ts
index 302a124..5725cef 100644
--- a/packages/commands/src/commands/knowledge/service-delete.ts
+++ b/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"],
diff --git a/packages/commands/src/commands/knowledge/service-list.ts b/packages/commands/src/commands/knowledge/service-list.ts
index 5575034..44e62f2 100644
--- a/packages/commands/src/commands/knowledge/service-list.ts
+++ b/packages/commands/src/commands/knowledge/service-list.ts
@@ -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"],
diff --git a/skills/bailian-cli/reference/knowledge.md b/skills/bailian-cli/reference/knowledge.md
index 1f14e12..970f765 100644
--- a/skills/bailian-cli/reference/knowledge.md
+++ b/skills/bailian-cli/reference/knowledge.md
@@ -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