# Установка Abulafia в командную строку

Эта инструкция относится к текущей версии репозитория
[Enicast/Abulafia](https://github.com/Enicast/Abulafia). После установки
команда `abulafia` работает из обычного PowerShell, CMD или другого терминала
и не требует каждый раз переходить в каталог исходников.

## Установка в два клика на Windows

Этот способ предназначен для обычного пользователя, которому не нужны исходники.

1. Откройте страницу [Releases](https://github.com/Enicast/Abulafia/releases).
2. Скачайте файл `Abulafia-Setup-<версия>-x64.exe`.
3. Откройте файл двойным щелчком.
4. Оставьте включёнными пункты создания ярлыка и добавления команды в `PATH`.
5. Нажмите `Установить`, затем `Завершить`.

После установки Abulafia доступна:

- с ярлыка на рабочем столе;
- из меню «Пуск»;
- командой `abulafia` в новом PowerShell или CMD.

Установщик уже содержит совместимую версию Node.js, production-зависимости,
базу журналов и runtime Abulafia. Отдельно устанавливать Git, Node.js, npm или
Bun не требуется. Поддерживаются Windows 10/11 на обычных 64-битных компьютерах
Intel/AMD и совместимых Windows-системах.

API key 302.AI не встраивается в установщик. Пользователь вводит свой ключ один
раз при первоначальной настройке; после этого ключ хранится в пользовательском
профиле Abulafia.

Если Windows SmartScreen показывает предупреждение «Неизвестный издатель», это
означает, что EXE пока не подписан коммерческим сертификатом подписи кода.
Проверить загруженный файл можно по SHA-256 из соседнего файла
`Abulafia-Setup-<версия>-x64.exe.sha256`.

## 1. Требования для установки из исходников

Разделы ниже нужны разработчикам. Для EXE-установщика эти зависимости не нужны.

- Windows 10/11, macOS или Linux.
- Node.js `>=20.19.0` и `<25`. Рекомендуется Node.js 22 LTS.
- npm.
- Git для установки из репозитория.
- API key 302.AI для запросов к модели.

Проверка:

```powershell
node --version
npm --version
git --version
```

Если `node` или `npm` не найдены, установите Node.js 22 LTS с
[nodejs.org](https://nodejs.org/) и откройте новый терминал.

## 2. Установка из исходников

### Новый компьютер или новая копия проекта

```powershell
cd I:\Claude
git clone https://github.com/Enicast/Abulafia.git
cd .\Abulafia
npm install
npm run cli:install
```

### Репозиторий уже скачан

Откройте PowerShell в корне репозитория, где находится `package.json`:

```powershell
npm install
npm run cli:install
```

`npm run cli:install` выполняет production-сборку, собирает локальный npm-пакет,
устанавливает его глобально и проверяет установленную команду через
`abulafia --version`.

После завершения откройте новый PowerShell и проверьте:

```powershell
Get-Command abulafia
abulafia --version
abulafia doctor
```

Теперь Abulafia можно запускать из любого проекта:

```powershell
cd C:\work\my-research
abulafia
```

Для разработки исходников без глобальной установки по-прежнему доступна
команда:

```powershell
npm run dev
```

## 3. Если команда не найдена

Узнайте каталог глобальных npm-команд:

```powershell
npm prefix --global
```

В Windows это обычно:

```text
C:\Users\<пользователь>\AppData\Roaming\npm
```

Добавьте его в текущую сессию PowerShell:

```powershell
$npmGlobalPrefix = npm prefix --global
$env:Path = "$npmGlobalPrefix;$env:Path"
abulafia --version
```

Если после этого команда работает, закройте и снова откройте PowerShell. Если
новый терминал всё равно не видит команду, добавьте результат
`npm prefix --global` в пользовательскую переменную `Path`.

## 4. Первичная настройка 302.AI

API key вводится один раз и сохраняется в пользовательском состоянии Abulafia.
Повторно указывать его при каждом запуске не нужно.

```powershell
abulafia model login 302ai
abulafia model set 302ai/gpt-5.4
```

Во время `model login`:

1. Оставьте endpoint `https://api.302.ai/v1`.
2. Вставьте API key 302.AI.
3. Укажите модели `gpt-5.4,gpt-5.4-nano`, если список не определился
   автоматически.

Проверка:

```powershell
abulafia model list
abulafia status
```

Переключение модели:

```powershell
abulafia model set 302ai/gpt-5.4
abulafia model set 302ai/gpt-5.4-nano
```

Если 302.AI возвращает `503 No available models currently`, CLI установлен
правильно, но выбранная модель временно недоступна у провайдера. Переключитесь
на вторую разрешённую модель или повторите запрос позже.

### Web-поиск

Дополнительный API key для базового web-поиска не обязателен. При первом запуске
создаётся маршрут `auto`: он использует настроенные Perplexity, Exa или Gemini,
а если они недоступны, последовательно пробует безключевые Brave, DuckDuckGo и Bing.

```powershell
abulafia search status
abulafia search set auto
abulafia search test "official journal aims and scope"
```

Чтобы принудительно использовать безключевой маршрут:

```powershell
abulafia search set brave
```

## 5. Запуск интерактивной консоли

Перейдите в каталог проекта с материалами и запустите:

```powershell
cd C:\work\my-research
abulafia
```

После открытия интерфейса можно вводить обычные запросы или workflow-команды. Для известных workflow ведущий `/` необязателен:

```text
/story A01 .\article.md
/story S01 .\article.md Нужно определить подходящие журналы и необходимые доработки
deepresearch Проверить актуальные требования журналов по AI ethics
/evaluate-stories all .\outputs\my-story-run
```

Для Journal-Yuga агент сначала уточняет задачу и критерии приёмки. Команда:

```text
хватит вопросов
```

завершает уточнение и запускает работу с уже собранными требованиями.

## 6. Story workflow и локальный smoke-runner

`abulafia story` выполняет полноценную многоступенчатую работу через модель. Для
локальной проверки структуры без запроса к 302.AI используйте только явно
названную команду `abulafia story-local` или `/story-local` внутри интерфейса.

Одна story:

```powershell
abulafia story-local A01 .\article.md
abulafia story-local S01 .\article.md "Нужно проверить структуру артефактов"
```

Несколько stories:

```powershell
abulafia story-local A01,A02,A03 .\article.md
```

Исследовательская цепочка:

```powershell
abulafia story-local chain A01-A10 .\article.md
```

Цепочка Journal-Yuga:

```powershell
abulafia story-local chain S01-S11 .\article.md
```

Проверка артефактов:

```powershell
abulafia evaluate-stories S01 .\outputs\journal-yuga-runs\<имя-запуска>
abulafia evaluate-stories all .\outputs\my-story-run
```

Результаты создаются в каталоге проекта, из которого запущена команда:

```text
outputs/
outputs/journal-yuga-runs/<имя-запуска>/
```

## 7. База журналов

Глобальный пакет включает актуальную базу:

```text
knowledge/journals/journal_yuga_venue_database.md
```

Порядок поиска Journal-Yuga:

1. `knowledge/journals/journal_yuga_venue_database.md`.
2. Локальные досье `knowledge/journals/*.md`.
3. Курированный индекс `knowledge/journals/index.yaml`.
4. Интернет, только если локальной информации недостаточно.

Если в текущем проекте есть собственный каталог `knowledge/journals`, он имеет
приоритет над встроенной базой установленного пакета.

## 8. Обновление

### Установленная через EXE версия

Скачайте новый `Abulafia-Setup-<версия>-x64.exe` со страницы Releases и
запустите его. Мастер заменит файлы программы; сохранённые API key, настройки и
сессии в `%USERPROFILE%\.abulafia` останутся на месте.

### Установленная из исходников версия

В каталоге клонированного репозитория:

```powershell
git pull
npm install
npm run cli:install
abulafia --version
```

Команда `npm run cli:install` заменяет ранее установленную глобальную версию.
Пользовательские настройки и API key в `%USERPROFILE%\.abulafia` сохраняются.

## 9. Удаление

### Установленная через EXE версия

Откройте `Параметры Windows → Приложения → Установленные приложения`, найдите
**Abulafia** и нажмите `Удалить`.

### Установленная из исходников версия

Удалить глобальную CLI-команду:

```powershell
npm uninstall --global abulafia
```

Пользовательские настройки и API key при этом остаются в:

```text
%USERPROFILE%\.abulafia
```

Удаляйте этот каталог отдельно только в том случае, если также хотите стереть
настройки, сессии и сохранённую авторизацию.

## 10. Сборка Windows-установщика

Этот раздел нужен только сопровождающим проекта. Установите Inno Setup 6:

```powershell
winget install --id JRSoftware.InnoSetup --exact
```

Затем из корня репозитория:

```powershell
npm install
npm run build:windows-installer
```

Готовые файлы:

```text
dist/installer/Abulafia-Setup-<версия>-x64.exe
dist/installer/Abulafia-Setup-<версия>-x64.exe.sha256
```

Локальный smoke-тест выполняет реальную тихую установку, запускает установленную
CLI и затем проверяет удаление:

```powershell
.\scripts\install\test-windows-installer.ps1
```

## 11. Диагностика

Проверить установленный файл:

```powershell
Get-Command abulafia | Format-List Name,Source,CommandType
```

Проверить окружение:

```powershell
abulafia doctor
abulafia status
abulafia model list
```

Если глобальная команда повреждена, переустановите её из корня репозитория:

```powershell
npm install
npm run cli:install
```

Проверки для разработчика:

```powershell
npm run typecheck
npm test
```