@h-ai/vecdb 0.1.0-alpha.32 → 0.1.0-alpha.34

package/dist/index.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { core, ok, err } from '@h-ai/core';
+import { spawn } from 'child_process';
+import { setTimeout } from 'timers/promises';
 import { createHash } from 'crypto';
 
 // src/vecdb-config.ts
@@ -112,10 +114,31 @@ var QdrantConfigSchema = z.object({
   metric: DistanceMetricSchema.optional(),
   ...OperationLogConfigFieldSchema
 });
+var ChromaConfigSchema = z.object({
+  type: z.literal("chroma"),
+  /** 本地持久化路径（嵌入式模式：提供且无 url 时自动拉起本地服务） */
+  path: z.string().optional(),
+  /** 已有 Chroma 服务 URL（提供时直连，不自动拉起进程） */
+  url: z.string().url().optional(),
+  /** 主机（默认 localhost） */
+  host: z.string().default("localhost"),
+  /** 端口（默认 8000） */
+  port: z.number().int().min(1).max(65535).default(8e3),
+  /** API Key（可选，连接受保护的 Chroma 服务时使用） */
+  apiKey: z.string().optional(),
+  /** 拉起本地服务的可执行命令（默认 'chroma'，可指定绝对路径） */
+  serverCommand: z.string().default("chroma"),
+  /** 拉起本地服务的就绪等待超时（毫秒，默认 30000） */
+  startupTimeout: z.number().int().positive().default(3e4),
+  /** 距离度量（默认 cosine） */
+  metric: DistanceMetricSchema.optional(),
+  ...OperationLogConfigFieldSchema
+});
 var VecdbConfigSchema = z.discriminatedUnion("type", [
   LancedbConfigSchema,
   PgvectorConfigSchema,
-  QdrantConfigSchema
+  QdrantConfigSchema,
+  ChromaConfigSchema
 ]);
 var VecdbErrorInfo = {
   CONNECTION_FAILED: "001:500",
@@ -302,8 +325,295 @@ function createBaseVectorOps(ctx, driver) {
   };
 }
 
