docs(knowledge): 修改多处参数描述为“精确匹配”并完善错误处理说明

- 将 category-list、file-list、service-list 等命令参数的描述更新为强调“精确匹配”
- file-list 命令中 --name 参数改为匹配不含扩展名的精确文件名，并在备注中补充说明
- kb-stats 命令严格校验时间格式，增强无效格式报错及提示
- 丰富知识相关测试用例，增加对不存在 ID 的服务端错误传递和非零退出的正向断言
- 优化知识文档上传测试，支持跳过 node_modules/.git 文件夹及显示被跳过文件详情
- 修正知识搜索及聊天流程中未发布版本号引发的服务器拒绝场景测试
- 更新知识模块命令文档，补充参数要求和用法提示，提升用户指引明确度

Author: clark-fc

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

@@ -13,12 +13,12 @@ const CATEGORY_LIST_FLAGS = {
   collectionId: {
     type: "string",
     valueHint: "<id>",
-    description: "Filter by collection ID",
+    description: "Filter by exact collection ID",
   },
   parentId: {
     type: "string",
     valueHint: "<id>",
-    description: "List sub-categories of this category",
+    description: "List sub-categories of this exact parent category",
   },
   name: {
     type: "string",

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

@@ -13,18 +13,18 @@ const FILE_LIST_FLAGS = {
   categoryId: {
     type: "string",
     valueHint: "<id>",
-    description: "Category to list (find ids via the category list command)",
+    description: "Category to list (find ids via the category list command); exact match",
     required: true,
   },
   name: {
     type: "string",
     valueHint: "<text>",
-    description: "Filter by file name",
+    description: "Filter by exact file name without its extension (a.md → pass a)",
   },
   fileId: {
     type: "array",
     valueHint: "<id>",
-    description: "Filter by file ID (repeatable)",
+    description: "Filter by exact file ID (repeatable)",
   },
   nextToken: {
     type: "string",
@@ -46,6 +46,7 @@ export default defineCommand({
   flags: FILE_LIST_FLAGS,
   notes: [
     "A real category id is required — the default value is not resolved here. Find the id via the category list command.",
+    "--name matches the exact file name without its extension (for a.md pass a); partial keywords return no results.",
     "Pagination is cursor-based: reuse the printed next token to continue.",
   ],
   exampleArgs: [

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

@@ -38,7 +38,10 @@ export function toEpochSecondsString(input: string): string {
     // Digits-only input is treated as Unix seconds; 13-digit millisecond timestamps are reduced to seconds
     return input.length >= 13 ? String(Math.floor(Number(input) / 1000)) : input;
   }
-  const parsedMs = Date.parse(input);
+  // Non-numeric input must be a full ISO date (YYYY-MM-DD, optionally with a time
+  // part). Date.parse alone is too lenient — V8 silently reads truncated input
+  // like "2026-" as Jan 1st, which would query a misleading range.
+  const parsedMs = /^\d{4}-\d{2}-\d{2}([T ].*)?$/.test(input) ? Date.parse(input) : Number.NaN;
   if (Number.isNaN(parsedMs)) {
     throw new BailianError(
       `Invalid time value: ${input}`,

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

@@ -34,7 +34,7 @@ const SERVICE_LIST_FLAGS = {
   indexId: {
     type: "string",
     valueHint: "<id>",
-    description: "Filter by linked knowledge base (pipeline) ID",
+    description: "Filter by exact linked knowledge base (pipeline) ID",
   },
   ...PAGE_FLAGS,
   ...WORKSPACE_FLAG,

packages/commands/tests/e2e/knowledge/journeys/j1-cold-start.e2e.test.ts

@@ -152,6 +152,30 @@ describe.skipIf(!isKbAdminE2EReady())("journey J1: 冷启动首答 (live, 自清
         answerText.includes(marker),
         answerText || "(empty)",
       );
+
+      // 5) Negative branch: calling a version number that was never published —
+      // the server rejects (HTTP 400, verified live) and the CLI exits non-zero
+      // with the error passed through (the version set is server-side state)
+      const chatBadVersionRun = await reporter.runStep(
+        "chat unpublished version (expect reject)",
+        JOURNEY_J1_ROUTES,
+        [
+          "knowledge",
+          "chat",
+          "--message",
+          `What is ${marker}?`,
+          "--agent-id",
+          chatAgentId,
+          "--agent-version",
+          "999",
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ],
+      );
+      expect(chatBadVersionRun.exitCode, "未发布版本号应被服务端拒绝").not.toBe(0);
+      expect(chatBadVersionRun.stderr).toMatch(/HTTP 400/);
     } finally {
       for (const agentId of serviceAgentIds) {
         const deleteRun = await reporter.runStep(

packages/commands/tests/e2e/knowledge/journeys/j2-content-ops.e2e.test.ts

@@ -67,6 +67,27 @@ describe.skipIf(!isKbAdminE2EReady())("journey J2: 内容运维 (live, 自清理
       expect(docStatusRun.exitCode, docStatusRun.stderr).toBe(0);
       expect(docStatusRun.stdout.trim()).toBe("COMPLETED");
 
+      // 2.1) Negative branch: querying a job id that does not exist on this base —
+      // the server error (Index.IndexJobNotExist, verified live) passes through
+      // verbatim with a non-zero exit
+      const badJobStatusRun = await reporter.runStep(
+        "doc status unknown job (expect reject)",
+        JOURNEY_J2_ROUTES,
+        [
+          "knowledge",
+          "doc",
+          "status",
+          "--index-id",
+          kb.indexId,
+          "--job-id",
+          "job_nonexistent_e2e",
+          "--workspace-id",
+          workspaceId,
+        ],
+      );
+      expect(badJobStatusRun.exitCode, "不存在的 job id 应被服务端拒绝").not.toBe(0);
+      expect(badJobStatusRun.stderr).toMatch(/not exist/i);
+
       // 2.5) knowledge stats — monitor endpoint returns valid structure (hard)
       const statsRun = await reporter.runStep("kb stats", JOURNEY_J2_ROUTES, [
         "knowledge",

packages/commands/tests/e2e/knowledge/journeys/j3-chunk-tuning.e2e.test.ts

@@ -158,6 +158,39 @@ describe.skipIf(!isKbAdminE2EReady())("journey J3: 检索精修 (live, 自清理
         restored.satisfied,
         `attempts=${restored.attempts} exit=${restored.value.exitCode}`,
       );
+
+      // 5) Negative branch: deleting a chunk id that does not exist on this base —
+      // the server rejects (Index.InvalidParameter, verified live) and the error
+      // passes through verbatim; the marker chunk must remain recallable afterwards
+      const badDeleteRun = await reporter.runStep(
+        "chunk delete unknown id (expect reject)",
+        JOURNEY_J3_ROUTES,
+        [
+          "knowledge",
+          "chunk",
+          "delete",
+          "--index-id",
+          kb.indexId,
+          "--chunk-id",
+          "chunk_nonexistent_e2e_0000",
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ],
+      );
+      expect(badDeleteRun.exitCode, "不存在的 chunk id 应被服务端拒绝").not.toBe(0);
+      expect(badDeleteRun.stderr).toMatch(/invalid|not exist/i);
+
+      const afterBadDelete = await reporter.runStep(
+        "retrieve after failed delete",
+        JOURNEY_J3_ROUTES,
+        retrieveArgs,
+      );
+      expect(afterBadDelete.exitCode, afterBadDelete.stderr).toBe(0);
+      expect(
+        nodesRecallMarker(afterBadDelete.stdout, marker),
+        `失败的删除误伤: ${marker} 不再召回`,
+      ).toBe(true);
     } finally {
       await cleanupKbFixture(reporter, JOURNEY_J3_ROUTES, fixture, workspaceId);
       reporter.finalize();

packages/commands/tests/e2e/knowledge/journeys/j4-service-tuning.e2e.test.ts

@@ -280,6 +280,30 @@ describe.skipIf(!isKbAdminE2EReady())("journey J4: 问答服务调优 (live, 自
       );
       reporter.recordNote(`正式版 search 轮询 ${releasedPoll.attempts} 次`);
       expect(releasedPoll.satisfied, `发布后正式版 search 未召回 ${marker}`).toBe(true);
+
+      // 6) Negative branch: calling a version number that was never published —
+      // the server rejects (RagAgentNotExist, verified live) and the CLI exits
+      // non-zero with the error passed through (the version set is server-side state)
+      const badVersionSearchRun = await reporter.runStep(
+        "search unpublished version (expect reject)",
+        JOURNEY_J4_ROUTES,
+        [
+          "knowledge",
+          "search",
+          "--query",
+          marker,
+          "--agent-id",
+          agentId,
+          "--agent-version",
+          "999",
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ],
+      );
+      expect(badVersionSearchRun.exitCode, "未发布版本号应被服务端拒绝").not.toBe(0);
+      expect(badVersionSearchRun.stderr).toMatch(/Agent application not found|RagAgentNotExist/i);
     } finally {
       if (agentId) {
         const deleteRun = await reporter.runStep("cleanup: service delete", JOURNEY_J4_ROUTES, [

packages/commands/tests/e2e/knowledge/journeys/j5-data-plane.e2e.test.ts

@@ -141,6 +141,26 @@ describe.skipIf(!isConnectorE2EReady())("journey J5: 数据面治理 (live, 自
       ]);
       expect(fileDeleteRun.exitCode, fileDeleteRun.stderr).toBe(0);
       reporter.markCleaned(fileId);
+
+      // 3.1) Negative branch: deleting the same file again — it no longer exists,
+      // so the server rejects ("Cant find out file", verified live) and the error
+      // passes through verbatim with a non-zero exit
+      const repeatDeleteRun = await reporter.runStep(
+        "file delete again (expect reject)",
+        JOURNEY_J5_ROUTES,
+        [
+          "knowledge",
+          "file",
+          "delete",
+          "--file-id",
+          fileId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ],
+      );
+      expect(repeatDeleteRun.exitCode, "重复删除已不存在的文件应被服务端拒绝").not.toBe(0);
+      expect(repeatDeleteRun.stderr).toMatch(/cant find|InvalidParameter/i);
     } finally {
       if (categoryId) {
         // 4) Clean up the self-created category + list verifies removal

packages/commands/tests/e2e/knowledge/knowledge-chunk-category-file.e2e.test.ts

@@ -17,7 +17,7 @@ import {
   KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES,
   KNOWLEDGE_KB_DELETE_ROUTES,
 } from "../topic-routes.ts";
-import { deleteKbWithRetry } from "./journeys/journey-helpers.ts";
+import { deleteKbWithRetry, pollUntil } from "./journeys/journey-helpers.ts";
 
 interface DryRunBody {
   endpoint?: string;
@@ -854,6 +854,21 @@ describe.skipIf(!isKbAdminE2EReady())(
   () => {
     const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
 
+    test("file get 不存在的 file-id: 服务端错误原样透传 (非零退出)", async () => {
+      const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "file",
+        "get",
+        "--file-id",
+        "file_nonexistent_e2e_0000",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(exitCode).not.toBe(0);
+      // Verified live: HTTP 200 + InvalidParameter with a "cant find" message
+      expect(stderr).toMatch(/cant find|InvalidParameter/i);
+    }, 60_000);
+
     test("collection get/create live: 幂等复用固定名测试集合", async () => {
       // collection has no delete API — reuse a fixed name idempotently instead of creating
       // new ones (the legacy name e2e-test-connector is kept: that idempotent resource
@@ -1521,8 +1536,25 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: chunk/category/file 参数补全 (li
     const categoryId = categoryAddRun.stdout.trim();
     expect(categoryId).toMatch(/^cate_/);
 
+    // ── empty-result contract: a freshly created category has no files —
+    // text mode prints the friendly empty line and exits 0 (empty ≠ error) ──
+    const emptyCategoryListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "file",
+      "list",
+      "--category-id",
+      categoryId,
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(emptyCategoryListRun.exitCode, emptyCategoryListRun.stderr).toBe(0);
+    expect(emptyCategoryListRun.stdout).toMatch(/No files found\./);
+
     const fixtureDir = mkdtempSync(join(tmpdir(), "param-e2e-"));
-    const filePath = join(fixtureDir, `param-${Date.now()}.md`);
+    // Server contract (verified live): listFile fileName filters by the exact
+    // file name WITHOUT extension — keep the stem for the --name assertion below
+    const fileStem = `param-${Date.now()}`;
+    const filePath = join(fixtureDir, `${fileStem}.md`);
     writeFileSync(filePath, "# e2e param file\n");
     const uploadRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
       "knowledge",
@@ -1541,21 +1573,30 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: chunk/category/file 参数补全 (li
     let indexId: string | undefined;
 
     try {
-      // ── P2: file list --name (模糊匹配) ──
-      const fileListByNameRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
-        "knowledge",
-        "file",
-        "list",
-        "--category-id",
-        categoryId,
-        "--name",
-        "param-",
-        "--workspace-id",
-        workspaceId,
-        "--quiet",
-      ]);
-      expect(fileListByNameRun.exitCode, fileListByNameRun.stderr).toBe(0);
-      expect(fileListByNameRun.stdout.trim().split("\n")).toContain(fileId);
+      // ── P2: file list --name —— exact match on the extension-less file name
+      // (e.g. a.md → pass a); fuzzy/partial keywords return an empty set.
+      // Poll to absorb list-visibility lag right after upload ──
+      const fileListByNamePoll = await pollUntil(
+        () =>
+          runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+            "knowledge",
+            "file",
+            "list",
+            "--category-id",
+            categoryId,
+            "--name",
+            fileStem,
+            "--workspace-id",
+            workspaceId,
+            "--quiet",
+          ]),
+        (run) => run.exitCode === 0 && run.stdout.trim().split("\n").includes(fileId),
+        { timeoutMs: 60_000, intervalMs: 5_000 },
+      );
+      expect(
+        fileListByNamePoll.satisfied,
+        `file list --name 未包含 ${fileId} (attempts=${fileListByNamePoll.attempts})`,
+      ).toBe(true);
 
       // ── P2: file list --file-id ──
       const fileListByFileIdRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
@@ -1638,7 +1679,9 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: chunk/category/file 参数补全 (li
       ]);
       expect(listByParentRun.exitCode, listByParentRun.stderr).toBe(0);
 
-      // ── P3: category list --collection-id (no-error verification) ──
+      // ── P3: category list --collection-id — an unknown collection id is rejected
+      // by the server (Invalid connectorId, verified live) and the error passes
+      // through verbatim with a non-zero exit ──
       const listByCollectionRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
         "knowledge",
         "category",
@@ -1649,7 +1692,8 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: chunk/category/file 参数补全 (li
         workspaceId,
         "--quiet",
       ]);
-      expect(listByCollectionRun.exitCode, listByCollectionRun.stderr).toBe(0);
+      expect(listByCollectionRun.exitCode, "不存在的 collection id 应被服务端拒绝").not.toBe(0);
+      expect(listByCollectionRun.stderr).toMatch(/Invalid connectorId|InvalidParameter/i);
 
       // ── create kb for chunk tests ──
       const kbCreateRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
@@ -1744,6 +1788,45 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: chunk/category/file 参数补全 (li
           expect(node.metadata?.doc_id).toContain(fileId);
         }
 
+        // ── empty-result contract: a page far past the end returns no chunks —
+        // text mode prints the friendly empty line and exits 0 (empty ≠ error) ──
+        const chunkListEmptyPageRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--page-number",
+          "99",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(chunkListEmptyPageRun.exitCode, chunkListEmptyPageRun.stderr).toBe(0);
+        expect(chunkListEmptyPageRun.stdout).toMatch(/No chunks found\./);
+
+        // ── contract: updating a nonexistent chunk id — the server currently
+        // reports success (silent upsert-like semantics, verified live). The CLI
+        // passes the server result through without an existence pre-check; this
+        // assertion pins the known server behavior so a future server-side change
+        // (rejecting unknown ids) surfaces here immediately ──
+        const chunkUpdateMissingRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "update",
+          "--index-id",
+          indexId,
+          "--chunk-id",
+          "chunk_nonexistent_e2e_0000",
+          "--doc-id",
+          fileId,
+          "--content",
+          "content for a chunk id that should not exist",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(chunkUpdateMissingRun.exitCode, chunkUpdateMissingRun.stderr).toBe(0);
+        expect(chunkUpdateMissingRun.stdout).toMatch(/updated: chunk_nonexistent_e2e_0000/);
+
         // ── P4: chunk update --content-file ──
         if (addedChunkId) {
           const updateContentFile = join(fixtureDir, `chunk-update-${Date.now()}.txt`);