refactor(search): drop locale from POST /v1/search body

Public API accepts only { query }. Prompt uses query language only.
Cache keys no longer include locale; remove meta.locale_requested.
Update OpenAPI, smoke script, PRD, contract test.

Made-with: Cursor

Author: ilyar

docker/search/README.md

@@ -3,7 +3,7 @@
 Production image `spawndock/search:prod`: Qwen Code CLI + HTTP server on port **8790**.
 
 - **Browser:** `GET /knowledge/` — Swagger UI (OpenAPI from `/knowledge/openapi.yaml`).
-- **REST:** `GET /knowledge/api/v1/health`, `POST /knowledge/api/v1/search` ({ `query`, optional `locale` }).
+- **REST:** `GET /knowledge/api/v1/health`, `POST /knowledge/api/v1/search` (JSON `{ "query" }` only).
 - **MCP:** set `SEARCH_REST_API=true` and `SEARCH_API_URL=http://search:8790` on `mcp-server`.
 
 **Rate limits** apply only when `X-Forwarded-For` is set (traffic via Caddy). Direct calls from Docker (e.g. MCP) skip public quotas. Override tiers with JSON env `SEARCH_RATE_LIMIT_TIERS` (see `DEFAULT_TIERS` in `http-server.mjs`).

docker/search/http-server.mjs

@@ -62,21 +62,7 @@ function resolveKnowledgeRoot() {
   return "";
 }
 