-// src/providers/vecdb-provider-lancedb.ts
-var logger = core.logger.child({ module: "vecdb", scope: "lancedb" });
+// src/providers/vecdb-provider-chroma.ts
+var logger = core.logger.child({ module: "vecdb", scope: "chroma" });
+var DIMENSION_METADATA_KEY = "hai_dimension";
+var SPACE_METADATA_KEY = "hnsw:space";
+var HEARTBEAT_POLL_INTERVAL = 300;
+function isChromaModule(value) {
+  return typeof value === "object" && value !== null && typeof value.ChromaClient === "function";
+}
+var NOOP_EMBEDDING_FUNCTION = {
+  name: "hai-noop",
+  async generate() {
+    throw new Error("Chroma embedding function should not be called: vectors are provided explicitly");
+  }
+};
+function toChromaSpace(metric) {
+  if (metric === "euclidean")
+    return "l2";
+  if (metric === "dot")
+    return "ip";
+  return "cosine";
+}
+function fromChromaSpace(space) {
+  if (space === "l2")
+    return "euclidean";
+  if (space === "ip")
+    return "dot";
+  return "cosine";
+}
+function distanceToScore(distance, metric) {
+  if (metric === "cosine")
+    return Math.max(0, Math.min(1, 1 - distance));
+  return 1 / (1 + Math.max(0, distance));
+}
+function buildWhere(filter) {
+  if (!filter)
+    return void 0;
+  const entries = Object.entries(filter);
+  if (entries.length === 0)
+    return void 0;
+  if (entries.length === 1)
+    return { [entries[0][0]]: entries[0][1] };
+  return { $and: entries.map(([key, value]) => ({ [key]: value })) };
+}
+function createChromaProvider() {
+  let client = null;
+  let config = null;
+  let serverProcess = null;
+  function isMissingModuleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("chromadb");
+  }
+  async function loadChromaModule() {
+    try {
+      const mod = await import('chromadb');
+      if (!isChromaModule(mod)) {
+        const error = new Error("chromadb driver module does not export ChromaClient");
+        logger.error("Failed to load Chroma driver", { error: error.message });
+        return err(HaiVecdbError.DRIVER_NOT_FOUND, vecdbM("vecdb_driverNotFound", { params: { driver: "chromadb" } }), error);
+      }
+      return ok(mod);
+    } catch (error) {
+      if (isMissingModuleError(error)) {
+        logger.error("Failed to load Chroma driver", { error: error instanceof Error ? error.message : String(error) });
+        return err(HaiVecdbError.DRIVER_NOT_FOUND, vecdbM("vecdb_driverNotFound", { params: { driver: "chromadb" } }), error);
+      }
+      throw error;
+    }
+  }
+  function startEmbeddedServer(chromaConfig) {
+    const args = ["run", "--path", chromaConfig.path ?? "./data/chroma", "--host", chromaConfig.host, "--port", String(chromaConfig.port)];
+    logger.info("Starting embedded Chroma server", { command: chromaConfig.serverCommand, host: chromaConfig.host, port: chromaConfig.port });
+    const proc = spawn(chromaConfig.serverCommand, args, { stdio: "ignore" });
+    proc.on("error", (error) => {
+      logger.error("Chroma server process error", { error: error.message });
+    });
+    serverProcess = proc;
+  }
+  function stopEmbeddedServer() {
+    if (!serverProcess)
+      return;
+    try {
+      serverProcess.kill();
+    } catch (error) {
+      logger.warn("Failed to stop Chroma server", { error: error instanceof Error ? error.message : String(error) });
+    }
+    serverProcess = null;
+  }
+  async function waitForHeartbeat(chromaClient, timeout) {
+    const deadline = Date.now() + timeout;
+    let lastError;
+    while (Date.now() < deadline) {
+      try {
+        await chromaClient.heartbeat();
+        return;
+      } catch (error) {
+        lastError = error;
+        await setTimeout(HEARTBEAT_POLL_INTERVAL);
+      }
+    }
+    throw new Error(`Chroma heartbeat timed out after ${timeout}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+  }
+  async function getCollection(name) {
+    return client.getCollection({ name, embeddingFunction: NOOP_EMBEDDING_FUNCTION });
+  }
+  function readDimension(collection) {
+    const value = collection.metadata?.[DIMENSION_METADATA_KEY];
+    return typeof value === "number" ? value : 0;
+  }
+  function validateDimension(expected, actual) {
+    if (expected === 0 || expected === actual)
+      return null;
+    return err(
+      HaiVecdbError.DIMENSION_MISMATCH,
+      vecdbM("vecdb_dimensionMismatch", { params: { expected: String(expected), actual: String(actual) } })
+    );
+  }
+  const ctx = { isConnected: () => client !== null, logger, operationLog: () => config?.operationLog };
+  const collectionDriver = {
+    async create(name, options) {
+      logger.debug("Creating collection", { name, dimension: options.dimension, metric: options.metric });
+      const existing = await client.listCollections();
+      const exists = existing.some((item) => (typeof item === "string" ? item : item.name) === name);
+      if (exists)
+        return err(HaiVecdbError.COLLECTION_ALREADY_EXISTS, vecdbM("vecdb_collectionAlreadyExists", { params: { name } }));
+      const metric = options.metric ?? config?.metric ?? "cosine";
+      await client.getOrCreateCollection({
+        name,
+        metadata: { [SPACE_METADATA_KEY]: toChromaSpace(metric), [DIMENSION_METADATA_KEY]: options.dimension },
+        embeddingFunction: NOOP_EMBEDDING_FUNCTION
+      });
+      logger.info("Collection created", { name, dimension: options.dimension, metric });
+      return ok(void 0);
+    },
+    async drop(name) {
+      logger.debug("Dropping collection", { name });
+      const existing = await client.listCollections();
+      const exists = existing.some((item) => (typeof item === "string" ? item : item.name) === name);
+      if (!exists)
+        return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
+      await client.deleteCollection({ name });
+      logger.info("Collection dropped", { name });
+      return ok(void 0);
+    },
+    async exists(name) {
+      logger.debug("Checking collection exists", { name });
+      const existing = await client.listCollections();
+      return ok(existing.some((item) => (typeof item === "string" ? item : item.name) === name));
+    },
+    async info(name) {
+      logger.debug("Getting collection info", { name });
+      const existing = await client.listCollections();
+      if (!existing.some((item) => (typeof item === "string" ? item : item.name) === name))
+        return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
+      const collection = await getCollection(name);
+      const count = await collection.count();
+      return ok({
+        name,
+        dimension: readDimension(collection),
+        metric: fromChromaSpace(collection.metadata?.[SPACE_METADATA_KEY]),
+        count
+      });
+    },
+    async list() {
+      logger.debug("Listing collections");
+      const existing = await client.listCollections();
+      return ok(existing.map((item) => typeof item === "string" ? item : item.name));
+    }
+  };
+  function toWriteParams(documents) {
+    return {
+      ids: documents.map((doc) => doc.id),
+      embeddings: documents.map((doc) => doc.vector),
+      documents: documents.map((doc) => doc.content ?? null),
+      metadatas: documents.map((doc) => ({ ...doc.metadata, _content: doc.content ?? "" }))
+    };
+  }
+  const vectorDriver = {
+    async insert(collection, documents) {
+      logger.debug("Inserting vectors", { collection, count: documents.length });
+      const target = await getCollection(collection);
+      const expected = readDimension(target);
+      for (const doc of documents) {
+        const validation = validateDimension(expected, doc.vector.length);
+        if (validation)
+          return validation;
+      }
+      await target.add(toWriteParams(documents));
+      logger.info("Vectors inserted", { collection, count: documents.length });
+      return ok(void 0);
+    },
+    async upsert(collection, documents) {
+      logger.debug("Upserting vectors", { collection, count: documents.length });
+      const target = await getCollection(collection);
+      const expected = readDimension(target);
+      for (const doc of documents) {
+        const validation = validateDimension(expected, doc.vector.length);
+        if (validation)
+          return validation;
+      }
+      await target.upsert(toWriteParams(documents));
+      logger.info("Vectors upserted", { collection, count: documents.length });
+      return ok(void 0);
+    },
+    async delete(collection, ids) {
+      logger.debug("Deleting vectors", { collection, count: ids.length });
+      const target = await getCollection(collection);
+      await target.delete({ ids });
+      logger.info("Vectors deleted", { collection, count: ids.length });
+      return ok(void 0);
+    },
+    async search(collection, vector, options) {
+      const topK = options?.topK ?? 10;
+      const minScore = options?.minScore ?? 0;
+      logger.debug("Searching vectors", { collection, topK, hasFilter: !!options?.filter });
+      const target = await getCollection(collection);
+      const expected = readDimension(target);
+      const validation = validateDimension(expected, vector.length);
+      if (validation)
+        return validation;
+      const metric = fromChromaSpace(target.metadata?.[SPACE_METADATA_KEY]);
+      const response = await target.query({ queryEmbeddings: [vector], nResults: topK, where: buildWhere(options?.filter) });
+      const ids = response.ids[0] ?? [];
+      const distances = response.distances?.[0] ?? [];
+      const metadatas = response.metadatas?.[0] ?? [];
+      const results = [];
+      for (let i = 0; i < ids.length; i++) {
+        const score = distanceToScore(distances[i] ?? 0, metric);
+        if (score < minScore)
+          continue;
+        const metadata = metadatas[i] ?? {};
+        const { _content, ...rest } = metadata;
+        results.push({
+          id: ids[i],
+          score,
+          content: typeof _content === "string" && _content.length > 0 ? _content : void 0,
+          metadata: Object.keys(rest).length > 0 ? rest : void 0
+        });
+      }
+      return ok(results);
+    },
+    async count(collection) {
+      logger.debug("Counting vectors", { collection });
+      const target = await getCollection(collection);
+      return ok(await target.count());
+    }
+  };
+  return {
+    name: "chroma",
+    async connect(cfg) {
+      if (cfg.type !== "chroma")
+        return err(HaiVecdbError.UNSUPPORTED_TYPE, vecdbM("vecdb_unsupportedType", { params: { type: cfg.type } }));
+      const chromaConfig = cfg;
+      const embedded = !!chromaConfig.path && !chromaConfig.url;
+      const loadResult = await loadChromaModule();
+      if (!loadResult.success)
+        return loadResult;
+      try {
+        if (embedded)
+          startEmbeddedServer(chromaConfig);
+        const clientParams = chromaConfig.url ? { path: chromaConfig.url } : { host: chromaConfig.host, port: chromaConfig.port };
+        if (chromaConfig.apiKey)
+          clientParams.auth = { provider: "token", credentials: chromaConfig.apiKey, tokenHeaderType: "AUTHORIZATION" };
+        const chromaClient = new loadResult.data.ChromaClient(clientParams);
+        await waitForHeartbeat(chromaClient, embedded ? chromaConfig.startupTimeout : 5e3);
+        client = chromaClient;
+        config = chromaConfig;
+        logger.info("Chroma connected", { embedded, host: chromaConfig.host, port: chromaConfig.port });
+        return ok(void 0);
+      } catch (error) {
+        stopEmbeddedServer();
+        logger.error("Failed to connect to Chroma", { error: error instanceof Error ? error.message : String(error) });
+        return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_connectionFailed", { params: { error: String(error) } }), error);
+      }
+    },
+    async close() {
+      stopEmbeddedServer();
+      client = null;
+      config = null;
+      logger.info("Chroma connection closed");
+      return ok(void 0);
+    },
+    isConnected() {
+      return client !== null;
+    },
+    collection: createBaseCollectionOps(ctx, collectionDriver),
+    vector: createBaseVectorOps(ctx, vectorDriver)
+  };
+}
+var logger2 = core.logger.child({ module: "vecdb", scope: "lancedb" });
 function escapeLanceFilterValue(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "\\%").replace(/_/g, "\\_");
 }
@@ -316,7 +626,7 @@ function createLancedbProvider() {
       const mod = await import('@lancedb/lancedb');
       return ok(mod);
     } catch (error) {
-      logger.error("Failed to load @lancedb/lancedb", { error });
+      logger2.error("Failed to load @lancedb/lancedb", { error });
       return err(HaiVecdbError.DRIVER_NOT_FOUND, vecdbM("vecdb_driverNotFound", { params: { driver: "@lancedb/lancedb" } }), error);
     }
   }
@@ -363,10 +673,10 @@ function createLancedbProvider() {
     }
     return null;
   }
-  const ctx = { isConnected: () => connection !== null, logger, operationLog: () => config?.operationLog };
+  const ctx = { isConnected: () => connection !== null, logger: logger2, operationLog: () => config?.operationLog };
   const collectionDriver = {
     async create(name, options) {
-      logger.debug("Creating collection", { name, dimension: options.dimension, metric: options.metric });
+      logger2.debug("Creating collection", { name, dimension: options.dimension, metric: options.metric });
       const tableNames = await connection.tableNames();
       if (tableNames.includes(name)) {
         return err(HaiVecdbError.COLLECTION_ALREADY_EXISTS, vecdbM("vecdb_collectionAlreadyExists", { params: { name } }));
@@ -382,27 +692,27 @@ function createLancedbProvider() {
       const table = await connection.createTable(name, [initRecord]);
       await table.delete('id = "__init__"');
       collectionMetas.set(name, { dimension, metric });
-      logger.info("Collection created", { name, dimension, metric });
+      logger2.info("Collection created", { name, dimension, metric });
       return ok(void 0);
     },
     async drop(name) {
-      logger.debug("Dropping collection", { name });
+      logger2.debug("Dropping collection", { name });
       const tableNames = await connection.tableNames();
       if (!tableNames.includes(name)) {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
       }
       await connection.dropTable(name);
       collectionMetas.delete(name);
-      logger.info("Collection dropped", { name });
+      logger2.info("Collection dropped", { name });
       return ok(void 0);
     },
     async exists(name) {
-      logger.debug("Checking collection exists", { name });
+      logger2.debug("Checking collection exists", { name });
       const tableNames = await connection.tableNames();
       return ok(tableNames.includes(name));
     },
     async info(name) {
-      logger.debug("Getting collection info", { name });
+      logger2.debug("Getting collection info", { name });
       const table = await openTable(name);
       if (!table) {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
@@ -417,14 +727,14 @@ function createLancedbProvider() {
       });
     },
     async list() {
-      logger.debug("Listing collections");
+      logger2.debug("Listing collections");
       const tableNames = await connection.tableNames();
       return ok(tableNames);
     }
   };
   const vectorDriver = {
     async insert(collection, documents) {
-      logger.debug("Inserting vectors", { collection, count: documents.length });
+      logger2.debug("Inserting vectors", { collection, count: documents.length });
       const table = await openTable(collection);
       if (!table) {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
@@ -440,11 +750,11 @@ function createLancedbProvider() {
         metadata: JSON.stringify(doc.metadata ?? {})
       }));
       await table.add(records);
-      logger.info("Vectors inserted", { collection, count: documents.length });
+      logger2.info("Vectors inserted", { collection, count: documents.length });
       return ok(void 0);
     },
     async upsert(collection, documents) {
-      logger.debug("Upserting vectors", { collection, count: documents.length });
+      logger2.debug("Upserting vectors", { collection, count: documents.length });
       const table = await openTable(collection);
       if (!table) {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
@@ -462,27 +772,27 @@ function createLancedbProvider() {
       if (typeof table.mergeInsert === "function") {
         await table.mergeInsert("id").whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(records);
       } else {
-        logger.warn("LanceDB mergeInsert is unavailable, falling back to delete/add upsert");
+        logger2.warn("LanceDB mergeInsert is unavailable, falling back to delete/add upsert");
         const ids = documents.map((d) => `"${escapeLanceFilterValue(d.id)}"`).join(", ");
         await table.delete(`id IN (${ids})`);
         await table.add(records);
       }
-      logger.info("Vectors upserted", { collection, count: documents.length });
+      logger2.info("Vectors upserted", { collection, count: documents.length });
       return ok(void 0);
     },
     async delete(collection, ids) {
-      logger.debug("Deleting vectors", { collection, count: ids.length });
+      logger2.debug("Deleting vectors", { collection, count: ids.length });
       const table = await openTable(collection);
       if (!table) {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
       }
       const idList = ids.map((id) => `"${escapeLanceFilterValue(id)}"`).join(", ");
       await table.delete(`id IN (${idList})`);
-      logger.info("Vectors deleted", { collection, count: ids.length });
+      logger2.info("Vectors deleted", { collection, count: ids.length });
       return ok(void 0);
     },
     async search(collection, vector, options) {
-      logger.debug("Searching vectors", { collection, topK: options?.topK, hasFilter: !!options?.filter });
+      logger2.debug("Searching vectors", { collection, topK: options?.topK, hasFilter: !!options?.filter });
       const table = await openTable(collection);
       if (!table) {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
@@ -517,7 +827,7 @@ function createLancedbProvider() {
       return ok(searchResults);
     },
     async count(collection) {
-      logger.debug("Counting vectors", { collection });
+      logger2.debug("Counting vectors", { collection });
       const table = await openTable(collection);
       if (!table) {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
@@ -557,10 +867,10 @@ function createLancedbProvider() {
           } catch {
           }
         }));
-        logger.info("LanceDB connected", { path: lanceConfig.path });
+        logger2.info("LanceDB connected", { path: lanceConfig.path });
         return ok(void 0);
       } catch (error) {
-        logger.error("Failed to connect to LanceDB", { error });
+        logger2.error("Failed to connect to LanceDB", { error });
         return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_connectionFailed", { params: { error: String(error) } }), error);
       }
     },
@@ -568,7 +878,7 @@ function createLancedbProvider() {
       connection = null;
       config = null;
       collectionMetas.clear();
-      logger.info("LanceDB connection closed");
+      logger2.info("LanceDB connection closed");
       return ok(void 0);
     },
     isConnected() {
@@ -578,7 +888,7 @@ function createLancedbProvider() {
     vector: createBaseVectorOps(ctx, vectorDriver)
   };
 }
-var logger2 = core.logger.child({ module: "vecdb", scope: "pgvector" });
+var logger3 = core.logger.child({ module: "vecdb", scope: "pgvector" });
 function isPgModule(value) {
   if (typeof value !== "object" || value === null) {
     return false;
@@ -608,7 +918,7 @@ function createPgvectorProvider() {
         return "<=>";
     }
   }
-  function distanceToScore(distance) {
+  function distanceToScore2(distance) {
     const metric = config?.metric ?? "cosine";
     switch (metric) {
       case "cosine":
@@ -630,13 +940,13 @@ function createPgvectorProvider() {
       const mod = await import('pg');
       if (!isPgModule(mod)) {
         const error = new Error("pg driver module does not export Pool");
-        logger2.error("Failed to load pg driver", { error: error.message });
+        logger3.error("Failed to load pg driver", { error: error.message });
         return err(HaiVecdbError.DRIVER_NOT_FOUND, vecdbM("vecdb_driverNotFound", { params: { driver: "pg" } }), error);
       }
       return ok(mod);
     } catch (error) {
       if (isMissingModuleError(error, "pg")) {
-        logger2.error("Failed to load pg driver", { error: error instanceof Error ? error.message : String(error) });
+        logger3.error("Failed to load pg driver", { error: error instanceof Error ? error.message : String(error) });
         return err(HaiVecdbError.DRIVER_NOT_FOUND, vecdbM("vecdb_driverNotFound", { params: { driver: "pg" } }), error);
       }
       throw error;
@@ -677,14 +987,14 @@ function createPgvectorProvider() {
     }
     return null;
   }
-  const ctx = { isConnected: () => pool !== null, logger: logger2, operationLog: () => config?.operationLog };
+  const ctx = { isConnected: () => pool !== null, logger: logger3, operationLog: () => config?.operationLog };
   const collectionDriver = {
     async create(name, options) {
       const table = tableName(name);
       const dimension = options.dimension;
       const metric = options.metric ?? config?.metric ?? "cosine";
       const indexType = config?.indexType ?? "hnsw";
-      logger2.debug("Creating collection", { name, dimension, metric, indexType });
+      logger3.debug("Creating collection", { name, dimension, metric, indexType });
       const checkResult = await pool.query(
         `SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = $1)`,
         [table]
@@ -715,12 +1025,12 @@ function createPgvectorProvider() {
           WITH (lists = 100)
         `);
       }
