Назначение и границы
Долгая агентная обработка не должна терять задание после разрыва соединения или повторно применять уже готовый результат.
Наблюдаемый событийный контур: постановка задания, настоящая очередь, обработка, результат и повтор. Внешний трекер и агент заменены безопасными моками.
- YouTrack, MCP и агент — явные моки. Публичного запуска shell/Codex и отправки комментариев нет.
- Искусственная задержка 700 мс показывает этапы; это не измерение скорости настоящего агента.
- Два контейнера по 128 MiB. 20 заданий на сессию, 1000 всего; stream до 8 MiB / 1000 сообщений / одного часа.
Архитектура и схемы
- Используется исходный модуль jetstream.js и общий dryAnalysis, вынесенный без изменения алгоритма.
- Учебный отказ выполняет NAK; повтор доставляется реальным JetStream через 2,5 секунды.
- Worker проверяет completed, а gateway применяет результат один раз.
- SQLite WAL хранит сессионную историю; события добавляются атомарным SQL, чтобы параллельные обновления не терялись.
Code-map: от функции к коду
Карта привязана к версии 2a7c7e856505. Она помогает проследить изменение через интерфейс, API, модуль, данные и проверку.
| Функция | Экран / API | Модуль | Данные / проверка |
|---|---|---|---|
| Учебный webhook | POST api/jobs | portfolio-gateway, portfolio-store.create | фиксированный corpus, SQLite jobs; quota test |
| Очередь | схема / api/state | jetstream.openJetStream | NATS stream + consumers; production QA |
| Анализ | timeline | portfolio-worker, dry-analysis | исходный dry-run formatter; missing context test |
| Повтор | POST api/jobs/id/replay | worker completed guard | тот же ID, duplicate_ignored; production QA |
| Изоляция / сброс | GET state / DELETE jobs | portfolio-store.owned | owner SHA-256, TTL; isolation + expiry tests |
Как работать с картой
- Перед изменением найти функцию и пройти связи до API, состояния и хранилища.
- Проверить входы, ошибки, повторные события и зависимые сценарии.
- После изменения обновить карту и затронутые схемы вместе с кодом.
- Выполнить связанные проверки и привязать новые материалы к версии исходников.
Сценарии и API
- Выберите учебное задание и проследите timeline обработки.
- Повторите завершённое задание: появится duplicate_ignored без второй выдачи результата.
- Запустите прерывание до ACK и дождитесь повторной доставки.
- Откройте пример нехватки контекста, проверьте отдельную сессию и сброс.
Проверка опубликованной версии
- Три unit-теста: исходный dryAnalysis, ownership/TTL/quota и атомарная запись событий. Реальный restart worker подтверждён production QA.
- Real JetStream jobs/results; duplicate_ignored and exactly one result application
- Signed cookie; cross-session read/replay/reset isolation
- {"scenario": "Actual worker container restart with pending delivery", "restartAt": "2026-09-07T00:01:22.460Z", "jobId": "09a53fd9-c9b4-4aa7-9d54-8a0c58fc2972", "completedAt": "2026-09-07T00:01:26.504Z"}
- Arbitrary command fields rejected; no shell endpoint
- Подтверждённого GitHub CI для этого SHA нет; перечислены выполненные локальные проверки и сценарии опубликованной версии. Исторические CI-ссылки, если есть, отмечены отдельно.
Результаты описывают проверенные сценарии и конкретную версию. Они не являются оценкой коммерческого успеха или качества моделей на независимой выборке.
Измерения
- Сохранено 13 содержательных кадров фактического интерфейса.
- Дата, сценарий и версия указаны у каждого кадра.
- Максимум RAM контейнеров в коротком тесте: 59.63 MiB. Общие службы учитываются отдельно; магазин включает свою БД.
- Измерено 6 повторений сценария; медиана 1712.5 мс, максимум 2953 мс. Время включает браузер и HTTPS; методика и ограничения приложены.
Запуск и эксплуатация
Исходный контур предполагал YouTrack webhook, Codex worker, MCP и комментарий в трекере. Публичный образ не содержит этих исполняющих интеграций; схема демо показана отдельно.
Сборка Dockerfile.portfolio выполняется вне VPS. Два контейнера разделяют SQLite volume и отдельную учётную запись NATS AGENTS. API доступен только через localhost:18405/Nginx.
Readiness API проверяет NATS, worker — свежий heartbeat. Реальный docker restart worker выполнен в эксплуатационной проверке во время незавершённого задания: после старта оно завершилось, результат применился один раз. Публичной кнопки остановки процесса нет.
Общие правила эксплуатации: готовые файлы и закреплённые образы собираются вне VPS; секреты не входят в артефакты. Общесерверный docker prune не применяется. Логи backend ограничены ротацией, изменения log options требуют пересоздания контейнера.
Перед изменением пройти code-map от функции к экрану/API, модулю и данным. После изменения обновить карту и схемы, выполнить связанные сценарии, включая ошибку, повтор и сброс. Источник истины — конкретная версия кода, а не старая диаграмма.
Откат проверен 2026-09-07T01:06:02.122021+00:00: 20260907-verified → 20260907 → 20260907-verified. После каждого переключения подтверждены HTTPS, readiness и SHA. Это проверка конфигурации и артефактов на одном проверенном SHA; обратная миграция БД не выполнялась.
Стек
| Node.js 24 | HTTP gateway, безопасный worker и исходный dry-run formatter. |
|---|---|
| NATS JetStream | Настоящие subjects jobs/results, durable consumers и ACK/NAK. |
| SQLite WAL | Общая API/worker история, ownership и атомарные append. |
Материалы и исходники
История репозитория: с 22 мая 2026. Публичный безопасный контур: 7 сентября 2026.