Розробка
Налаштуйте репозиторій настільного застосунку Oleafly, завантажте його закріплені sidecar-бінарники, запустіть застосунок і зрозумійте головні точки розширення.
Oleafly — це настільний застосунок Tauri 2 (відкривається в новій вкладці). Його фронтенд на React і TypeScript спілкується з Rust через Tauri IPC. 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/Фронтенд — це робочий простір 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Перевірки перед відкриттям pull request
Розділ «Перевірки перед відкриттям pull request»Запустіть відповідні локальні перевірки перед відкриттям 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 записує їхні поточні результати при кожній зміні коду. Локальний запуск поза мережею не може засвідчити, що в графі залежностей немає жодного advisory.
Для змін, видимих користувачам, також запустіть наскрізний набір тестів проти справжнього застосунку й компілятора. Див. e2e/README.md (відкривається в новій вкладці).
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downЯк працює компіляція
Розділ «Як працює компіляція»- Фронтенд завантажує з бекенда дескриптор
project_engineі його прапорці можливостей, а потім викликаєcompileProject(projectId, mainDoc, offline)через Tauri IPC. - Rust виконує диспетчеризацію через
DocumentEngine. Код інтерфейсу не повинен робити висновків про поведінку рушія з імені файлу. - LaTeX типово використовує вбудований Tectonic. Замість цього проєкт може обрати pdfLaTeX, XeLaTeX або LuaLaTeX через
latexmk. Повна системна установка TeX має пріоритет над керованим Oleafly TinyTeX. Спільний детектор вимагає наявності основних компіляторів,latexmk,kpsewhichі Biber, перш ніж надати цей пріоритет. - Typst запускає точно ту версію, яку проєкт закріпив у
project.json: вбудований sidecar, завантаження з перевіреною контрольною сумою або системний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 щодо sidecar (відкривається в новій вкладці) визначає входи bundle.externalBin із суфіксами цільових триплетів і відкриває упакований sidecar під іменем без суфікса під час виконання. Адаптер 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, відкрийте правдиві можливості, додайте закріплений контрольними сумами шлях завантаження й перевірки sidecar, потім споживайте дескриптор у елементах керування інтерфейсу. - Додати шаблон проєкту → покладіть теку з маніфестом
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: ідіоматично, невеликі команди, доброзичливі рядки помилок.
- UI: Tailwind v4 + токени Geist. Повторно використовуйте примітиви
Button,TooltipіSelect.
Випуск
Розділ «Випуск»Пакування орієнтується на macOS Apple Silicon, Windows x64, Linux x64 і Linux ARM64. Кожна збірка завантажує й перевіряє свої sidecar-компілятори та вбудований ресурс мовних серверів. Релізні збірки підтримують підписування й нотаризацію Apple на macOS та Azure Artifact Signing на Windows. Див. випуск релізів та встановлення для користувачів.