# Пользовательский мануал Abulafia

## 1. Что такое Abulafia

Abulafia — интерактивный AI-агент для исследовательской работы. Он умеет
искать и анализировать источники, читать статьи, сравнивать аргументы, готовить
обзоры, проверять рукописи и вести многоступенчатые сценарии A01-A10 и
Journal-Yuga S01-S11.

В отличие от обычного чата, сложные результаты сохраняются в Markdown-файлы.
Их можно открыть, передать другому человеку, проверить и использовать на
следующем этапе.

## 2. Установка

Самый простой вариант для Windows:

1. Скачайте `Abulafia-Setup-<версия>-x64.exe` из GitHub Releases.
2. Откройте файл двойным щелчком.
3. Нажмите `Установить`.
4. Запустите Abulafia с рабочего стола или из меню «Пуск».

Node.js, npm, Bun и Git для такой установки не нужны: необходимые runtime и
dependencies находятся внутри установщика.

Полная инструкция, обновление и удаление описаны в
[INSTALL_AND_RUN.md](INSTALL_AND_RUN.md).

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

Откройте PowerShell и выполните:

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

Во время login укажите:

- endpoint: `https://api.302.ai/v1`;
- свой API key 302.AI;
- модели `gpt-5.4,gpt-5.4-nano`, если список не определился автоматически.

Ключ сохраняется в пользовательском профиле Abulafia. Повторно вводить его при
каждом запуске не требуется.

Проверка:

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

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

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

Web-поиск на чистой установке работает в режиме `auto`. Настроенные Perplexity,
Exa или Gemini имеют приоритет; без них используется безключевая цепочка Brave, DuckDuckGo и Bing.

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

`gpt-5.4` предназначена для сложной аналитики и tool-calling. `gpt-5.4-nano`
оставляйте для коротких текстовых запросов: она не рекомендуется для `story`,
`deepresearch` и других многоступенчатых workflow. Если nano выбрана по
умолчанию, Abulafia автоматически использует доступную `gpt-5.4` на время
такого workflow.

## 4. Рабочий проект

Создайте отдельную папку для конкретного исследования:

```powershell
mkdir C:\Research\my-project
cd C:\Research\my-project
abulafia
```

Abulafia считает текущую папку рабочим проектом. Относительные пути во всех
командах разрешаются от неё, а результаты создаются внутри неё.

Рекомендуемая структура:

```text
my-project/
  article.md              исходная статья или материалы
  sources/                дополнительные источники
  reviews/                письма редакторов и рецензентов
  knowledge/journals/     проектные досье журналов, если нужны
  outputs/                результаты Abulafia
  papers/                 подготовленные черновики
  notes/                  журналы сессий и заметки
  experiments/            код и результаты экспериментов
```

В интерактивной консоли можно выполнить `/init`, чтобы создать базовую структуру
исследовательского проекта и `AGENTS.md`.

## 5. Как работать с интерактивной консолью

Запуск:

```powershell
cd C:\Research\my-project
abulafia
```

После запуска можно вводить обычные запросы:

```text
Проанализируй article.md, найди слабые места аргументации и сохрани отчёт.
```

Или использовать slash-команды:

```text
/deepresearch Правовое регулирование генеративного AI в университетах
/lit AI-supported reflection in legal education
/review .\article.md
/story S01 .\article.md Нужны журналы Scopus без добавления новой эмпирики
```

Полезные команды discovery:

| Команда | Что показывает |
| --- | --- |
| `/help` | Сгруппированную справку Abulafia. |
| `/commands` | Все реально доступные slash-команды. |
| `/tools` | Все реально вызываемые tools и их параметры. |
| `/capabilities` | Количество workflows, tools и установленных packages. |
| `/agents` | Доступные runtime agents. |
| `/outputs` | Созданные артефакты проекта. |
| `/abulafia-model` | Интерактивное меню моделей. |
| `/search <текст>` | Поиск по прошлым сессиям. |
| `/jobs` | Фоновые процессы и scheduled jobs. |
| `/quit` | Выход из консоли. |

Фактический набор package-команд может различаться. Используйте `/commands` и
`/tools`, а не угадывайте имя инструмента.

## 6. Основные research workflows

