# Инструкции проекта chat-agent (Git: webrtc-komaroff) ## Область действия и источники - Эти инструкции действуют для всего репозитория. Более близкий `AGENTS.md`, если он появится в компоненте, уточняет их только для своего поддерева. - Сначала используй этот файл и ближайшие `.knowledge/*`, затем проверенные документы и конфигурацию репозитория. - Project overlay `monitorsoft:chat-agent` дополняет локальные источники знаниями о связанных checkout и runtime, но не заменяет их. - Корпоративные правила применяй только к затронутому контуру и только после проектных источников. ## Карта знаний - Общая структура и владельцы: `.knowledge/project-inventory.md`. - Development, debug, delivery и verification: `.knowledge/workflows.md`. - Архитектура и межсервисные контракты: `DOCS/ARCHITECTURE.md` и `DOCS/NATS.md`. - Быстрый запуск: `DOCS/START_HERE.md` и `DOCS/QUICKSTART.md`. - Production-path диагностика: `DOCS/DIAGNOSTICS.md`. ## Применимые skills и роль - Проектные знания: `$monitorsoft-project-knowledge`. - Корпоративные требования: `$monitorsoft-corporate-development-context`. - Поставка, DRS и runtime evidence: `$monitorsoft-service-deployment`, `$monitorsoft-dry-stack-dsl`, `$monitorsoft-insight-stack-debug`, `$monitorsoft-drs-insight-diff`, `$monitorsoft-gitlab-deploy-correlator`. - Browser и NATS evidence: `$monitorsoft-gis-browser-access`, `$monitorsoft-nats-flow-trace`. - После явного запроса пользователя на сабагента для read-only диагностики используй проектную роль `monitorsoft_chat_agent_flow_debugger`. ## Инварианты и безопасность - Сохраняй пользовательские dirty/untracked изменения; не выполняй reset, checkout или cleanup чужой работы. - Изменение NATS subject или payload является межсервисным контрактом: проверяй producer, consumer, документацию и совместимость вместе. - При смене workflow runtime согласуй Compose profile с `NATS_WORKFLOW_RUN_SUBJECT` и `NATS_WORKFLOW_HEALTH_SUBJECT`; скрытого fallback нет. - Debug Compose запускай detached: завершение attached-процесса останавливает containers и IDE attach sessions. - Credentials используй только через logical IDs `monitorsoft/dev/gitlab`, `monitorsoft/dev/insight` и `monitorsoft/dev/nats`; значения не записывай в Git, вывод или документацию. - Push, pipeline, deployment, restart и изменение общего runtime выполняй только когда они прямо входят в задачу. Разделяй source, pipeline/image, stack/ingress и named live behavior как разные уровни доказательств. ## Production ownership - Chat: `chat-agent` → `https://chat-agent.gis-master.ru/`; Frontend/Core/Agent/LLM/workflows, Postgres и общий NATS. - Voice: `py_faster_whisper` → `https://voice.gis-master.ru/`; единственный live ASR bridge, пять file UI, diagnostics, lock, пять H100 requesters и три CPU sidecars. - Все внешние HTTP/API/WS проходят OAuth2. NATS UI/pgweb/Postgres остаются внутренними. Старые application hosts отключены. - Subjects Core/bridge: `webrtc.komaroff.asr.stream.*` / `webrtc.komaroff.asr.text.*`; остальные file UI имеют `STREAM_BRIDGE_ENABLED=0`. Прежний ASR mode сохраняется. - Общая сеть `web-rtc-komaroff_default`, H100/Ollama/TURN не переносятся. Сохраняй Postgres volume и физический `whisper_bench_jobs` на `gis-master.ru`. - Перед переключением дождись освобождения voice file lock и нулевых активных jobs. Порядок C3: все новые images → проверка точного состава/mounts/сети/rollback images → drain и свежие idle gauges/file lock → retirement точных 15 старых services → новый backend с Frontend=0 → проверка базы/admission → Frontend=1. Обязательные PG backup/restore, перенос старой истории и сравнение прежних строк отменены владельцем 06.10.2026; схему можно менять. Voice не поставляется повторно. Не повторяй исторический deploy с `--prune`. - Подробный runbook: `DOCS/DEPLOYMENT.md`. Source, CI/image, config/runtime и реальные сценарии проверяй отдельно. ## OpenWiki This repository has a generated `openwiki/` evidence index. It is optional just-in-time context, not required startup reading. - Treat source code and tests as authoritative. A brief's unknowns and review items are verification gaps, not automatic requirements. - Prefer the narrowest quiet validation that proves the changed behavior. Preserve complete failure output. The scheduled OpenWiki GitHub Actions workflow refreshes the repository wiki. Do not hand-edit generated OpenWiki pages unless explicitly asked; prefer updating source code/docs and letting OpenWiki regenerate. ## Проверенное production-состояние [Приёмка C3 · 06.10.2026](): namespace `chat-agent`, 13 сервисов, CI/deploy 4930 e9122e0, 33/33 хода и 5/5 WSS; неизменённый voice — file/stages/ семь model-конфигураций и сохранённые 55 benchmark-записей. Live ASR — streaming, active workflow — ruby_node. Все текущие revisions проверяй отдельно: выборочная сборка допускает разные SHA приложений. После миграции не повторять retirement для обычного обновления одного образа. C0/C1/C2 и снимок 04.10 — история. При приёмке busy file upload проверяй ordinary и staged UI: обе должны быстро получить HTTP 409; после освобождения lock повторная загрузка получает 202 и DONE. Перед отказом сервер дочитывает multipart body, чтобы ingress не оставлял запрос на 100%. HTTP-регрессии — `tests/test_webui_upload_lock.py` в voice repository. Для browser-проверки WebRTC используй отдельную тестовую сессию и дождись connected ICE/DTLS перед речью. Синтетический источник должен продолжать отправку silent PCM после WAV; остановка пакетов не является паузой и закономерно вызывает stream_disconnected. Проверяй partial → final и ответ ассистента по совпадающим session/stream ID. Во время ответа agent_busy отклоняет новую речь. После теста выключи голос и восстанови getUserMedia/RTCPeerConnection; не запускай direct workflow probes одновременно с голосовым тестом. ## WebRTC Trickle ICE [Сигнализация](): двусторонний Trickle ICE opt-in, один audio media, точные aiortc 1.14.0 / aioice 0.10.2. Внутренние API изолированы в `src_webrtc_ingress/ice/trickle.py`; legacy peer неизменён. Сохраняй DATA indication и STUN cleanup. Capability 404 — единственный legacy fallback. HTTP/WS защищены OAuth и токеном подключения (только память, не URL/логи). Сигнализация 10 с, media 20 с после answer, WS auth 3 с; предел 128 кандидатов / 16 КиБ. Потеря ICE WS после connected предупреждает без разрыва media. Проверять реальные DTLS/RTP/PCM до завершения STUN на обеих сторонах и late/cleanup tests, затем пять Chrome connects, speech partial/final/assistant и историю. Поставка через exact SHA CI, backend ingress/Core → Frontend/Ruby с проверкой OCI/digest; ASR payload и соседние владельцы не меняются. Приёмка 05.10.2026: [отчёт](), Core a925c28 / Frontend 95595f2, CI 4899/4900; пять подключений, медиана 1245 мс, реальный TURN/DTLS/RTP и speech partial/final/assistant. TCP host-кандидаты Chrome пропускаются без отмены UDP-пар. Сохраняй STUN/TURN; полное отключение клиентского STUN не подтверждено как рабочая конфигурация. Снимок не заменяет свежую проверку при следующем rollout. ## Переработанный тракт Core — единственный admission/ASR owner; WebRTC и WSS — отдельные ingress с общим FIFO. Production runtime только Ruby + AsyncGraph; альтернативы source/local. Deadline/queues/cancel/streaming/session filters описаны в DOCS/CHAT_AGENT_EXECUTION.md. Данные, rename, exact image checks и совместимый откат — DOCS/DEPLOYMENT.md. Физические legacy имена network/volumes/voice aliases/subjects сохраняются; Git remote не переименовывается. Датированные C0/C1/C2 — evidence, не текущая health.