docs(knowledge): 强制添加知识库描述参数

- 升级知识库创建命令，`--description` 参数变为必填，描述知识库内容和用途
- 更新所有相关文档示例，统一加入 `--description` 参数和示例文本
- CLI 校验增强，缺失或超长的描述参数本地报错，避免服务端拒绝
- 优化服务创建命令，推荐填写描述以帮助 agent 选择合适服务
- 多个测试用例添加对描述参数的验证和断言
- 知识库和集合列表中描述信息作为区分同类项目的辅助信息显式展示
- 其他细节调整包括命令帮助及参数说明内容的更新

Author: clark-fc

docs/knowledge/kb.md

@@ -128,14 +128,15 @@ bl knowledge info --index-id idx-xxx --workspace-id ws-xxx
 **用法**
 
 ```bash
-bl knowledge create --name <text> (--doc-id <id> | --category-id <id>) [flags]
+bl knowledge create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]
 ```
 
 **参数**
 
 | 参数                        | 类型   | 必填 | 说明                                                     |
 | --------------------------- | ------ | ---- | -------------------------------------------------------- |
 | `--name <text>`             | string | 是   | 知识库名称（1-20 字符，工作区内唯一）                    |
+| `--description <text>`      | string | 是   | 知识库装了什么内容、给谁用（1-200 字符）                 |
 | `--doc-id <id>`             | array  | 否¹  | 数据中心文件 ID（可重复）；与 `--category-id` 互斥       |
 | `--category-id <id>`        | array  | 否¹  | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 |
 | `--embedding-model <name>`  | string | 否   | 向量模型名称（默认：`text-embedding-v4`）                |
@@ -148,6 +149,7 @@ bl knowledge create --name <text> (--doc-id <id> | --category-id <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
 ```
 
 ---

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

docs/knowledge/service.md

@@ -142,14 +142,14 @@ bl knowledge service create --name <text> --scene <chat|search> [flags]
 | ------------------------ | ------ | ---- | ------------------------------------------------- |
 | `--name <text>`          | string | 是   | 服务名称（最多 200 字符，同一场景下工作区内唯一） |
 | `--scene <chat\|search>` | string | 是   | 服务场景：`chat`（Q&A）或 `search`（检索）        |
-| `--description <text>`   | string | 否   | 服务描述（最多 1000 字符）                        |
+| `--description <text>`   | string | 建议 | 这个服务能回答什么、给谁用（最多 1000 字符）      |
 | `--index-id <id>`        | string | 否   | 绑定此知识库；其他配置使用服务端默认值            |
 
 **参数约束**
 
 - `--name` 最多 200 字符
 - `--scene` 只能是 `chat` 或 `search`
-- `--description` 最多 1000 字符
+- `--description` 最多 1000 字符；建议填写 —— agent 靠它判断该调用哪个服务
 
 **输出**
 

packages/commands/src/commands/knowledge/collection-create.ts

@@ -20,8 +20,9 @@ const COLLECTION_CREATE_FLAGS = {
     type: "string",
     valueHint: "<text>",
     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,
   },

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

@@ -29,6 +29,16 @@ const KB_CREATE_FLAGS = {
     },
     required: true,
   },
+  description: {
+    type: "string",
+    valueHint: "<text>",
+    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: "<id>",
@@ -107,7 +117,7 @@ export default defineCommand({
     "zh-CN": "创建知识库并导入数据中心文件或类目",
   },
   auth: "apiKey",
-  usageArgs: "--name <text> (--doc-id <id> | --category-id <id>) [flags]",
+  usageArgs: "--name <text> --description <text> (--doc-id <id> | --category-id <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",

packages/commands/src/commands/knowledge/retrieve.ts

@@ -82,6 +82,13 @@ export default defineCommand({
   auth: "apiKey",
   usageArgs: "--index-id <id> --query <text> [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"',

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

@@ -32,8 +32,10 @@ const SERVICE_CREATE_FLAGS = {
     type: "string",
     valueHint: "<text>",
     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) {

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

@@ -14,8 +14,8 @@ const SERVICE_LIST_FLAGS = {
     type: "string",
     valueHint: "<scene>",
     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,
   },

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

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,