Merge pull request #261 from AmintaCCCP/fix/persist-vector-search-config

fix: persist full vector search config to backend + stop sync loop (#259)

Author: AmintaCCCP

server/src/db/schema.ts

@@ -129,6 +129,11 @@ export function initializeSchema(db: Database.Database): void {
       embedding_config_id TEXT,
       index_mode TEXT NOT NULL DEFAULT 'readme',
       readme_max_chars INTEGER NOT NULL DEFAULT 6000,
+      search_threshold REAL DEFAULT 0.35,
+      search_top_k INTEGER DEFAULT 30,
+      enable_hyde INTEGER DEFAULT 1,
+      enable_reranking INTEGER DEFAULT 1,
+      embedding_format_version INTEGER,
       status_json TEXT,
       last_sync_at TEXT,
       created_at TEXT NOT NULL DEFAULT (datetime('now')),
@@ -149,6 +154,11 @@ export function initializeSchema(db: Database.Database): void {
   addColumnIfMissing(db, 'asset_filters', 'sort_order', 'INTEGER DEFAULT 0');
   addColumnIfMissing(db, 'vector_search_configs', 'index_mode', "TEXT NOT NULL DEFAULT 'readme'");
   addColumnIfMissing(db, 'vector_search_configs', 'readme_max_chars', 'INTEGER NOT NULL DEFAULT 6000');
+  addColumnIfMissing(db, 'vector_search_configs', 'search_threshold', 'REAL DEFAULT 0.35');
+  addColumnIfMissing(db, 'vector_search_configs', 'search_top_k', 'INTEGER DEFAULT 30');
+  addColumnIfMissing(db, 'vector_search_configs', 'enable_hyde', 'INTEGER DEFAULT 1');
+  addColumnIfMissing(db, 'vector_search_configs', 'enable_reranking', 'INTEGER DEFAULT 1');
+  addColumnIfMissing(db, 'vector_search_configs', 'embedding_format_version', 'INTEGER');
   addColumnIfMissing(db, 'repositories', 'vector_indexed_at', 'TEXT');
   addColumnIfMissing(db, 'repositories', 'license', 'TEXT');
   // 上一次向量索引时采用的 license 值（SPDX id / null）。用于增量谓词判断 license 是否

server/src/routes/configs.ts

@@ -681,7 +681,7 @@ router.get('/api/configs/vector-search', (req, res) => {
     const row = db.prepare('SELECT * FROM vector_search_configs WHERE id = ?').get('default') as Record<string, unknown> | undefined;
 
     if (!row) {
-      res.json({ enabled: false, workerUrl: '', authToken: '', embeddingConfigId: '', indexMode: 'readme', readmeMaxChars: 6000 });
+      res.json({ enabled: false, workerUrl: '', authToken: '', embeddingConfigId: '', indexMode: 'readme', readmeMaxChars: 6000, searchThreshold: 0.35, searchTopK: 30, enableHyDE: true, enableReranking: true });
       return;
     }
 
@@ -710,6 +710,11 @@ router.get('/api/configs/vector-search', (req, res) => {
       embeddingConfigId: row.embedding_config_id ?? '',
       indexMode: row.index_mode ?? 'readme',
       readmeMaxChars: row.readme_max_chars ?? 6000,
+      searchThreshold: typeof row.search_threshold === 'number' ? row.search_threshold : 0.35,
+      searchTopK: typeof row.search_top_k === 'number' ? row.search_top_k : 30,
+      enableHyDE: row.enable_hyde === 1,
+      enableReranking: row.enable_reranking === 1,
+      embeddingFormatVersion: typeof row.embedding_format_version === 'number' ? row.embedding_format_version : undefined,
       status,
       lastSyncAt: row.last_sync_at ?? null,
     });
@@ -724,6 +729,7 @@ router.put('/api/configs/vector-search', (req, res) => {
   try {
     const db = getDb();
     const { enabled, workerUrl, authToken, embeddingConfigId, indexMode, readmeMaxChars, status, lastSyncAt } = req.body as Record<string, unknown>;
+    const { searchThreshold, searchTopK, enableHyDE, enableReranking, embeddingFormatVersion } = req.body as Record<string, unknown>;
 
     let encryptedToken = '';
     const hasAuthToken = Object.prototype.hasOwnProperty.call(req.body, 'authToken');
@@ -741,11 +747,22 @@ router.put('/api/configs/vector-search', (req, res) => {
     const statusJson = status ? JSON.stringify(status) : null;
     const mode = indexMode === 'description' ? 'description' : 'readme';
     const maxChars = typeof readmeMaxChars === 'number' && readmeMaxChars > 0 ? readmeMaxChars : 6000;
+    const threshold = typeof searchThreshold === 'number' && Number.isFinite(searchThreshold) && searchThreshold >= 0 && searchThreshold <= 1
+      ? searchThreshold
+      : 0.35;
+    const topK = typeof searchTopK === 'number' && Number.isInteger(searchTopK) && searchTopK >= 5 && searchTopK <= 50
+      ? searchTopK
+      : 30;
+    const hyde = enableHyDE === true ? 1 : 0;
+    const reranking = enableReranking === true ? 1 : 0;
+    const formatVersion = typeof embeddingFormatVersion === 'number' && Number.isInteger(embeddingFormatVersion) && embeddingFormatVersion >= 1
+      ? embeddingFormatVersion
+      : null;
 
     db.prepare(`
-      INSERT OR REPLACE INTO vector_search_configs (id, enabled, worker_url, auth_token_encrypted, embedding_config_id, index_mode, readme_max_chars, status_json, last_sync_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
-    `).run('default', enabled ? 1 : 0, workerUrl ?? '', encryptedToken, embeddingConfigId ?? '', mode, maxChars, statusJson, lastSyncAt ?? null);
+      INSERT OR REPLACE INTO vector_search_configs (id, enabled, worker_url, auth_token_encrypted, embedding_config_id, index_mode, readme_max_chars, search_threshold, search_top_k, enable_hyde, enable_reranking, embedding_format_version, status_json, last_sync_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+    `).run('default', enabled ? 1 : 0, workerUrl ?? '', encryptedToken, embeddingConfigId ?? '', mode, maxChars, threshold, topK, hyde, reranking, formatVersion, statusJson, lastSyncAt ?? null);
 
     res.json({ updated: true });
   } catch (err) {

server/tests/routes/vectorSearchConfig.test.ts

@@ -0,0 +1,144 @@
+import express from 'express';
+import request from 'supertest';
+import { describe, expect, it, vi } from 'vitest';
+
+const getDbMock = vi.fn();
+
+vi.mock('../../src/db/connection.js', () => ({
+  getDb: () => getDbMock(),
+}));
+
+vi.mock('../../src/services/crypto.js', () => ({
+  decrypt: (value: string) => value,
+  encrypt: (value: string) => value,
+}));
+
+vi.mock('../../src/config.js', () => ({
+  config: { encryptionKey: 'test-encryption-key' },
+}));
+
+const { default: configsRouter } = await import('../../src/routes/configs.js');
+
+const createTestApp = () => {
+  const app = express();
+  app.use(express.json());
+  app.use(configsRouter);
+  return app;
+};
+
+// PUT binds params in INSERT order; capture them so we can assert what persisted.
+function capturePut(): { params: unknown[][] } {
+  const capture = { params: [] as unknown[][] };
+  getDbMock.mockReturnValue({
+    prepare: () => ({
+      get: () => undefined,
+      run: (...p: unknown[]) => {
+        capture.params.push(p);
+      },
+    }),
+  });
+  return capture;
+}
+
+function mockGetReturningRow(row: Record<string, unknown>) {
+  getDbMock.mockReturnValue({
+    prepare: (sql: string) => ({
+      get: () => (sql.includes('vector_search_configs') ? row : undefined),
+      run: () => ({ changes: 1 }),
+    }),
+  });
+}
+
+const fullConfig = {
+  enabled: true,
+  workerUrl: 'https://example.com/vectorize',
+  authToken: 'worker-secret-token',
+  embeddingConfigId: 'emb_test1',
+  indexMode: 'readme',
+  readmeMaxChars: 8000,
+  searchThreshold: 0.42,
+  searchTopK: 25,
+  enableHyDE: false,
+  enableReranking: true,
+  embeddingFormatVersion: 2,
+};
+
+describe('vector search config route (GET/PUT /api/configs/vector-search)', () => {
+  it('PUT persists all vector-search fields to the backend', async () => {
+    const capture = capturePut();
+    const res = await request(createTestApp()).put('/api/configs/vector-search').send(fullConfig);
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ updated: true });
+    expect(capture.params).toHaveLength(1);
+
+    const p = capture.params[0];
+    expect(p[0]).toBe('default');
+    expect(p[1]).toBe(1); // enabled
+    expect(p[2]).toBe(fullConfig.workerUrl);
+    expect(p[3]).toBe(fullConfig.authToken); // encrypted (encrypt is identity in mock)
+    expect(p[4]).toBe(fullConfig.embeddingConfigId);
+    expect(p[5]).toBe(fullConfig.indexMode);
+    expect(p[6]).toBe(fullConfig.readmeMaxChars);
+    expect(p[7]).toBe(fullConfig.searchThreshold);
+    expect(p[8]).toBe(fullConfig.searchTopK);
+    expect(p[9]).toBe(0); // enableHyDE false → 0
+    expect(p[10]).toBe(1); // enableReranking true → 1
+    expect(p[11]).toBe(2); // embedding_format_version
+  });
+
+  it('GET returns all persisted vector-search fields', async () => {
+    const row = {
+      id: 'default',
+      enabled: 1,
+      worker_url: fullConfig.workerUrl,
+      auth_token_encrypted: fullConfig.authToken,
+      embedding_config_id: fullConfig.embeddingConfigId,
+      index_mode: fullConfig.indexMode,
+      readme_max_chars: fullConfig.readmeMaxChars,
+      search_threshold: fullConfig.searchThreshold,
+      search_top_k: fullConfig.searchTopK,
+      enable_hyde: 0,
+      enable_reranking: 1,
+      embedding_format_version: 2,
+      status_json: null,
+      last_sync_at: null,
+    };
+    mockGetReturningRow(row);
+
+    const res = await request(createTestApp()).get('/api/configs/vector-search?decrypt=true');
+
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({
+      enabled: true,
+      workerUrl: fullConfig.workerUrl,
+      authToken: fullConfig.authToken,
+      embeddingConfigId: fullConfig.embeddingConfigId,
+      indexMode: fullConfig.indexMode,
+      readmeMaxChars: fullConfig.readmeMaxChars,
+      searchThreshold: fullConfig.searchThreshold,
+      searchTopK: fullConfig.searchTopK,
+      enableHyDE: false,
+      enableReranking: true,
+      embeddingFormatVersion: 2,
+    });
+  });
+
+  it('PUT normalizes out-of-range search params and clears the format version when absent', async () => {
+    const capture = capturePut();
+    await request(createTestApp()).put('/api/configs/vector-search').send({
+      enabled: false,
+      authToken: '',
+      searchThreshold: 5,
+      searchTopK: 999,
+      embeddingFormatVersion: 0,
+    });
+
+    const p = capture.params[0];
+    expect(p[7]).toBe(0.35); // out-of-range threshold → default
+    expect(p[8]).toBe(30); // out-of-range topK → default
+    expect(p[9]).toBe(0); // enable_hyde absent → false
+    expect(p[10]).toBe(0); // enable_reranking absent → false
+    expect(p[11]).toBeNull(); // embeddingFormatVersion 0 (invalid) → null
+  });
+});

src/services/autoSync.ts

@@ -43,6 +43,67 @@ function quickHash(data: unknown): string {
   return JSON.stringify(data);
 }
 
+/** Canonical fingerprint for the vector search config.
+ *
+ * The backend GET payload and the store config have different key sets/order
+ * (backend adds authTokenStatus/status/lastSyncAt, the store always carries
+ * embeddingFormatVersion). A naive quickHash over each raw side therefore never
+ * matches, which kept the poll→push loop running forever. Fingerprinting only the
+ * shared, meaningful fields makes both sides converge after one round-trip.
+ */
+export function vectorSearchFingerprint(config: unknown): string {
+  const c = (config ?? {}) as Record<string, unknown>;
+  return quickHash({
+    enabled: !!c.enabled,
+    workerUrl: c.workerUrl ?? '',
+    authToken: c.authToken ?? '',
+    embeddingConfigId: c.embeddingConfigId ?? '',
+    indexMode: c.indexMode ?? 'readme',
+    readmeMaxChars: c.readmeMaxChars ?? 6000,
+    searchThreshold: c.searchThreshold ?? 0.35,
+    searchTopK: c.searchTopK ?? 30,
+    enableHyDE: c.enableHyDE ?? true,
+    enableReranking: c.enableReranking ?? true,
+    embeddingFormatVersion: c.embeddingFormatVersion ?? null,
+  });
+}
+
+/**
+ * Decide whether a fresh/empty backend must NOT overwrite a locally configured
+ * vector search. Mirrors the repositories bootstrap guard: on the first-ever sync
+ * in this session, an empty backend (nothing stored) must not wipe a working local
+ * config — otherwise the local worker/embedding setup is lost and the follow-up
+ * push then persists the wiped (empty) config to the backend. When true, the
+ * caller keeps the local config and pushes it up instead.
+ */
+export function shouldPreserveLocalVectorSearch(
+  backendConfig: unknown,
+  localConfig: unknown,
+  isFirstSync: boolean
+): boolean {
+  if (!isFirstSync) return false;
+  const b = (backendConfig ?? {}) as Record<string, unknown>;
+  const l = (localConfig ?? {}) as Record<string, unknown>;
+  const backendEmpty = !b.enabled && !b.workerUrl && !b.embeddingConfigId;
+  const localConfigured = !!(l.enabled || l.workerUrl || l.embeddingConfigId);
+  return backendEmpty && localConfigured;
+}
+
+/**
+ * True when the backend's stored vector-search authToken is unusable (empty or
+ * failed to decrypt) but the local client has a working token to preserve. The
+ * caller must then queue a repair push: during a pull the store subscription is
+ * suppressed, so without it the preserved token would never reach the backend,
+ * the stored fingerprint (with the local token) would never match the backend's
+ * empty token, and the poll→push loop would run forever.
+ */
+export function shouldQueueVectorSearchRepairPush(backendConfig: unknown, localConfig: unknown): boolean {
+  const b = (backendConfig ?? {}) as Record<string, unknown>;
+  const l = (localConfig ?? {}) as Record<string, unknown>;
+  const backendTokenUnusable = b.authTokenStatus === 'decrypt_failed' || !b.authToken;
+  return backendTokenUnusable && !!l.authToken;
+}
+
 function setRepositorySyncVisualState(isSyncing: boolean): void {
   if (typeof window === 'undefined') return;
   window.dispatchEvent(new CustomEvent('gsm:repository-sync-visual-state', { detail: { isSyncing } }));
@@ -171,9 +232,8 @@ export async function syncFromBackend(): Promise<void> {
     }
 
     if (vectorSearchResult.status === 'fulfilled') {
-      const hash = quickHash(vectorSearchResult.value);
+      const hash = vectorSearchFingerprint(vectorSearchResult.value);
       if (hash !== _lastHash.vectorSearch) {
-        hashes.vectorSearch = hash;
         changed.vectorSearch = true;
       }
     }
@@ -277,16 +337,27 @@ export async function syncFromBackend(): Promise<void> {
     }
     if (changed.vectorSearch && vectorSearchResult.status === 'fulfilled') {
       const backendConfig = vectorSearchResult.value;
-      // Preserve local authToken if backend returned empty or decrypt_failed
       const localConfig = state.vectorSearchConfig;
-      if ((backendConfig as Record<string, unknown>).authTokenStatus === 'decrypt_failed' || !backendConfig.authToken) {
-        if (localConfig.authToken) {
+      // Bootstrap guard (mirrors repositories): a fresh/empty backend must not
+      // wipe a locally-configured vector search — keep local and push it up.
+      if (shouldPreserveLocalVectorSearch(backendConfig, localConfig, _lastHash.vectorSearch === '')) {
+        _hasPendingPush = true;
+      } else {
+        // Preserve local authToken if backend returned empty or decrypt_failed,
+        // and queue a repair push so the backend is re-synced with it. Without
+        // the push the preserved token stays local-only and the poll loop keeps
+        // re-detecting the backend/effective fingerprint mismatch.
+        if (shouldQueueVectorSearchRepairPush(backendConfig, localConfig)) {
           logger.warn('sync.decryptFailed', 'Backend decrypt_failed for vector search authToken, preserving local value');
           backendConfig.authToken = localConfig.authToken;
+          _hasPendingPush = true;
         }
+        state.setVectorSearchConfig(backendConfig);
+        // Fingerprint the effective store config (after merge/normalization) so it
+        // matches the push fingerprint in syncToBackend(); hashing the raw backend
+        // payload instead would leave the two sides forever unequal.
+        _lastHash.vectorSearch = vectorSearchFingerprint(useAppStore.getState().vectorSearchConfig);
       }
-      state.setVectorSearchConfig(backendConfig);
-      _lastHash.vectorSearch = hashes.vectorSearch;
     }
     // Sync active selections from settings
     if (changed.settings && settingsResult.status === 'fulfilled') {
@@ -404,7 +475,7 @@ export async function syncToBackend(): Promise<void> {
     if (aiSync.status === 'fulfilled') _lastHash.ai = quickHash(state.aiConfigs);
     if (webdavSync.status === 'fulfilled') _lastHash.webdav = quickHash(state.webdavConfigs);
     if (embeddingSync.status === 'fulfilled') _lastHash.embedding = quickHash(state.embeddingConfigs);
-    if (vectorSearchSync.status === 'fulfilled') _lastHash.vectorSearch = quickHash(state.vectorSearchConfig);
+    if (vectorSearchSync.status === 'fulfilled') _lastHash.vectorSearch = vectorSearchFingerprint(state.vectorSearchConfig);
     if (settingsSync.status === 'fulfilled') {
       _lastHash.settings = quickHash({
         activeAIConfig: state.activeAIConfig,