Эксплуатация харнеса

Как правильно развернуть, настроить и эксплуатировать Temporality как рабочий харнес — стек, обновления, провайдеры, аутентификация, знания, навыки, песочницы, наблюдаемость, бэкапы и диагностика.

Это руководство — для того, кто отвечает за работающий стенд: развёртывание, обновление, настройка провайдеров и доступа, наблюдаемость и разбор типовых проблем. Повседневная работа пользователя разобрана в соседних разделах, точные значения переменных — в Справочнике.

#1. Стек: что где крутится и где живёт состояние

Compose поднимает семь сервисов:

Где живёт состояние — важно для бэкапов и миграций:

• Postgres — источник истины. События наблюдения (observation_events), знания и их историю, пользователей/сессии/ IdP-конфиг, секреты (зашифрованы KERNEL_SECRET_MASTER_KEY), ревью артефактов, квоты. Пишет kernel (через outbox → journal), читают все.
• KERNEL_SANDBOX_ROOT — персистентные воркспейсы песочниц (файлы, которые агент правит между ранами). По умолчанию в compose — /srv/temporality/sandbox.
• Temporal — состояние активных воркфлоу. Завершённые раны живут в Postgres как события; Temporal нужен, чтобы продолжить незавершённые.

Ничего важного не живёт в контейнерах: их можно пересоздавать.

#2. Развёртывание и обновление

#Перенос скиллов и агентов между стендами

Набор поведенческих конфигураций переносится одним JSON-файлом во внутреннем формате temporality.transfer/v1:

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://stand-a.example/kernel-api/v1/workspace/export?type=all" -o transfer.json
curl -H "Authorization: Bearer $ADMIN_TOKEN" -F [email protected] \
  "https://stand-b.example/kernel-api/v1/workspace/import?mode=merge"

• type=skills|agents|all, ids=ci-fix,dev-1 — выборочное экспортирование.
• Импорт создаёт отсутствующее и никогда не перетирает молча: у скилла с изменениями новая версия ложится черновиком (применяет человек), агент при mode=merge (по умолчанию) пропускается, с mode=overwrite — обновляется.
• Ответ содержит постатейный отчёт (created/updated/skipped/errors). То же самое — кнопками «Экспорт…/Импорт…» на страницах Навыков и Агентов.
• Внутри переносятся: манифест, тело, версии с провенансом (у скиллов); модель, промпты, определение, инструменты, имена секретов, песочница (у агентов). Стендозависимое — привязка к оргединице, ID провайдера — сохраняется как есть: на целевом стенде проверьте, что провайдер и секреты с теми же именами существуют.

Обновление стенда до последнего релиза:

docker compose pull && docker compose up -d

Для контролируемого обновления (или отката) версия закрепляется явно:

TEMPORALITY_VERSION=2026.2.113 docker compose up -d

Порядок обновления стенда:

1. Прочитай заметки релиза (аннотация тега) — миграции и ломающие изменения пишутся туда.
2. docker compose pull journal debugger agent-kernel
3. docker compose up -d — миграции Postgres применяются автоматически при старте kernel (migrations/workspace, миграции квот); журнал миграций — идемпотентный.
4. Проверь здоровье: docker compose ps (все healthy), дашборд /dashboard, один тестовый ран.

Откат — подними предыдущий закреплённый TEMPORALITY_VERSION. Миграции схемы не откатываются: перед крупными обновлениями делай дамп (§11). Локальная сборка из исходников вместо GHCR:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build agent-kernel debugger

(docker-compose.dev.yml переключает образы на build из репозитория; перебивает только указанные сервисы.) Признак частого сбоя: при первой сборке двух целей одновременно buildx иногда спотыкается о блокировку кэша — повторная сборка проходит.

#3. Провайдеры и модели

Минимум для работы — три переменные провайдера по умолчанию:

TEMPORALITY_MODEL_BASE_URL=https://api.provider.com/v1
TEMPORALITY_MODEL_ID=mimo-v2.6-flash
TEMPORALITY_MODEL_API_KEY=...

Полная настройка — на странице /providers: несколько провайдеров, каталоги моделей, назначение моделей по ролям.

