@h-ai/vecdb 0.1.0-alpha9 → 1.0.0-beta.2

package/dist/index.d.ts

@@ -5,49 +5,98 @@ import { HaiResult } from '@h-ai/core';
 /**
  * @h-ai/vecdb — 向量数据库配置 Schema
  *
- * 本文件定义向量数据库模块的错误码常量、Zod Schema 和配置类型。
- * 支持 LanceDB（默认）、pgvector、Qdrant 三种后端。
+ * 本文件定义向量数据库模块的 Zod Schema 和配置类型；错误码见 vecdb-types。
+ * 支持 LanceDB（默认）、pgvector、Qdrant、Chroma 四种后端。
  * @module vecdb-config
  */
 
 /**
- * 向量数据库类型枚举
+ * 向量数据库类型
+ * @example
+ * ```ts
+ * import type { VecdbType } from '@h-ai/vecdb'
  *
- * 支持的向量数据库类型：
- * - `lancedb` — LanceDB 嵌入式向量数据库（默认）
- * - `pgvector` — PostgreSQL + pgvector 扩展
- * - `qdrant` — Qdrant 向量搜索引擎
+ * const value: VecdbType = 'qdrant'
+ * void value
+ * ```
  */
-declare const VecdbTypeSchema: z.ZodEnum<{
-    lancedb: "lancedb";
-    pgvector: "pgvector";
-    qdrant: "qdrant";
-}>;
-/** 向量数据库类型 */
-type VecdbType = z.infer<typeof VecdbTypeSchema>;
+type VecdbType = 'lancedb' | 'pgvector' | 'qdrant' | 'chroma';
 /**
  * 距离度量类型
  *
  * - `cosine` — 余弦相似度（默认，适用于文本嵌入）
  * - `euclidean` — 欧氏距离（L2）
  * - `dot` — 内积（点积）
+ * @example
+ * ```ts
+ * import { DistanceMetricSchema } from '@h-ai/vecdb'
+ *
+ * const value = DistanceMetricSchema.parse('cosine')
+ * void value
+ * ```
  */
 declare const DistanceMetricSchema: z.ZodDefault<z.ZodEnum<{
     cosine: "cosine";
     euclidean: "euclidean";
     dot: "dot";
 }>>;
-/** 距离度量类型 */
+/**
+ * 距离度量类型
+ * @example
+ * ```ts
+ * import type { DistanceMetric } from '@h-ai/vecdb'
+ *
+ * const value: DistanceMetric = 'cosine'
+ * void value
+ * ```
+ */
 type DistanceMetric = z.infer<typeof DistanceMetricSchema>;
 /**
- * LanceDB 配置 Schema
+ * 操作日志配置；read/write 默认关闭，长度和级别由 Schema 校验。
+ * @example
+ * ```ts
+ * import { VecdbOperationLogConfigSchema } from '@h-ai/vecdb'
  *
+ * const value = VecdbOperationLogConfigSchema.parse({ read: false, write: true, maxLength: 500, level: 'debug' })
+ * void value
+ * ```
+ */
+declare const VecdbOperationLogConfigSchema: z.ZodObject<{
+    read: z.ZodDefault<z.ZodBoolean>;
+    write: z.ZodDefault<z.ZodBoolean>;
+    maxLength: z.ZodDefault<z.ZodNumber>;
+    level: z.ZodDefault<z.ZodEnum<{
+        info: "info";
+        debug: "debug";
+        trace: "trace";
+    }>>;
+}, z.core.$strip>;
+/**
+ * 已解析的操作日志配置，单位和默认值与 Schema 保持一致。
  * @example
  * ```ts
- * { type: 'lancedb', path: './data/vecdb' }
+ * import { VecdbOperationLogConfigSchema, type VecdbOperationLogConfig } from '@h-ai/vecdb'
+ *
+ * const value: VecdbOperationLogConfig = VecdbOperationLogConfigSchema.parse({})
+ * void value
  * ```
  */
+type VecdbOperationLogConfig = z.infer<typeof VecdbOperationLogConfigSchema>;
+/**
+ * LanceDB 配置 Schema
+ *
+ */
 declare const LancedbConfigSchema: z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
     type: z.ZodLiteral<"lancedb">;
     path: z.ZodString;
     metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
