Разработка
Настройте репозиторий настольного приложения Oleafly, загрузите его закреплённые сайдкары, запустите приложение и разберитесь в основных точках расширения.
Oleafly — настольное приложение на Tauri 2 (откроется в новой вкладке). Его фронтенд на React и TypeScript общается с Rust через IPC Tauri. Rust отвечает за файлы проекта, компиляцию, секреты, маршрутизацию MCP и запросы к провайдерам ИИ.
Структура репозитория
Заголовок раздела «Структура репозитория»Oleafly/├── src/ React app shell (stores, Tauri client, UI kit, port adapters)│ ├── components/ ui (shadcn-style), layout, editor glue, preview panes, ai│ ├── contributions/ registers rail tabs / commands / AI toolsets into the registry│ ├── features/ compile, synctex, export│ ├── lib/ tauri wrappers, github, spellcheck, utils, package shims│ └── store/ zustand stores├── packages/ @oleafly/* frontend packages consumed as TS source│ ├── latex/ latex-intelligence/ ai-core/ ai-tools/ registry/│ └── editor/ preview/ diagram/ preflight/ pdf-to-latex/ templates/ wysiwyg/├── crates/│ └── oleafly-agent/ provider clients, streaming, and agent orchestration├── src-tauri/│ ├── src/ Tauri commands, engines, config, Git, MCP, paths, projects│ ├── binaries/ fetched Tectonic, Biber, and Typst sidecars│ ├── resources/ templates, dictionaries, TeX data, language servers│ └── tauri.conf.json├── scripts/fetch-tectonic.sh├── scripts/fetch-biber.sh├── scripts/fetch-typst.sh├── scripts/fetch-language-servers.mjs└── docs/Фронтенд — это workspace на pnpm. Переиспользуемые функции живут в packages/*
за внедряемыми портами, а оболочка приложения соединяет их вместе. Прочитайте
Архитектуру фронтенда до изменений в
packages/: там описаны паттерн портов, реестр контрибуций и настройка алиасов.
Предварительные требования
Заголовок раздела «Предварительные требования»- Node.js 22.13+ и pnpm 11.9+ (точная версия pnpm объявлена в
package.json) - Rust (stable) через rustup (откроется в новой вкладке)
- Системные зависимости Tauri 2 (откроется в новой вкладке) для вашей ОС
- Необязательно при настройке: pandoc (откроется в новой вкладке) для компиляции PDF из Markdown и экспорта документов (приложение может установить закреплённую сборку по требованию)
Первый запуск
Заголовок раздела «Первый запуск»pnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri devДля одной платформы передайте её целевой триплет Rust в каждый скрипт загрузки. Триплет хоста можно узнать командой rustc -vV. Команда загрузки языковых серверов выбирает текущий хост, если только вы не передадите цель через её базовый скрипт.
Повседневная работа
Заголовок раздела «Повседневная работа»pnpm tauri dev # run the app with hot reload (frontend) + cargo incremental (backend)pnpm build # typecheck + build the frontend (tsc -b && vite build)pnpm tauri build # produce a distributable bundleПроверки перед открытием PR
Заголовок раздела «Проверки перед открытием PR»Перед открытием pull request выполните соответствующие локальные проверки:
pnpm build # frontend typecheck (noUnusedLocals/Parameters on)pnpm test # vitest across src/ and packages/pnpm audit --prod --audit-level high # registry-backed npm advisory checkcargo check --workspace --all-targets # Rust workspace compilescargo deny --manifest-path src-tauri/Cargo.toml check # Rust advisories, licenses, and sourcesОбе команды аудита требуют доступа к реестру и сети. CI записывает их текущие результаты при каждом изменении кода. Локальный запуск без сети не может подтвердить, что граф зависимостей свободен от уязвимостей.
Для изменений, видимых пользователю, дополнительно запустите сквозной набор тестов на реальном приложении и компиляторе. См. e2e/README.md (откроется в новой вкладке).
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downКак работает компиляция
Заголовок раздела «Как работает компиляция»- Фронтенд загружает из бэкенда дескриптор
project_engineи его флаги возможностей, затем вызываетcompileProject(projectId, mainDoc, offline)через IPC Tauri. - Rust выполняет диспетчеризацию через
DocumentEngine. Код интерфейса не должен делать выводов о поведении движка из имени файла. - LaTeX по умолчанию использует встроенный Tectonic. Вместо этого проект может выбрать pdfLaTeX, XeLaTeX или LuaLaTeX через
latexmk. Полная системная установка TeX имеет приоритет над управляемым Oleafly TinyTeX. Общий детектор требует наличия основных компиляторов,latexmk,kpsewhichи Biber, прежде чем предоставить этот приоритет. - Typst запускает ровно ту версию, которую проект закрепил в
project.json: встроенный сайдкар, загрузку с проверенной контрольной суммой или системныйtypst, сообщающий эту версию. Он компилирует выбранный основной документ.typс понятными человеку диагностическими сообщениями и явным путём вывода PDF. При включённой автокомпиляции Rust вместо этого держит один процессtypst watchна проект (src-tauri/src/typst_watch.rs). Разрешение версий, закрепление и подходящий Tinymist описаны вdocs/typst-toolchain.mdрепозитория настольного приложения. - Markdown вызывает Pandoc напрямую для
.md/.markdownс явным путём вывода и--pdf-engine=<absolute bundled Tectonic path>. Руководство Pandoc прямо разрешает полный путь к движку PDF. Не заменяйте его неявным системнымpdflatex: упакованный Oleafly не должен зависеть от необъявленной установки TeX. Процесс запускается с корнем проекта в качестве рабочего каталога, поэтому относительные пути к изображениям, файлам библиографии и файлам CSL работают и для корневых, и для вложенных основных документов.
Документация сайдкаров Tauri (откроется в новой вкладке) определяет
входы bundle.externalBin с суффиксами целевых триплетов и открывает упакованный
сайдкар во время выполнения под именем без суффикса. Адаптер Pandoc в Oleafly
находит этот упакованный исполняемый файл Tectonic рядом с исполняемым файлом
приложения, что соответствует структуре настольного пакета Tauri. Модульные
тесты покрывают кандидатов app-bundle macOS и debug/release Cargo, а рабочий
процесс выпуска проверяет подготовленный соседний файл без суффикса на каждой
целевой платформе.
Загрузки Tectonic, Biber, Typst и языковых серверов версионируются и закреплены контрольными суммами. Их скрипты загрузки проверяют структуру архива и распаковывают только просмотренные пути исполняемых файлов и ресурсов. CI и сборки выпуска используют одни и те же скрипты.
- Все движки передают поток нормализованных событий журнала и ошибок. Rust возвращает метаданные компиляции через JSON IPC. Сам PDF получается отдельно как необработанные двоичные данные через IPC, а не встраивается в результат в виде base64.
- Фронтенд отрисовывает байты PDF с помощью pdf.js и передаёт нормализованные диагностические сообщения в CodeMirror.
Дескрипторы движков описывают политику компиляции, профили форматирования и предпроверки исходника, а также наборы функций, экспорта и типов шаблонов. Потребители на фронтенде используют дескриптор хранилища файлов в режиме fail-closed, а не угадывают по расширениям. См. матрицу движков документов (откроется в новой вкладке).
Typst сообщает supports_synctex=true и supports_offline=true, а
supports_isolated_compile=false. Синхронизация исходника и PDF идёт через
подобранный для проекта Tinymist и требует Tinymist 0.13.30 или новее, поэтому
typst_toolchain::describe_project понижает supports_synctex до false
для проекта, закреплённого на Typst 0.11 или 0.12
(typst_sync::supported_for_project). Офлайн-режим блокирует загрузку пакетов
Typst, поэтому компиляция в нём использует только общий кэш пакетов и папку
typst-packages проекта. Изолированная компиляция остаётся доступной только
для LaTeX: путь рисунков TikZ отклоняет проекты Typst, а инструменты рисунков
ассистента отрисовывают фрагменты Typst, например холст CeTZ или диаграмму
fletcher, через render_typst_snippet. Добавляйте поведение движка только
после того, как возможность бэкенда станет правдивой. Не добавляйте исключения
интерфейса, основанные на расширениях.
Где хранится состояние
Заголовок раздела «Где хранится состояние»- Конфигурация:
~/.oleafly/config.json(0600на Unix). Здесь хранятся несекретные настройки. - Секреты:
~/.oleafly/ai-secrets.jsonи~/.oleafly/app-secrets.json, зашифрованные доступным только владельцу~/.oleafly/ai-secrets.key. GitHub и MCP используют общийapp-secrets.json. Учётные данные провайдеров ИИ хранятся вai-secrets.json. - Проекты:
~/.oleafly/projects/<id>/— обычные папки с.git. - Журнал приложения:
~/.oleafly/app.log.
Основные точки расширения
Заголовок раздела «Основные точки расширения»- Добавить провайдера ИИ → обновите
crates/oleafly-agent/src/provider.rs, затем отразите его отображаемые метаданные вpackages/ai-core/src/providers.ts. Тест согласованности каталога держит оба списка в соответствии. - Добавить команду Tauri → объявите в
src-tauri/src/*.rs, зарегистрируйте вsrc-tauri/src/lib.rs, оберните вsrc/lib/tauri.ts. - Добавить движок документов → реализуйте
DocumentEngineвsrc-tauri/src/document_engine.rs, объявите правдивые возможности, добавьте путь загрузки сайдкара с закреплённой контрольной суммой и дымовой проверки, затем используйте дескриптор в элементах интерфейса. - Добавить шаблон проекта → положите папку с манифестом
template.jsonвsrc-tauri/resources/templates/(общие для движков метаданные шаблонов остаются запланированной работой). - Добавить инструмент для ИИ →
packages/ai-tools/src/tools.ts. Нужные ему сервисы приложения проходят черезAiToolsHostвsrc/lib/ai-tools.ts. - Добавить вкладку рельса / команду палитры или омнибара / набор инструментов ИИ → зарегистрируйте её в
src/contributions/(см. Архитектура фронтенда).
Внутреннее устройство синхронизации и GitHub
Заголовок раздела «Внутреннее устройство синхронизации и GitHub»Поток устройств OAuth выполняется на стороне сервера в Rust (src-tauri/src/github.rs), потому что конечные точки OAuth не поддерживают CORS. Вызовы API (api.github.com) идут из фронтенда.
Стиль кода
Заголовок раздела «Стиль кода»- TypeScript: следуйте тому, что уже есть. Без комментариев, если их не попросили. Соблюдайте
noUnusedLocals/noUnusedParameters. - Rust: идиоматичный код, небольшие команды, понятные сообщения об ошибках.
- Интерфейс: Tailwind v4 и токены Geist. Переиспользуйте примитивы
Button,TooltipиSelect.
Упаковка нацелена на macOS Apple Silicon, Windows x64, Linux x64 и Linux ARM64. Каждая сборка загружает и проверяет свои сайдкары компиляторов и встроенный ресурс языковых серверов. Сборки выпуска поддерживают подписывание и нотаризацию Apple на macOS и Azure Artifact Signing на Windows. См. выпуск релизов и установку для пользователей.