#Роли моделей и куда какая попадает

• chat — основная модель агентов (диалог, инструменты, план).
• embedding — семантический слой знаний (§6).
• asr — расшифровка аудио; в ролях чата участвовать не должна.

Каталог моделей синхронизируется с провайдером по расписанию (KERNEL_PROVIDER_MODELS_REFRESH, по умолчанию 24h, 0 — выключить цикл) плюс ручной refresh и probe-проверка в UI.

Судья (judge) — отдельная chat-модель для оценок. Она используется шире, чем кажется: контур качества, нормализация областей знаний, супервайзерские проходы и кейсы, вердикт worth_skill при майнинге навыков, выбор модели в мастерах-черновиках (агент/навык/команда): env-модель → judge-модель → первый chat-кандидат каталога. Не-chat записи каталога (ASR, embedding, image) из кандидатов отфильтрованы — если мастер «взял первую попавшуюся ASR-модель», обнови каталог и назначь роли явно.

#Стрим и таймауты

Буферизующие гейтвеи (отдают весь ответ одним чанком) — не поломка. В трейсе это видно как вердикт «провайдер не стримит (один чанк)» на длинных вызовах; ретраи стрима — по лестнице с нарастающим интервалом («↻ повтор стрима после N с»). Диагностика «Ожидание подключения», которая долго не сменяется токенами, означает проблему SSE-транспорта до провайдера, а не выбор модели. Зависший вызов можно толкнуть вручную — кнопка ↻ на живой строке вызова модели отменяет запрос и перезапускает ход.

#4. Аутентификация и доступ

Четыре режима, от простого к корпоративному:

1. Без аутентификации — KERNEL_AUTH_TOKENS пуст. Только для локальных экспериментов.
2. Bearer-токены — KERNEL_AUTH_TOKENS=token:user:role:projects,.... Для сервисных агентов и скриптов.
3. Пароль + сессии — основной режим UI. Вход password-first, форма «Пароль | API-токен». Сессии: KERNEL_SESSION_TTL (скользящая, 12h), KERNEL_SESSION_ABSOLUTE_TTL (7d); KERNEL_COOKIE_SECURE=true за HTTPS.
4. OIDC SSO — федерация (Keycloak/Entra/Authentik), JIT-провижининг, маппинги групп на роли, роль deny = «вход успешен, доступ запрещён» до ручного решения. Конфиг — /users (admin-only), каждое изменение пишет аудит-событие.

Self-service: пользователь меняет свой пароль через меню аккаунта (POST /v1/auth/password). Аккаунт с паролем подтверждает текущий; SSO-аккаунт без локального пароля задаёт первый с пустым полем current — минимум 8 символов, bearer-токен переживает смену. Break-glass: при включённом SSO парольный вход остаётся только у admin (недоступность IdP не блокирует эксплуатацию).

Проектный скоупинг: роль + список проектов в токене, для SSO — маппинги claim'ов; * означает все проекты. Оргструктура (/org) дополнительно ограничивает видимость по подразделениям.

#5. Секреты

• KERNEL_SECRET_MASTER_KEY (openssl rand -hex 32) — ключ шифрования секретов в Postgres. Потеря ключа = потеря всех секретов. Храни вне стенда; ротация — только с перекриптованием.
• Секреты создаются в /secrets, ссылаются из конфигов как secret://…; значение разрешается на границе использования.
• KERNEL_SECRET_CACHE_TTL_SECONDS — сколько разрешённое значение живёт в памяти ядра.
• Выдача секрета рану — событие secret.issued в трейсе (показывается явно, это аудит-факт, не шум).

#6. Знания, подсказки и embeddings

Семантический слой (похожесть знаний, подсказки похожего опыта, предсказание конфликтов, семантический поиск) требует модель embeddings:

KERNEL_EMBEDDINGS_MODEL=intfloat/multilingual-e5-small

Модель грузится ин-процесс (rembed) с Hugging Face. Если она не загрузилась, ядро работает дальше, но с баннером «настроены не все инструменты» и без семантики — ретраи идут с нарастающим интервалом; проверь доступ до huggingface.co. Кэш модели — на диске; при проблемах прав владельца смотри лог (есть fallback на пользователя ОС).

