Инструкции проекта 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.