lampac/AGENT.md

AGENT.md — инструкции для ИИ-агентов

Работа с проектом: локальный Docker-развёртывание Lampac NextGen. Человек читает ответы только на русском.

Источники правды (порядок приоритета)

1. Официальная документация — docs.lampac.dev (полный текст страниц: https://docs.lampac.dev/llms-full.txt, индекс: llms.txt). Не гадать по памяти — проверять в доках.
2. Живой контейнер — состояние модулей, манифестов и конфигов брать из контейнера:

   docker exec lampac sh -c 'cat /lampac/module/<Имя>/manifest.json'
   docker exec lampac cat /lampac/current.conf   # merged-конфиг: base + init
   

3. Логи контейнера — docker logs lampac.
4. Локальные файлы проекта: docker-compose.yaml, config/init.conf, mods/.

Ключевые правила

1. Никогда не правь файлы внутри контейнера/образа

Файлы в /lampac/module/ (и любые другие в образе) сгорают при обновлении (docker compose pull && up -d). Включение встроенного модуля делается только пользовательской копией:

docker cp lampac:/lampac/module/<Имя> "mods/<Имя>"
# в mods/<Имя>/manifest.json -> "enable": true
# в docker-compose.yaml -> "- ./mods/<Имя>:/lampac/mods/<Имя>"
# docker compose up -d

См. также официальные шаги: Включить модуль, Пользовательские модули.

2. Механика загрузки модуля (4 независимых фильтра)

Модуль грузится, только если выполнены все:

Фильтр	Где
"enable": true	manifest.json модуля (копия в mods/ для встроенных)
Имя не в BaseModule.SkipModules	base.conf (в образе) + config/init.conf
Имя попадает в BaseModule.LoadModules	если allowlist задан (у нас не задан — грузится всё остальное)
Runtime-флаг	секция модуля в config/init.conf, например "gst": { "enable": true }

SkipModules имеет приоритет над LoadModules — модуль из обоих списков не грузится. Паттерны: точное имя, группа (OnlineUKR), regex (LME.*), .*.

3. config/init.conf — валидный JSON

JSON без trailing comma. Перед применением правок проверять:

python3 -m json.tool config/init.conf > /dev/null && echo OK

После правки конфига: docker compose restart (том смонтирован, up -d не нужен). После правки manifest.json в mods/ с dynamic: true — тоже restart (или ждать hot-rebuild). После изменения томов в compose — docker compose up -d.

4. Клиентские плагины Lampa

• Встроенные плагины: флаги LampaWeb.initPlugins (tracks, dlna, catalog, sync, backup, ...).
• Дополнительные: LampaWeb.customPlugins — записи со status: 1 добавляются как есть; поддерживается плейсхолдер {localhost} (подставляется реальный адрес сервера).
• Если плагин «не виден» в веб-клиенте — сначала проверить HTTP-статус его URL на сервере (curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:9118/<плагин>.js), а не лезть в клиент.

4.1 Каталог плагинов (store) /extensions

• Раздел «Плагины» веб-клиента грузит каталог с /extensions (при LampaWeb.initPlugins.pirate_store: true).
• Источник: /lampac/module/LampaWeb/plugins/extensions.json — переопределён mount из ./plugins/extensions.json. Править хост-файл, в контейнер не залезать.
• {localhost} в ссылках store сервер заменяет своим адресом при выдаче.
• Статика: /lampac/plugins/ не раздаётся (проверено: файл → 404), корень wwwroot — раздаётся. Все плагины каталога — локальный mirror в ./plugins/, смонтирован одним directory-mount в /lampac/wwwroot/plugins/ → ссылки store {localhost}/plugins/<имя>.js. Не монтировать каталог целиком в корень wwwroot — скроется веб-клиент lampa-main.
• Обновление плагина: исходный URL — в plugins/sources.json; скачать, перезаписать файл, перезапуск не нужен (статика).
• При проверке скачанного плагина отличать: (а) реальный код, (б) лоадер putScriptAsync (абсолютные URL — безопасен локально; host от currentScript — требуется патч, см. showy.js), (в) пустой stub/placeholder (мёртвый плагин, из каталога удалять).
• Кеш-ловушка: ответ /extensions (и других LampaWeb-маршрутов) кешируется на диск в cache/static/<bucket>/<id>.json; кеш переживает docker compose restart. После правки store: rm -rf cache/static/59 (bucket /extensions), перезапуск не нужен. Заголовок X-StatiCache-Status: HIT/MISS показывает состояние.

5. AdminPanel API из скриптов (root-авторизация)

• Root-пароль = содержимое config/passwd. Механизм: cookie accspasswd=<пароль> (таков штатный сценарий: страница входа auth.html сама кладёт пароль в эту cookie). Заголовок lcrqpasswd — для внутренних вызовов, на /adminpanel/api/* с ним уходит 302 на /adminpanel/auth.
• Не передавать root-пароль в query string (предупреждение доков).
• Сервер может отвечать 404 вместо 401/403, чтобы не раскрывать админский endpoint.
• Основные маршруты: GET /adminpanel/api/init (чтение), POST /adminpanel/api/init (полная запись), POST /adminpanel/api/init/section/{key} (секция), GET /adminpanel/api/current (merged-конфиг), GET /adminpanel/api/users-json.
• Правка секций через API пишется в init.conf — watcher подхватит без рестарта (runtime-параметры). customPlugins — runtime-параметр: плагин появляется в /lampainit.js через ~1 с.

6. Диагностика «модуль не найден»

Чек-лист (в этом порядке):

1. curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:9118/<маршрут> — 404 подтверждает, что модуль не загружен.
2. docker logs lampac | grep -E "compilation|loaded module" | grep <Имя> — скомпилирован ли и загружен ли.
3. Манифест: enable: true? (в mods/ для встроенных)
4. Фильтры SkipModules/LoadModules в config/init.conf.
5. Runtime-секция модуля в config/init.conf.
6. В логе после старта ожидаются строки compilation <Имя>, configure module: <Имя> (если есть конфиг-секция), loaded module: <Имя>.

7. Команды эксплуатации

docker compose up -d            # запуск / пересоздание (при изменении compose)
docker compose restart          # после правки init.conf / mods
docker compose logs -f          # логи
docker compose pull && docker compose up -d   # обновление (сначала поменять тег в compose)
docker exec lampac sh -c '...'  # осмотр состояния в контейнере

container_name: lampac — контейнер один; одновременный запуск нескольких compose-файлов с одним именем невозможен. docker-compose.override.yml (gitignore) живёт только на сервере Proxmox и не коммитится.

8. Чего не трогать

• config/passwd, cache/, database/, dlna/ — в .gitignore, не коммитить и не «чинить» содержимое. Исключение: cache/static/ — одноразовый диск-кеш ответов LampaWeb; очистка (rm -rf cache/static/<bucket>) — штатное действие после правки store/статических маршрутов (см. 4.1).
• Тег образа в docker-compose.yaml закреплён точным digest (1.68.0@sha256:752dafd8…): тег 1.68.0 на ghcr mutable, его переиздавали, и новая сборка ломает Roslyn-компиляцию наших копий mods/ (пример: Music → CS0103 MusicMetadataCacheService, crash-loop). Обновление образа = новый digest + пересборка копий mods/ из нового образа. Не делать «просто» docker compose pull без фиксации digest.
• LampaWeb.autoupdate — веб-клиент Lampa сам обновляется из git (yumata/lampa), wwwroot/lampa-main в контейнере перезаписывается — туда не править.

9. После изменений в проекте

Обновлять README.md и AGENT.md в той же ревизии: структура, включённые модули, секции конфига, новые правила.

10. Безопасность (не публиковать)

config/passwd, cookie accspasswd, заголовок lcrqpasswd, bot_token в TelegramBot. Маршруты /adminpanel, /weblog, Tracks, Catalog, DLNA, proxy-модули — только для доверенной сети без WAF не открывать.

11. Tg-notify.bot (Telegram-бот)

• Механика: long polling по TelegramBot.bot_token; если токен пуст — polling не стартует (в логе [TelegramBot] Установите bot_token…, сервер работает). После правки секции: docker compose restart lampac.
• Три подсистемы: трекер серий (Trakt→TMDB), трекер озвучек (параллельно Mirage/Collaps/VideoHub через lampac_host: /lite/mirage, /lite/collaps, /lite/cdnvideohub), клиентский плагин tg-notify.js (вкладка «TG Подписки», перехват 🔔). Полный разбор — в README.md.
• Данные подписок: database/tgnotify/{users.json,subscriptions.json} (том ./database/, в .gitignore). Не «чинить» вручную — это живые данные бота.
• Диагностика: GET /tg-notify.js (200 без авторизации), GET /api/tg/voices (200), /api/tg/* остальной — требует user_uid. Озвучки могут не работать, если балансеры недоступны (проверить GET /lite/mirage — тело disable/ошибка, /lite/collaps — 503); тогда уведомления приходят только о выходе серий.
• kp_api_key опционален: без него VideoHub резолвит kinopoisk_id только через мост /externalids (покрытие ~40%), иначе — молча пропускается, Mirage/Collaps работают.

12. TelegramAuth / TelegramAuthBot (вход через Telegram)

• Не путать с Tg-notify.bot (уведомления): эта пара — аутентификация (вход в Lampa через Telegram вместо пароля), группа Community, в образе выключена (SkipModules + enable: false).
• Гейт (LampaWeb.telegramAuthGate) активен только при accsdb.enable: true + telegramAuthGate.enabled: true + непустом botUsername, иначе тихий откат на deny.js. У нас accsdb не включён — связка неактуальна, включать только вместе с accsdb.
• mutations_api_secret одинаковый в обоих модулях, ненулевой в проде; bot_token — в init.conf, не коммитить (см. правило 10).