diff --git a/docs/adr/ADR-2026-06-13-auto-link-requires-db-match.md b/docs/adr/ADR-2026-06-13-auto-link-requires-db-match.md new file mode 100644 index 0000000..b46f13a --- /dev/null +++ b/docs/adr/ADR-2026-06-13-auto-link-requires-db-match.md @@ -0,0 +1,69 @@ +# Авто-раскладка только при подтверждённом матче в метабазе + +- Дата: 2026-06-13 + +## Контекст + +jellybit распознаёт содержимое релиза через LLM по **недоверенным** +сигналам: имя торрента, текстовый контекст человека, распарсенное +сообщение бота — всё управляется извне и может содержать инъекции. По +результату распознавания нужно решить: разложить файлы хардлинками +автоматически или отправить на ревью человеку. Цена ошибки авто-раскладки +реальна — мусор в библиотеке Jellyfin под неверным названием/папкой, +возможно поверх чужого. Хочется максимум авто, но не ценой тихих ошибок. + +Силы и ограничения: + +- LLM хорошо разбирает русские и релиз-имена, но галлюцинирует, а его + самооценка (`confidence`) плохо откалибрована и тривиально поддаётся + инъекции из тех же недоверенных сигналов. +- Внешние базы (TMDB/TVDB/TVMaze) дают **независимый** авторитетный сигнал: + каноническое имя + `provider_id`. Но русские релизы и аниме часто в них + отсутствуют. +- Безопасность раскладки уже держится на валидации пути, не на промпте + (см. [recognition.md](../specs/recognition.md)); решение «авто vs review» — + второй слой защиты, на уровне доверия результату. + +## Рассмотренные варианты + +- **Гейт по самооценке LLM (`confidence ≥ порог`).** Просто и даёт + максимум авто. Но `confidence` не откалибрована и инъектируема — + «уверенный» неверный ответ прошёл бы молча. Небезопасно. +- **LLM + структурная валидация, без обязательной базы.** Ловит часть + ошибок (число файлов у фильма, дыры/дубли в нумерации S·E), но не ловит + «правильную структуру под неверным названием». Недостаточно как + единственный гейт авто. +- **Авто только при подтверждённом матче в базе + валидация + + согласованность сигналов.** Независимый авторитет снимает риск «LLM + придумал». Цена — рус/аниме (нет в базах) всегда идут в review, но это и + так нужный кейс. + +## Решение + +Авто-раскладку делаем, только если выполнено **всё**: (1) единственный +сильный матч в метабазе по названию+году, давший `provider_id`; +(2) структурная валидация без предупреждений; (3) пред-парс (`go-ptn`) и +LLM не противоречат по типу/названию/году. Нет матча или база выключена → +**всегда review**. Самооценку LLM учитываем лишь как вспомогательный +сигнал, не как гейт. + +Почему так: безопасность держится на **независимой** проверке (база), а не +на доверии к выходу LLM, построенному из недоверенных данных. Это разом +закрывает основной кейс (рус/аниме отсутствуют в базах → человек +подтверждает) и убирает целый класс тихих ошибок «модель уверенно +ошиблась». Review здесь — не наказание, а штатный режим для всего, что +база не подтвердила (петля «догадка → подсказка → перераспознавание», см. +[review-ux.md](../specs/review-ux.md)). Полная модель уверенности — в +[recognition.md](../specs/recognition.md). + +## Последствия + +- `+` Нет тихих авто-ошибок раскладки: всё неподтверждённое видит человек. +- `+` `provider_id` из базы заодно даёт каноническое имя папки + (`[tmdbid-…]`) — Jellyfin не путает русские названия. +- `−` Рус/аниме и всё, чего нет в базах, всегда требует ручного + подтверждения — авто там недоступно by design. +- `−` Без включённых TMDB/TVDB/TVMaze авто-раскладки нет вовсе: сервис + работает в режиме «распознал → review». +- Делает цикл ревью критичным: если он неудобен, ручное подтверждение + станет узким местом — поэтому review-ux вынесен в отдельную спеку. diff --git a/docs/adr/README.md b/docs/adr/README.md index 0b39f76..53fdc7a 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -56,6 +56,7 @@ | Дата | Запись | Статус | | ---------- | ---------------------------------------------------------------- | ------ | +| 2026-06-13 | [Авто-раскладка только при матче в метабазе](ADR-2026-06-13-auto-link-requires-db-match.md) | — | | 2026-06-13 | [Docker как единица деплоя](ADR-2026-06-13-docker-deploy.md) | — | | 2026-06-13 | [Хардлинки вместо копирования и симлинков](ADR-2026-06-13-hardlinks.md) | — | | 2026-06-13 | [Go и доставка одним бинарём](ADR-2026-06-13-go-single-binary.md) | — | diff --git a/docs/specs/recognition.md b/docs/specs/recognition.md index 5b8999b..00825b8 100644 --- a/docs/specs/recognition.md +++ b/docs/specs/recognition.md @@ -82,6 +82,9 @@ notes пояснения, неоднозначности ## Модель уверенности +Почему авто только при матче в базе, а не по самооценке LLM — +[ADR-2026-06-13-auto-link-requires-db-match](../adr/ADR-2026-06-13-auto-link-requires-db-match.md). + Авто-раскладка — только если выполнено **всё**: 1. **Подтверждённый матч в базе** — единственный сильный результат