connectbase-client 3.39.2 → 3.41.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.41.0] - 2026-07-02
+
+### Added — 웹 배포 파일당 크기 한도 사전 검증 (fail-fast)
+
+`connectbase deploy` 가 파일을 수집한 직후, 서버로 업로드하기 **전에** 각 파일이 웹 스토리지
+파일당 크기 한도를 넘는지 검사한다(플랫폼 이슈 019f221b). 기존에는 전량 수집·업로드를 마친
+뒤에야 서버에서 원시 DB 오류(`Error 8025 (HY000): entry too large`)로 실패해 원인 파악이
+어려웠다.
+
+- 초과 파일이 있으면 **어떤 파일이 얼마나 큰지**(바이너리는 원본→base64 크기까지) 나열하고,
+  파일 스토리지(`cb.storage`) 사용을 안내한 뒤 업로드 없이 즉시 종료한다.
+- 검사 기준: 파일 내용은 DB(TiDB Text 컬럼)에 저장되며 단일 엔트리 한도 6 MiB 를 넘을 수 없다.
+  바이너리는 base64(약 1.33x)로 저장되므로 원본 기준 실질 상한은 약 4.5 MB.
+- 텍스트 파일은 UTF-8 바이트 기준으로 정확히 계산(멀티바이트 문자 포함).
+
+## [3.40.0] - 2026-06-28
+
+### Added — KB 하이브리드(시맨틱) 검색 지원
+
+지식베이스 검색에 BM25 키워드 + 벡터 의미 검색을 RRF(Reciprocal Rank Fusion)로 융합하는
+하이브리드 검색을 추가했다. 콘솔 > **AI** 에서 임베딩을 켠 앱(gemini / openai BYOK)에서
+동작하며, 오타·동의어·의역에 강하다.
+
+- **\`KnowledgeSearchRequest.hybrid?: boolean\`** — \`cb.knowledge.search()\` 에 hybrid 옵션 추가.
+  미설정(기본)이면 임베딩을 켠 앱에서 자동 적용, \`false\` 면 키워드 전용 검색을 강제.
+- **\`AIChatRequest.hybrid?: boolean\`** — \`cb.ai.chat()\` / \`cb.ai.chatStream()\` 의 RAG 검색에도
+  동일 옵션 적용. 미설정이면 임베딩을 켠 앱에서 자동 적용된다.
+- 임베딩 미설정 앱에서는 무시되며 기존 BM25 검색으로 동작한다(하위호환, 회귀 없음).
+
 ## [3.39.2] - 2026-06-26
 
 ### Performance — 터널 프록시 응답 지연 제거 (TCP_NODELAY / keep-alive)

package/dist/cli.js

@@ -215,6 +215,7 @@ var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".zip",
   ".wasm"
 ]);
+var WEB_FILE_MAX_STORED_BYTES = 6 * 1024 * 1024 - 64 * 1024;
 function sha256Hex(value) {
   return crypto.createHash("sha256").update(value, "utf8").digest("hex");
 }
@@ -281,6 +282,29 @@ function collectFiles(dir, baseDir = dir) {
   }
   return files;
 }
+function formatSize(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+function validateFileSizes(files) {
+  const oversized = files.map((f) => {
+    const storedBytes = Buffer.byteLength(f.content, "utf8");
+    const originalBytes = f.isBinary ? Math.round(f.content.length * 3 / 4) : storedBytes;
+    return { path: f.path, isBinary: f.isBinary, storedBytes, originalBytes };
+  }).filter((f) => f.storedBytes > WEB_FILE_MAX_STORED_BYTES);
+  if (oversized.length === 0) return;
+  error(`\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uD30C\uC77C\uB2F9 \uD06C\uAE30 \uD55C\uB3C4(\uC57D ${formatSize(WEB_FILE_MAX_STORED_BYTES)})\uB97C \uCD08\uACFC\uD55C \uD30C\uC77C\uC774 \uC788\uC5B4 \uBC30\uD3EC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4:`);
+  for (const f of oversized) {
+    const detail = f.isBinary ? `${formatSize(f.originalBytes)} \u2192 base64 ${formatSize(f.storedBytes)}` : formatSize(f.storedBytes);
+    error(`  \u2022 ${f.path} (${detail})`);
+  }
+  log("");
+  warn("\uC815\uC801 \uD638\uC2A4\uD305 \uD30C\uC77C\uC740 DB \uB2E8\uC77C \uC5D4\uD2B8\uB9AC(6 MiB)\uC5D0 \uC800\uC7A5\uB418\uBA70, \uBC14\uC774\uB108\uB9AC\uB294 base64(\uC57D 1.33x)\uB85C");
+  warn("\uBD80\uD480\uC5B4 \uC6D0\uBCF8 \uAE30\uC900 \uC57D 4.5 MB \uAC00 \uC2E4\uC9C8 \uC0C1\uD55C\uC785\uB2C8\uB2E4.");
+  warn(`\uB300\uC6A9\uB7C9 \uC5D0\uC14B(3D \uBAA8\uB378\xB7\uB3D9\uC601\uC0C1\xB7\uD070 \uD3F0\uD2B8 \uB4F1)\uC740 \uD30C\uC77C \uC2A4\uD1A0\uB9AC\uC9C0(${colors.cyan}cb.storage${colors.reset}, presigned URL)\uC5D0`);
+  warn("\uC62C\uB9AC\uACE0 URL \uB85C \uCC38\uC870\uD558\uC138\uC694. \uD30C\uC77C \uC2A4\uD1A0\uB9AC\uC9C0\uB294 \uD30C\uC77C\uB2F9 \uACE0\uC815 \uC0C1\uD55C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  process.exit(1);
+}
 var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
 async function makeRequest(url, method, headers, body, reqOpts = {}) {
   return new Promise((resolve2, reject) => {
@@ -378,6 +402,7 @@ async function deploy(directory, config, isDev = false, deployOpts = {}) {
     error("\uBC30\uD3EC\uD560 \uD30C\uC77C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4");
     process.exit(1);
   }
+  validateFileSizes(files);
   const totalSize = files.reduce((sum, f) => sum + f.content.length, 0);
   const sizeKB = (totalSize / 1024).toFixed(1);
   log(`${colors.green}\u2713${colors.reset} ${files.length}\uAC1C \uD30C\uC77C \uBC1C\uACAC (${sizeKB} KB)`);

package/dist/index.d.mts

@@ -2402,14 +2402,15 @@ declare class StorageAPI {
      * 파일 목록 조회
      *
      * @param storageId - 파일 스토리지 ID
-     * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+     * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+     *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
      *
      * @example
      * ```ts
