Архивация спеки

2026-06-28 12:27:50 +03:00
parent d8ef7063f4
commit 694a9f4bef
7 changed files with 101 additions and 12 deletions
@@ -0,0 +1,62 @@
+## Why
+
+При добавлении magnet-загрузки jellybit не передаёт в qBittorrent
+человекочитаемое имя, поэтому в списке qBit задачи выглядят безлико:
+`rutracker-topic-6514485`. Контекст загрузки (заголовок релиза от
+торрент-бота) у нас уже есть — из него можно собрать аккуратное имя
+(«Дюна: Часть вторая (2024)») и сразу класть его в qBittorrent. Небольшая
+доработка с заметной отдачей в повседневной эксплуатации.
+
+Это также первая capability, переносимая из `docs/specs` в OpenSpec
+(пилот формата): change засевает capability `ingest` дельтой `ADDED`.
+
+## What Changes
+
+- `ingest` выводит из контекста загрузки **отображаемое имя** и передаёт
+  его в qBittorrent при добавлении.
+- Имя строится LLM: из контекста извлекаются название, год, режиссёр и (для
+  сериала) номер сезона; название — на русском для российского контента,
+  иначе на английском. Результат — короткая читаемая строка, а не кусок
+  сырого контекста.
+- LLM даётся до **трёх попыток**; при неудаче — **алгоритмический фолбек**
+  (первая содержательная строка контекста, очистка и обрезка по длине) без
+  сетевых запросов.
+- Если ни LLM, ни фолбек не дали имени (контекст пуст/бесполезен) —
+  отображаемое имя не передаётся: qBittorrent оставляет своё (`dn`/имя из
+  торрента). Поведение при отсутствии контекста не меняется.
+- `qbt.AddRequest` получает поле для отображаемого имени, пробрасываемое в
+  параметр `rename` API `/torrents/add`.
+
+Не входит в объём (Non-goals):
+
+- Переименование уже добавленных в qBittorrent задач.
+- Изменение логики распознавания (`recognize`) и раскладки — отображаемое
+  имя нужно лишь для списка qBit и не влияет на пути на диске (jellybit
+  по-прежнему читает реальные пути из qBit API).
+- Источники кроме magnet (`.torrent`/url) — отдельная задача.
+
+## Capabilities
+
+### New Capabilities
+- `ingest`: приём загрузки (источник + контекст) — дедупликация по
+  infohash, заведение задачи и передача источника в qBittorrent. В рамках
+  этого change добавляется требование о выводе и передаче отображаемого
+  имени. Базовое поведение приёма фиксируется как контекст существующего
+  кода.
+
+### Modified Capabilities
+<!-- OpenSpec-спеки пусты; существующих capability нет. -->
+
+## Impact
+
+- **Код:** `internal/ingest` (вывод имени, новая зависимость на LLM-провайдер
+  и алгоритмический фолбек), `internal/qbt` (поле `Rename` в `AddRequest`,
+  form-field `rename`). Возможен небольшой хелпер вывода имени (в `ingest`
+  или соседнем пакете).
+- **Конфиг:** возможен бюджет попыток LLM (переиспользовать существующий
+  `llm.max_retries` либо отдельный параметр) — уточняется в design.
+- **Внешние системы:** дополнительный вызов LLM на каждую новую загрузку
+  (расход токенов); деградирует штатно — при недоступности LLM работает
+  алгоритмический фолбек.
+- **Инварианты:** не затрагиваются. Имя влияет только на отображение в
+  qBittorrent; пути на диске берутся из qBit API, источник не трогаем.