docs(PRD): status table, context-mode advisory, retrieval §5.8, NR backlog

Sync public knowledge PRD with shipped search (corpus, locale, MCP rate limit).
Clarify context-mode is client-side; server may adopt BM25 ideas separately.

Made-with: Cursor

Author: ilyar

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

@@ -14,6 +14,8 @@
 
 **Связь с MCP:** текущий поисковый sidecar — **основной upstream для инструментов знаний в `mcp-server`** (поиск по корпусу для MCP-клиентов). Любые изменения сервиса **`search`** (имя контейнера, URL, порты, формат вызова, переменные окружения, контракт ответа, health, аутентификация внутри сети при необходимости) **обязаны** быть отражены **в реализации MCP в том же репозитории `repo/api`**: код сервера MCP, конфигурация Docker Compose, деплой, тесты. Публичный REST под **`/knowledge/api`** и браузерный UI — **дополнительная** поверхность того же сервиса; **нельзя** менять только контейнер поиска без обновления путей вызова и контракта, которыми пользуется MCP. Подробно §5.3.
 
+**Инструменты агента (например [context-mode](https://github.com/mksglu/context-mode)):** см. **§13** — это **не** замена сервису `search` на сервере, а дополнительный слой на машине разработчика/агента.
+
 ---
 
 ## 2. Goals
@@ -34,14 +36,19 @@
 - **Внутренняя реализация ответа** (как формируется текст ответа, откуда берётся контекст, какие компоненты задействованы) — **вне этого PRD** и **не отражается** во внешнем REST-контракте; клиентам это недоступно и не требуется.
 - Оплата/биллинг — вне scope; tier привязан к **валидности токена** и **конфигу**, не к Stripe.
 - Глобальный CDN — не требуется для v1.
+- **Встраивание клиентского MCP (в т.ч. context-mode) внутрь контейнера `search` как обязательной зависимости публичного API** — вне scope: см. **§13**.
 
 ---
 
 ## 4. Current state (baseline)
 
-- Прод-стек: **Caddy** проксирует большую часть трафика на **`mcp-server:3000`**; sidecar поиска (сейчас **`qwen-search`**) слушает внутри сети (например `:8790`).
-- **MCP (`mcp-server`) напрямую зависит от этого сервиса:** инструменты knowledge вызывают поиск по HTTP (или контейнерному режиму) через конфигурацию вроде **`QWEN_MODE`**, **`QWEN_API_URL=http://qwen-search:8790`**, клиент в **`src/`** (qwen/MCP-логика), **`depends_on` / health** в **`docker-compose.prod.yml`**. Без работоспособного поискового sidecar цепочка MCP → знания **не выполняется**.
-- Токен **`API_TOKEN`** уже выдаётся оператором/ботом и кладётся в `.env` (для публичного API и других компонентов; для внутреннего вызова MCP из docker-сети правила могут отличаться — см. реализацию).
+*(по состоянию репозитория `repo/api`, дорожная карта — **§12**.)*
+
+- Прод-стек: **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).
+- Токен **`API_TOKEN`** выдаётся оператором/ботом и кладётся в `.env` на **`search`** и связанные сервисы; невалидный Bearer → **401**.
 
 ## 5. Target architecture
 
@@ -256,27 +263,49 @@ rate_limit_tiers:
 - **Шифрование в транзите до пользователя** обеспечивается **Caddy** (и инфраструктурой перед ним), не отдельной настройкой `search`.
 - Рассмотреть **WAF-уровень** позже (на Caddy или выше — вне scope `search` v1).
 
+### 5.8 Пайплайн извлечения контекста (maintainer-facing)
+
+Раздел **не меняет** внешний REST-контракт, но фиксирует текущую реализацию и направления улучшений.
+
+| Компонент | Статус | Заметки |
+|-----------|--------|---------|
+| Монтирование корпуса **`/corpus`** (прод) и **`KNOWLEDGE_ROOT`** | **Done** | Образ также содержит снимок **`knowledge/`** в **`/opt/search/knowledge`** для запуска без volume. |
+| Ранжирование фрагментов перед вызовом LLM | **Done** | Эвристика по токенам запроса и `.md` (Unicode-токены для кириллицы); см. `docker/search/knowledge-rank.mjs`, зеркало логики в `src/local-search.ts`. |
+| Учёт **`locale`** в промпте | **Done** | Явные инструкции `ru` / `en` / авто по языку запроса. |
+| Поле **`sources`** | **Done** | Из JSON ответа модели; если пусто — fallback из ранжированных источников. |
+| Диагностика сбоев Qwen (**stdout/stderr** в **502**) | **Done** | Усечённые потоки в `message` для оператора. |
+
+**Будущие улучшения (см. §12, NR-RET):** по желанию заменить или дополнить эвристику поиском уровня **BM25 / FTS** (как в локальных MCP-инструментах), **RRF**, нормализация запросов — без изменения путей **`/knowledge/api/v1/*`**.
+
 ---
 
 ## 6. Configuration reference (для операторов)
 
-Пример переменных (имена итоговые — утвердить в implementer pass):
+Актуальный набор (расширять по мере появления переменных в `docker-compose` / entrypoint):
 
-- `SEARCH_HTTP_PORT`
-- `SEARCH_RATE_LIMIT_TIERS` (JSON) **или** путь к файлу `SEARCH_RATE_LIMIT_CONFIG`
-- `API_TOKEN` (shared secret для basic-tier в v1)
-- `TRUSTED_PROXY_CIDRS` / `REAL_IP_HEADER` для корректного IP клиента **за Caddy** (ingress уже терминирует TLS и проксирует HTTP на `search`)
+| Переменная | Назначение |
+|------------|------------|
+| `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_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`**. |
+| `QWEN_TIMEOUT_MS` / `SEARCH_TIMEOUT_MS` | Таймаут вызова Qwen. |
+| `X-Forwarded-For` | От Caddy — определяет публичный клиентский IP для rate limit; внутренние вызовы без этого заголовка лимит не потребляют. |
+
+*Исторически:* часть имён сохраняет префикс **`QWEN_*`** у sidecar; новые параметры по возможности именовать **`SEARCH_*`**.
 
 ---
 
 ## 7. Migration plan
 
-1. Ввести сервис **`search`** параллельно с `qwen-search` (опциональный short-lived alias в compose).
-2. **Обновить реализацию MCP** под новый hostname/URL/контракт: код (`src/mcp.ts`, `src/qwen/*` и смежное), переменные окружения **`mcp-server`**, интеграционные тесты; убедиться, что инструменты knowledge снова получают ответы от **`search`**.
-3. Переключить Caddy **`/knowledge*`** → **`search`** (UI + публичный API).
-4. Обновить ENV в **`mcp-server`** на новые имена; депрекейт **`QWEN_*`** после перевода.
-5. Удалить старый сервис **`qwen-search`** после проверки **и** регресса MCP.
-6. Обновить документацию оператора и Telegram-тексты при необходимости.
+1. ~~Ввести сервис **`search`** параллельно с `qwen-search`~~ — **Done** (отметка для истории; alias не обязателен).
+2. ~~**Обновить реализацию MCP** под новый hostname/URL/контракт~~ — **Done** (`SEARCH_REST_API`, `SEARCH_API_URL`, клиент `src/qwen/search-http.ts`).
+3. ~~Переключить Caddy **`/knowledge*`** → **`search`**~~ — **Done**.
+4. ~~Обновить ENV **`mcp-server`**; зачистить устаревшие **`QWEN_*`** где заменены~~ — **частично** (некоторые **`QWEN_*`** ещё используются у образа/search — см. compose; при рефакторинге свести к одной схеме имён).
+5. ~~Удалить **`qwen-search`**~~ — **Done** (as сервис **`search`**).
+6. Документация оператора / бот-тексты — **по необходимости** (ссылка на этот PRD и OPERATOR.md).
 
 ---
 
@@ -285,6 +314,8 @@ rate_limit_tiers:
 - Метрики: счётчики по tier (accepted, 429), latency search.
 - Алерты: рост доли 429 на free (возможная атака) vs. organic traffic.
 
+**Статус:** в коде **`search`** пока нет встроенного Prometheus/OpenTelemetry; **NR-OBS** — вынести счётчики и гистограммы latency в следующую итерацию.
+
 ---
 
 ## 9. Testing requirements
@@ -294,12 +325,15 @@ rate_limit_tiers:
 - **MCP ↔ `search`:** тесты, подтверждающие, что **`mcp-server`** (или его модуль knowledge tool) получает корректный ответ от **`search`** при конфигурации, совпадающей с compose-деплоем.
 - Contract: snapshot OpenAPI + тесты **`/knowledge/api/v1/health`**, **`/knowledge/api/v1/search`**, плюс отдача UI и спецификации под **`/knowledge/`**.
 
+**Сделано в репозитории:** оффлайн-проверка OpenAPI (`src/__tests__/knowledge-openapi-contract.test.ts`); **smoke** против прода/стенда: **`npm run smoke:knowledge`** (`scripts/smoke-knowledge-search.mjs`). E2E с поднятым Caddy в CI — **желательно** (NR-TEST).
+
 ---
 
 ## 10. Open questions
 
-1. Дневной лимит: граница **UTC 00:00** vs. часовой пояс оператора (для v1 обычно UTC).
+1. Дневной лимит: граница **UTC 00:00** vs. часовой пояс оператора (для v1 обычно UTC) — **зафиксировать в OPERATOR.md**.
 2. Нужны ли дополнительные read-only эндпоинты под **`/knowledge/api/v1/...`** (например метаданные корпуса) с правилом «без квоты» или «с квотой».
+3. Нужна ли явная **версия корпуса** / ETag в **`meta`** ответа **search** для клиентов SDK.
 
 ---
 
@@ -310,4 +344,48 @@ rate_limit_tiers:
 
 ---
 
-*Document version: 1.4 — 2026-03-24 — добавлена обязательная связь с реализацией **MCP** (§1, §4, §5.3, G7, миграция, тесты); уточнены внутренний vs публичный вход и rate limit для MCP (§5.4.6).*
+## 12. Implementation status (живая сводка)
+
+### 12.1 Goals §2
+
+| ID | Статус | Примечание |
+|----|--------|------------|
+| G1 | **Done** | Сервис **`search`**, OpenAPI **`/knowledge/api/v1/*`**. |
+| G2 | **Done** | Caddy → **`search`** для **`/knowledge*`**. |
+| G3 | **Done** | Swagger UI, **`openapi/knowledge-v1.yaml`**. |
+| G4 | **Done** | Опциональный Bearer, **401** при неверном токене. |
+| G5 | **Done** | Дефолтные лимиты; **429** с `tier` / `limit`. |
+| G6 | **Done** | `SEARCH_RATE_LIMIT_TIERS` (JSON). |
+| G7 | **Done** | MCP + compose + тесты синхронизированы. |
+
+### 12.2 Новые требования (backlog)
+
+| ID | Требование | Приоритет |
+|----|------------|-----------|
+| **NR-RET-1** | Оценить **FTS5 / BM25** или **сведение рангов (RRF)** для релевантности фрагментов корпуса вместо или вместе с текущей эвристикой; сохранить контракт API. | P2 |
+| **NR-RET-2** | Опциональный **кэш** ответов по `(query нормализованный, locale, версия корпуса)` при неизменном корпусе — снижение стоимости Qwen и latency. | 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 |
+| **NR-DOC-1** | OpenAPI: уточнить схему **`sources`** / **`meta`** (согласованность `file` с историческими упоминаниями `path` / `title` в тексте PRD). | P3 |
+
+---
+
+## 13. Context-mode ([`mksglu/context-mode`](https://github.com/mksglu/context-mode)) и оптимизация
+
+**Что это:** MCP-сервер и связанные хуки для **локальной** среды агента (Cursor, Claude Code и др.). Даёт **песочницу** для команд, **индексацию** (FTS5, BM25, RRF) и **поиск по индексу** так, чтобы **сырые объёмы** не попадали в контекстное окно модели.
+
+**Связь с сервисом `search`:**
+
+| Вопрос | Ответ |
+|--------|--------|
+| Можно ли «просто подключить» context-mode внутрь Docker **`search`** как замену Qwen? | **Нет.** context-mode не является HTTP-сервисом ответов на вопросы пользователей; это протокол **MCP** и инструменты для **клиента** агента. |
+| Дает ли context-mode выигрыш **на сервере** SpawnDock? | **Не напрямую.** Запуск MCP stdio в sidecar усложнит архитектуру и не даст публичному REST стабильного контракта без отдельного адаптера. Имеет смысл **заимствовать идеи** (BM25, RRF,/snippets) в **`knowledge-rank`** или отдельном модуле — см. **NR-RET-1** / §5.8. |
+| Где context-mode полезен продукту SpawnDock? | Для **разработчиков и операторов**: при работе с логами деплоя, длинной документацией и ответами **`/knowledge/api`** использовать **`ctx_execute` / `ctx_batch_execute` / `ctx_index`** так, чтобы агент не засорял контекст; при интеграции с публичным API — снимать крупные JSON через sandbox. |
+| Лицензия | У проекта context-mode лицензия **ELv2** — перед копипастой кода в **`repo/api`** нужна **правовая** проверка; безопаснее внедрять схожие алгоритмы самостоятельно или через зависимости с совместимой лицензией. |
+
+**Итог:** context-mode **не** ставится обязательной зависимостью сервиса **`search`**; оптимизация **серверного** поиска идёт через **NR-*** и §5.8; context-mode рекомендуется как **дополнение на стороне клиента** при разработке и эксплуатации.
+
+---
+
+*Document version: 1.5 — 2026-03-25 — §4/§6/§7 актуализированы; §5.8 пайплайн; §12 статус и backlog; §13 context-mode; §9 smoke-тесты; NR для retrieval/observability/HA.*