-      logger2.info("Collection created", { name, dimension, metric, indexType });
+      logger3.info("Collection created", { name, dimension, metric, indexType });
       return ok(void 0);
     },
     async drop(name) {
       const table = tableName(name);
-      logger2.debug("Dropping collection", { name });
+      logger3.debug("Dropping collection", { name });
       const checkResult = await pool.query(
         `SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = $1)`,
         [table]
@@ -729,11 +1039,11 @@ function createPgvectorProvider() {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name } }));
       }
       await pool.query(`DROP TABLE ${quoteIdent(table)}`);
-      logger2.info("Collection dropped", { name });
+      logger3.info("Collection dropped", { name });
       return ok(void 0);
     },
     async exists(name) {
-      logger2.debug("Checking collection exists", { name });
+      logger3.debug("Checking collection exists", { name });
       const result = await pool.query(
         `SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = $1)`,
         [tableName(name)]
@@ -741,7 +1051,7 @@ function createPgvectorProvider() {
       return ok(result.rows[0].exists);
     },
     async info(name) {
-      logger2.debug("Getting collection info", { name });
+      logger3.debug("Getting collection info", { name });
       const table = tableName(name);
       const dimensionResult = await getCollectionDimension(name);
       if (!dimensionResult.success) {
@@ -758,7 +1068,7 @@ function createPgvectorProvider() {
     },
     async list() {
       const prefix = config?.tablePrefix ?? "vec_";
-      logger2.debug("Listing collections");
+      logger3.debug("Listing collections");
       const result = await pool.query(
         `SELECT table_name FROM information_schema.tables WHERE table_name LIKE $1 AND table_schema = 'public'`,
         [`${prefix}%`]
@@ -772,7 +1082,7 @@ function createPgvectorProvider() {
   const vectorDriver = {
     async insert(collection, documents) {
       const table = tableName(collection);
-      logger2.debug("Inserting vectors", { collection, count: documents.length });
+      logger3.debug("Inserting vectors", { collection, count: documents.length });
       const dimensionResult = await getCollectionDimension(collection);
       if (!dimensionResult.success) {
         return dimensionResult;
@@ -794,12 +1104,12 @@ function createPgvectorProvider() {
         `INSERT INTO ${qi} (id, vector, content, metadata) VALUES ${values.join(", ")}`,
         params
       );
-      logger2.info("Vectors inserted", { collection, count: documents.length });
+      logger3.info("Vectors inserted", { collection, count: documents.length });
       return ok(void 0);
     },
     async upsert(collection, documents) {
       const table = tableName(collection);
-      logger2.debug("Upserting vectors", { collection, count: documents.length });
+      logger3.debug("Upserting vectors", { collection, count: documents.length });
       const dimensionResult = await getCollectionDimension(collection);
       if (!dimensionResult.success) {
         return dimensionResult;
@@ -825,15 +1135,15 @@ function createPgvectorProvider() {
            metadata = EXCLUDED.metadata`,
         params
       );
-      logger2.info("Vectors upserted", { collection, count: documents.length });
+      logger3.info("Vectors upserted", { collection, count: documents.length });
       return ok(void 0);
     },
     async delete(collection, ids) {
       const table = tableName(collection);
-      logger2.debug("Deleting vectors", { collection, count: ids.length });
+      logger3.debug("Deleting vectors", { collection, count: ids.length });
       const placeholders = ids.map((_, i) => `$${i + 1}`).join(", ");
       await pool.query(`DELETE FROM ${quoteIdent(table)} WHERE id IN (${placeholders})`, ids);
-      logger2.info("Vectors deleted", { collection, count: ids.length });
+      logger3.info("Vectors deleted", { collection, count: ids.length });
       return ok(void 0);
     },
     async search(collection, vector, options) {
@@ -841,7 +1151,7 @@ function createPgvectorProvider() {
       const topK = options?.topK ?? 10;
       const minScore = options?.minScore ?? 0;
       const op = distanceOp();
-      logger2.debug("Searching vectors", { collection, topK, hasFilter: !!options?.filter });
+      logger3.debug("Searching vectors", { collection, topK, hasFilter: !!options?.filter });
       const dimensionResult = await getCollectionDimension(collection);
       if (!dimensionResult.success) {
         return dimensionResult;
@@ -874,7 +1184,7 @@ function createPgvectorProvider() {
         filterParams
       );
       const searchResults = result.rows.map((row) => {
-        const score = distanceToScore(row.distance);
+        const score = distanceToScore2(row.distance);
         return {
           id: row.id,
           score,
@@ -886,7 +1196,7 @@ function createPgvectorProvider() {
     },
     async count(collection) {
       const table = tableName(collection);
-      logger2.debug("Counting vectors", { collection });
+      logger3.debug("Counting vectors", { collection });
       const result = await pool.query(`SELECT COUNT(*) as count FROM ${quoteIdent(table)}`);
       return ok(Number.parseInt(String(result.rows[0].count), 10));
     }
@@ -914,10 +1224,10 @@ function createPgvectorProvider() {
         pool = new Pool(poolConfig);
         await pool.query("CREATE EXTENSION IF NOT EXISTS vector");
         config = pgConfig;
-        logger2.info("pgvector connected", { host: pgConfig.host, database: pgConfig.database });
+        logger3.info("pgvector connected", { host: pgConfig.host, database: pgConfig.database });
         return ok(void 0);
       } catch (error) {
-        logger2.error("Failed to connect to pgvector", { error: error instanceof Error ? error.message : String(error) });
+        logger3.error("Failed to connect to pgvector", { error: error instanceof Error ? error.message : String(error) });
         return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_connectionFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
       }
     },
@@ -928,10 +1238,10 @@ function createPgvectorProvider() {
         }
         pool = null;
         config = null;
-        logger2.info("pgvector connection closed");
+        logger3.info("pgvector connection closed");
         return ok(void 0);
       } catch (error) {
-        logger2.error("Failed to close pgvector connection", { error: error instanceof Error ? error.message : String(error) });
+        logger3.error("Failed to close pgvector connection", { error: error instanceof Error ? error.message : String(error) });
         return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_closeFailed", { params: { error: String(error) } }), error);
       }
     },
@@ -954,7 +1264,7 @@ function sanitizeUrl(url) {
     return "(invalid url)";
   }
 }
-var logger3 = core.logger.child({ module: "vecdb", scope: "qdrant" });
+var logger4 = core.logger.child({ module: "vecdb", scope: "qdrant" });
 function isQdrantModule(value) {
   if (typeof value !== "object" || value === null) {
     return false;
@@ -990,13 +1300,13 @@ function createQdrantProvider() {
       const mod = await import('@qdrant/js-client-rest');
       if (!isQdrantModule(mod)) {
         const error = new Error("@qdrant/js-client-rest driver module does not export QdrantClient");
-        logger3.error("Failed to load Qdrant driver", { error: error.message });
+        logger4.error("Failed to load Qdrant driver", { error: error.message });
         return err(HaiVecdbError.DRIVER_NOT_FOUND, vecdbM("vecdb_driverNotFound", { params: { driver: "@qdrant/js-client-rest" } }), error);
       }
       return ok(mod);
     } catch (error) {
       if (isMissingModuleError(error, "@qdrant/js-client-rest")) {
-        logger3.error("Failed to load Qdrant driver", { error: error instanceof Error ? error.message : String(error) });
+        logger4.error("Failed to load Qdrant driver", { error: error instanceof Error ? error.message : String(error) });
         return err(HaiVecdbError.DRIVER_NOT_FOUND, vecdbM("vecdb_driverNotFound", { params: { driver: "@qdrant/js-client-rest" } }), error);
       }
       throw error;
@@ -1038,10 +1348,10 @@ function createQdrantProvider() {
       })
     );
   }
-  const ctx = { isConnected: () => client !== null, logger: logger3, operationLog: () => config?.operationLog };
+  const ctx = { isConnected: () => client !== null, logger: logger4, operationLog: () => config?.operationLog };
   const collectionDriver = {
     async create(name, options) {
-      logger3.debug("Creating collection", { name, dimension: options.dimension, metric: options.metric });
+      logger4.debug("Creating collection", { name, dimension: options.dimension, metric: options.metric });
       const collections = await client.getCollections();
       const exists = collections.collections.some((c) => c.name === name);
       if (exists) {
@@ -1054,21 +1364,21 @@ function createQdrantProvider() {
           distance: toQdrantDistance(metric)
         }
       });
-      logger3.info("Collection created", { name, dimension: options.dimension, metric });
+      logger4.info("Collection created", { name, dimension: options.dimension, metric });
       return ok(void 0);
     },
     async drop(name) {
-      logger3.debug("Dropping collection", { name });
+      logger4.debug("Dropping collection", { name });
       const infoResult = await getCollectionInfo(name);
       if (!infoResult.success) {
         return infoResult;
       }
       await client.deleteCollection(name);
-      logger3.info("Collection dropped", { name });
+      logger4.info("Collection dropped", { name });
       return ok(void 0);
     },
     async exists(name) {
-      logger3.debug("Checking collection exists", { name });
+      logger4.debug("Checking collection exists", { name });
       try {
         await client.getCollection(name);
         return ok(true);
@@ -1080,7 +1390,7 @@ function createQdrantProvider() {
       }
     },
     async info(name) {
-      logger3.debug("Getting collection info", { name });
+      logger4.debug("Getting collection info", { name });
       const infoResult = await getCollectionInfo(name);
       if (!infoResult.success) {
         return infoResult;
@@ -1098,7 +1408,7 @@ function createQdrantProvider() {
       });
     },
     async list() {
-      logger3.debug("Listing collections");
+      logger4.debug("Listing collections");
       const collections = await client.getCollections();
       const names = collections.collections.map((c) => c.name);
       return ok(names);
@@ -1106,7 +1416,7 @@ function createQdrantProvider() {
   };
   const vectorDriver = {
     async insert(collection, documents) {
-      logger3.debug("Inserting vectors", { collection, count: documents.length });
+      logger4.debug("Inserting vectors", { collection, count: documents.length });
       const dimensionResult = await getCollectionDimension(collection);
       if (!dimensionResult.success) {
         return dimensionResult;
@@ -1127,11 +1437,11 @@ function createQdrantProvider() {
         }
       }));
       await client.upsert(collection, { points });
-      logger3.info("Vectors inserted", { collection, count: documents.length });
+      logger4.info("Vectors inserted", { collection, count: documents.length });
       return ok(void 0);
     },
     async upsert(collection, documents) {
-      logger3.debug("Upserting vectors", { collection, count: documents.length });
+      logger4.debug("Upserting vectors", { collection, count: documents.length });
       const dimensionResult = await getCollectionDimension(collection);
       if (!dimensionResult.success) {
         return dimensionResult;
@@ -1152,20 +1462,20 @@ function createQdrantProvider() {
         }
       }));
       await client.upsert(collection, { points });
-      logger3.info("Vectors upserted", { collection, count: documents.length });
+      logger4.info("Vectors upserted", { collection, count: documents.length });
       return ok(void 0);
     },
     async delete(collection, ids) {
-      logger3.debug("Deleting vectors", { collection, count: ids.length });
+      logger4.debug("Deleting vectors", { collection, count: ids.length });
       const uuids = ids.map(hashToUuid);
       await client.delete(collection, { points: uuids });
-      logger3.info("Vectors deleted", { collection, count: ids.length });
+      logger4.info("Vectors deleted", { collection, count: ids.length });
       return ok(void 0);
     },
     async search(collection, vector, options) {
       const topK = options?.topK ?? 10;
       const minScore = options?.minScore ?? 0;
-      logger3.debug("Searching vectors", { collection, topK, hasFilter: !!options?.filter });
+      logger4.debug("Searching vectors", { collection, topK, hasFilter: !!options?.filter });
       const dimensionResult = await getCollectionDimension(collection);
       if (!dimensionResult.success) {
         return dimensionResult;
@@ -1202,7 +1512,7 @@ function createQdrantProvider() {
       return ok(results);
     },
     async count(collection) {
-      logger3.debug("Counting vectors", { collection });
+      logger4.debug("Counting vectors", { collection });
       const infoResult = await getCollectionInfo(collection);
       if (!infoResult.success) {
         return infoResult;
@@ -1230,17 +1540,17 @@ function createQdrantProvider() {
         await qdrantClient.getCollections();
         client = qdrantClient;
         config = qdrantConfig;
-        logger3.info("Qdrant connected", { url: sanitizeUrl(qdrantConfig.url) });
+        logger4.info("Qdrant connected", { url: sanitizeUrl(qdrantConfig.url) });
         return ok(void 0);
       } catch (error) {
-        logger3.error("Failed to connect to Qdrant", { error: error instanceof Error ? error.message : String(error) });
+        logger4.error("Failed to connect to Qdrant", { error: error instanceof Error ? error.message : String(error) });
         return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_connectionFailed", { params: { error: String(error) } }), error);
       }
     },
     async close() {
       client = null;
       config = null;
-      logger3.info("Qdrant connection closed");
+      logger4.info("Qdrant connection closed");
       return ok(void 0);
     },
     isConnected() {
@@ -1252,7 +1562,7 @@ function createQdrantProvider() {
 }
 
 // src/vecdb-main.ts
-var logger4 = core.logger.child({ module: "vecdb", scope: "main" });
+var logger5 = core.logger.child({ module: "vecdb", scope: "main" });
 var currentProvider = null;
 var currentConfig = null;
 var initInProgress = false;
@@ -1264,6 +1574,8 @@ function createProvider(config) {
       return createPgvectorProvider();
     case "qdrant":
       return createQdrantProvider();
+    case "chroma":
+      return createChromaProvider();
   }
 }
 var notInitialized = core.module.createNotInitializedKit(
@@ -1281,22 +1593,22 @@ var vecdb = {
    */
   async init(config) {
     if (initInProgress) {
-      logger4.warn("Vecdb init already in progress, skipping concurrent call");
+      logger5.warn("Vecdb init already in progress, skipping concurrent call");
       return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_initInProgress"));
     }
     initInProgress = true;
     try {
       if (currentProvider) {
-        logger4.warn("Vecdb module is already initialized, reinitializing");
+        logger5.warn("Vecdb module is already initialized, reinitializing");
         const closeResult = await vecdb.close();
         if (!closeResult.success) {
           return closeResult;
         }
       }
-      logger4.info("Initializing vecdb module");
+      logger5.info("Initializing vecdb module");
       const parseResult = VecdbConfigSchema.safeParse(config);
       if (!parseResult.success) {
-        logger4.error("Vecdb config validation failed", { error: parseResult.error.message });
+        logger5.error("Vecdb config validation failed", { error: parseResult.error.message });
         return err(HaiVecdbError.CONFIG_ERROR, vecdbM("vecdb_configError", { params: { error: parseResult.error.message } }), parseResult.error);
       }
       const parsed = parseResult.data;
@@ -1304,7 +1616,7 @@ var vecdb = {
         const provider = createProvider(parsed);
         const connectResult = await provider.connect(parsed);
         if (!connectResult.success) {
-          logger4.error("Vecdb module initialization failed", {
+          logger5.error("Vecdb module initialization failed", {
             code: connectResult.error.code,
             message: connectResult.error.message
           });
@@ -1312,10 +1624,10 @@ var vecdb = {
         }
         currentProvider = provider;
         currentConfig = parsed;
-        logger4.info("Vecdb module initialized", { type: parsed.type });
+        logger5.info("Vecdb module initialized", { type: parsed.type });
         return ok(void 0);
       } catch (error) {
-        logger4.error("Vecdb module initialization failed", { error });
+        logger5.error("Vecdb module initialization failed", { error });
         return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_initFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
       }
     } finally {
@@ -1342,6 +1654,35 @@ var vecdb = {
   get config() {
     return currentConfig ? core.sanitize.sanitizeSensitiveFields(currentConfig) : null;
   },
+  /** 获取底层后端的原始连接信息（含凭证，未初始化时为 null；仅供同进程内集成使用） */
+  get rawConnection() {
+    if (!currentConfig)
+      return null;
+    if (currentConfig.type === "qdrant")
+      return { type: "qdrant", url: currentConfig.url, apiKey: currentConfig.apiKey };
+    if (currentConfig.type === "pgvector") {
+      return {
+        type: "pgvector",
+        connectionString: currentConfig.url,
+        host: currentConfig.host,
+        port: currentConfig.port,
+        database: currentConfig.database,
+        user: currentConfig.user,
+        password: currentConfig.password
+      };
+    }
+    if (currentConfig.type === "chroma") {
+      return {
+        type: "chroma",
+        url: currentConfig.url,
+        host: currentConfig.host,
+        port: currentConfig.port,
+        apiKey: currentConfig.apiKey,
+        path: currentConfig.path
+      };
+    }
+    return { type: currentConfig.type, path: currentConfig.path };
+  },
   /** 检查是否已初始化 */
   get isInitialized() {
     return currentProvider !== null && currentProvider.isConnected();
@@ -1354,20 +1695,20 @@ var vecdb = {
   async close() {
     if (!currentProvider) {
       currentConfig = null;
-      logger4.info("Vecdb module already closed, skipping");
+      logger5.info("Vecdb module already closed, skipping");
       return ok(void 0);
     }
-    logger4.info("Closing vecdb module");
+    logger5.info("Closing vecdb module");
     try {
       const closeResult = await currentProvider.close();
       if (!closeResult.success) {
-        logger4.error("Vecdb module close failed", { code: closeResult.error.code, message: closeResult.error.message });
+        logger5.error("Vecdb module close failed", { code: closeResult.error.code, message: closeResult.error.message });
         return closeResult;
       }
-      logger4.info("Vecdb module closed");
+      logger5.info("Vecdb module closed");
       return ok(void 0);
     } catch (error) {
-      logger4.error("Vecdb module close failed", { error });
+      logger5.error("Vecdb module close failed", { error });
       return err(HaiVecdbError.CONNECTION_FAILED, vecdbM("vecdb_closeFailed", { params: { error: error instanceof Error ? error.message : String(error) } }), error);
     } finally {
       currentProvider = null;