feat: 支持以只读模式打开已有 zvec

Author: banxuan.zyx

README.md

@@ -57,6 +57,7 @@ await ctx.close();
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `vectorsDir` | `string` | `.context/vectors` | Directory to store vector files |
+| `readOnly` | `boolean` | `false` | Open existing `.zvec` files only. In read-only mode, missing libraries are not created and `load()`/writes throw. |
 | `basePath` | `string` | `process.cwd()` | Base path for resolving document IDs. Set for cross-machine consistent IDs. |
 | `onProgress` | `(phase, detail) => void` | — | Progress callback for `load()` phases: `'load'` → `'embed'` → `'insert'`. |
 | queryExpansion | QueryExpansionOptions | false | false  | Query expansion with user-provided synonym map. false disables. Without synonyms, expansion is a no-op. |
@@ -98,6 +99,24 @@ const ctxNoExpand = await Context.create({
 });
 ```
 
+#### Read-only zvec Example
+
+Use `readOnly: true` when `.zvec` files are prepared elsewhere and the current
+process should only query them:
+
+```typescript
+const ctx = await Context.create({
+  vectorsDir: '.context/vectors',
+  readOnly: true,
+});
+
+const results = await ctx.query('How to configure a line chart', { library: 'g2' });
+```
+
+In read-only mode, `Context` opens existing `${library}.zvec` files with
+`ZVecOpen`. It does not create missing stores, and `load()` will throw because
+it would mutate the zvec file.
+
 ### `ctx.load(library, pattern)`
 
 Load files into a specified library with automatic batch vectorization. Documents are embedded in batches and inserted into the vector store. A content-hash change detection mechanism re-embeds files whose content has changed since the last load.
@@ -219,4 +238,4 @@ await ctx.close();
 
 ## License
 
-MIT
+MIT

src/context.ts

@@ -46,14 +46,18 @@ export class Context {
 
     const vectorsDir = options.vectorsDir ?? '.context/vectors';
 
-    if (!fs.existsSync(vectorsDir)) {
+    if (!options.readOnly && !fs.existsSync(vectorsDir)) {
       fs.mkdirSync(vectorsDir, { recursive: true });
     }
 
     return new Context(options, embedder, { dimensions: embedder.dimensions });
   }
 
   async load(library: string, pattern: string | string[]): Promise<void> {
+    if (this.options.readOnly) {
+      throw new Error(`Cannot load docs into library "${library}" in read-only mode`);
+    }
+
     const patterns = Array.isArray(pattern) ? pattern : [pattern];
     const files = await glob(patterns, { absolute: true });
 
@@ -164,4 +168,4 @@ export class Context {
   async close(): Promise<void> {
     this.store.close();
   }
-}
+}

src/storage/store.ts

@@ -43,6 +43,10 @@ export class Store {
     if (fs.existsSync(filePath)) {
       collection = ZVecOpen(filePath);
     } else {
+      if (this.options?.readOnly) {
+        throw new Error(`Cannot open zvec for library "${library}" in read-only mode: ${filePath} does not exist`);
+      }
+
       const schema = buildZvecSchema(this.embedder.dimensions, tokenizerName);
       collection = ZVecCreateAndOpen(filePath, schema);
     }
@@ -53,6 +57,10 @@ export class Store {
 
   /** Insert docs (upsert semantics). */
   addDoc(library: string, docs: ZvecDoc[]): void {
+    if (this.options?.readOnly) {
+      throw new Error(`Cannot add docs to library "${library}" in read-only mode`);
+    }
+
     const collection = this.acquireZvec(library);
     if (docs.length === 0) return;
 
@@ -166,4 +174,4 @@ export class Store {
       fields: r.fields ?? {},
     }));
   }
-}
+}

src/types.ts

@@ -48,6 +48,16 @@ export interface ContextOptions {
    * Defaults to `'.context/vectors'`.
    */
   vectorsDir?: string;
+  /**
+   * Open existing vector files without creating or mutating zvec stores.
+   *
+   * When enabled, `query()` can read from existing `${library}.zvec` files,
+   * while `load()` and any write path will throw. Missing zvec files are
+   * reported as errors instead of being created.
+   *
+   * Defaults to `false`.
+   */
+  readOnly?: boolean;
   /**
    * Base path for resolving document IDs.
    *

test/storage/store.test.ts

@@ -43,6 +43,13 @@ describe('Store', () => {
       const zvec2 = store.acquireZvec('test-lib', 'jieba');
       expect(zvec1).toBe(zvec2);
     });
+
+    it('should not create missing zvec in read-only mode', () => {
+      const readOnlyStore = new Store(testDir, embedder, { readOnly: true });
+      expect(() => readOnlyStore.acquireZvec('missing-lib', 'jieba')).toThrow(/read-only mode/);
+      expect(fs.existsSync(path.join(testDir, 'missing-lib.zvec'))).toBe(false);
+      readOnlyStore.close();
+    });
   });
 
   describe('addDoc', () => {
@@ -60,6 +67,12 @@ describe('Store', () => {
     it('should not throw for empty docs array', () => {
       expect(() => store.addDoc('test-lib', [])).not.toThrow();
     });
+
+    it('should reject writes in read-only mode', () => {
+      const readOnlyStore = new Store(testDir, embedder, { readOnly: true });
+      expect(() => readOnlyStore.addDoc('test-lib', [])).toThrow(/read-only mode/);
+      readOnlyStore.close();
+    });
   });
 
   describe('fetchDocs', () => {
@@ -110,4 +123,4 @@ describe('Store', () => {
       expect(() => store.close()).not.toThrow();
     });
   });
-});
+});