| Команда | Назначение | Типичный результат |
| --- | --- | --- |
| `/deepresearch <тема>` | Глубокое исследование с несколькими источниками и проверкой. | Cited brief в `outputs/` и provenance sidecar. |
| `/lit <тема>` | Обзор научной литературы и состояния области. | Literature review в `outputs/`. |
| `/review <файл>` | Критический peer review артефакта. | Structured review в `outputs/`. |
| `/draft <задача>` | Создание paper-style черновика из материалов. | Draft в `papers/`. |
| `/compare <источники>` | Сравнение источников или подходов. | Comparison matrix в `outputs/`. |
| `/audit <статья и код>` | Проверка соответствия утверждений статьи публичному коду. | Audit report в `outputs/`. |
| `/replicate <статья>` | Планирование или выполнение воспроизведения. | Plan, scripts и results. |
| `/autoresearch <метрика>` | Итеративный экспериментальный цикл. | Experiment files и JSONL log. |
| `/summarize <источник>` | Иерархическое суммирование большого файла, URL или PDF. | Summary в `outputs/`. |
| `/watch <тема>` | Baseline-обзор и регулярные проверки. | Baseline плюс schedule. |
| `/log` | Сохранение итогов текущей сессии. | Log в `notes/session-logs/`. |

Те же top-level workflows можно передать при запуске:

```powershell
abulafia deepresearch "AI governance in higher education"
abulafia lit "AI in legal education"
abulafia review .\article.md
abulafia compare .\source-a.md .\source-b.md
```

## 7. Skills, workflows, agents и tools

Эти сущности не взаимозаменяемы:

- skill сообщает модели правила применения способности;
- workflow задаёт многоступенчатый процесс и становится slash-командой;
- agent задаёт специализированную роль и контракт результата;
- tool выполняет конкретное действие;
- package добавляет новые tools и commands в runtime.

Обычно пользователь запускает workflow или формулирует задачу естественным
языком. Вручную «запускать SKILL.md» не нужно.

Например, `/deepresearch` использует skill `deep-research`, orchestration prompt
и базовых agents `researcher`, `verifier`, `reviewer`. Tool `web_search` при этом
является только одним из возможных действий внутри workflow.

Полный справочник находится в [SKILLS_REFERENCE.md](SKILLS_REFERENCE.md).

## 8. Story-сценарии A01-A10

A-series предназначена для полного исследовательского pipeline:

```text
A01 brief
  -> A02 source discovery
  -> A03 thematic screening
  -> A04 quality screening
  -> A05 analytical review
  -> A06 human validation
  -> A07 landscapes
  -> A08 focus validation
  -> A09 hypotheses
  -> A10 report
```

Запуск одной story внутри интерактивной консоли:

```text
/story A01 .\article.md Сформируй исследовательский brief и критерии отбора
```

Несколько stories:

```text
/story A01,A02,A03 .\article.md Исследовать влияние AI на юридическое образование
```

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

```text
/story chain A01-A10 .\article.md Подготовить систематическое исследование
```

Предыдущий артефакт передаётся следующей story как handoff. Зависимые соседние
этапы выполняются последовательно.

## 9. Journal-Yuga S01-S11

S-series решает задачи публикационной маршрутизации:

| Story | Когда применять |
| --- | --- |
| S01 | Есть черновик, но неизвестно, куда подавать. |
| S02 | Уже выбран конкретный журнал. |
| S03 | Есть только abstract или идея. |
| S04 | Нужна минимальная формальная адаптация под ВАК/Q3/Q4/локальный журнал. |
| S05 | Подача в conference proceedings. |
| S06 | Статья проектируется заранее под пул Q1/Q2. |
| S07 | Русский текст адаптируется под англоязычный venue. |
| S08 | Получен rejection или Revise & Resubmit. |
| S09 | Есть пользовательский корпус статей журнала. |
| S10 | Нужна финальная проверка submission package. |
| S11 | Нужен академический профиль editors и точки теоретического резонанса. |

Пример S01:

```text
/story S01 .\article.md Нужны журналы Scopus, Q2-Q3, без новой эмпирики и без потери философского аргумента
```

Пример S02:

```text
/story S02 .\article.md Целевой журнал: The Law Teacher. Нужна карта несоответствий и план адаптации
```

Пример S08:

```text
/story S08 .\article.md .\reviews\editor-letter.md .\reviews\reviewer-1.md Подготовить revision plan
```

Перед исследованием Journal-Yuga задаёт только блокирующие вопросы. Если
информации уже достаточно или вы готовы принять assumptions, напишите:

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

