# Архитектура Abulafia ## 1. Назначение системы Abulafia является research-first оболочкой над Pi coding agent runtime. Она добавляет единый CLI, настройку моделей, исследовательский system prompt, workflow-команды, специализированные skills и agents, Journal-Yuga и правила создания проверяемых артефактов. Главный архитектурный принцип: результат сложной задачи должен существовать не только в чате, но и как устойчивый файл с понятным происхождением, ограничениями и следующим шагом. ## 2. Общая схема ```mermaid flowchart TD U["Пользователь"] --> L["abulafia.cmd / bin/abulafia.js"] L --> C["CLI: src/cli.ts"] C -->|"setup, doctor, model, packages"| A["Локальные административные команды"] C -->|"story-local / evaluate-stories"| D["Детерминированный smoke/evaluation runner"] C -->|"chat, abulafia story и workflow-команды"| P["Pi runtime"] P --> M["Model registry и 302.AI"] P --> S["SYSTEM.md"] P --> W["prompts/*.md workflows"] P --> E["research-tools extension"] P --> K["Pi packages, tools и commands"] W --> G["Skills и agents"] E --> G G --> O["Артефакты: outputs, papers, notes, experiments"] D --> O G --> J["Journal-Yuga state и knowledge/journals"] ``` ## 3. Слои системы ### 3.1 Launcher и CLI Точка входа находится в `bin/abulafia.js`. Она запускает собранный `dist/index.js`, который проверяет поддерживаемую версию Node.js и передаёт управление в `src/cli.ts`. CLI выполняет два типа задач: - локальные команды: `setup`, `doctor`, `status`, `model`, `packages`, `search`, `update`, `story-local`, `evaluate-stories`; - запуск интерактивного Pi runtime с начальным prompt или без него. Команды, описанные в `prompts/*.md` с `topLevelCli: true`, можно запускать и как CLI-команды. Например, `abulafia deepresearch "тема"` превращается в начальный prompt `/deepresearch тема` внутри Pi. ### 3.2 Pi runtime `src/pi/launch.ts` запускает Pi как дочерний Node.js-процесс с общим терминалом. Перед запуском система: 1. проверяет Node.js и наличие Pi; 2. применяет совместимые runtime patches; 3. подключает Promise polyfill и CLI wrapper; 4. разрешает пути внешних executable-файлов; 5. передаёт Pi system prompt, extensions, prompt templates, model и session dir; 6. формирует изолированное окружение Abulafia. `src/pi/runtime.ts` добавляет в окружение дочернего процесса: - `ABULAFIA_CODING_AGENT_DIR` и `PI_CODING_AGENT_DIR`; - отдельный npm prefix в `%USERPROFILE%\.abulafia\npm-global`; - пути к sessions, memory и web-search config; - флаг 302.AI provider overlay; - пути к Pandoc, Mermaid CLI и браузеру, когда они доступны. ### 3.3 Model registry и 302.AI Авторизация и пользовательские модели хранятся в пользовательском каталоге Abulafia. `src/model/registry.ts` создаёт Pi `ModelRegistry` и добавляет overlay провайдера `302ai` с endpoint `https://api.302.ai/v1`. Текущие преднастроенные модели: - `302ai/gpt-5.4`, reasoning включён; - `302ai/gpt-5.4-nano`, reasoning выключен. Для обеих моделей зарегистрировано окно контекста 128 000 токенов и максимум 16 384 output tokens. Эти значения являются конфигурацией клиента, а не гарантией фактических лимитов конкретного тарифа 302.AI. API key сохраняется через Pi auth storage в пользовательском профиле и не должен находиться в репозитории или story-артефактах. ### 3.4 System prompt `.abulafia/SYSTEM.md` задаёт глобальные правила: - evidence over fluency; - первичные источники предпочтительнее пересказов; - наблюдения отделяются от выводов; - непроверенные данные не выдаются за факты; - результаты, числа, таблицы и графики должны иметь provenance; - сложная работа сохраняется на диск; - внутренний chain-of-thought не публикуется, но показывается безопасный операционный статус; - работа не объявляется проверенной без реальной проверки. ### 3.5 Workflow prompts Файлы `prompts/*.md` превращаются Pi в slash-команды. Workflow является оркестратором: он определяет этапы, подключаемые agents и skills, формат артефакта и проверки перед завершением. Примеры: - `prompts/deepresearch.md` -> `/deepresearch`; - `prompts/lit.md` -> `/lit`; - `prompts/review.md` -> `/review`; - `prompts/story.md` -> `/story`; - `prompts/evaluate-stories.md` -> `/evaluate-stories`; - `prompts/summarize.md` -> `/summarize`. ### 3.6 Skills Skill хранится в `skills//SKILL.md` и содержит YAML frontmatter плюс операционный контракт. Skill отвечает на вопросы: - когда способность релевантна; - какой workflow или tool использовать; - какие agents привлекать; - какой файл создать; - какие ограничения качества соблюдать. Skill сам по себе не является исполняемым бинарным модулем. Его инструкции загружаются runtime и применяются моделью или parent workflow. ### 3.7 Agents Agent-файлы находятся в `.abulafia/agents/`. Базовые agents: - `researcher` собирает и структурирует первичные доказательства; - `verifier` проверяет URL, citations и provenance; - `reviewer` выполняет критический peer review; - `writer` создаёт связный документ на основе уже собранных материалов. Story-agents A01-A10 и S01-S11 являются отдельными контрактами. Они могут появляться в списке agents, но это не означает, что Pi `subagent` поддерживает их как runtime mode. По умолчанию `/story` применяет такой контракт напрямую в parent workflow, а базовым subagents делегирует только узкие подзадачи. ### 3.8 Tools и packages Tool является реально вызываемой функцией. Tools поступают из Pi, extensions и установленных packages. Фактический набор зависит от платформы и конфигурации. Базовая поставка подключает packages для: - alphaXiv и работы со статьями; - subagents; - web/PDF access и document parsing; - Markdown preview, charts и Mermaid; - background processes и schedule; - Zotero; - session search и memory. В интерактивной консоли `/tools`, `/commands` и `/capabilities` показывают фактически обнаруженный набор, поэтому они точнее статического списка. ## 4. Потоки исполнения ### 4.1 Обычный research workflow ```mermaid sequenceDiagram participant Hu as "Пользователь" participant Pi as "Parent workflow" participant R as "Researcher" participant V as "Verifier / Reviewer" participant FS as "Файловая система" Hu->>Pi: "/deepresearch тема" Pi->>FS: "Создать план и live status" Pi->>R: "Собрать первичные источники" R->>FS: "Записать evidence" Pi->>Pi: "Синтезировать выводы" Pi->>V: "Проверить claims и citations" V->>FS: "Записать проверенный результат" Pi->>FS: "Проверить существование артефакта" Pi-->>Hu: "Путь к результату и ограничения" ``` ### 4.2 Model-driven story `/story S01 article.md <задача>` исполняется внутри Pi: 1. `prompts/story.md` разбирает story IDs. 2. Parent workflow читает соответствующие agent и skill contracts. 3. Для S-story подключается `journal-yuga-common`. 4. Создаются plan, evidence и live-status файлы. 5. Story выполняется моделью с доступными tools. 6. Проверяется ожидаемый primary output. 7. Создаётся `story-run-report.md`. ### 4.3 Локальный deterministic story runner `abulafia story-local ...` и интерактивный `/story-local ...` вызывают `src/workflows/story-runner.ts` без LLM tool-calling. Он нужен для: - smoke-тестов; - демонстраций без расхода API; - проверки структуры state и output; - воспроизводимого evaluator pipeline. Локальный runner не заменяет полноценное модельное исследование. В частности, он не выполняет web fallback и помечает внешние свойства журналов как требующие верификации. ### 4.4 Story evaluation `evaluate-stories` находит ожидаемые артефакты, проверяет обязательные секции, рассчитывает оценку и создаёт coverage report. Это evaluator результатов, а не запуск story-агента. ## 5. Journal-Yuga Все S01-S11 используют общий протокол `journal-yuga-common`. ### 5.1 Clarification gate До исполнения должны быть известны источник статьи/идеи, цель публикации, ограничения, допустимые и запрещённые изменения и ожидаемый результат. Если блокирующих данных нет, agent задаёт вопросы и сохраняет intake state. Фраза `хватит вопросов` переводит run в forced-start: agent продолжает с имеющейся информацией и явно маркирует assumptions и unknowns. ### 5.2 Порядок поиска журналов 1. `knowledge/journals/journal_yuga_venue_database.md`. 2. Досье `knowledge/journals/*.md`. 3. Курированный индекс `knowledge/journals/index.yaml`. 4. Web search, только если локальных данных недостаточно. Каждый lookup записывается в `journal-search-log.md`. Повторно используемые наблюдения могут дописываться в досье журнала без удаления прежней истории. Локальная база является кэшем, а не whitelist: если после семантического отбора остаётся меньше трёх доказательно обоснованных кандидатов, workflow обязан расширить поиск через web-инструменты, когда они доступны. ### 5.3 State machine ```mermaid stateDiagram-v2 [*] --> intake intake --> awaiting_user: "Не хватает критериев" awaiting_user --> intake: "Пользователь ответил" awaiting_user --> executing: "хватит вопросов" intake --> executing: "Критерии полны" executing --> blocked: "Инструмент или источник недоступен" executing --> complete: "Артефакты проверены" blocked --> executing: "Блокер устранён" complete --> [*] ``` ### 5.4 Bounded contexts и evidence ontology Journal-Yuga хранит отдельно слои `Article`, `Field`, `Venue`, `Fit`, `Adaptation`, `Compliance` и `Memory`. Структурированный пакет находится в `publication-model.yaml`; его схема лежит в `knowledge/contracts/journal-yuga-publication-model.schema.json`. Каждый проверяемый claim должен иметь запись в `evidence-ledger.yaml` с provenance, состоянием доступа/извлечения и одним из типов `source_fact`, `text_extracted_claim`, `inferred_pattern`, `corpus_observation`, `user_tacit_note`, `vendor_claim`, `unknown` или `conflicting_evidence`. `unknown` не считается отсутствием, а publisher claim не считается независимой проверкой индексации. `protected-core.md` фиксирует центральный тезис, объект, концептуальные различия, позицию автора и ключевой словарь. Изменение с меткой `core_touching` требует явного согласия пользователя. S01-S11 являются независимо маршрутизируемыми capabilities. Последовательность возникает только при реальной зависимости или явном вызове `story chain`; режим `story all` должен строить dependency graph, а не притворяться линейным pipeline. ## 6. Состояние и каталоги ### 6.1 Пользовательское состояние По умолчанию `%USERPROFILE%\.abulafia` содержит: ```text .abulafia/ agent/ auth.json, models.json, settings.json, agents, skills, themes sessions/ сохранённые Pi-сессии memory/ долговременная память packages npm-global/ изолированные Pi packages .state/ bootstrap state web-search.json конфигурация веб-поиска ``` `ABULAFIA_HOME` позволяет перенести пользовательский root. Bootstrap sync копирует встроенные agents, skills и themes в пользовательский каталог и отслеживает hashes, чтобы обновлять управляемые файлы, не перезаписывая пользовательские изменения без необходимости. ### 6.2 Состояние проекта ```text outputs/ обзоры, evaluations, story outputs papers/ paper-style drafts experiments/ код и результаты экспериментов notes/ промежуточные заметки и session logs outputs/.status/abulafia-live-status.md ``` Journal-Yuga дополнительно создаёт: ```text outputs/journal-yuga-runs// state.yaml publication-model.yaml evidence-ledger.yaml protected-core.md intake.md acceptance-criteria.md decision-log.md journal-search-log.md .md story-run-report.md ``` ## 7. Live status `extensions/research-tools/live-status.ts` и story workflow используют `outputs/.status/abulafia-live-status.md`. В UI выводятся публичные сведения: - текущий этап; - активные contracts и skills; - используемые источники и досье; - проверяемая рабочая гипотеза; - последние candidate recommendations; - следующий шаг. Это операционный статус, а не скрытый chain-of-thought модели. Файл является временным: он очищается при старте сессии и перед каждым новым model turn, поэтому завершённый story-run не показывается как текущая работа. ## 8. Packaging Исходная версия устанавливается через npm, а Windows installer создаётся поверх self-contained native bundle. В EXE входят Node.js, production dependencies, runtime workspace, skills, agents, prompts и knowledge base. Основные команды сборки: ```powershell npm run build npm run build:native-bundle npm run build:windows-installer ``` Release workflow собирает native bundles для поддерживаемых платформ и Windows Setup, выполняет smoke-тест установленной CLI и публикует assets в GitHub Release при выпуске новой версии. ## 9. Инварианты безопасности и качества - API keys не сохраняются в проектных артефактах. - Web и paper sources должны иметь проверяемые URL или identifiers. - Непроведённые эксперименты не превращаются в выдуманные результаты. - Story outputs должны соответствовать своим skill contracts. - Состояние Journal-Yuga не должно теряться между уточнениями. - Автоматическое обновление досье только добавляет наблюдения. - `verified` означает, что проверка действительно была выполнена. - Ошибка инструмента фиксируется как blocker; malformed tool calls не должны использоваться как способ продолжения.