feat: align MCP corpus rank with MiniSearch; LRU cache for search HTTP

- Add src/corpus-minisearch.ts and wire local-search rankDocuments (SEARCH_RANKER)
- search sidecar: response cache keyed by corpus mtime, optional KNOWLEDGE_CACHE_REVISION
- Export corpusMaxMtime for cache keys; meta.cache_hit on cache lookup
- PRD 1.7 / .env.example

Made-with: Cursor

Author: ilyar

.env.example

@@ -20,6 +20,12 @@ QWEN_CONTAINER_RUNTIME=docker
 QWEN_CONTAINER_CORPUS_PATH=/corpus
 QWEN_CONTAINER_MAX_STDOUT_BYTES=524288
 QWEN_CONTAINER_MAX_STDERR_BYTES=65536
+# Knowledge ranking in MCP (local-search) and search sidecar default: minisearch; use legacy for old heuristic only.
+SEARCH_RANKER=minisearch
+# search container: LRU cache of full JSON answers (same query+locale+corpus mtime). 0 = disabled.
+SEARCH_RESPONSE_CACHE_MAX=64
+# Bust cache after deploy without filesystem mtime change (optional string).
+KNOWLEDGE_CACHE_REVISION=
 # Public URL clients use (scheme + host, no trailing slash). With Caddy on 80/443 use http://your-host or https://your-host
 PUBLIC_ORIGIN=https://spawn-dock.w3voice.net
 # docker-compose.prod.yml mounts ./data/state → /app/.spawndock

docker/search/http-server.mjs

