Встановлення й запуск
Вимоги
- Windows 10 або 11.
- Python 3.10 або новіший.
- Модельний API: локальний OpenAI-сумісний сервер (наприклад, LM Studio) або обліковий запис OpenRouter чи Venice.
Інсталятор
Інсталятор для 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 у текстовому редакторі й заповніть ключ лише того провайдера, яким користуватиметеся:
OPENROUTER_API_KEY— для OpenRouter;VENICE_API_KEY— для Venice (лише моделі зuncensored=true).
Локальному провайдеру ключ не потрібен. Ключі лишаються на вашому комп’ютері; не публікуйте файл .env.
Ключ у налаштуваннях замість .env
Ключ можна ввести й у застосунку: Налаштування → Моделі, блок «Ключ провайдера» під вибором провайдера й моделі (такий самий блок є в налаштуваннях оцінювача й допоміжної класифікації). Ключ зберігається у сховищі облікових даних Windows, діє одразу, без перезапуску, і більше не показується: видно лише, звідки він береться.
- Якщо ключ є і в
.env, і в сховищі, діє ключ із.env; блок про це скаже. - Ключ у сховищі прив’язаний до назви змінної («Параметри підключення» → «Змінна середовища з ключем») і спільний для всіх ваших творів і тек даних на цьому комп’ютері.
- Кнопка «Видалити збережений ключ» прибирає його зі сховища; у Windows запис також видно в «Диспетчері облікових даних» під назвою
Obscura.
У встановленні з вихідного коду для цього потрібен пакет 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
-
--env-file .envбере ключі провайдерів із того самого файла.env, що й звичайний запуск. Без цього параметра застосунок шукає.envу теці творів; ключ, збережений у налаштуваннях (сховище Windows), діє в обох випадках. -
Твори зберігаються в теці
Obscuraу вашому профілі (%USERPROFILE%\Obscura); іншу теку задає--data-dir. -
Журнал —
logs\obscura.logу теці творів. Якщо застосунок не зміг стартувати, він покаже повідомлення з причиною та шляхом до журналу. -
Якщо порт 8765 зайнятий, застосунок бере вільний; адреса є в журналі й у файлі
server.json. -
Перед оновленням формату бази застосунок сам робить резервну копію в сусідню теку
Obscura-backupsі не стартує, якщо копію зробити не вдалося. Старі копії він не видаляє. -
Повторний запуск, поки застосунок працює, лише відкриває його сторінку.
На 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. Команда повідомляє про проблеми, але нічого не виправляє й не видаляє. Якщо резервування чи відновлення перервалося, не використовуйте неповний каталог: повторіть відновлення з перевіреної копії в інший новий каталог.
Оновлення
Збережіть ручні правки, зупиніть сервер, оновіть код і запустіть сервер знову. Схема даних оновлюється під час відкриття сховища. Після збою незавершені запуски позначаються як перервані й продовжуються лише за вашою командою.