@@ -56,38 +105,35 @@ declare const LancedbConfigSchema: z.ZodObject<{
         dot: "dot";
     }>>>;
 }, z.core.$strip>;
-/** LanceDB 配置类型 */
-type LancedbConfig = z.infer<typeof LancedbConfigSchema>;
 /**
- * pgvector 索引类型
+ * LanceDB 配置类型
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema, type LancedbConfig } from '@h-ai/vecdb'
  *
- * - `ivfflat` — IVFFlat 索引（适合中等规模数据）
- * - `hnsw` — HNSW 索引（适合大规模数据，检索速度更快）
+ * const parsed = VecdbConfigSchema.parse({ type: 'lancedb', path: './data/vecdb' })
+ * if (parsed.type === 'lancedb') {
+ *   const config: LancedbConfig = parsed
+ *   void config
+ * }
+ * ```
  */
-declare const PgvectorIndexTypeSchema: z.ZodDefault<z.ZodEnum<{
-    ivfflat: "ivfflat";
-    hnsw: "hnsw";
-}>>;
+type LancedbConfig = z.infer<typeof LancedbConfigSchema>;
 /**
  * pgvector 配置 Schema
  *
- * @example
- * ```ts
- * // 使用连接字符串
- * { type: 'pgvector', url: 'postgres://user:pass@localhost:5432/mydb' }
- *
- * // 使用分开的字段
- * {
- *     type: 'pgvector',
- *     host: 'localhost',
- *     port: 5432,
- *     database: 'mydb',
- *     user: 'admin',
- *     password: 'secret'
- * }
- * ```
  */
 declare const PgvectorConfigSchema: z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
     type: z.ZodLiteral<"pgvector">;
     url: z.ZodOptional<z.ZodString>;
     host: z.ZodDefault<z.ZodString>;
@@ -106,17 +152,35 @@ declare const PgvectorConfigSchema: z.ZodObject<{
     }>>>;
     tablePrefix: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
-/** pgvector 配置类型 */
-type PgvectorConfig = z.infer<typeof PgvectorConfigSchema>;
 /**
- * Qdrant 配置 Schema
- *
+ * pgvector 配置类型
  * @example
  * ```ts
- * { type: 'qdrant', url: 'http://localhost:6333' }
+ * import { VecdbConfigSchema, type PgvectorConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'pgvector', host: 'db', database: 'shop' })
+ * if (parsed.type === 'pgvector') {
+ *   const config: PgvectorConfig = parsed
+ *   void config
+ * }
  * ```
  */
+type PgvectorConfig = z.infer<typeof PgvectorConfigSchema>;
+/**
+ * Qdrant 配置 Schema
+ *
+ */
 declare const QdrantConfigSchema: z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
     type: z.ZodLiteral<"qdrant">;
     url: z.ZodDefault<z.ZodString>;
     apiKey: z.ZodOptional<z.ZodString>;
@@ -126,14 +190,91 @@ declare const QdrantConfigSchema: z.ZodObject<{
         dot: "dot";
     }>>>;
 }, z.core.$strip>;
-/** Qdrant 配置类型 */
+/**
+ * Qdrant 配置类型
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema, type QdrantConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'qdrant', url: 'http://localhost:6333' })
+ * if (parsed.type === 'qdrant') {
+ *   const config: QdrantConfig = parsed
+ *   void config
+ * }
+ * ```
+ */
 type QdrantConfig = z.infer<typeof QdrantConfigSchema>;
