From a6291e00e10fc24a768d8088aa162be174082e50 Mon Sep 17 00:00:00 2001 From: "zeyu.fz" Date: Sat, 22 Aug 2026 11:21:22 +0800 Subject: [PATCH 1/4] =?UTF-8?q?docs(knowledge):=20=E5=BC=BA=E5=88=B6?= =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E7=9F=A5=E8=AF=86=E5=BA=93=E6=8F=8F=E8=BF=B0?= =?UTF-8?q?=E5=8F=82=E6=95=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 升级知识库创建命令，`--description` 参数变为必填，描述知识库内容和用途 - 更新所有相关文档示例，统一加入 `--description` 参数和示例文本 - CLI 校验增强，缺失或超长的描述参数本地报错，避免服务端拒绝 - 优化服务创建命令，推荐填写描述以帮助 agent 选择合适服务 - 多个测试用例添加对描述参数的验证和断言 - 知识库和集合列表中描述信息作为区分同类项目的辅助信息显式展示 - 其他细节调整包括命令帮助及参数说明内容的更新 --- docs/knowledge/kb.md | 10 +- docs/knowledge/knowledge-cli-guide.md | 4 +- docs/knowledge/service.md | 4 +- .../commands/knowledge/collection-create.ts | 5 +- .../src/commands/knowledge/kb-create.ts | 28 ++++- .../src/commands/knowledge/retrieve.ts | 7 ++ .../src/commands/knowledge/service-create.ts | 12 +- .../src/commands/knowledge/service-list.ts | 4 +- .../src/commands/knowledge/service-update.ts | 9 ++ .../e2e/knowledge/journeys/journey-helpers.ts | 2 + .../knowledge-chunk-category-file.e2e.test.ts | 9 +- .../knowledge-doc-status.e2e.test.ts | 2 + .../knowledge/knowledge-kb-create.e2e.test.ts | 50 ++++++++ .../knowledge/knowledge-kb-delete.e2e.test.ts | 2 + .../knowledge/knowledge-service.e2e.test.ts | 41 ++++++- .../tests/e2e/knowledge/knowledge.e2e.test.ts | 7 +- .../tests/e2e/knowledge/verified-models.ts | 36 ++++++ packages/core/src/types/knowledge-admin.ts | 11 ++ packages/kscli/README.md | 1 + packages/kscli/README.zh.md | 1 + skills/bailian-cli/reference/knowledge.md | 109 +++++++++--------- 21 files changed, 275 insertions(+), 79 deletions(-) create mode 100644 packages/commands/tests/e2e/knowledge/verified-models.ts diff --git a/docs/knowledge/kb.md b/docs/knowledge/kb.md index 25fcf5e1e..25a9b35b4 100644 --- a/docs/knowledge/kb.md +++ b/docs/knowledge/kb.md @@ -128,7 +128,7 @@ bl knowledge info --index-id idx-xxx --workspace-id ws-xxx **用法** ```bash -bl knowledge create --name (--doc-id | --category-id ) [flags] +bl knowledge create --name --description (--doc-id | --category-id ) [flags] ``` **参数** @@ -136,6 +136,7 @@ bl knowledge create --name (--doc-id | --category-id ) [flags] | 参数 | 类型 | 必填 | 说明 | | --------------------------- | ------ | ---- | -------------------------------------------------------- | | `--name ` | string | 是 | 知识库名称（1-20 字符，工作区内唯一） | +| `--description ` | string | 是 | 知识库装了什么内容、给谁用（1-200 字符） | | `--doc-id ` | array | 否¹ | 数据中心文件 ID（可重复）；与 `--category-id` 互斥 | | `--category-id ` | array | 否¹ | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 | | `--embedding-model ` | string | 否 | 向量模型名称（默认：`text-embedding-v4`） | @@ -148,6 +149,7 @@ bl knowledge create --name (--doc-id | --category-id ) [flags] **参数约束** - `--name` 长度 1-20 字符 +- `--description` 长度 1-200 字符，缺失或超长会在本地被拦截 - `--doc-id` 和 `--category-id` 互斥，必须提供其一 **输出** @@ -176,13 +178,13 @@ json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和 ```bash # 从指定文件创建知识库 -bl knowledge create --name demo --doc-id file-xxx --workspace-id ws-xxx +bl knowledge create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx # 从分类导入并等待导入完成 -bl knowledge create --name demo --category-id cate-xxx --wait +bl knowledge create --name demo --description '产品文档' --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 create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx ``` --- diff --git a/docs/knowledge/knowledge-cli-guide.md b/docs/knowledge/knowledge-cli-guide.md index 04ae6394f..5080938ff 100644 --- a/docs/knowledge/knowledge-cli-guide.md +++ b/docs/knowledge/knowledge-cli-guide.md @@ -153,7 +153,7 @@ 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 +bl knowledge create --name my-kb --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx --wait # → 返回 index-id (pipelineId) 和导入任务状态 # 3. 创建检索服务（search 场景） @@ -245,7 +245,7 @@ bl knowledge doc import-oss \ # → 返回各文件的 fileId # 2. 创建知识库并导入这些文件 -bl knowledge create --name oss-kb --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait +bl knowledge create --name oss-kb --description 'OSS 导入文档' --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 diff --git a/docs/knowledge/service.md b/docs/knowledge/service.md index d0d06372c..a4cb2d61d 100644 --- a/docs/knowledge/service.md +++ b/docs/knowledge/service.md @@ -142,14 +142,14 @@ bl knowledge service create --name --scene [flags] | ------------------------ | ------ | ---- | ------------------------------------------------- | | `--name ` | string | 是 | 服务名称（最多 200 字符，同一场景下工作区内唯一） | | `--scene ` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） | -| `--description ` | string | 否 | 服务描述（最多 1000 字符） | +| `--description ` | string | 建议 | 这个服务能回答什么、给谁用（最多 1000 字符） | | `--index-id ` | string | 否 | 绑定此知识库；其他配置使用服务端默认值 | **参数约束** - `--name` 最多 200 字符 - `--scene` 只能是 `chat` 或 `search` -- `--description` 最多 1000 字符 +- `--description` 最多 1000 字符；建议填写 —— agent 靠它判断该调用哪个服务 **输出** diff --git a/packages/commands/src/commands/knowledge/collection-create.ts b/packages/commands/src/commands/knowledge/collection-create.ts index 2db8031e8..818e620dd 100644 --- a/packages/commands/src/commands/knowledge/collection-create.ts +++ b/packages/commands/src/commands/knowledge/collection-create.ts @@ -20,8 +20,9 @@ const COLLECTION_CREATE_FLAGS = { type: "string", valueHint: "", description: { - "en-US": "Collection description (required by the server)", - "zh-CN": "数据集合描述（服务端必填）", + "en-US": + "What this collection holds and what it is for — tells collections apart in the list", + "zh-CN": "数据集合装了什么内容、给谁用，用于在列表中区分同类集合", }, required: true, }, diff --git a/packages/commands/src/commands/knowledge/kb-create.ts b/packages/commands/src/commands/knowledge/kb-create.ts index 25aa960ab..794f3ecc8 100644 --- a/packages/commands/src/commands/knowledge/kb-create.ts +++ b/packages/commands/src/commands/knowledge/kb-create.ts @@ -29,6 +29,16 @@ const KB_CREATE_FLAGS = { }, required: true, }, + description: { + type: "string", + valueHint: "", + description: { + "en-US": + "What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-200 chars)", + "zh-CN": "知识库装了什么内容、给谁用，用于在 Workspace 列表中区分同类知识库（1–200 个字符）", + }, + required: true, + }, docId: { type: "array", valueHint: "", @@ -107,7 +117,7 @@ export default defineCommand({ "zh-CN": "创建知识库并导入数据中心文件或类目", }, auth: "apiKey", - usageArgs: "--name (--doc-id | --category-id ) [flags]", + usageArgs: "--name --description (--doc-id | --category-id ) [flags]", flags: KB_CREATE_FLAGS, notes: [ { @@ -126,11 +136,20 @@ export default defineCommand({ }, ], exampleArgs: [ - "--name demo --doc-id file-xxx --workspace-id ws-xxx", - "--name demo --category-id cate-xxx --wait", + { + "en-US": "--name demo --description 'product docs' --doc-id file-xxx --workspace-id ws-xxx", + "zh-CN": "--name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx", + }, + { + "en-US": "--name demo --description 'product docs' --category-id cate-xxx --wait", + "zh-CN": "--name demo --description '产品文档' --category-id cate-xxx --wait", + }, ], validate(flags) { if (flags.name.length < 1 || flags.name.length > 20) return "--name must be 1-20 characters"; + if (flags.description.length < 1 || flags.description.length > 200) { + return "--description must be 1-200 characters"; + } const hasDocIds = !!flags.docId?.length; const hasCategoryIds = !!flags.categoryId?.length; if (hasDocIds && hasCategoryIds) return "Use either --doc-id or --category-id, not both"; @@ -147,6 +166,9 @@ export default defineCommand({ // Note: the public docs' example uses sinkType DEFAULT, but BUILT_IN is what works against the live API. const body = { name: flags.name, + // The server enforces description as a required 1-200 char field (the public + // API docs still list it as absent from CreateIndexV2Request.required). + description: flags.description, structureType: "unstructured", sinkType: "BUILT_IN", embeddingModelName: flags.embeddingModel ?? "text-embedding-v4", diff --git a/packages/commands/src/commands/knowledge/retrieve.ts b/packages/commands/src/commands/knowledge/retrieve.ts index 26c8a5bfd..d8dae1a0f 100644 --- a/packages/commands/src/commands/knowledge/retrieve.ts +++ b/packages/commands/src/commands/knowledge/retrieve.ts @@ -82,6 +82,13 @@ export default defineCommand({ auth: "apiKey", usageArgs: "--index-id --query [flags]", flags: RETRIEVE_FLAGS, + notes: [ + { + "en-US": + "--rerank-model requires the target knowledge base to already have a rerank model configured; otherwise every value is rejected.", + "zh-CN": "--rerank-model 要求目标知识库已配置重排序模型，否则任何取值都会被拒绝。", + }, + ], exampleArgs: [ { "en-US": '--index-id idx_xxx --query "How to use Alibaba Cloud Bailian"', diff --git a/packages/commands/src/commands/knowledge/service-create.ts b/packages/commands/src/commands/knowledge/service-create.ts index 0609b1134..d0947d2b1 100644 --- a/packages/commands/src/commands/knowledge/service-create.ts +++ b/packages/commands/src/commands/knowledge/service-create.ts @@ -32,8 +32,10 @@ const SERVICE_CREATE_FLAGS = { type: "string", valueHint: "", description: { - "en-US": "Service description (up to 1000 chars)", - "zh-CN": "服务描述（最多 1000 个字符）", + "en-US": + "What this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars)", + "zh-CN": + "这个服务能回答什么、给谁用 —— 建议填写：agent 靠它判断该调用哪个服务（最多 1000 个字符）", }, }, indexId: { @@ -71,7 +73,11 @@ export default defineCommand({ }, ], exampleArgs: [ - "--name my-qa --scene chat --workspace-id ws-xxx", + { + "en-US": + "--name my-qa --scene chat --description 'answers product FAQs' --workspace-id ws-xxx", + "zh-CN": "--name my-qa --scene chat --description '回答产品常见问题' --workspace-id ws-xxx", + }, "--name my-search --scene search --index-id idx-xxx", ], validate(flags) { diff --git a/packages/commands/src/commands/knowledge/service-list.ts b/packages/commands/src/commands/knowledge/service-list.ts index 32fdfa44b..a3c346a67 100644 --- a/packages/commands/src/commands/knowledge/service-list.ts +++ b/packages/commands/src/commands/knowledge/service-list.ts @@ -14,8 +14,8 @@ const SERVICE_LIST_FLAGS = { type: "string", valueHint: "", description: { - "en-US": "Service scene: chat (Q&A) or search (retrieval). Required by the server", - "zh-CN": "服务场景：chat（问答）或 search（检索），服务端必填", + "en-US": "Service scene: chat (Q&A) or search (retrieval)", + "zh-CN": "服务场景：chat（问答）或 search（检索）", }, required: true, }, diff --git a/packages/commands/src/commands/knowledge/service-update.ts b/packages/commands/src/commands/knowledge/service-update.ts index bc41d2b79..e1ff67d97 100644 --- a/packages/commands/src/commands/knowledge/service-update.ts +++ b/packages/commands/src/commands/knowledge/service-update.ts @@ -201,6 +201,15 @@ const KNOWN_CONFIG_KEYS = new Set([ "session_file_max_parse_length", "enable_kb_router", "kb_router_model", + "user_system_prompt", + "anti_leak_prompt", + "refusal_prompt", + "credibility_prompt", + "enable_thinking", + "enable_temperature", + "enable_credibility", + "enable_max_completion_tokens", + "session_file_parse_mode", "rerank_top_n", "hybrid_rerank", "kb_search_configs", diff --git a/packages/commands/tests/e2e/knowledge/journeys/journey-helpers.ts b/packages/commands/tests/e2e/knowledge/journeys/journey-helpers.ts index 192b41077..9ec77a25a 100644 --- a/packages/commands/tests/e2e/knowledge/journeys/journey-helpers.ts +++ b/packages/commands/tests/e2e/knowledge/journeys/journey-helpers.ts @@ -323,6 +323,8 @@ export async function createKbWithDocs( "create", "--name", kbName, + "--description", + `journey ${journeyId} fixture knowledge base (safe to delete)`, ...fileIds.flatMap((fileId) => ["--doc-id", fileId]), "--workspace-id", workspaceId, diff --git a/packages/commands/tests/e2e/knowledge/knowledge-chunk-category-file.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-chunk-category-file.e2e.test.ts index fc00111da..ef3e4a604 100644 --- a/packages/commands/tests/e2e/knowledge/knowledge-chunk-category-file.e2e.test.ts +++ b/packages/commands/tests/e2e/knowledge/knowledge-chunk-category-file.e2e.test.ts @@ -18,6 +18,7 @@ import { KNOWLEDGE_KB_DELETE_ROUTES, } from "../topic-routes.ts"; import { deleteKbWithRetry, pollUntil } from "./journeys/journey-helpers.ts"; +import { VERIFIED_RERANK_MODEL } from "./verified-models.ts"; interface DryRunBody { endpoint?: string; @@ -1058,6 +1059,8 @@ describe.skipIf(!isKbAdminE2EReady())( "create", "--name", `e2e-cate-kb-${Date.now() % 100000000}`.slice(0, 20), + "--description", + "e2e fixture knowledge base (safe to delete)", "--category-id", categoryId, "--workspace-id", @@ -1158,6 +1161,8 @@ describe.skipIf(!isKbAdminE2EReady())( "create", "--name", `e2e-ck-${Date.now() % 100000000}`, + "--description", + "e2e fixture knowledge base (safe to delete)", "--doc-id", fileId, "--workspace-id", @@ -1319,7 +1324,7 @@ describe.skipIf(!isKbAdminE2EReady())( "chunk chain fixture", "--rerank", "--rerank-model", - "qwen3-rerank-hybrid", + VERIFIED_RERANK_MODEL, "--rerank-mode", "similar", "--rerank-top-n", @@ -1701,6 +1706,8 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: chunk/category/file 参数补全 (li "create", "--name", `e2e-pk-${Date.now() % 100000000}`.slice(0, 20), + "--description", + "e2e fixture knowledge base (safe to delete)", "--doc-id", fileId, "--workspace-id", diff --git a/packages/commands/tests/e2e/knowledge/knowledge-doc-status.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-doc-status.e2e.test.ts index 31517ebb2..6b98c4b6d 100644 --- a/packages/commands/tests/e2e/knowledge/knowledge-doc-status.e2e.test.ts +++ b/packages/commands/tests/e2e/knowledge/knowledge-doc-status.e2e.test.ts @@ -148,6 +148,8 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge doc status (live, 自清 "create", "--name", `e2e-st-${Date.now() % 100000000}`, + "--description", + "e2e fixture knowledge base (safe to delete)", "--doc-id", fileIdA, "--workspace-id", diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts index 651ee64fc..af144b4cd 100644 --- a/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts +++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts @@ -5,6 +5,7 @@ import { KNOWLEDGE_KB_CREATE_ROUTES } from "../topic-routes.ts"; interface DryRunBody { endpoint?: string; request?: { + description?: string; sourceType?: string; sinkType?: string; docIds?: string[]; @@ -23,6 +24,7 @@ describe("e2e: knowledge kb create", () => { ]); expect(exitCode, stderr).toBe(0); expect(stderr).toMatch(/--name/i); + expect(stderr).toMatch(/--description/i); expect(stderr).toMatch(/--doc-id/i); expect(stderr).toMatch(/--category-id/i); expect(stderr).toMatch(/--embedding-model/i); @@ -33,6 +35,40 @@ describe("e2e: knowledge kb create", () => { const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [ "knowledge", "create", + "--description", + "demo base", + "--doc-id", + "file_test", + "--workspace-id", + "ws_test", + ]); + expect(exitCode).toBe(2); + }); + + // The server rejects a missing description with HTTP 400 (Index.InvalidParameter); + // the CLI must stop it locally instead. + test("缺 --description 报 USAGE (2)", async () => { + const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [ + "knowledge", + "create", + "--name", + "demo", + "--doc-id", + "file_test", + "--workspace-id", + "ws_test", + ]); + expect(exitCode).toBe(2); + }); + + test("--description 201 字符报 USAGE (2)", async () => { + const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [ + "knowledge", + "create", + "--name", + "demo", + "--description", + "x".repeat(201), "--doc-id", "file_test", "--workspace-id", @@ -47,6 +83,8 @@ describe("e2e: knowledge kb create", () => { "create", "--name", "demo", + "--description", + "demo base", "--workspace-id", "ws_test", ]); @@ -59,6 +97,8 @@ describe("e2e: knowledge kb create", () => { "create", "--name", "demo", + "--description", + "demo base", "--doc-id", "file_test", "--category-id", @@ -75,6 +115,8 @@ describe("e2e: knowledge kb create", () => { "create", "--name", "x".repeat(21), + "--description", + "demo base", "--doc-id", "file_test", "--workspace-id", @@ -89,6 +131,8 @@ describe("e2e: knowledge kb create", () => { "create", "--name", "demo", + "--description", + "demo base", "--doc-id", "file_test", "--workspace-id", @@ -103,6 +147,8 @@ describe("e2e: knowledge kb create", () => { expect(data.request?.sourceType).toBe("DATA_CENTER_FILE"); expect(data.request?.docIds).toEqual(["file_test"]); expect(data.request?.sinkType).toBe("BUILT_IN"); + // description is a server-required field — it must reach the request body verbatim + expect(data.request?.description).toBe("demo base"); // Defaults are part of the contract — the server applies no fallback of its own expect(data.request?.embeddingModelName).toBe("text-embedding-v4"); expect(data.request?.chunkSize).toBe(600); @@ -114,6 +160,8 @@ describe("e2e: knowledge kb create", () => { "create", "--name", "demo", + "--description", + "demo base", "--doc-id", "file_test", "--embedding-model", @@ -138,6 +186,8 @@ describe("e2e: knowledge kb create", () => { "create", "--name", "demo", + "--description", + "demo base", "--category-id", "cate_test", "--workspace-id", diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-delete.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-delete.e2e.test.ts index d19bce905..04629e751 100644 --- a/packages/commands/tests/e2e/knowledge/knowledge-kb-delete.e2e.test.ts +++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-delete.e2e.test.ts @@ -101,6 +101,8 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge kb 写链路 (live, 自清 "create", "--name", kbName, + "--description", + "e2e fixture knowledge base (safe to delete)", "--doc-id", fileId, "--workspace-id", diff --git a/packages/commands/tests/e2e/knowledge/knowledge-service.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-service.e2e.test.ts index 1d35d5781..5f60768cf 100644 --- a/packages/commands/tests/e2e/knowledge/knowledge-service.e2e.test.ts +++ b/packages/commands/tests/e2e/knowledge/knowledge-service.e2e.test.ts @@ -7,6 +7,7 @@ import { join } from "node:path"; import { describe, expect, test } from "vite-plus/test"; import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts"; import { KNOWLEDGE_SERVICE_ROUTES } from "../topic-routes.ts"; +import { pickDifferentAgentModel } from "./verified-models.ts"; interface DryRunBody { endpoint?: string; @@ -780,6 +781,33 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge service 参数全覆盖 (l expect(listIndexIdRun.exitCode, listIndexIdRun.stderr).toBe(0); // ── P0 组1: update --name --version-desc --model → get 读回 3 个 scalar ── + // --model 取值自适应：先读回草稿当前模型，再挑一个不同的已验证模型写入, + // 断言才能证明「值真的变了」而不是把默认值原样写回 + const baselineGetRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [ + "knowledge", + "service", + "get", + "--agent-id", + agentId, + "--agent-version", + "beta", + "--workspace-id", + workspaceId, + "--output", + "json", + ]); + expect(baselineGetRun.exitCode, baselineGetRun.stderr).toBe(0); + const baselineModel = parseStdoutJson<{ + data?: { agent_details?: Array<{ agent_config?: { agent_model?: string } }> }; + }>(baselineGetRun.stdout).data?.agent_details?.[0]?.agent_config?.agent_model; + const targetModel = pickDifferentAgentModel(baselineModel); + if (targetModel === undefined) { + // 白名单缩到只剩当前模型 —— 跳过模型断言而不是断言一个空操作 + process.stderr.write( + `skip --model assertion: no verified model differs from ${baselineModel}\n`, + ); + } + const newName = `${serviceName}-renamed`; const updateScalarRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [ "knowledge", @@ -791,8 +819,7 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge service 参数全覆盖 (l newName, "--version-desc", "beta-v1", - "--model", - "qwen-plus", + ...(targetModel === undefined ? [] : ["--model", targetModel]), "--workspace-id", workspaceId, ]); @@ -816,14 +843,18 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge service 参数全覆盖 (l data?: { agent_name?: string; agent_details?: Array<{ - agent_version_desc?: string; + agent_version_desc?: string | null; agent_config?: { agent_model?: string }; }>; }; }>(scalarGetRun.stdout); expect(scalarGetData.data?.agent_name).toBe(newName); - expect(scalarGetData.data?.agent_details?.[0]?.agent_config?.agent_model).toBe("qwen-plus"); - expect(scalarGetData.data?.agent_details?.[0]?.agent_version_desc).toBe("beta-v1"); + if (targetModel !== undefined) { + expect(scalarGetData.data?.agent_details?.[0]?.agent_config?.agent_model).toBe(targetModel); + } + // --version-desc 在 beta 草稿上是服务端空操作：update 返回 200 但存为 null。 + // 版本说明只在 deploy 时传入、或对已发布版本 update 才能落库（下方 P0 组4 覆盖）。 + expect(scalarGetData.data?.agent_details?.[0]?.agent_version_desc).toBeNull(); // ── P0 组2: update --policy turbo → get 读回 ── const updateTurboRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [ diff --git a/packages/commands/tests/e2e/knowledge/knowledge.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge.e2e.test.ts index 160a4ed6d..682d5267a 100644 --- a/packages/commands/tests/e2e/knowledge/knowledge.e2e.test.ts +++ b/packages/commands/tests/e2e/knowledge/knowledge.e2e.test.ts @@ -6,6 +6,7 @@ import { runCommandE2e, } from "../helpers.ts"; import { KNOWLEDGE_ROUTES } from "../topic-routes.ts"; +import { VERIFIED_RERANK_MODEL } from "./verified-models.ts"; // ---- Types ---- @@ -168,7 +169,7 @@ describe("e2e: knowledge retrieve dry-run", () => { "hello", "--rerank", "--rerank-model", - "qwen3-rerank-hybrid", + VERIFIED_RERANK_MODEL, "--rerank-mode", "custom", "--rerank-instruct", @@ -187,7 +188,7 @@ describe("e2e: knowledge retrieve dry-run", () => { expect(data.request?.enable_reranking).toBe(true); expect(data.request?.dense_similarity_top_k).toBe(100); expect(data.request?.sparse_similarity_top_k).toBe(50); - expect(data.request?.rerank?.[0]?.model_name).toBe("qwen3-rerank-hybrid"); + expect(data.request?.rerank?.[0]?.model_name).toBe(VERIFIED_RERANK_MODEL); expect(data.request?.rerank?.[0]?.rerank_mode).toBe("custom"); expect(data.request?.rerank?.[0]?.rerank_instruct).toBe("按相关性排序"); }); @@ -220,7 +221,7 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge retrieve 参数补全 (liv "e2e test", "--rerank", "--rerank-model", - "qwen3-rerank-hybrid", + VERIFIED_RERANK_MODEL, "--rerank-mode", "custom", "--rerank-instruct", diff --git a/packages/commands/tests/e2e/knowledge/verified-models.ts b/packages/commands/tests/e2e/knowledge/verified-models.ts new file mode 100644 index 000000000..589f206fc --- /dev/null +++ b/packages/commands/tests/e2e/knowledge/verified-models.ts @@ -0,0 +1,36 @@ +// Model values verified against the live API, shared by the knowledge e2e cases so a +// server-side model rotation only needs one edit here. +// +// Deliberately test-only: the command layer must NOT mirror these lists into local +// validation. Model catalogs churn with server-side launches/deprecations, so a +// hardcoded allowlist in the CLI would block valid models until users upgrade. + +/** + * Accepted values for `agent_config.agent_model` (service create/update). + * Everything else — including qwen-plus, qwen-max, qwen3-max, qwen3.7-flash, + * qwen3.7-max and deepseek-v3 — is rejected with + * HTTP 401 InvalidParameter "agent model not allowed: ". + * The first entry is also the server-side default for a freshly created service. + */ +export const VERIFIED_AGENT_MODELS = ["qwen3.6-plus", "qwen3.7-plus"] as const; + +/** + * Accepted value for `rerank[].model_name` on index/retrieve. + * Gotcha: the server only branches on the `-hybrid` suffix — the model prefix is + * ignored (`qwen3-rerank` and `gte-rerank` score identically to omitting the field, + * `qwen3-rerank-hybrid` and `gte-rerank-hybrid` score identically to each other), so + * the effective scoring model is the index's own `rerankModelName`. Unknown names and + * indexes without `rerankModelName` both fail with + * HTTP 500 Index.IndexRerankError "index rerank config() error.". + */ +export const VERIFIED_RERANK_MODEL = "qwen3-rerank-hybrid"; + +/** + * Pick a verified model that differs from the current one, so a write → read-back + * assertion proves the value actually changed instead of re-writing the default. + * Returns undefined when the allowlist has shrunk to the model already in use — the + * caller must then skip the model assertion instead of asserting a no-op. + */ +export function pickDifferentAgentModel(currentModel: string | undefined): string | undefined { + return VERIFIED_AGENT_MODELS.find((model) => model !== currentModel); +} diff --git a/packages/core/src/types/knowledge-admin.ts b/packages/core/src/types/knowledge-admin.ts index 32107821d..3ca4e8f24 100644 --- a/packages/core/src/types/knowledge-admin.ts +++ b/packages/core/src/types/knowledge-admin.ts @@ -186,6 +186,17 @@ export interface RagAgentConfig { session_file_max_parse_length?: number; enable_kb_router?: string; kb_router_model?: string; + // Fields the server returns in the beta draft config; typed so read-merge-write + // round-trips them without a passthrough warning. Observed value kinds, not docs. + user_system_prompt?: string; + anti_leak_prompt?: string; + refusal_prompt?: string; + credibility_prompt?: string; + enable_thinking?: boolean; + enable_temperature?: boolean; + enable_credibility?: boolean; + enable_max_completion_tokens?: boolean; + session_file_parse_mode?: string; rerank_top_n?: number; hybrid_rerank?: Record; kb_search_configs?: Array>; diff --git a/packages/kscli/README.md b/packages/kscli/README.md index 76e4c8e36..67a2e0048 100644 --- a/packages/kscli/README.md +++ b/packages/kscli/README.md @@ -42,6 +42,7 @@ npm install -g knowledge-studio-cli # 1. Create a knowledge base kscli kb create \ --name "my-kb" \ + --description "my product docs knowledge base" \ --embedding-model text-embedding-v3 \ --workspace-id diff --git a/packages/kscli/README.zh.md b/packages/kscli/README.zh.md index 5e0a44cba..d485a8058 100644 --- a/packages/kscli/README.zh.md +++ b/packages/kscli/README.zh.md @@ -42,6 +42,7 @@ npm install -g knowledge-studio-cli # 1. 创建知识库 kscli kb create \ --name "my-kb" \ + --description "我的产品文档知识库" \ --embedding-model text-embedding-v3 \ --workspace-id diff --git a/skills/bailian-cli/reference/knowledge.md b/skills/bailian-cli/reference/knowledge.md index 6c02e30ae..a5e8c4f93 100644 --- a/skills/bailian-cli/reference/knowledge.md +++ b/skills/bailian-cli/reference/knowledge.md @@ -362,16 +362,16 @@ bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file- #### Flags -| Flag | Type | Required | Description | -| ---------------------- | ------ | -------- | --------------------------------------------------------------- | -| `--name ` | string | yes | Collection name | -| `--description ` | string | yes | Collection description (required by the server) | -| `--store-type ` | string | no | Storage: platform (managed) or custom (your own OSS bucket) | -| `--oss-region ` | string | no | OSS region id (required with --store-type custom) | -| `--oss-bucket ` | string | no | OSS bucket name (required with --store-type custom) | -| `--workspace-id ` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| `--api-key ` | string | no | API key | -| `--base-url ` | string | no | API base URL | +| Flag | Type | Required | Description | +| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------- | +| `--name ` | string | yes | Collection name | +| `--description ` | string | yes | What this collection holds and what it is for — tells collections apart in the list | +| `--store-type ` | string | no | Storage: platform (managed) or custom (your own OSS bucket) | +| `--oss-region ` | string | no | OSS region id (required with --store-type custom) | +| `--oss-bucket ` | string | no | OSS bucket name (required with --store-type custom) | +| `--workspace-id ` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| `--api-key ` | string | no | API key | +| `--base-url ` | string | no | API base URL | #### Notes @@ -420,27 +420,28 @@ bl knowledge collection get --name my-collection ### `bl knowledge create` -| Field | Value | -| ------------------ | --------------------------------------------------------------------------------- | -| **Name** | `knowledge create` | -| **Description** | Create a knowledge base and import data-center files or categories | -| **Authentication** | API Key | -| **Usage** | `bl knowledge create --name (--doc-id \| --category-id ) [flags]` | +| Field | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------ | +| **Name** | `knowledge create` | +| **Description** | Create a knowledge base and import data-center files or categories | +| **Authentication** | API Key | +| **Usage** | `bl knowledge create --name --description (--doc-id \| --category-id ) [flags]` | #### Flags -| Flag | Type | Required | Description | -| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------ | -| `--name ` | string | yes | Knowledge base name (1-20 chars, unique in workspace) | -| `--doc-id ` | array | no | Data-center file id to import (repeatable); mutually exclusive with --category-id | -| `--category-id ` | array | no | Import every file under this category (repeatable); mutually exclusive with --doc-id | -| `--embedding-model ` | string | no | Embedding model name (default: text-embedding-v4) | -| `--chunk-size ` | number | no | Chunk size in characters (default: 600, recommended 300-800) | -| `--wait` | switch | no | Poll the initial import job to a terminal state | -| `--poll-interval ` | number | no | Polling interval when waiting (default: 5) | -| `--workspace-id ` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| `--api-key ` | string | no | API key | -| `--base-url ` | string | no | API base URL | +| Flag | Type | Required | Description | +| --------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- | +| `--name ` | string | yes | Knowledge base name (1-20 chars, unique in workspace) | +| `--description ` | string | yes | What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-200 chars) | +| `--doc-id ` | array | no | Data-center file id to import (repeatable); mutually exclusive with --category-id | +| `--category-id ` | array | no | Import every file under this category (repeatable); mutually exclusive with --doc-id | +| `--embedding-model ` | string | no | Embedding model name (default: text-embedding-v4) | +| `--chunk-size ` | number | no | Chunk size in characters (default: 600, recommended 300-800) | +| `--wait` | switch | no | Poll the initial import job to a terminal state | +| `--poll-interval ` | number | no | Polling interval when waiting (default: 5) | +| `--workspace-id ` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| `--api-key ` | string | no | API key | +| `--base-url ` | string | no | API base URL | #### Notes @@ -451,11 +452,11 @@ bl knowledge collection get --name my-collection #### Examples ```bash -bl knowledge create --name demo --doc-id file-xxx --workspace-id ws-xxx +bl knowledge create --name demo --description 'product docs' --doc-id file-xxx --workspace-id ws-xxx ``` ```bash -bl knowledge create --name demo --category-id cate-xxx --wait +bl knowledge create --name demo --description 'product docs' --category-id cate-xxx --wait ``` ### `bl knowledge delete` @@ -911,6 +912,10 @@ bl knowledge list --name demo --page-number 2 --page-size 50 | `--api-key ` | string | no | API key | | `--base-url ` | string | no | API base URL | +#### Notes + +- --rerank-model requires the target knowledge base to already have a rerank model configured; otherwise every value is rejected. + #### Examples ```bash @@ -999,15 +1004,15 @@ bl knowledge service copy --agent-id aid-xxx --workspace-id ws-xxx #### Flags -| Flag | Type | Required | Description | -| ---------------------- | ------ | -------- | ----------------------------------------------------------------- | -| `--name ` | string | yes | Service name (up to 200 chars, unique per scene in the workspace) | -| `--scene ` | string | yes | Service scene: chat (Q&A) or search (retrieval) | -| `--description ` | string | no | Service description (up to 1000 chars) | -| `--index-id ` | string | no | Bind this knowledge base; other settings use server defaults | -| `--workspace-id ` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| `--api-key ` | string | no | API key | -| `--base-url ` | string | no | API base URL | +| Flag | Type | Required | Description | +| ---------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | +| `--name ` | string | yes | Service name (up to 200 chars, unique per scene in the workspace) | +| `--scene ` | string | yes | Service scene: chat (Q&A) or search (retrieval) | +| `--description ` | string | no | What this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars) | +| `--index-id ` | string | no | Bind this knowledge base; other settings use server defaults | +| `--workspace-id ` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| `--api-key ` | string | no | API key | +| `--base-url ` | string | no | API base URL | #### Notes @@ -1018,7 +1023,7 @@ bl knowledge service copy --agent-id aid-xxx --workspace-id ws-xxx #### Examples ```bash -bl knowledge service create --name my-qa --scene chat --workspace-id ws-xxx +bl knowledge service create --name my-qa --scene chat --description 'answers product FAQs' --workspace-id ws-xxx ``` ```bash @@ -1141,18 +1146,18 @@ bl knowledge service get --agent-id aid-xxx --agent-version beta #### Flags -| Flag | Type | Required | Description | -| --------------------- | ------ | -------- | ----------------------------------------------------------------------- | -| `--scene ` | string | yes | Service scene: chat (Q&A) or search (retrieval). Required by the server | -| `--status ` | string | no | Filter by status: draft, deployed (includes edited) or deleted | -| `--name ` | string | no | Filter by service name (fuzzy match) | -| `--agent-id ` | string | no | Filter by exact agent ID | -| `--index-id ` | string | no | Filter by exact linked knowledge base (pipeline) ID | -| `--page-number ` | number | no | Page number (default: 1) | -| `--page-size ` | number | no | Page size per request | -| `--workspace-id ` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| `--api-key ` | string | no | API key | -| `--base-url ` | string | no | API base URL | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| `--scene ` | string | yes | Service scene: chat (Q&A) or search (retrieval) | +| `--status ` | string | no | Filter by status: draft, deployed (includes edited) or deleted | +| `--name ` | string | no | Filter by service name (fuzzy match) | +| `--agent-id ` | string | no | Filter by exact agent ID | +| `--index-id ` | string | no | Filter by exact linked knowledge base (pipeline) ID | +| `--page-number ` | number | no | Page number (default: 1) | +| `--page-size ` | number | no | Page size per request | +| `--workspace-id ` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| `--api-key ` | string | no | API key | +| `--base-url ` | string | no | API base URL | #### Notes From b830a14e116213f74caa61b1c48d0bef121ca5d0 Mon Sep 17 00:00:00 2001 From: "zeyu.fz" Date: Sat, 22 Aug 2026 11:52:39 +0800 Subject: [PATCH 2/4] =?UTF-8?q?docs(knowledge):=20=E6=89=A9=E5=B1=95?= =?UTF-8?q?=E7=9F=A5=E8=AF=86=E5=BA=93=E6=8F=8F=E8=BF=B0=E9=95=BF=E5=BA=A6?= =?UTF-8?q?=E9=99=90=E5=88=B6=E5=88=B0=20500=20=E5=AD=97=E7=AC=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修改命令行参数文档，将 --description 长度限制由 200 字符增加到 500 字符 - 更新代码校验逻辑，支持描述长度最大 500 字符 - 调整相关提示信息，反映新的长度限制 - 修改测试用例，支持 501 字符的描述参数触发用法错误 - 更新 CLI 参考文档中描述字段的长度说明 --- docs/knowledge/kb.md | 4 ++-- .../commands/src/commands/knowledge/kb-create.ts | 12 ++++++------ .../e2e/knowledge/knowledge-kb-create.e2e.test.ts | 4 ++-- skills/bailian-cli/reference/knowledge.md | 2 +- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/knowledge/kb.md b/docs/knowledge/kb.md index 25a9b35b4..83fc10e5d 100644 --- a/docs/knowledge/kb.md +++ b/docs/knowledge/kb.md @@ -136,7 +136,7 @@ bl knowledge create --name --description (--doc-id | --catego | 参数 | 类型 | 必填 | 说明 | | --------------------------- | ------ | ---- | -------------------------------------------------------- | | `--name ` | string | 是 | 知识库名称（1-20 字符，工作区内唯一） | -| `--description ` | string | 是 | 知识库装了什么内容、给谁用（1-200 字符） | +| `--description ` | string | 是 | 知识库装了什么内容、给谁用（1-500 字符） | | `--doc-id ` | array | 否¹ | 数据中心文件 ID（可重复）；与 `--category-id` 互斥 | | `--category-id ` | array | 否¹ | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 | | `--embedding-model ` | string | 否 | 向量模型名称（默认：`text-embedding-v4`） | @@ -149,7 +149,7 @@ bl knowledge create --name --description (--doc-id | --catego **参数约束** - `--name` 长度 1-20 字符 -- `--description` 长度 1-200 字符，缺失或超长会在本地被拦截 +- `--description` 长度 1-500 字符，缺失或超长会在本地被拦截 - `--doc-id` 和 `--category-id` 互斥，必须提供其一 **输出** diff --git a/packages/commands/src/commands/knowledge/kb-create.ts b/packages/commands/src/commands/knowledge/kb-create.ts index 794f3ecc8..0855ba3d2 100644 --- a/packages/commands/src/commands/knowledge/kb-create.ts +++ b/packages/commands/src/commands/knowledge/kb-create.ts @@ -34,8 +34,8 @@ const KB_CREATE_FLAGS = { valueHint: "", description: { "en-US": - "What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-200 chars)", - "zh-CN": "知识库装了什么内容、给谁用，用于在 Workspace 列表中区分同类知识库（1–200 个字符）", + "What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-500 chars)", + "zh-CN": "知识库装了什么内容、给谁用，用于在 Workspace 列表中区分同类知识库（1–500 个字符）", }, required: true, }, @@ -147,8 +147,8 @@ export default defineCommand({ ], validate(flags) { if (flags.name.length < 1 || flags.name.length > 20) return "--name must be 1-20 characters"; - if (flags.description.length < 1 || flags.description.length > 200) { - return "--description must be 1-200 characters"; + if (flags.description.length < 1 || flags.description.length > 500) { + return "--description must be 1-500 characters"; } const hasDocIds = !!flags.docId?.length; const hasCategoryIds = !!flags.categoryId?.length; @@ -166,8 +166,8 @@ export default defineCommand({ // Note: the public docs' example uses sinkType DEFAULT, but BUILT_IN is what works against the live API. const body = { name: flags.name, - // The server enforces description as a required 1-200 char field (the public - // API docs still list it as absent from CreateIndexV2Request.required). + // description is a required field; length limit is 1-500 (the public API docs + // still list it as absent from CreateIndexV2Request.required). description: flags.description, structureType: "unstructured", sinkType: "BUILT_IN", diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts index af144b4cd..a7dc33b9c 100644 --- a/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts +++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts @@ -61,14 +61,14 @@ describe("e2e: knowledge kb create", () => { expect(exitCode).toBe(2); }); - test("--description 201 字符报 USAGE (2)", async () => { + test("--description 501 字符报 USAGE (2)", async () => { const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [ "knowledge", "create", "--name", "demo", "--description", - "x".repeat(201), + "x".repeat(501), "--doc-id", "file_test", "--workspace-id", diff --git a/skills/bailian-cli/reference/knowledge.md b/skills/bailian-cli/reference/knowledge.md index a5e8c4f93..1fc2aab71 100644 --- a/skills/bailian-cli/reference/knowledge.md +++ b/skills/bailian-cli/reference/knowledge.md @@ -432,7 +432,7 @@ bl knowledge collection get --name my-collection | Flag | Type | Required | Description | | --------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- | | `--name ` | string | yes | Knowledge base name (1-20 chars, unique in workspace) | -| `--description ` | string | yes | What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-200 chars) | +| `--description ` | string | yes | What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-500 chars) | | `--doc-id ` | array | no | Data-center file id to import (repeatable); mutually exclusive with --category-id | | `--category-id ` | array | no | Import every file under this category (repeatable); mutually exclusive with --doc-id | | `--embedding-model ` | string | no | Embedding model name (default: text-embedding-v4) | From a95ad7242b2e91c28ccfb465d6e5d1650be726bd Mon Sep 17 00:00:00 2001 From: "zeyu.fz" Date: Sat, 22 Aug 2026 12:19:55 +0800 Subject: [PATCH 3/4] =?UTF-8?q?docs(cli):=20=E6=B7=BB=E5=8A=A0=E5=AE=8C?= =?UTF-8?q?=E6=95=B4=E7=9A=84=20KSCLI=20=E5=91=BD=E4=BB=A4=E6=89=8B?= =?UTF-8?q?=E5=86=8C=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增知识库管理（kb）命令详解，包含创建、查询、更新、删除和状态监控 - 补充文档（doc）管理命令，包括文件上传、导入状态查询、标签管理等 - 增加数据中心文件（file）管理说明，覆盖文件列表、详情、删除操作 - 完善集合与分类管理（collection/category）命令手册，支持创建、查询、删除等功能 - 详细描述 chunk 管理命令，包括添加、更新、查询和删除操作 - 统一说明通用约定，涵盖鉴权、全局参数、输出格式、确认机制及干跑模式 - 提供丰富参数说明、输出格式及使用示例，提升 CLI 使用体验和易用性 --- docs/kscli/chunk.md | 248 ++++++++ docs/kscli/collection-category.md | 268 +++++++++ docs/kscli/doc.md | 344 +++++++++++ docs/kscli/file.md | 157 +++++ docs/kscli/kb.md | 342 +++++++++++ docs/kscli/kscli-cli-guide.md | 929 ++++++++++++++++++++++++++++++ docs/kscli/search-chat.md | 218 +++++++ docs/kscli/service.md | 401 +++++++++++++ 8 files changed, 2907 insertions(+) create mode 100644 docs/kscli/chunk.md create mode 100644 docs/kscli/collection-category.md create mode 100644 docs/kscli/doc.md create mode 100644 docs/kscli/file.md create mode 100644 docs/kscli/kb.md create mode 100644 docs/kscli/kscli-cli-guide.md create mode 100644 docs/kscli/search-chat.md create mode 100644 docs/kscli/service.md diff --git a/docs/kscli/chunk.md b/docs/kscli/chunk.md new file mode 100644 index 000000000..e75b8691a --- /dev/null +++ b/docs/kscli/chunk.md @@ -0,0 +1,248 @@ +# Chunk 管理命令手册 + +Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli chunk add` + +直接向知识库添加 chunk。 + +**用法** + +```bash +kscli chunk add --index-id (--content | --field ) [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------------- | ------ | ---- | ------------------------------------------------------------------------------------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--doc-id ` | string | 否² | 所属文档 ID；表格/图片知识库必填，文档型可选 | +| `--content ` | string | 否¹ | Chunk 正文，最多 6000 字符（文档型）；与 `--content-file` 互斥 | +| `--content-file ` | string | 否¹ | 从 UTF-8 文本文件读取正文（`.md`/`.txt` 等）；与 `--content` 互斥 | +| `--title ` | string | 否 | Chunk 标题，最多 50 字符（文档型） | +| `--image-url ` | array | 否 | Chunk 图片 URL（可重复，最多 10 个；文档型） | +| `--field ` | array | 否¹ | 任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥 | + +> ¹ `--content`/`--content-file`/`--title`/`--image-url` 与 `--field` 互斥，必须提供其一。 +> ² 表格/图片知识库必须提供 `--doc-id`。文档型知识库可选。 + +**参数约束** + +- `--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 +kscli chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx + +# 添加表格行（字段方式） +kscli chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2 + +# 从文件读取内容 +kscli chunk add --index-id idx-xxx --content-file ./chunk.md --doc-id doc-xxx +``` + +--- + +#### `kscli chunk list` + +列出知识库中的 chunk，含内容和状态。 + +**用法** + +```bash +kscli chunk list --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ------------------- | ------ | ---- | ------------------------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--doc-id ` | string | 否 | 只显示属于此文档的 chunk | +| `--page-number ` | number | 否 | 页码（默认：1） | +| `--page-size ` | 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 +kscli chunk list --index-id idx-xxx --workspace-id ws-xxx + +# 只看某文档的 chunk +kscli chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50 +``` + +--- + +#### `kscli chunk update` + +更新 chunk 内容或切换其检索可见性。 + +**用法** + +```bash +kscli chunk update --index-id --chunk-id --doc-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------------- | ------ | ---- | ------------------------------------------------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--chunk-id ` | string | 是 | Chunk ID（`metadata._id`，来自 chunk list 输出） | +| `--doc-id ` | string | 是 | 所属文档 ID（`metadata.doc_id`，来自 chunk list 输出） | +| `--content ` | string | 否¹ | 新内容，10-6000 字符；与 `--content-file` 互斥 | +| `--content-file ` | string | 否¹ | 从 UTF-8 文本文件读取新内容 | +| `--title ` | 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 +# 修改内容 +kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" --workspace-id ws-xxx + +# 排除 chunk 不参与检索 +kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude + +# 恢复检索 +kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include +``` + +--- + +#### `kscli chunk delete` + +从知识库中删除 chunk（不可逆）。 + +**用法** + +```bash +kscli chunk delete --index-id --chunk-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | ------------------------------------------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--chunk-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 +kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx + +# 跳过确认 +kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --yes +``` + +--- + +← [返回总览](./kscli-cli-guide.md) diff --git a/docs/kscli/collection-category.md b/docs/kscli/collection-category.md new file mode 100644 index 000000000..b4061c49f --- /dev/null +++ b/docs/kscli/collection-category.md @@ -0,0 +1,268 @@ +# 数据中心集合与分类命令手册 + +集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli collection create` + +创建 FILE 数据集合。 + +**用法** + +```bash +kscli collection create --name --description [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | ---------------------------------------------------------------- | +| `--name ` | string | 是 | 集合名称（1-20 字符） | +| `--description ` | string | 是 | 集合描述 | +| `--store-type ` | string | 否 | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） | +| `--oss-region ` | string | 否 | OSS region ID（`--store-type custom` 时必填） | +| `--oss-bucket ` | 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 +# 创建平台托管的集合 +kscli collection create --name my-collection --description "team docs" --workspace-id ws-xxx + +# 创建使用自有 OSS bucket 的集合 +kscli collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket +``` + +--- + +#### `kscli collection get` + +查看数据集合详情。 + +**用法** + +```bash +kscli collection get (--collection-id | --name ) [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | -------- | +| `--collection-id ` | string | 否¹ | 集合 ID | +| `--name ` | string | 否¹ | 集合名称 | + +> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。 + +**参数约束** + +- `--collection-id` 和 `--name` 互斥，必须提供其一 + +**输出** + +text 模式： + +``` +id: conn-xxx +name: my-collection +description: team docs +``` + +quiet 模式：输出集合 ID。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- getConnector 不返回 `fileConnectorConfig`（`storeType`/`regionId`/`bucketName`），这些字段仅在创建时通过请求体传入，查询时不可读回。 + +**示例** + +```bash +# 按 ID 查询 +kscli collection get --collection-id conn-xxx --workspace-id ws-xxx + +# 按名称查询 +kscli collection get --name my-collection +``` + +--- + +#### `kscli category list` + +列出数据中心分类。 + +**用法** + +```bash +kscli category list [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | ------------------------------------------------------ | +| `--collection-id ` | string | 否 | 按集合 ID 过滤 | +| `--parent-id ` | string | 否 | 列出此分类的子分类 | +| `--name ` | string | 否 | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） | +| `--next-token ` | string | 否 | 游标分页令牌 | +| `--max-result ` | number | 否 | 每页条数（默认：20） | + +**输出** + +text 模式： + +``` +cate-xxx product-docs +cate-yyy system-docs [default] +next: --next-token eyJ... +``` + +> 标记 `[default]` 的是文件未指定分类时的默认归属。 + +quiet 模式：每行一个 `categoryId`。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 分页是游标方式：使用输出的 `next: --next-token ` 继续翻页。 + +**示例** + +```bash +# 列出所有分类 +kscli category list --workspace-id ws-xxx + +# 按名称过滤 +kscli category list --name my-category + +# 翻页 +kscli category list --next-token eyJ... +``` + +--- + +#### `kscli category add` + +创建数据中心分类。 + +**用法** + +```bash +kscli category add --name [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | -------------------------------- | +| `--name ` | string | 是 | 分类名称（1-20 字符） | +| `--parent-id ` | string | 否 | 创建为指定分类的子分类 | +| `--collection-id ` | string | 否 | 创建在此集合下（默认：平台集合） | + +**参数约束** + +- `--name` 长度 1-20 字符 + +**输出** + +text 模式： + +``` +created: cate-xxx (product-docs) +``` + +quiet 模式：输出分类 ID。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 用分类按业务域组织数据中心文件。 + +**示例** + +```bash +# 创建分类 +kscli category add --name product-docs --workspace-id ws-xxx + +# 创建子分类 +kscli category add --name sub --parent-id cate-xxx +``` + +--- + +#### `kscli category delete` + +删除数据中心分类。 + +**用法** + +```bash +kscli category delete --category-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| -------------------- | ------ | ---- | ------------ | +| `--category-id ` | string | 是 | 分类 ID | +| `--yes` | switch | 否 | 跳过确认提示 | + +**输出** + +text 模式： + +``` +deleted: cate-xxx +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- 含文件或子分类的分类的删除行为由服务端定义——服务端错误原样透传。 + +**示例** + +```bash +# 删除分类（交互确认） +kscli category delete --category-id cate-xxx --workspace-id ws-xxx + +# 跳过确认 +kscli category delete --category-id cate-xxx --yes +``` + +--- + +← [返回总览](./kscli-cli-guide.md) diff --git a/docs/kscli/doc.md b/docs/kscli/doc.md new file mode 100644 index 000000000..60cea6776 --- /dev/null +++ b/docs/kscli/doc.md @@ -0,0 +1,344 @@ +# 文档管理命令手册 + +文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli doc list` + +列出知识库中的文档及其解析/索引状态。 + +**用法** + +```bash +kscli doc list --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ------------------- | ------ | ---- | ------------------------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--page-number ` | number | 否 | 页码（默认：1） | +| `--page-size ` | 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` 的关系：通过 `kb create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；通过 `doc upload --index-id` 导入的，`doc_id` 可能包含 workspace 后缀。 +- 页大小默认 10（服务端默认），最大 100。 + +**示例** + +```bash +# 列出文档 +kscli doc list --index-id idx-xxx --workspace-id ws-xxx + +# 每页 100 条 +kscli doc list --index-id idx-xxx --page-size 100 +``` + +--- + +#### `kscli doc status` + +查看知识库导入任务状态。 + +**用法** + +```bash +kscli doc status --index-id --job-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| --------------------------- | ------ | ---- | --------------------------------------------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--job-id ` | string | 是 | 导入任务 ID（`ingestionId`，由 create/upload 返回） | +| `--page-number ` | number | 否 | 页码 | +| `--page-size ` | number | 否 | 每页条数 | +| `--wait` | switch | 否 | 轮询直到任务到达终态 | +| `--poll-interval ` | 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 +# 查看任务状态 +kscli doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx + +# 轮询等待完成，10 秒间隔 +kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10 +``` + +--- + +#### `kscli doc upload` + +上传本地文件或目录到数据中心，可选导入到知识库。 + +**用法** + +```bash +kscli doc upload --file [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| --------------------------- | ------ | ---- | ---------------------------------------------------------------- | +| `--file ` | array | 是 | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 | +| `--index-id ` | string | 否 | 上传后导入到此知识库（所有文件合并为一个导入任务） | +| `--category-id ` | string | 否 | 目标数据中心分类（默认：工作区默认分类） | +| `--tag ` | array | 否 | 文件标签（可重复），应用到每个上传的文件 | +| `--wait` | switch | 否 | 轮询导入任务直到终态（需要 `--index-id`） | +| `--poll-interval ` | 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 +# 上传单个文件 +kscli doc upload --file ./a.md --workspace-id ws-xxx + +# 上传多个文件并导入到知识库，等待完成 +kscli doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait + +# 上传整个目录 +kscli doc upload --file ./docs/ --workspace-id ws-xxx + +# 干跑预览（查看将上传和跳过的文件） +kscli doc upload --file ./docs/ --dry-run --verbose +``` + +--- + +#### `kscli doc delete` + +从知识库中删除文档及其 chunk。 + +**用法** + +```bash +kscli doc delete --index-id --doc-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | ----------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--doc-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` 应从 `doc list --quiet` 获取，而非 `doc upload` 返回的 `fileId`。 +- 删除是异步的：服务端立即返回 Success，但 `doc list` 中可能仍显示该文档（约 30 秒后传播完成）。 +- 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。 + +**示例** + +```bash +# 删除单个文档 +kscli doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx + +# 批量删除，跳过确认 +kscli doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes +``` + +--- + +#### `kscli doc tag` + +批量更新数据中心文件的标签。 + +**用法** + +```bash +kscli doc tag --doc-id --tag [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| --------------- | ------ | ---- | ------------------------------------------------------ | +| `--doc-id ` | array | 是 | 数据中心文件 ID（可重复，最多 20 个/次） | +| `--tag ` | array | 是 | 标签（可重复），应用到每个 `--doc-id` | +| `--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 +# 追加标签 +kscli doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx + +# 覆盖标签 +kscli doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite +``` + +--- + +#### `kscli doc import-oss` + +从已授权的 OSS bucket 批量导入文件到数据中心。 + +**用法** + +```bash +kscli doc import-oss --bucket --region --oss-key [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| -------------------- | ------ | ---- | ------------------------------------- | +| `--bucket ` | string | 是 | 已授权的 OSS bucket 名称 | +| `--region ` | string | 是 | OSS region ID（如 `cn-beijing`） | +| `--oss-key ` | array | 是 | OSS 对象 key（可重复，最多 10 个/次） | +| `--category-id ` | string | 否 | 目标数据中心分类（默认：默认分类） | +| `--tag ` | 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 +# 导入单个文件 +kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx + +# 导入多个文件并覆盖 +kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite +``` + +--- + +← [返回总览](./kscli-cli-guide.md) diff --git a/docs/kscli/file.md b/docs/kscli/file.md new file mode 100644 index 000000000..e4edce0cd --- /dev/null +++ b/docs/kscli/file.md @@ -0,0 +1,157 @@ +# 数据中心文件管理命令手册 + +数据中心是知识库文件的存储层。文件通过 `doc upload` 或 `doc import-oss` 进入数据中心，再导入到知识库。数据中心文件可被多个知识库引用。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli file list` + +列出数据中心分类下的文件。 + +**用法** + +```bash +kscli file list --category-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------- | ------ | ---- | -------------------------------------------------- | +| `--category-id ` | string | 是 | 分类 ID（通过 `category list` 或 `file get` 获取） | +| `--name ` | string | 否 | 按文件名过滤 | +| `--file-id ` | array | 否 | 按文件 ID 过滤（可重复） | +| `--next-token ` | string | 否 | 游标分页令牌（从上次输出获取） | +| `--max-result ` | 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 ` 继续翻页。 + +**示例** + +```bash +# 列出分类下文件 +kscli file list --category-id cate-xxx --workspace-id ws-xxx + +# 按名称过滤 +kscli file list --category-id cate-xxx --name report + +# 翻页 +kscli file list --category-id cate-xxx --next-token eyJ... +``` + +--- + +#### `kscli file get` + +查看数据中心文件详情。 + +**用法** + +```bash +kscli file get --file-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------- | ------ | ---- | --------------- | +| `--file-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 +# 查看文件详情 +kscli file get --file-id file-xxx --workspace-id ws-xxx +``` + +--- + +#### `kscli file delete` + +从数据中心永久删除文件。 + +**用法** + +```bash +kscli file delete --file-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------- | ------ | ---- | --------------- | +| `--file-id ` | string | 是 | 数据中心文件 ID | +| `--yes` | switch | 否 | 跳过确认提示 | + +**输出** + +text 模式： + +``` +deleted: file-xxx +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- **不可逆操作**：如果知识库引用了此文件，相关文档索引会失效。 +- 与 `doc delete` 的区别：`doc delete` 只从单个知识库索引中移除文档，数据中心源文件保留；`file delete` 删除源文件本身，影响所有引用它的知识库。 + +**示例** + +```bash +# 删除文件（交互确认） +kscli file delete --file-id file-xxx --workspace-id ws-xxx + +# 跳过确认 +kscli file delete --file-id file-xxx --yes +``` + +--- + +← [返回总览](./kscli-cli-guide.md) diff --git a/docs/kscli/kb.md b/docs/kscli/kb.md new file mode 100644 index 000000000..5fa4c34b8 --- /dev/null +++ b/docs/kscli/kb.md @@ -0,0 +1,342 @@ +# 知识库管理命令手册 + +知识库（Knowledge Base / pipeline / index）是 RAG 的核心载体，存储文档解析后的向量索引。本组命令覆盖知识库的创建、查看、更新、删除和监控。 + +> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 + +--- + +#### `kscli kb list` + +列出工作区中的知识库。 + +**用法** + +```bash +kscli kb list [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ------------------- | ------ | ---- | --------------------------------- | +| `--name ` | string | 否 | 按知识库名称模糊过滤（1-20 字符） | +| `--page-number ` | number | 否 | 页码（默认：1） | +| `--page-size ` | 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 +# 列出所有知识库 +kscli kb list --workspace-id ws-xxx + +# 按名称过滤，第二页 +kscli kb list --name demo --page-number 2 --page-size 50 +``` + +--- + +#### `kscli kb info` + +查看知识库配置详情。 + +**用法** + +```bash +kscli kb info --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | --------- | +| `--index-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。 + +**注意事项** + +- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。 + +**示例** + +```bash +# 查看知识库详情 +kscli kb info --index-id idx-xxx --workspace-id ws-xxx +``` + +--- + +#### `kscli kb create` + +创建知识库并导入数据中心文件或分类。 + +**用法** + +```bash +kscli kb create --name --description (--doc-id | --category-id ) [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| --------------------------- | ------ | ---- | -------------------------------------------------------- | +| `--name ` | string | 是 | 知识库名称（1-20 字符，工作区内唯一） | +| `--description ` | string | 是 | 知识库装了什么内容、给谁用（1-500 字符） | +| `--doc-id ` | array | 否¹ | 数据中心文件 ID（可重复）；与 `--category-id` 互斥 | +| `--category-id ` | array | 否¹ | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 | +| `--embedding-model ` | string | 否 | 向量模型名称（默认：`text-embedding-v4`） | +| `--chunk-size ` | number | 否 | 切片大小，字符数（默认：600，建议 300-800） | +| `--wait` | switch | 否 | 轮询初始导入任务直到终态 | +| `--poll-interval ` | number | 否 | 轮询间隔秒数（默认：5） | + +> ¹ `--doc-id` 和 `--category-id` 二选一，必须提供其一。 + +**参数约束** + +- `--name` 长度 1-20 字符 +- `--description` 长度 1-500 字符，缺失或超长会在本地被拦截 +- `--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 +# 从指定文件创建知识库 +kscli kb create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx + +# 从分类导入并等待导入完成 +kscli kb create --name demo --description '产品文档' --category-id cate-xxx --wait + +# 指定向量模型和切片大小 +kscli kb create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx +``` + +--- + +#### `kscli kb update` + +更新知识库名称、描述或 rerank 阈值。 + +**用法** + +```bash +kscli kb update --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ---------------------------- | ------ | ---- | -------------------------------------------------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--name ` | string | 否 | 新名称（1-20 字符） | +| `--description ` | string | 否 | 新描述 | +| `--rerank-min-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 +# 更新描述 +kscli kb update --index-id idx-xxx --description "product docs v2" --workspace-id ws-xxx + +# 调整 rerank 阈值 +kscli kb update --index-id idx-xxx --rerank-min-score 0.3 +``` + +--- + +#### `kscli kb delete` + +删除知识库及其所有文档和 chunk。 + +**用法** + +```bash +kscli kb delete --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | ------------ | +| `--index-id ` | string | 是 | 知识库 ID | +| `--yes` | switch | 否 | 跳过确认提示 | + +**输出** + +text 模式： + +``` +deleted: idx-xxx +``` + +quiet 模式：无输出。 + +json 模式：返回 API 原始响应。 + +**注意事项** + +- **不可逆操作**：知识库及所有索引内容被永久删除。 +- 数据中心中的源文件不受影响，仅删除知识库索引。 +- 不带 `--yes` 时，CLI 会先查询知识库名称和文档数量作为确认摘要。 + +**示例** + +```bash +# 删除（交互确认） +kscli kb delete --index-id idx-xxx --workspace-id ws-xxx + +# 跳过确认 +kscli kb delete --index-id idx-xxx --yes +``` + +--- + +#### `kscli kb stats` + +查看知识库存储和 QPS 监控数据。 + +**用法** + +```bash +kscli kb stats --index-id [flags] +``` + +**参数** + +| 参数 | 类型 | 必填 | 说明 | +| ----------------- | ------ | ---- | ----------------------------------------------- | +| `--index-id ` | string | 是 | 知识库 ID | +| `--start