Перейти до вмісту
Oleaflyv0.4.12

Налаштуйте репозиторій настільного застосунку 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/: там описано патерн портів, реєстр внесків і з’єднання аліасів.

Вікно термінала
pnpm install
./scripts/fetch-tectonic.sh all
./scripts/fetch-biber.sh all
./scripts/fetch-typst.sh all
pnpm language-servers:fetch
pnpm 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 check
cargo check --workspace --all-targets # Rust workspace compiles
cargo 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

Як працює компіляція

Розділ «Як працює компіляція»
Як компіляція проходить через застосунокФронтенд викликає compileProject через Tauri IPC. У Rust DocumentEngine вибирає рушій проєкту: Tectonic, latexmk, Typst або Pandoc із Tectonic. PDF повертається до переглядача pdf.js як сирий двійковий IPC, а потокові події журналу стають діагностикою в CodeMirror.ФронтендRust, src-tauriЗапит на компіляціюcompileProject()Переглядач pdf.jsПоказує PDFCodeMirrorДіагностикаDocumentEngineВибирає рушійTectoniclatexmkTypstPandoc, TectonicTauri IPCБайти PDFПотокові журналиЯк компіляція проходить через застосунокФронтенд викликає compileProject через Tauri IPC. У Rust DocumentEngine вибирає рушій проєкту: Tectonic, latexmk, Typst або Pandoc із Tectonic. PDF повертається до переглядача pdf.js як сирий двійковий IPC, а потокові події журналу стають діагностикою в CodeMirror.ФронтендcompileProject()DocumentEngineУ RustРушійTectonic, latexmk,Typst або Pandocpdf.jsПоказує PDFCodeMirrorДіагностикаTauri IPCPDFЖурнали
Фронтенд просить Rust скомпілювати, і DocumentEngine запускає рушій проєкту. PDF повертається як двійковий IPC, а потокові журнали перетворюються на діагностику.
  1. Фронтенд завантажує з бекенда дескриптор project_engine і його прапорці можливостей, а потім викликає compileProject(projectId, mainDoc, offline) через Tauri IPC.
  2. Rust виконує диспетчеризацію через DocumentEngine. Код інтерфейсу не повинен робити висновків про поведінку рушія з імені файлу.
  3. LaTeX типово використовує вбудований Tectonic. Замість цього проєкт може обрати pdfLaTeX, XeLaTeX або LuaLaTeX через latexmk. Повна системна установка TeX має пріоритет над керованим Oleafly TinyTeX. Спільний детектор вимагає наявності основних компіляторів, latexmk, kpsewhich і Biber, перш ніж надати цей пріоритет.
  4. Typst запускає точно ту версію, яку проєкт закріпив у project.json: вбудований sidecar, завантаження з перевіреною контрольною сумою або системний typst, що повідомляє цю версію. Він компілює обраний головний документ .typ зі зрозумілими людині діагностичними повідомленнями та явним шляхом виводу PDF. Коли увімкнена автокомпіляція, Rust натомість тримає один процес typst watch на проєкт (src-tauri/src/typst_watch.rs). Розв’язання версій, закріплення та відповідний Tinymist описано в docs/typst-toolchain.md репозиторію настільного застосунку.
  5. 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 і збірки релізу використовують ті самі скрипти.

  1. Усі рушії передають потоком нормалізовані події журналу й помилок. Rust повертає метадані компіляції через JSON IPC. Сам PDF отримується окремо як сирі двійкові дані через IPC, а не вбудовується в результат як base64.
  2. Фронтенд відтворює байти 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. Див. випуск релізів та встановлення для користувачів.

Перегляд зображення

Не вдалося завантажити відповіді ШІ

Спробуйте ще раз або скористайтеся пошуком у документації.