+/**
+ * Chroma 配置 Schema
+ *
+ * Chroma 在 Node 端只有 HTTP 客户端（无进程内嵌入式）。本 Provider 支持两种模式：
+ * - **嵌入式**：提供 `path` 且不提供 `url` 时，init 自动拉起本地 `chroma run` 服务
+ *   （持久化到 `path`），close 时关闭；数据落地本地目录，无需手动启动服务。
+ * - **直连**：提供 `url`（或已运行的 host:port）时，直接连接已有 Chroma 服务，不拉起进程。
+ *
+ */
+declare const ChromaConfigSchema: z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
+    type: z.ZodLiteral<"chroma">;
+    path: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    serverCommand: z.ZodDefault<z.ZodString>;
+    startupTimeout: z.ZodDefault<z.ZodNumber>;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
+}, z.core.$strip>;
+/**
+ * Chroma 配置类型
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema, type ChromaConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'chroma', url: 'http://localhost:8000' })
+ * if (parsed.type === 'chroma') {
+ *   const config: ChromaConfig = parsed
+ *   void config
+ * }
+ * ```
+ */
+type ChromaConfig = z.infer<typeof ChromaConfigSchema>;
 /**
  * 统一向量数据库配置 Schema（判别联合体）
  *
  * 根据 `type` 字段区分不同向量数据库类型的配置。
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema } from '@h-ai/vecdb'
+ *
+ * const value = VecdbConfigSchema.parse({ type: 'qdrant', url: 'http://localhost:6333' })
+ * void value
+ * ```
  */
 declare const VecdbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
     type: z.ZodLiteral<"lancedb">;
     path: z.ZodString;
     metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
@@ -142,6 +283,16 @@ declare const VecdbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         dot: "dot";
     }>>>;
 }, z.core.$strip>, z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
     type: z.ZodLiteral<"pgvector">;
     url: z.ZodOptional<z.ZodString>;
     host: z.ZodDefault<z.ZodString>;
@@ -160,6 +311,16 @@ declare const VecdbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>>;
     tablePrefix: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
     type: z.ZodLiteral<"qdrant">;
     url: z.ZodDefault<z.ZodString>;
     apiKey: z.ZodOptional<z.ZodString>;
@@ -168,19 +329,68 @@ declare const VecdbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         euclidean: "euclidean";
         dot: "dot";
     }>>>;
+}, z.core.$strip>, z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
+    type: z.ZodLiteral<"chroma">;
+    path: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    serverCommand: z.ZodDefault<z.ZodString>;
+    startupTimeout: z.ZodDefault<z.ZodNumber>;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
 }, z.core.$strip>], "type">;