Эксплуатация знаний:

• Жизненный цикл: proposed → confirmed → (challenged/invalidated/superseded). Проверка — ручная или судейская; неподтверждённое в подсказки не попадает.
• Оспорить/инвалидировать можно прямо из трейса рана (⚑ на событии со знанием) и из досье.
• Примаринг: перед ходом агент получает подсказки похожего опыта (hint.query → memory.read); факты использования (hint.used/проигнорировано) видны в knowledge-группе трейса — по ним оценивают пользу опыта.
• Нормализация областей знаний выполняется судьёй; карта областей — /knowledge.

#7. Навыки и артефакты

Навыки — версионируемые процедуры с контрактом. Пути создания: описание в UI, импорт, вручную и майнинг — супервайзер ищет повторяющиеся три-граммы вызовов инструментов между ранами, детерминированный гейт отсекает read-only последовательности, судья выносит вердикт worth_skill с обоснованием; кандидат попадает в очередь и префиллится черновиком на /skills. Версии: черновик 0.x, применение/отклонение редакций — человеком; в списке навыков бейджи draft и «↺ N» — ожидающие черновики-редакции. Не копи неприменённые редакции: просматривай очередь по бейджу.

Артефакты — документы, которые агенты подгружают по требованию. Статусы: draft / in_review / rejected / approved / superseded (жизненный цикл — на уровне версии: правка утверждённого — только новая редакция и повторное согласование). Ревью-цикл: submit (идемпотентен по версии) → уведомление ревьюерам → решение только человеком (само-одобрение запрещено на уровне API) → approved/rejected. Ревьюеры: режим all (все должны) или any (любого достаточно). Квота отправок на ран — ARTIFACT_SUBMIT_PER_DAY. Тела артефактов рендерят markdown с mermaid-диаграммами (типовые ошибки LLM в erDiagram чинятся автоматически).

#8. Агенты, команды и план-DAG

• Агент (/agent-config): модель, системный промпт, инструменты и их подтверждения, песочница. max_turns ограничивает длину рана — для дочерних ранов задаётся из задачи.
• Команда (/teams): конвейер lead → исполнители → QA. Манифест команды фиксирует роли и лимиты.
• План — DAG задач с зависимостями. Ключевые поля задачи: on_failure (continue | stop | abort — что делать с волной при падении задачи), mode: wave (поэтапный запуск готовыми батчами вместо полного DAG-упорядочивания), max_turns. Ревью-задачи работают как ворота: следующий этап не стартует без вердикта.
• Супервайзер — периодический триаж упавших ранов (KERNEL_SUPERVISOR_TRIAGE_INTERVAL, 2m; значение ниже минимального трактуется как дефолт — выключателя нет). Предлагает перезапуски и кейсы; спорные операции ждут reconcile-решения человека в панели рана.

#9. Песочницы, инструменты и лимиты

#Egress-контроль (белые списки адресов)

Песочница с сетью попадает не в общий bridge, а в internal-сеть без маршрута наружу; единственный выход — egress-proxy (squid), чей конфиг ядро генерирует из настроек агентов. Семантика: публичный интернет разрешён (NetworkAccess), приватные диапазоны (LAN, RFC1918, metadata) запрещены по умолчанию, и только явные записи в egress_allowlist агента открывают конкретные внутренние адреса:

egress_allowlist: ["api.github.com", "*.example.com", "gitlab.corp:8443", "10.20.30.0/24"]

Формат: домен, глоб, CIDR, хост:порт. Прокси сам резолвит имена — внутренний DNS работает, а отказ сопровождается понятной ошибкой. Не-HTTP трафик наружу (ssh, произвольные порты) не ходит — для задач агентов это почти всегда не важно, и это фича. Контролируется только HTTP(S): значения секретов всё равно защищены сканером утечки и canary.

Разворачивается автоматически вместе со стеком (сервис egress-proxy + сети temporality-sandbox-internal/temporality-egress-out); без egress-стека песочницы работают по-старому через bridge.

#Прочее