@@ -8,14 +8,16 @@ import { spawn } from "node:child_process";
 import { readFileSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { rankKnowledgeForQuery } from "./knowledge-rank.mjs";
+import { corpusMaxMtime, rankKnowledgeForQuery } from "./knowledge-rank.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PORT = parseInt(process.env.SEARCH_HTTP_PORT || process.env.QWEN_HTTP_PORT || "8790", 10);
 const TIMEOUT_MS = parseInt(process.env.QWEN_TIMEOUT_MS || process.env.SEARCH_TIMEOUT_MS || "120000", 10);
 const MAX_STDOUT = parseInt(process.env.QWEN_SEARCH_MAX_STDOUT || process.env.SEARCH_MAX_STDOUT || "524288", 10);
 const LISTEN = process.env.SEARCH_HTTP_BIND || process.env.QWEN_HTTP_BIND || "0.0.0.0";
 const API_TOKEN = (process.env.API_TOKEN || "").trim();
+const SEARCH_RESPONSE_CACHE_MAX = parseInt(process.env.SEARCH_RESPONSE_CACHE_MAX || "64", 10);
+const KNOWLEDGE_CACHE_REVISION = (process.env.KNOWLEDGE_CACHE_REVISION || "").trim();
 
 const DEFAULT_TIERS = {
   free: { requests_per_minute: 1, requests_per_day: 10 },
@@ -104,6 +106,42 @@ function readOpenapiYaml() {
   return readFileSync(openapiPath(), "utf8");
 }
 
+/** LRU-ish: move key to end on get (Map preserves insertion order). */
+const searchResponseCache = new Map();
+
+function normalizeQueryForCache(q) {
+  return q.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+function searchCacheKey(knowledgeRoot, locale, query) {
+  const mtime = knowledgeRoot ? corpusMaxMtime(knowledgeRoot) : 0;
+  const loc = (locale ?? "").trim().toLowerCase();
+  return `${KNOWLEDGE_CACHE_REVISION}|${mtime}|${loc}|${normalizeQueryForCache(query)}`;
+}
+
+function searchCacheGet(key) {
+  const v = searchResponseCache.get(key);
+  if (v !== undefined) {
+    searchResponseCache.delete(key);
+    searchResponseCache.set(key, v);
+  }
+  return v;
+}
+
+function searchCacheSet(key, value) {
+  if (SEARCH_RESPONSE_CACHE_MAX <= 0) {
+    return;
+  }
+  if (searchResponseCache.has(key)) {
+    searchResponseCache.delete(key);
+  }
+  searchResponseCache.set(key, value);
+  while (searchResponseCache.size > SEARCH_RESPONSE_CACHE_MAX) {
+    const first = searchResponseCache.keys().next().value;
+    searchResponseCache.delete(first);
+  }
+}
+
 function clientFacingIp(req) {
   const xff = req.headers["x-forwarded-for"];
   if (typeof xff === "string" && xff.trim().length > 0) {
@@ -279,6 +317,15 @@ function normalizeSearchBody(rawText) {
 
 async function runSearchQuery(query, locale) {
   const knowledgeRoot = resolveKnowledgeRoot();
+  const cacheKey = searchCacheKey(knowledgeRoot, locale, query);
+  const cached = searchCacheGet(cacheKey);
+  if (cached) {
+    return {
+      ...cached,
+      meta: { ...cached.meta, cache_hit: true },
+    };
+  }
+
   let matches = [];
   if (knowledgeRoot) {
     try {
@@ -296,7 +343,9 @@ async function runSearchQuery(query, locale) {
   }
   const meta = {};
   if (locale) meta.locale_requested = locale;
-  return { answer: normalized.answer, sources, meta };
+  const result = { answer: normalized.answer, sources, meta };
+  searchCacheSet(cacheKey, result);
+  return result;
 }
 
 function sendJson(res, status, body) {

docker/search/knowledge-rank.mjs

@@ -169,7 +169,7 @@ function walkKnowledgeTree(dir) {
   return files;
 }
 
-function corpusMaxMtime(rootDir) {
+export function corpusMaxMtime(rootDir) {
   let max = 0;
   try {
     for (const p of walkKnowledgeTree(rootDir)) {

docs/PRD-public-knowledge-search-service.md

@@ -170,7 +170,7 @@ Caddy по-прежнему монтирует весь продукт под п
 |------|-----|----------|
 | `answer` | string | Основной текст ответа |
 | `sources` | array | **Опционально.** Унифицированный список источников из корпуса (например `{ "path": "guides/foo.md", "title": "..." }`) — структура задаётся в OpenAPI `components.schemas` |
-| `meta` | object | **Опционально.** Служебные не секретные поля (например `request_id`) |
+| `meta` | object | **Опционально.** Служебные не секретные поля (например `locale_requested`, `cache_hit` при попадании в LRU-кэш **`search`**) |
 
 Нормативные детали полей **`sources`** / **`meta`** — только в OpenAPI; клиент опирается на спецификацию, без знания внутренней реализации.
 
@@ -274,6 +274,8 @@ rate_limit_tiers:
 | Учёт **`locale`** в промпте | **Done** | Явные инструкции `ru` / `en` / авто по языку запроса. |
 | Поле **`sources`** | **Done** | Из JSON ответа модели; если пусто — fallback из ранжированных источников. |
 | Диагностика сбоев Qwen (**stdout/stderr** в **502**) | **Done** | Усечённые потоки в `message` для оператора. |
+| Совпадение ранжирования MCP и **search** | **Done** | Оба пути: MiniSearch по секциям + legacy fallback; `SEARCH_RANKER=legacy` для отката. |
+| Кэш готового ответа (Qwen) | **Done** | LRU в `http-server.mjs`; см. `SEARCH_RESPONSE_CACHE_MAX`. |
 
 **Будущие улучшения (см. §12, NR-RET):** по желанию заменить или дополнить эвристику поиском уровня **BM25 / FTS** (как в локальных MCP-инструментах), **RRF**, нормализация запросов — без изменения путей **`/knowledge/api/v1/*`**.
 
@@ -288,7 +290,9 @@ rate_limit_tiers:
 | `SEARCH_HTTP_PORT` / `QWEN_HTTP_PORT` | Порт HTTP listener (по умолчанию **8790**). |
 | `SEARCH_HTTP_BIND` / `QWEN_HTTP_BIND` | Bind address (по умолчанию **0.0.0.0**). |
 | `KNOWLEDGE_ROOT` | Корень Markdown-корпуса (**рекомендуется `/corpus`** в проде). |
-| `SEARCH_RANKER` | `minisearch` (по умолчанию) или `legacy` — только эвристика по токенам. |
+| `SEARCH_RANKER` | `minisearch` (по умолчанию) или `legacy` — только эвристика по токенам (MCP `local-search` и sidecar). |
+| `SEARCH_RESPONSE_CACHE_MAX` | LRU-кэш готовых JSON-ответов **search** (ключ: ревизия + mtime корпуса + locale + query). **`0`** — выкл. |
+| `KNOWLEDGE_CACHE_REVISION` | Произвольная строка для инвалидации кэша без смены файлов на диске. |
 | `SEARCH_RATE_LIMIT_TIERS` | JSON override лимитов **free** / **basic** (см. §5.6). |
 | `API_TOKEN` | Общий секрет для **Bearer** и tier **basic** на **`search`**. |
 | `PROD_QWEN_OAUTH_CREDS` / `QWEN_OAUTH_CREDS_B64` | Base64 **oauth_creds** для Qwen CLI в контейнере; после смены секрета — **пересобрать/перезапустить** **`search`**. |
@@ -364,7 +368,7 @@ rate_limit_tiers:
 | ID | Требование | Приоритет |
 |----|------------|-----------|
 | **NR-RET-1** | ~~Оценить BM25~~ — **частично done** (MiniSearch + секции). Далее: **FTS5 / RRF / trigram** при необходимости; контракт API без изменений. | P2 |
-| **NR-RET-2** | Опциональный **кэш** ответов по `(query нормализованный, locale, версия корпуса)` при неизменном корпусе — снижение стоимости Qwen и latency. | P3 |
+| **NR-RET-2** | **Частично done:** in-memory LRU в **`search`** (`SEARCH_RESPONSE_CACHE_MAX`, mtime корпуса + `KNOWLEDGE_CACHE_REVISION`). Далее: shared store при нескольких репликах. | P3 |
 | **NR-OBS-1** | Метрики (**accepted/429/latency/502**) и точки интеграции с мониторингом хоста. | P2 |
 | **NR-HA-1** | При **>1 реплики** `search` — вынести дневные/минутные счётчики rate limit из in-memory (**Redis** и аналоги); см. §5.6.3. | P2 |
 | **NR-TEST-1** | CI: e2e контейнер **`search`** + health + search с моком Qwen или dry-run режимом. | P3 |
@@ -389,4 +393,4 @@ rate_limit_tiers:
 
 ---
 
-*Document version: 1.6 — 2026-03-25 — §5.8 MiniSearch ranker; §6 `SEARCH_RANKER`; NR-RET-1 частично закрыт; vitest exclude `docker/search`.*
+*Document version: 1.7 — 2026-03-25 — MCP `local-search` + MiniSearch; кэш ответов `search`; §6 cache env; meta `cache_hit`.*

package-lock.json

@@ -26,6 +26,7 @@
     "cors": "^2.8.6",
     "express": "^5.2.1",
     "express-rate-limit": "^8.3.1",
+    "minisearch": "^7.1.0",
     "ws": "^8.19.0",
     "zod": "^4.3.6"
   },

package.json

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { rankCorpusWithMiniSearch, splitIntoSections, tokenizeRankTerms } from "../corpus-minisearch.js";
+
+describe("corpus-minisearch", () => {
+  it("splitIntoSections respects headings", () => {
+    const parts = splitIntoSections("a.md", "# One\nx\n\n## Two\ny");
+    expect(parts.map((p) => p.section)).toEqual(["One", "Two"]);
+    expect(parts[0].content).toContain("x");
+  });
+
+  it("tokenizeRankTerms keeps Cyrillic tokens", () => {
+    expect(tokenizeRankTerms("как сделать TMA")).toEqual(["как", "сделать", "tma"]);
+  });
+
+  it("rankCorpusWithMiniSearch surfaces the best matching section", () => {
+    const ranked = rankCorpusWithMiniSearch("telegram WebApp mini app", [
+      {
+        file: "guides/x.md",
+        content: "# Noise\nNothing here.\n\n# Telegram\nUse WebApp for Telegram Mini App.",
+      },
+    ]);
+    expect(ranked.length).toBeGreaterThan(0);
+    expect(ranked[0].section).toBe("Telegram");
+    expect(ranked[0].file).toBe("guides/x.md");
+  });
+});

src/__tests__/corpus-minisearch.test.ts

@@ -0,0 +1,163 @@
+/**
+ * MiniSearch (BM25) ranking over Markdown sections — same strategy as docker/search/knowledge-rank.mjs.
+ */
+import MiniSearch from "minisearch";
+
+export interface CorpusDocument {
+  file: string;
+  content: string;
+}
+
+export interface RankedCorpusChunk {
+  file: string;
+  score: number;
+  section: string;
+  snippet: string;
+}
+
+const MAX_RESULTS = 5;
+const MIN_TOKEN_LENGTH = 2;
+const STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "for",
+  "how",
+  "is",
+  "into",
+  "that",
+  "the",
+  "this",
+  "what",
+  "with",
+]);
+
+function unicodeTokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter((t) => t.length > 0);
+}
+
+/** Exported for tests and snippet logic aligned with legacy ranker. */
+export function tokenizeRankTerms(query: string): string[] {
+  return unicodeTokenize(query).filter(
+    (token) => token.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(token),
+  );
+}
+
+export function splitIntoSections(
+  relPath: string,
+  content: string,
+): ReadonlyArray<{ file: string; section: string; content: string }> {
+  const lines = content.split(/\r?\n/);
+  const out: { file: string; section: string; content: string }[] = [];
+  let sectionTitle = "Overview";
+  const buf: string[] = [];
+  const flush = () => {
+    const text = buf.join("\n").trim();
+    if (text.length > 0) {
+      out.push({ file: relPath, section: sectionTitle, content: text });
+    }
+    buf.length = 0;
+  };
+  for (const line of lines) {
+    const m = /^#{1,6}\s+(.+)$/.exec(line);
+    if (m) {
+      flush();
+      sectionTitle = m[1].trim();
+      continue;
+    }
+    buf.push(line);
+  }
+  flush();
+  return out;
+}
+
+function extractSnippet(content: string, matchIndex: number): string {
+  const windowStart = Math.max(0, matchIndex - 120);
+  const windowEnd = Math.min(content.length, matchIndex + 220);
+  const rawSnippet = content
+    .slice(windowStart, windowEnd)
+    .replace(/\s+/g, " ")
+    .trim();
+  if (rawSnippet.length <= 220) {
+    return rawSnippet;
+  }
+  return `${rawSnippet.slice(0, 217)}...`;
+}
+
+function snippetFromContent(content: string, query: string): string {
+  const terms = tokenizeRankTerms(query);
+  if (terms.length === 0) {
+    const fb = unicodeTokenize(query).filter((t) => t.length >= 1);
+    for (const t of fb) {
+      const i = content.toLowerCase().indexOf(t);
+      if (i !== -1) {
+        return extractSnippet(content, i);
+      }
+    }
+    return extractSnippet(content, 0);
+  }
+  const lower = content.toLowerCase();
+  let best = -1;
+  for (const t of terms) {
+    const i = lower.indexOf(t);
+    if (i !== -1 && (best === -1 || i < best)) {
+      best = i;
+    }
+  }
+  const idx = best === -1 ? 0 : best;
+  return extractSnippet(content, idx);
+}
+
+/**
+ * Rank corpus slices with MiniSearch (per-heading chunks). Rebuilds index each call — fine for MCP corpus sizes.
+ */
+export function rankCorpusWithMiniSearch(
+  query: string,
+  documents: ReadonlyArray<CorpusDocument>,
+): ReadonlyArray<RankedCorpusChunk> {
+  const rows: { id: number; file: string; section: string; content: string }[] = [];
+  let id = 0;
+  for (const doc of documents) {
+    for (const sec of splitIntoSections(doc.file, doc.content)) {
+      rows.push({ id: id++, file: sec.file, section: sec.section, content: sec.content });
+    }
+  }
+  if (rows.length === 0) {
+    return [];
+  }
+
+  const mini = new MiniSearch({
+    fields: ["content", "section", "file"],
+    storeFields: ["file", "section", "content"],
+    idField: "id",
+    tokenize: (string) => unicodeTokenize(string).filter((t) => t.length >= 1),
+  });
+  mini.addAll(rows);
+
+  const hits = mini.search(query, {
+    prefix: true,
+    fuzzy: 0.12,
+    boost: { section: 2.2, file: 1.65, content: 1 },
+  });
+
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  const out: RankedCorpusChunk[] = [];
+  for (const h of hits.slice(0, MAX_RESULTS)) {
+    const hid = h.id as number;
+    const stored = byId.get(hid);
+    if (!stored) {
+      continue;
+    }
+    out.push({
+      file: stored.file,
+      score: h.score,
+      section: stored.section,
+      snippet: snippetFromContent(stored.content, query),
+    });
+  }
+  return out;
+}