-/** 向量数据库配置类型（判别联合体） */
+/**
+ * 向量数据库配置类型（判别联合体）
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema, type VecdbConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'qdrant', url: 'http://localhost:6333' })
+ * const config: VecdbConfig = parsed
+ * void config
+ * ```
+ */
 type VecdbConfig = z.infer<typeof VecdbConfigSchema>;
 /**
  * 向量数据库配置输入类型（用于 init 等入口）
  *
  * 说明：Zod 的 default 会让输入端字段可省略，但输出端字段为必填。
  * 因此对外 API（如 vecdb.init）更适合接收 VecdbConfigInput。
+ * @example
+ * ```ts
+ * import type { VecdbConfigInput } from '@h-ai/vecdb'
+ *
+ * const value: VecdbConfigInput = { type: 'qdrant', url: 'http://localhost:6333' }
+ * void value
+ * ```
  */
 type VecdbConfigInput = z.input<typeof VecdbConfigSchema>;
 
 /**
  * Vecdb 模块标准错误定义对象。
+ * @example
+ * ```ts
+ * import { HaiVecdbError } from '@h-ai/vecdb'
+ * import { err } from '@h-ai/core'
+ *
+ * const result = err(HaiVecdbError.COLLECTION_NOT_FOUND, 'Collection missing')
+ * if (!result.success) void result.error.code
+ * ```
  */
 declare const HaiVecdbError: {
     readonly CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
@@ -202,15 +412,12 @@ declare const HaiVecdbError: {
  * 向量文档接口
  *
  * 表示一条存入向量数据库的记录，包含向量、文本内容和元数据。
- *
  * @example
  * ```ts
- * const doc: VectorDocument = {
- *   id: 'doc-001',
- *   vector: [0.1, 0.2, 0.3, ...],
- *   content: '这是文档内容',
- *   metadata: { source: 'wiki', page: 1 },
- * }
+ * import type { VectorDocument } from '@h-ai/vecdb'
+ *
+ * const value: VectorDocument = { id: 'doc_1', vector: [0.1, 0.2, 0.3], content: 'Example text', metadata: { tenant: 'shop' } }
+ * void value
  * ```
  */
 interface VectorDocument {
@@ -225,20 +432,24 @@ interface VectorDocument {
 }
 /**
  * 向量搜索选项
- *
  * @example
  * ```ts
- * const options: VectorSearchOptions = {
- *   topK: 10,
- *   filter: { source: 'wiki' },
- *   minScore: 0.7,
- * }
+ * import type { VectorSearchOptions } from '@h-ai/vecdb'
+ *
+ * const value: VectorSearchOptions = { topK: 5, filter: { tenant: 'shop' }, minScore: 0.7 }
+ * void value
  * ```
  */
 interface VectorSearchOptions {
     /** 返回的最大结果数（默认 10） */
     topK?: number;
-    /** 元数据过滤条件（键值对，精确匹配） */
+    /**
+     * 元数据过滤，具体能力以 Provider 为准。
+     * LanceDB：顶层字面量键的 AND 精确匹配，仅支持 string、有限 number、boolean、null；
+     * 类型严格区分，null 不匹配缺失字段；空对象不筛选，不支持对象/数组/undefined。
+     * 条件在 topK 前执行，不支持的值返回 CONFIG_ERROR。其它后端不保证相同 null/复杂值语义。
+     * @example { tenant: 'acme', active: true, page: 1, removedAt: null }
+     */
     filter?: Record<string, unknown>;
     /** 最低相似度阈值（0-1，低于此值的结果将被过滤） */
     minScore?: number;
@@ -247,15 +458,12 @@ interface VectorSearchOptions {
  * 向量搜索结果
  *
  * 包含匹配的文档和相似度得分。
- *
  * @example
  * ```ts
- * const result: VectorSearchResult = {
- *   id: 'doc-001',
- *   score: 0.95,
- *   content: '匹配的文档内容',
- *   metadata: { source: 'wiki' },
- * }
+ * import type { VectorSearchResult } from '@h-ai/vecdb'
+ *
+ * const value: VectorSearchResult = { id: 'doc_1', score: 0.95, content: 'Example text', metadata: { tenant: 'shop' } }
+ * void value
  * ```
  */
 interface VectorSearchResult {
@@ -274,15 +482,12 @@ interface VectorSearchResult {
  * 集合信息接口
  *
  * 描述一个向量集合的元信息。
- *
  * @example
  * ```ts
- * const info: CollectionInfo = {
- *   name: 'docs',
- *   dimension: 1536,
- *   metric: 'cosine',
- *   count: 42,
- * }
+ * import type { CollectionInfo } from '@h-ai/vecdb'
+ *
+ * const value: CollectionInfo = { name: 'docs', dimension: 3, metric: 'cosine', count: 1 }
+ * void value
  * ```
  */
 interface CollectionInfo {
@@ -299,14 +504,15 @@ interface CollectionInfo {
  * 集合管理操作接口
  *
  * 通过 `vecdb.collection` 访问，管理向量集合的创建、删除和查询。
- *
  * @example
  * ```ts
- * // 创建集合
- * await vecdb.collection.create('my-docs', { dimension: 1536 })
+ * import type { CollectionOperations } from '@h-ai/vecdb'
  *
- * // 列出集合
- * const result = await vecdb.collection.list()
+ * async function read(operations: CollectionOperations) {
+ *   const result = await operations.list()
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
  * ```
  */
 interface CollectionOperations {
@@ -348,13 +554,12 @@ interface CollectionOperations {
 }
 /**
  * 集合创建选项
- *
  * @example
  * ```ts
- * const options: CollectionCreateOptions = {
- *   dimension: 1536,
- *   metric: 'cosine',
- * }
+ * import type { CollectionCreateOptions } from '@h-ai/vecdb'
+ *
+ * const value: CollectionCreateOptions = { dimension: 3, metric: 'cosine' }
+ * void value
  * ```
  */
 interface CollectionCreateOptions {
@@ -367,17 +572,15 @@ interface CollectionCreateOptions {
  * 向量操作接口
  *
  * 通过 `vecdb.vector` 访问，管理向量文档的增删改查和搜索。
- *
  * @example
  * ```ts
- * // 插入向量
- * await vecdb.vector.insert('my-docs', [
- *   { id: 'doc-1', vector: [...], content: '文档1' },
- *   { id: 'doc-2', vector: [...], content: '文档2' },
- * ])
- *
- * // 搜索向量
- * const result = await vecdb.vector.search('my-docs', queryVector, { topK: 5 })
+ * import type { VectorOperations } from '@h-ai/vecdb'
+ *
+ * async function read(operations: VectorOperations) {
+ *   const result = await operations.search('docs', [0.1, 0.2, 0.3], { topK: 5 })
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
  * ```
  */
 interface VectorOperations {
@@ -386,15 +589,19 @@ interface VectorOperations {
      *
      * @param collection - 集合名称
      * @param documents - 文档列表
-     * @returns 成功返回 ok(undefined)
+     * @returns 成功返回 ok(undefined)；LanceDB 已有 ID 保留不覆盖，同批重复 ID 返回 CONFIG_ERROR。
+     * Qdrant 成功前等待服务端应用写入。
+     * @example await vecdb.vector.insert('docs', [{ id: 'doc-1', vector: [1, 0] }])
      */
     insert: (collection: string, documents: VectorDocument[]) => Promise<HaiResult<void>>;
     /**
-     * 更新向量文档（按 id 匹配，整体替换）
+     * 插入或更新向量文档（按 id 匹配，整体替换）
      *
      * @param collection - 集合名称
-     * @param documents - 待更新的文档（id 必须已存在）
-     * @returns 成功返回 ok(undefined)
+     * @param documents - 待写入文档；已有 ID 更新，不存在的 ID 插入
+     * @returns 成功返回 ok(undefined)；LanceDB 缺少原子主键能力或同批重复 ID 返回 CONFIG_ERROR。
+     * Qdrant 成功前等待服务端应用写入。
+     * @example await vecdb.vector.upsert('docs', [{ id: 'doc-1', vector: [1, 0], content: 'updated' }])
      */
     upsert: (collection: string, documents: VectorDocument[]) => Promise<HaiResult<void>>;
     /**
@@ -403,6 +610,7 @@ interface VectorOperations {
      * @param collection - 集合名称
      * @param ids - 文档 ID 列表
      * @returns 成功返回 ok(undefined)
+     * Qdrant 成功前等待服务端应用删除。
      */
     delete: (collection: string, ids: string[]) => Promise<HaiResult<void>>;
     /**
@@ -412,6 +620,7 @@ interface VectorOperations {
      * @param vector - 查询向量
      * @param options - 搜索选项
      * @returns 搜索结果列表（按相似度降序排列）
+     * @example await vecdb.vector.search('docs', [1, 0], { topK: 5, filter: { tenant: 'acme', active: true } })
      */
     search: (collection: string, vector: number[], options?: VectorSearchOptions) => Promise<HaiResult<VectorSearchResult[]>>;
     /**
@@ -419,30 +628,26 @@ interface VectorOperations {
      *
      * @param collection - 集合名称
      * @returns 文档数量
+     * Qdrant 使用精确 count，不依赖集合信息的近似统计。
      */
     count: (collection: string) => Promise<HaiResult<number>>;
 }
 /**
  * 向量数据库服务接口（通过 `vecdb` 对象访问）
- *
  * @example
  * ```ts
  * import { vecdb } from '@h-ai/vecdb'
  *
- * // 初始化（LanceDB）
- * await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
- *
- * // 创建集合
- * await vecdb.collection.create('docs', { dimension: 1536 })
- *
- * // 插入向量
- * await vecdb.vector.insert('docs', [{ id: '1', vector: [...], content: '...' }])
- *
- * // 搜索
- * const result = await vecdb.vector.search('docs', queryVector, { topK: 5 })
- *
- * // 关闭
- * await vecdb.close()
+ * const initialized = await vecdb.init({ type: 'qdrant', url: 'http://localhost:6333' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await vecdb.collection.list()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await vecdb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 interface VecdbFunctions {
@@ -450,8 +655,15 @@ interface VecdbFunctions {
     init: (config: VecdbConfigInput) => Promise<HaiResult<void>>;
     /** 关闭连接 */
     close: () => Promise<HaiResult<void>>;
-    /** 当前配置（未初始化时为 null） */
+    /** 当前脱敏配置快照（未初始化时为 null） */
     readonly config: VecdbConfig | null;
+    /**
+     * 获取底层后端的原始连接信息（含凭证，未初始化时为 null）
+     *
+     * 供需要直连同一向量库的外部引擎（如 mem0 OSS）复用后端。返回值包含未脱敏的凭证，
+     * 仅供同进程内集成使用，禁止写入日志或返回给外部调用方。
+     */
+    readonly rawConnection: VecdbConnection | null;
     /** 是否已初始化 */
     readonly isInitialized: boolean;
     /** 集合管理操作 */
@@ -459,6 +671,40 @@ interface VecdbFunctions {
     /** 向量操作 */
     readonly vector: VectorOperations;
 }
+/**
+ * 向量库原始连接信息
+ *
+ * 由 `vecdb.rawConnection` 暴露，字段按后端类型填充。包含凭证，仅供同进程内集成使用。
+ * @example
+ * ```ts
+ * import type { VecdbConnection } from '@h-ai/vecdb'
+ *
+ * const value: VecdbConnection = { type: 'qdrant', url: 'http://localhost:6333' }
+ * void value
+ * ```
+ */
+interface VecdbConnection {
+    /** 后端类型 */
+    type: VecdbConfig['type'];
+    /** 服务 URL（qdrant、chroma；Chroma 内嵌模式含实际本地端口） */
+    url?: string;
+    /** API Key / Bearer token（qdrant、chroma） */
+    apiKey?: string;
+    /** 主机（pgvector、chroma） */
+    host?: string;
+    /** 端口（pgvector、chroma） */
+    port?: number;
+    /** 数据库名（pgvector） */
+    database?: string;
+    /** 用户名（pgvector） */
+    user?: string;
+    /** 密码（pgvector） */
+    password?: string;
+    /** 连接串（pgvector） */
+    connectionString?: string;
+    /** 本地持久化路径（lancedb 或内嵌 chroma） */
+    path?: string;
+}
 
 /**
  * @h-ai/vecdb — 向量数据库服务主入口
@@ -477,29 +723,22 @@ interface VecdbFunctions {
  * - `vecdb.vector` - 向量操作（插入/搜索/删除）
  * - `vecdb.config` - 当前配置
  * - `vecdb.isInitialized` - 初始化状态
- *
  * @example
  * ```ts
  * import { vecdb } from '@h-ai/vecdb'
  *
- * // 初始化（LanceDB）
- * await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
- *
- * // 集合操作
- * await vecdb.collection.create('docs', { dimension: 1536 })
- *
- * // 向量操作
- * await vecdb.vector.insert('docs', [
- *   { id: '1', vector: [...], content: '文档内容' },
- * ])
- *
- * // 搜索
- * const result = await vecdb.vector.search('docs', queryVector, { topK: 5 })
- *
- * // 关闭
- * await vecdb.close()
+ * const initialized = await vecdb.init({ type: 'qdrant', url: 'http://localhost:6333' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await vecdb.collection.list()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await vecdb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 declare const vecdb: VecdbFunctions;
 
-export { type CollectionCreateOptions, type CollectionInfo, type CollectionOperations, type DistanceMetric, DistanceMetricSchema, HaiVecdbError, type LancedbConfig, LancedbConfigSchema, type PgvectorConfig, PgvectorConfigSchema, PgvectorIndexTypeSchema, type QdrantConfig, QdrantConfigSchema, type VecdbConfig, type VecdbConfigInput, VecdbConfigSchema, type VecdbFunctions, type VecdbType, VecdbTypeSchema, type VectorDocument, type VectorOperations, type VectorSearchOptions, type VectorSearchResult, vecdb };
+export { type ChromaConfig, type CollectionCreateOptions, type CollectionInfo, type CollectionOperations, type DistanceMetric, DistanceMetricSchema, HaiVecdbError, type LancedbConfig, type PgvectorConfig, type QdrantConfig, type VecdbConfig, type VecdbConfigInput, VecdbConfigSchema, type VecdbConnection, type VecdbFunctions, type VecdbOperationLogConfig, VecdbOperationLogConfigSchema, type VecdbType, type VectorDocument, type VectorOperations, type VectorSearchOptions, type VectorSearchResult, vecdb };