test(knowledge): 添加多模态与表格型仓库 E2E 测试套件支持

- 新增多模态问答及检索服务的 live E2E 测试用例，支持基于图像参数的功能验证
- 补充表格库的 chunk add/list/delete 闭环测试，验证了 field channel 的必填项和读写一致性
- 增加图片库 chunk list 的 metadata 验证，确保 image_url 数组和可见性标志存在
- 实现带覆盖重导功能的 doc import-oss 测试，确认覆盖后 fileId 变更及旧文件失效
- 编写自有 OSS Bucket 的幂等复用集合创建和获取测试，确保服务端的 tag-based 访问控制支持
- 在 gating 中添加对各类长驻知识库及服务环境变量的就绪检测函数

Author: clark-fc

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

@@ -22,7 +22,8 @@ const CHUNK_ADD_FLAGS = {
   docId: {
     type: "string",
     valueHint: "<id>",
-    description: "Attach the chunk to this document (document-type knowledge bases)",
+    description:
+      "Owning document ID; required for table/image knowledge bases (the server rejects field-channel chunks without it), optional for document-type",
   },
   content: {
     type: "string",
@@ -73,6 +74,7 @@ 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).",
     "The API is idempotent but rate-limited to 10 calls per second — throttle batch scripts.",
     "The response carries no chunk id; list chunks afterwards to find the new one.",
     "For table/image knowledge bases use --field with Excel column headers as keys; values are passed through as strings.",

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

@@ -47,6 +47,7 @@ export default defineCommand({
   flags: COLLECTION_CREATE_FLAGS,
   notes: [
     "Store type defaults to platform (managed storage); custom uses your authorized OSS bucket.",
+    "Custom buckets must carry the bucket tag bailian-connector-access=ReadAndWrite (Bailian's tag-based access control); without it the server rejects creation with a misleading 'setBucketCORS failed' error.",
     "There is no collection delete API — create collections deliberately.",
   ],
   exampleArgs: [
@@ -71,15 +72,17 @@ export default defineCommand({
     const format = detectOutputFormat(settings.output);
 
     const storeType = (flags.storeType ?? "platform").toUpperCase();
-    // The server contract still uses connector* fields; only the CLI-facing term is collection
+    // The server contract still uses connector* fields; only the CLI-facing term is collection.
+    // CUSTOM fields are regionId/bucketName per api/connector/add-connector.md (live-verified;
+    // the earlier ossRegionId/ossBucket naming was an implementation error, rejected with InvalidParameter).
     const body = {
       connectorType: "FILE",
       connectorName: flags.name,
       description: flags.description,
       fileConnectorConfig: {
         storeType,
         ...(storeType === "CUSTOM"
-          ? { ossRegionId: flags.ossRegion, ossBucket: flags.ossBucket }
+          ? { regionId: flags.ossRegion, bucketName: flags.ossBucket }
           : {}),
       },
     };

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

@@ -69,8 +69,11 @@ export default defineCommand({
       const storeType = collection?.fileConnectorConfig?.storeType;
       emitBare(`storeType: ${storeType ?? "-"}`);
       if (storeType === "CUSTOM") {
-        emitBare(`  ossRegion: ${collection?.fileConnectorConfig?.ossRegionId ?? "-"}`);
-        emitBare(`  ossBucket: ${collection?.fileConnectorConfig?.ossBucket ?? "-"}`);
+        // Defensive branch: live-verified getConnector responses do NOT echo
+        // fileConnectorConfig at all (storeType prints "-"); kept in case the
+        // server starts returning it. Field names follow the create contract.
+        emitBare(`  ossRegion: ${collection?.fileConnectorConfig?.regionId ?? "-"}`);
+        emitBare(`  ossBucket: ${collection?.fileConnectorConfig?.bucketName ?? "-"}`);
       }
       return;
     }

packages/commands/src/commands/knowledge/doc-import-oss.ts

@@ -54,6 +54,7 @@ export default defineCommand({
   notes: [
     "The bucket must be authorized to the platform service role beforehand; permission errors from the server are passed through with a pointer to check AliyunServiceRoleForBailian in the RAM console.",
     "File names are derived from the OSS key basename.",
+    "--overwrite replaces the previously imported file and issues a NEW fileId (the old one becomes invalid) — verified live.",
   ],
   exampleArgs: [
     "--bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx",
@@ -94,14 +95,21 @@ export default defineCommand({
       body,
     });
 
-    const fileIds = response.data?.fileIds ?? [];
+    // Live-verified shape: results come back as addFileResultList (the docs' flat
+    // fileIds field is not returned); per-file status is SUCCESS on success
+    const results = response.data?.addFileResultList ?? [];
+    const fileIds = results
+      .map((result) => result.fileId)
+      .filter((fileId): fileId is string => !!fileId);
     if (settings.quiet) {
       for (const fileId of fileIds) emitBare(fileId);
       return;
     }
     if (format === "text") {
       emitBare(`imported: ${fileIds.length} file(s)`);
-      for (const fileId of fileIds) emitBare(`  ${fileId}`);
+      for (const result of results) {
+        emitBare(`  ${result.fileId ?? "-"}  ${result.status ?? "-"}  ${result.ossKey ?? ""}`);
+      }
       return;
     }
     emitResult(response, format);

packages/commands/tests/e2e/helpers.ts

@@ -29,9 +29,15 @@ export {
   isConnectorE2EReady,
   isConsoleE2EReady,
   isDashScopeE2EReady,
+  isImageKbE2EReady,
   isKbAdminE2EReady,
+  isMultimodalChatE2EReady,
+  isMultimodalSearchE2EReady,
   isOpenApiE2EReady,
+  isOssImportE2EReady,
   isSearchE2EReady,
+  isTableKbE2EReady,
+  isTableSearchE2EReady,
 } from "e2e/gating";
 
 const e2eDir = dirname(fileURLToPath(import.meta.url));

packages/commands/tests/e2e/knowledge/knowledge-chat.e2e.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, test } from "vite-plus/test";
-import { isChatE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import {
+  isChatE2EReady,
+  isMultimodalChatE2EReady,
+  parseStdoutJson,
+  runCommandE2e,
+} from "../helpers.ts";
 import { KNOWLEDGE_CHAT_ROUTES } from "../topic-routes.ts";
 
 interface ContentPart {
@@ -389,3 +394,34 @@ describe.skipIf(!isChatE2EReady())("e2e: knowledge chat (live)", () => {
     expect(stderr).toBeTruthy();
   });
 });
+
+// Long-lived console-created fixture (multimodal Q&A services cannot be created
+// via the CLI — see .env BAILIAN_E2E_IMAGE_CHAT_AGENT_ID)
+describe.skipIf(!isMultimodalChatE2EReady())(
+  "e2e: knowledge chat --image live (常驻 fixture)",
+  () => {
+    const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+    const imageChatAgentId = process.env.BAILIAN_E2E_IMAGE_CHAT_AGENT_ID!;
+
+    test("多模态问答接受 --image 并返回非空回答", async () => {
+      const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHAT_ROUTES, [
+        "knowledge",
+        "chat",
+        "--message",
+        "图里有什么",
+        "--image",
+        "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg",
+        "--agent-id",
+        imageChatAgentId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<ChatJsonResult>(stdout);
+      expect(data.answer).toBeTruthy();
+      expect(data.answer.length).toBeGreaterThan(0);
+    }, 120_000);
+  },
+);