-     * // 루트 폴더의 파일 목록
+     * // 스토리지 전체 파일 목록 (flat 트리)
      * const files = await cb.storage.getFiles('storage-id')
      *
-     * // 특정 폴더의 하위 파일 목록
+     * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
      * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
      * ```
      */
@@ -7370,6 +7371,12 @@ interface KnowledgeSearchRequest {
     top_k?: number;
     /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
     agentic?: boolean;
+    /**
+     * Hybrid 검색 — BM25 키워드 + 벡터 시맨틱 검색을 RRF 로 융합.
+     * 미설정(기본): 콘솔 > AI 에서 embedding 을 켠 앱은 자동 적용.
+     * `false`: 키워드 전용 검색 강제. embedding 미설정 앱에서는 무시(BM25 only).
+     */
+    hybrid?: boolean;
     /**
      * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
      * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
@@ -7655,6 +7662,11 @@ interface AIChatRequest {
     knowledgeBaseId?: string;
     topK?: number;
     agentic?: boolean;
+    /**
+     * KB 검색 hybrid(BM25 + 벡터 시맨틱, RRF 융합) 제어. 미설정(기본)이면 콘솔 > AI 에서
+     * embedding 을 켠 앱은 자동 적용, `false` 면 키워드 전용 검색 강제.
+     */
+    hybrid?: boolean;
     toolGroupId?: string;
     /**
      * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에

package/dist/index.d.ts

@@ -2402,14 +2402,15 @@ declare class StorageAPI {
      * 파일 목록 조회
      *
      * @param storageId - 파일 스토리지 ID
-     * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+     * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+     *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
      *
      * @example
      * ```ts
-     * // 루트 폴더의 파일 목록
+     * // 스토리지 전체 파일 목록 (flat 트리)
      * const files = await cb.storage.getFiles('storage-id')
      *
-     * // 특정 폴더의 하위 파일 목록
+     * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
      * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
      * ```
      */
@@ -7370,6 +7371,12 @@ interface KnowledgeSearchRequest {
     top_k?: number;
     /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
     agentic?: boolean;
+    /**
+     * Hybrid 검색 — BM25 키워드 + 벡터 시맨틱 검색을 RRF 로 융합.
+     * 미설정(기본): 콘솔 > AI 에서 embedding 을 켠 앱은 자동 적용.
+     * `false`: 키워드 전용 검색 강제. embedding 미설정 앱에서는 무시(BM25 only).
+     */
+    hybrid?: boolean;
     /**
      * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
      * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
@@ -7655,6 +7662,11 @@ interface AIChatRequest {
     knowledgeBaseId?: string;
     topK?: number;
     agentic?: boolean;
+    /**
+     * KB 검색 hybrid(BM25 + 벡터 시맨틱, RRF 융합) 제어. 미설정(기본)이면 콘솔 > AI 에서
+     * embedding 을 켠 앱은 자동 적용, `false` 면 키워드 전용 검색 강제.
+     */
+    hybrid?: boolean;
     toolGroupId?: string;
     /**
      * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에

package/dist/index.js

@@ -2279,14 +2279,15 @@ var StorageAPI = class {
    * 파일 목록 조회
    *
    * @param storageId - 파일 스토리지 ID
-   * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+   * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+   *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
    *
    * @example
    * ```ts
-   * // 루트 폴더의 파일 목록
+   * // 스토리지 전체 파일 목록 (flat 트리)
    * const files = await cb.storage.getFiles('storage-id')
    *
-   * // 특정 폴더의 하위 파일 목록
+   * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
    * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
    * ```
    */

package/dist/index.mjs

@@ -2234,14 +2234,15 @@ var StorageAPI = class {
    * 파일 목록 조회
    *
    * @param storageId - 파일 스토리지 ID
-   * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+   * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+   *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
    *
    * @example
    * ```ts
-   * // 루트 폴더의 파일 목록
+   * // 스토리지 전체 파일 목록 (flat 트리)
    * const files = await cb.storage.getFiles('storage-id')
    *
-   * // 특정 폴더의 하위 파일 목록
+   * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
    * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
    * ```
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "3.39.2",
+  "version": "3.41.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",