Встановлення й запуск

Вимоги

Інсталятор

Інсталятор для Windows з’явиться згодом (#30). До того застосунок встановлюється з вихідного коду за кроками нижче.

До чат-клієнтів (Claude Desktop, Claude Code) Obscura підключається кнопкою «Підключити до Claude» у бібліотеці; подробиці — у розділі Чат-клієнти (MCP).

Встановлення з вихідного коду

Завантажте репозиторій obscura-text-writer і відкрийте PowerShell у його теці:

python -m venv .venv
./.venv/Scripts/python.exe -m pip install -r requirements-lock.txt
./.venv/Scripts/python.exe -m pip install --no-deps -e ".[web,publication]"
if (-not (Test-Path .env)) { Copy-Item .env.example .env }

Остання команда створює .env лише тоді, коли цього файла ще немає, тож повторний запуск не стирає ваших ключів.

Ключі провайдерів

Відкрийте .env у текстовому редакторі й заповніть ключ лише того провайдера, яким користуватиметеся:

Локальному провайдеру ключ не потрібен. Ключі лишаються на вашому комп’ютері; не публікуйте файл .env.

Ключ у налаштуваннях замість .env

Ключ можна ввести й у застосунку: Налаштування → Моделі, блок «Ключ провайдера» під вибором провайдера й моделі (такий самий блок є в налаштуваннях оцінювача й допоміжної класифікації). Ключ зберігається у сховищі облікових даних Windows, діє одразу, без перезапуску, і більше не показується: видно лише, звідки він береться.

У встановленні з вихідного коду для цього потрібен пакет keyring, якого немає в requirements-lock.txt:

./.venv/Scripts/python.exe -m pip install "keyring>=25,<26"

Без нього блок повідомить, що сховище недоступне, і ключ треба задати в .env.

Запуск

Особисті твори краще тримати в окремому каталозі поза текою застосунку:

./scripts/start.ps1 -DataDir "$env:LOCALAPPDATA/ObscuraTextWriter/data"

Браузер відкриє http://127.0.0.1:8765. Сервер слухає лише ваш комп’ютер. Інший порт задає параметр -Port, наприклад -Port 8770. Зупинка — Ctrl+C у вікні PowerShell.

Якщо запуск PowerShell-скриптів заборонено, використайте пряму команду:

./.venv/Scripts/python.exe -m storygen.server --data-dir "$env:LOCALAPPDATA/ObscuraTextWriter/data" --env-file .env --open-browser

Запуск без консолі

Команда storygen-desktop запускає застосунок без вікна PowerShell:

./.venv/Scripts/pythonw.exe -m storygen.desktop --env-file .env

На Windows значок у треї з’являється одразу. Лівий клік відкриває застосунок, а правий показує меню «Відкрити Obscura», «Тека творів», «Вийти». На інших системах значка немає: зупиніть застосунок клавішами Ctrl+C у терміналі.

Моделі

Після першого запуску відкрийте Налаштування → Моделі і для кожної ролі вкажіть провайдера, адресу API, точний ідентифікатор моделі та ліміти. Для локального сервера типова адреса — http://localhost:1235/v1. Кнопка отримання списку моделей показує доступні ідентифікатори й відомі ціни.

Резервне копіювання

Перед копіюванням зупиніть сервер. Штатна резервна копія перевіряє цілісність і хеші:

./.venv/Scripts/storygen.exe backup --data-dir "$env:LOCALAPPDATA/ObscuraTextWriter/data" --destination "D:/Backups/obscura-2026-11-11" --json
./.venv/Scripts/storygen.exe restore --backup-dir "D:/Backups/obscura-2026-11-11" --destination "D:/Restored/obscura" --json

Батьківські каталоги призначення мають існувати. Відновлення створює лише новий каталог і нічого не перезаписує. Можна також скопіювати весь каталог даних зупиненого сервера; не копіюйте базу окремо від текстів.

Щоб перевірити каталог даних без змін, виконайте ./.venv/Scripts/storygen.exe fsck --data-dir "<каталог>" --json. Команда повідомляє про проблеми, але нічого не виправляє й не видаляє. Якщо резервування чи відновлення перервалося, не використовуйте неповний каталог: повторіть відновлення з перевіреної копії в інший новий каталог.

Оновлення

Збережіть ручні правки, зупиніть сервер, оновіть код і запустіть сервер знову. Схема даних оновлюється під час відкриття сховища. Після збою незавершені запуски позначаються як перервані й продовжуються лише за вашою командою.