From 30f7525d506bf6425539a4202cc3a9dce39de6e8 Mon Sep 17 00:00:00 2001 From: "zeyu.fz" Date: Thu, 13 Aug 2026 16:42:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(commands):=20=E6=9B=B4=E6=96=B0=E7=9F=A5?= =?UTF-8?q?=E8=AF=86=E5=BA=93=E5=88=86=E5=9D=97=E5=91=BD=E4=BB=A4=E4=B8=AD?= =?UTF-8?q?=20--doc-id=20=E7=9A=84=E6=8F=8F=E8=BF=B0=E5=92=8C=E6=B3=A8?= =?UTF-8?q?=E6=84=8F=E4=BA=8B=E9=A1=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 说明 --doc-id 在实际使用中为必需，避免服务器返回 HTTP 500 错误 - 明确指出应使用 doc list 命令中的文档级别 ID，拒绝使用 chunk list 中的每行 doc_id - 新增说明向图片类型文档添加文本块会触发服务器错误，建议使用文本类型文档 - 对帮助文档中相关描述和备注进行了同步更新，增强使用指导性和准确性 --- packages/commands/src/commands/knowledge/chunk-add.ts | 5 +++-- skills/bailian-cli/reference/knowledge.md | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/commands/src/commands/knowledge/chunk-add.ts b/packages/commands/src/commands/knowledge/chunk-add.ts index 0efb374..4c0dc3d 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: "", description: - "Owning document ID; required for table/image knowledge bases (the server rejects field-channel chunks without it), optional for document-type", + "Owning document ID from the doc list command; required in practice — the server returns HTTP 500 (dataId不能为空) without it even for unstructured KBs", }, content: { type: "string", @@ -74,7 +74,8 @@ export default defineCommand({ flags: CHUNK_ADD_FLAGS, notes: [ "Document / table / image knowledge bases are supported; audio-video ones are not.", - "Table/image knowledge bases require --doc-id — verified live: the server returns 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).", + "--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.", "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/skills/bailian-cli/reference/knowledge.md b/skills/bailian-cli/reference/knowledge.md index 24d351b..c6b7a25 100644 --- a/skills/bailian-cli/reference/knowledge.md +++ b/skills/bailian-cli/reference/knowledge.md @@ -206,7 +206,7 @@ bl knowledge chat --message "Describe these images" --image https://example.com/ | Flag | Type | Required | Description | | ----------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--index-id ` | string | yes | Knowledge base ID | -| `--doc-id ` | string | no | Owning document ID; required for table/image knowledge bases (the server rejects field-channel chunks without it), optional for document-type | +| `--doc-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 | | `--content ` | string | no | Chunk body text, up to 6000 chars (document-type); alternative to --content-file | | `--content-file ` | string | no | Read chunk body from a UTF-8 plain text file (.md/.txt etc.) | | `--title ` | string | no | Chunk title, up to 50 chars (document-type) | @@ -219,7 +219,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. -- Table/image knowledge bases require --doc-id — verified live: the server returns 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). +- --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. - 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.