• KERNEL_SANDBOX_ROOT — корень воркспейсов. Дефолт кода ./.sandbox, в compose — /srv/temporality/sandbox. Не ставь /tmp: tmpfs-очистка при ребуте узла уничтожит воркспейсы агентов.
• KERNEL_SANDBOX_IMAGE — образ песочницы; TEMPORALITY_DOCKER_GID — gid группы docker на хосте (сокет). KERNEL_SANDBOX_PIDS, KERNEL_SANDBOX_SCRATCH_SIZE — лимиты контейнера.
• KERNEL_TOOL_MAX_SECONDS (900) — потолок одной команды; KERNEL_BG_TOOL_MAX_SECONDS (3600) — потолок фоновой команды (run_command c background: true); TEMPORALITY_TOOL_ACTIVITY_TIMEOUT (16m) — потолок активности run_tool.
• Веб: KERNEL_SEARXNG_URL (поиск), KERNEL_WEB_SEARCH_PER_MIN/KERNEL_BROWSER_PER_MIN (rate-лимиты), KERNEL_WEB_FETCH_ALLOW_PRIVATE (по умолчанию private-сети запрещены — SSRF-защита; включай осознанно), KERNEL_BROWSER_CDP_URL (lightpanda; пусто = browser off).
• MCP: KERNEL_MCP_COMMAND/_ARGS — внешний MCP-сервер, _ALLOW — разрешённые инструменты, _APPROVAL — требовать подтверждение.
• Квоты запусков: KERNEL_RUN_QUOTAS (project:limit, * — дефолт); превышение = 429. Цены для стоимости: KERNEL_MODEL_PRICES (model:prompt:completion).

#10. Наблюдаемость эксплуатации

• Трейс рана (/agents) — дерево ходов, свежие сверху; ход разворачивается целиком: вызовы инструментов, подтверждения, ответы. Окно — 50 событий, старые догружаются скроллом. Живая строка вызова модели показывает elapsed, токены, скорость и состояние канала; ↻ толкает зависший вызов. У работающего run_command прямо в строке — живой хвост консоли (буфер 2000 строк / 256 КБ, живёт 6h после активности; после очистки — fallback в журнал события ≤1 КБ).
• Дашборд (/dashboard) — health, модели, проекты, качество; /supervisor — очередь триажа; /mcp — состояние MCP-сервера.
• Шина событий: kernel пишет через outbox (kernel_event_outbox) в journal, UI слушает SSE + опрос каждые 10с как страховку. Аутентификация kernel→journal — TEMPORALITY_API_TOKEN (провижинится автоматически).
• Лаги UI обычно = лаг journal stream: смотри рестарты temporality-journal-1 и бэккофф переподключений.

#11. Резервное копирование и восстановление

Минимум — nightly:

docker exec temporality-postgres-1 pg_dump -U temporality temporality | gzip > backup-$(date +%F).sql.gz
tar -C /srv/temporality/sandbox -czf sandbox-$(date +%F).tgz .

Восстановление: поднять пустой стек той же версии → восстановить дамп → вернуть sandbox-корень → поднять kernel. Активные (незавершённые) раны после восстановления продолжаются, только если восстановлена и БД Temporal — в большинстве случаев достаточно принять, что незавершённые раны умрут и их перезапустят. Проверяй восстановление периодически на отдельном стенде — бэкап, который ни разу не восстанавливали, не бэкап.

#12. Диагностика типовых проблем

Практика: сначала трейс (он показывает и транспорт, и вердикты ретраев), потом логи kernel, потом journal. Большинство «зависаний» — транспорт до провайдера, и трейс это прямо называет.

#13. Дисциплина изменений

• Всё, что меняет поведение, выпускается тегом v2026.2.N с аннотацией — читай её перед обновлением.
• Конфиг стенда (.env, compose-оверлеи) держи в системе контроля версий; секреты — только ссылками secret://.
• Схема БД мигрирует только вперёд; между версиями с крупными миграциями делай дамп.
• Аудит-события (входы, выдачи секретов, изменения IdP-конфига) — часть эксплуатации: они ищутся в journal как обычные события.