-function localeDirective(locale) {
-  const l = (locale || "").trim().toLowerCase();
-  if (!l) {
-    return "Write the answer in the same language as the user query.";
-  }
-  if (l === "ru" || l.startsWith("ru-")) {
-    return "You MUST write the entire answer in Russian.";
-  }
-  if (l === "en" || l.startsWith("en-")) {
-    return "You MUST write the entire answer in English.";
-  }
-  return `You MUST write the entire answer in the primary language for locale ${locale} (BCP 47).`;
-}
-
-function buildSearchPrompt(query, locale, matches) {
+function buildSearchPrompt(query, matches) {
   const context =
     matches.length > 0
       ? matches
@@ -89,7 +75,7 @@ function buildSearchPrompt(query, locale, matches) {
 
   return [
     "You are a knowledge assistant for Telegram Mini App (TMA) and SpawnDock documentation.",
-    localeDirective(locale),
+    "Write the answer in the same language as the user query.",
     "When excerpts below are relevant, base your answer strictly on them.",
     'Respond with valid JSON only (no markdown fences): {"answer":"...","sources":[{"file":"path.md","section":"Heading"}]}',
     "List every excerpt source you used in \"sources\"; use [] only if excerpts were not used.",
@@ -113,10 +99,9 @@ function normalizeQueryForCache(q) {
   return q.trim().toLowerCase().replace(/\s+/g, " ");
 }
 
-function searchCacheKey(knowledgeRoot, locale, query) {
+function searchCacheKey(knowledgeRoot, query) {
   const mtime = knowledgeRoot ? corpusMaxMtime(knowledgeRoot) : 0;
-  const loc = (locale ?? "").trim().toLowerCase();
-  return `${KNOWLEDGE_CACHE_REVISION}|${mtime}|${loc}|${normalizeQueryForCache(query)}`;
+  return `${KNOWLEDGE_CACHE_REVISION}|${mtime}|${normalizeQueryForCache(query)}`;
 }
 
 function searchCacheGet(key) {
@@ -315,9 +300,9 @@ function normalizeSearchBody(rawText) {
   }
 }
 
-async function runSearchQuery(query, locale) {
+async function runSearchQuery(query) {
   const knowledgeRoot = resolveKnowledgeRoot();
-  const cacheKey = searchCacheKey(knowledgeRoot, locale, query);
+  const cacheKey = searchCacheKey(knowledgeRoot, query);
   const cached = searchCacheGet(cacheKey);
   if (cached) {
     return {
@@ -334,15 +319,14 @@ async function runSearchQuery(query, locale) {
       console.error("knowledge rank error:", err instanceof Error ? err.message : err);
     }
   }
-  const prompt = buildSearchPrompt(query, locale, matches);
+  const prompt = buildSearchPrompt(query, matches);
   const stdout = await runQwenPrompt(prompt);
   const normalized = normalizeSearchBody(extractQwenCliResult(stdout));
   let sources = normalized.sources;
   if (sources.length === 0 && matches.length > 0) {
     sources = matches.map((m) => ({ file: m.file, section: m.section }));
   }
   const meta = {};
-  if (locale) meta.locale_requested = locale;
   const result = { answer: normalized.answer, sources, meta };
   searchCacheSet(cacheKey, result);
   return result;
@@ -446,14 +430,13 @@ async function handleRequest(req, res) {
       return;
     }
     const query = typeof json.query === "string" ? json.query : "";
-    const locale = typeof json.locale === "string" ? json.locale : undefined;
     if (!query.trim()) {
       sendError(res, 400, "validation_error", "Field \"query\" is required and must be non-empty");
       return;
     }
 
     try {
-      const result = await runSearchQuery(query, locale);
+      const result = await runSearchQuery(query);
       sendJson(res, 200, result);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);

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

@@ -47,7 +47,7 @@
 - Прод-стек: **Caddy** отдаёт **`/knowledge*`** на контейнер **`search`** (внутренний HTTP, порт **`8790`**); остальной трафик — на **`mcp-server:3000`** по существующим правилам.
 - **Сервис Compose:** имя **`search`**, образ **`spawndock/search:prod`**; каталог корпуса **`./knowledge:/corpus:ro`**; переменная **`KNOWLEDGE_ROOT=/corpus`** (см. `docker-compose.prod.yml`).
 - **MCP (`mcp-server`):** при **`SEARCH_REST_API=true`** вызывает **`SEARCH_API_URL`** (например `http://search:8790`) на **`POST /knowledge/api/v1/search`**; внутрисетевые запросы **без** `X-Forwarded-For` **не** попадают под публичный rate limit (**§5.4.6** реализовано).
-- **Пайплайн ответа:** локальное ранжирование фрагментов из корпуса (Markdown под `KNOWLEDGE_ROOT`), подстановка выдержек и директивы **`locale`** в промпт **Qwen Code CLI**; поля **`sources`** заполняются из ответа модели либо fallback по ранжированным файлам. Аутентификация Qwen — OAuth (`PROD_QWEN_OAUTH_CREDS` / `QWEN_OAUTH_CREDS_B64` → `~/.qwen/oauth_creds.json` в entrypoint).
+- **Пайплайн ответа:** локальное ранжирование фрагментов из корпуса (Markdown под `KNOWLEDGE_ROOT`), подстановка выдержек в промпт **Qwen Code CLI**; язык ответа — **по языку запроса** (отдельного поля `locale` в API **нет**). Поля **`sources`** — из JSON модели либо fallback по ранжированным файлам. Аутентификация Qwen — OAuth (`PROD_QWEN_OAUTH_CREDS` / `QWEN_OAUTH_CREDS_B64` → `~/.qwen/oauth_creds.json` в entrypoint).
 - Токен **`API_TOKEN`** выдаётся оператором/ботом и кладётся в `.env` на **`search`** и связанные сервисы; невалидный Bearer → **401**.
 
 ## 5. Target architecture
@@ -155,13 +155,12 @@ Caddy по-прежнему монтирует весь продукт под п
 
 | Поле | Тип | Обязательность | Описание |
 |------|-----|----------------|----------|
-| `query` | string | **да** | Текст запроса к базе знаний; **без** полей, меняющих способ формирования ответа «снаружи» |
-| `locale` | string | нет | Предпочитаемая локаль ответа (например `en`, `ru`) — если сервис поддерживает; при отсутствии — поведение по умолчанию |
+| `query` | string | **да** | Текст запроса к базе знаний |
 
 Пример:
 
 ```json
-{ "query": "How do I wire a Telegram Mini App webhook?", "locale": "en" }
+{ "query": "How do I wire a Telegram Mini App webhook?" }
 ```
 
 **Ответ 200 (JSON):**
@@ -170,7 +169,7 @@ Caddy по-прежнему монтирует весь продукт под п
 |------|-----|----------|
 | `answer` | string | Основной текст ответа |
 | `sources` | array | **Опционально.** Унифицированный список источников из корпуса (например `{ "path": "guides/foo.md", "title": "..." }`) — структура задаётся в OpenAPI `components.schemas` |
-| `meta` | object | **Опционально.** Служебные не секретные поля (например `locale_requested`, `cache_hit` при попадании в LRU-кэш **`search`**) |
+| `meta` | object | **Опционально.** Служебные не секретные поля (например `cache_hit` при попадании в LRU-кэш **`search`**) |
 
 Нормативные детали полей **`sources`** / **`meta`** — только в OpenAPI; клиент опирается на спецификацию, без знания внутренней реализации.
 
@@ -271,7 +270,7 @@ rate_limit_tiers:
 |-----------|--------|---------|
 | Монтирование корпуса **`/corpus`** (прод) и **`KNOWLEDGE_ROOT`** | **Done** | Образ также содержит снимок **`knowledge/`** в **`/opt/search/knowledge`** для запуска без volume. |
 | Ранжирование фрагментов перед вызовом LLM | **Done** | По умолчанию **[MiniSearch](https://github.com/lucaong/minisearch)** (BM25-алгоритм) по секциям Markdown; при пустом hit — fallback на эвристику по токенам. `SEARCH_RANKER=legacy` — только эвристика. См. `docker/search/knowledge-rank.mjs`; зеркало эвристики в `src/local-search.ts`. |
-| Учёт **`locale`** в промпте | **Done** | Явные инструкции `ru` / `en` / авто по языку запроса. |
+| Язык ответа | **Done** | Только по тексту **`query`** (инструкция модели: совпадать с языком запроса); параметра **`locale`** нет. |
 | Поле **`sources`** | **Done** | Из JSON ответа модели; если пусто — fallback из ранжированных источников. |
 | Диагностика сбоев Qwen (**stdout/stderr** в **502**) | **Done** | Усечённые потоки в `message` для оператора. |
 | Совпадение ранжирования MCP и **search** | **Done** | Оба пути: MiniSearch по секциям + legacy fallback; `SEARCH_RANKER=legacy` для отката. |
@@ -291,7 +290,7 @@ rate_limit_tiers:
 | `SEARCH_HTTP_BIND` / `QWEN_HTTP_BIND` | Bind address (по умолчанию **0.0.0.0**). |
 | `KNOWLEDGE_ROOT` | Корень Markdown-корпуса (**рекомендуется `/corpus`** в проде). |
 | `SEARCH_RANKER` | `minisearch` (по умолчанию) или `legacy` — только эвристика по токенам (MCP `local-search` и sidecar). |
-| `SEARCH_RESPONSE_CACHE_MAX` | LRU-кэш готовых JSON-ответов **search** (ключ: ревизия + mtime корпуса + locale + query). **`0`** — выкл. |
+| `SEARCH_RESPONSE_CACHE_MAX` | LRU-кэш готовых JSON-ответов **search** (ключ: ревизия + mtime корпуса + нормализованный `query`). **`0`** — выкл. |
 | `KNOWLEDGE_CACHE_REVISION` | Произвольная строка для инвалидации кэша без смены файлов на диске. |
 | `SEARCH_RATE_LIMIT_TIERS` | JSON override лимитов **free** / **basic** (см. §5.6). |
 | `API_TOKEN` | Общий секрет для **Bearer** и tier **basic** на **`search`**. |
@@ -368,7 +367,7 @@ rate_limit_tiers:
 | ID | Требование | Приоритет |
 |----|------------|-----------|
 | **NR-RET-1** | ~~Оценить BM25~~ — **частично done** (MiniSearch + секции). Далее: **FTS5 / RRF / trigram** при необходимости; контракт API без изменений. | P2 |
-| **NR-RET-2** | **Частично done:** in-memory LRU в **`search`** (`SEARCH_RESPONSE_CACHE_MAX`, mtime корпуса + `KNOWLEDGE_CACHE_REVISION`). Далее: shared store при нескольких репликах. | P3 |
+| **NR-RET-2** | **Частично done:** in-memory LRU в **`search`** (`SEARCH_RESPONSE_CACHE_MAX`, mtime корпуса + `KNOWLEDGE_CACHE_REVISION` + query). Далее: 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 |
@@ -393,4 +392,4 @@ rate_limit_tiers:
 
 ---
 
-*Document version: 1.7 — 2026-03-25 — MCP `local-search` + MiniSearch; кэш ответов `search`; §6 cache env; meta `cache_hit`.*
+*Document version: 1.8 — 2026-03-25 — убран параметр **`locale`** из **`POST /v1/search`**; язык только по **`query`**.*

openapi/knowledge-v1.yaml

@@ -49,9 +49,7 @@ paths:
               properties:
                 query:
                   type: string
-                locale:
-                  type: string
-                  description: Preferred response locale (e.g. en, ru)
+                  description: Natural-language question; response language follows the query language.
       responses:
         "200":
           description: Search result

scripts/smoke-knowledge-search.mjs

@@ -42,7 +42,7 @@ async function main() {
   const searchRes = await fetch(`${base}/api/v1/search`, {
     method: "POST",
     headers,
-    body: JSON.stringify({ query: "SpawnDock TMA", locale: "en" }),
+    body: JSON.stringify({ query: "SpawnDock TMA" }),
   });
   const body = await searchRes.text();
   if (!searchRes.ok) {

src/__tests__/knowledge-openapi-contract.test.ts

@@ -14,5 +14,6 @@ describe("knowledge OpenAPI contract", () => {
     expect(yaml).toContain("/v1/search");
     expect(yaml).toContain("servers:");
     expect(yaml).toContain("/knowledge/api");
+    expect(yaml).not.toContain("locale");
   });
 });