После этой фразы agent обязан прекратить intake, поставить `forced_start: true`
и продолжить работу с явной маркировкой неизвестных данных.

## 10. Три режима запуска story

Это различие принципиально:

| Команда | Использует модель | Назначение |
| --- | --- | --- |
| `/story ...` внутри Abulafia | Да | Полноценное модельное выполнение story с tools и источниками. |
| `/story-local ...` внутри Abulafia | Нет | Быстрая локальная демонстрация и проверка структуры. |
| `abulafia story ...` в PowerShell | Да | Полноценный workflow с моделью, открытый в TUI. |
| `abulafia story-local ...` в PowerShell | Нет | Явный deterministic smoke-runner без модели. |

Для реального анализа статьи используйте `/story` внутри интерактивной консоли
или `abulafia story ...` из PowerShell. Только команды с суффиксом `-local`
создают структурные mock/deterministic outputs.

## 11. Проверка story-результатов

Evaluator не выполняет stories повторно. Он оценивает уже созданные файлы.

Одна story:

```text
/evaluate-stories S01 .\outputs\journal-yuga-runs\article
```

Все 21 story:

```text
/evaluate-stories all .\outputs\my-story-run
```

Без интерактивного UI:

```powershell
abulafia evaluate-stories all .\outputs\my-story-run
```

Результат содержит coverage table, score и decision по каждой story.

## 12. Где находятся результаты

Обычные workflows:

```text
outputs/
papers/
notes/
experiments/
```

A-series:

```text
outputs/<slug>/
  <A-story-output>.md
  story-run-report.md
```

Journal-Yuga:

```text
outputs/journal-yuga-runs/<slug>/
  state.yaml
  intake.md
  acceptance-criteria.md
  decision-log.md
  journal-search-log.md
  <S-story-output>.md
  story-run-report.md
```

Текущий операционный статус долгой задачи хранится в:

```text
outputs/.status/abulafia-live-status.md
```

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

Journal-Yuga ищет данные в следующем порядке:

1. `knowledge/journals/journal_yuga_venue_database.md`;
2. досье `knowledge/journals/*.md`;
3. `knowledge/journals/index.yaml`;
4. интернет, только если локальных сведений недостаточно.

Проектный каталог `knowledge/journals/` имеет приоритет над встроенной базой.
Новые устойчивые наблюдения дописываются в досье, а не заменяют старые записи.

## 14. Фоновые задачи и сохранённые сессии

`/jobs` показывает активные процессы, scheduled prompts и subagent tasks.

`/watch` может создать регулярную проверку темы через scheduling package.

Сессии сохраняются в `%USERPROFILE%\.abulafia\sessions`. Найти прошлую работу:

```text
/search journal yuga
```

Сохранить компактный итог текущей сессии:

```text
/log
```

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

### Команда не найдена

Закройте терминал и откройте новый. Затем:

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

### Модель не настроена

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

### 302.AI возвращает 503

`503 No available models currently` означает, что провайдер временно не может
выдать выбранную модель. Проверьте доступные модели в кабинете 302.AI и
повторите запрос позже. `gpt-5.4-nano` можно временно выбрать для простого чата,
но не для workflow с большим количеством инструментов.

### Tool not found

Не угадывайте сокращённое имя. Выполните:

```text
/tools
/capabilities
```

Если package отсутствует:

```powershell
abulafia packages list
abulafia doctor
```

### Story завершилась за секунду

Проверьте режим. Только `abulafia story-local` и `/story-local` являются
локальными deterministic runners. `abulafia story` и `/story` обязаны запускать
модель; если они завершаются за секунду без модельного хода, выполните
`abulafia doctor` и приложите журнал сессии как ошибку.

### Нужно понять, что сейчас происходит

Откройте:

```text
outputs/.status/abulafia-live-status.md
```

Live status показывает этап, активные contracts, skills, источники и следующий
шаг без публикации скрытого chain-of-thought.

## 16. Минимальный демонстрационный сценарий

```powershell
cd C:\work\Abulafia
abulafia
```

Внутри консоли:

```text
/story S01 .\demo\journal-yuga-console\article.md Нужно определить подходящие журналы, требуемые доработки и риски потери смысла. Scopus обязателен, новую эмпирику добавлять нельзя. Хватит вопросов.
```

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

```text
outputs/journal-yuga-runs/article/S01-journal-pool.md
outputs/journal-yuga-runs/article/story-run-report.md
```