Entwicklung
Das Oleafly-Desktop-Repository einrichten, seine gepinnten Sidecars abrufen, die App ausführen und die wichtigsten Erweiterungspunkte verstehen.
Oleafly ist eine Tauri 2 (öffnet in einem neuen Tab)-Desktop-App. Das React- und TypeScript-Frontend spricht über Tauri IPC mit Rust. Rust verwaltet Projektdateien, das Kompilieren, Secrets, MCP-Routing und Anfragen an KI-Anbieter.
Aufbau des Repositorys
Abschnitt betitelt „Aufbau des Repositorys“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/Das Frontend ist ein pnpm-Workspace. Wiederverwendbare Features liegen in packages/* hinter injizierten Ports, und die App-Shell verdrahtet sie miteinander. Lesen Sie Frontend-Architektur, bevor Sie packages/ anfassen: der Text erklärt das Port-Muster, die Contribution-Registry und die Alias-Verdrahtung.
Voraussetzungen
Abschnitt betitelt „Voraussetzungen“- Node.js 22.13+ und pnpm 11.9+ (die genaue pnpm-Version ist in
package.jsondeklariert) - Rust (stable) über rustup (öffnet in einem neuen Tab)
- Tauri-2-Systemabhängigkeiten (öffnet in einem neuen Tab) für Ihr Betriebssystem
- Optional bei der Einrichtung: pandoc (öffnet in einem neuen Tab) für die Kompilierung von Markdown zu PDF und den Dokumentexport (die App kann ihre gepinnte Version bei Bedarf selbst installieren)
Erster Start
Abschnitt betitelt „Erster Start“pnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri devFür eine einzelne Plattform übergeben Sie deren Rust-Target-Triple an jedes Shell-Abrufskript. Mit rustc -vV finden Sie das Triple des Hosts. Der Language-Server-Befehl wählt den aktuellen Host, außer Sie übergeben ein Ziel an das zugrunde liegende Skript.
Im Alltag
Abschnitt betitelt „Im Alltag“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 bundlePrüfungen vor einem Pull-Request
Abschnitt betitelt „Prüfungen vor einem Pull-Request“Führen Sie die einschlägigen lokalen Prüfungen aus, bevor Sie einen Pull-Request öffnen:
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 sourcesDie beiden Audit-Befehle brauchen Zugriff auf die Registry und das Netzwerk. CI zeichnet ihre aktuellen Ergebnisse bei jeder Codeänderung auf. Ein lokaler Lauf ohne Netzwerk kann nicht bestätigen, dass der Abhängigkeitsgraph frei von Advisories ist.
Führen Sie bei Änderungen, die Benutzer sehen, zusätzlich die End-to-End-Suite gegen die echte App und den echten Compiler aus. Siehe e2e/README.md (öffnet in einem neuen Tab).
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downWie ein Kompiliervorgang abläuft
Abschnitt betitelt „Wie ein Kompiliervorgang abläuft“- Das Frontend lädt den
project_engine-Deskriptor des Backends und seine Capability-Flags und ruft danncompileProject(projectId, mainDoc, offline)über Tauri IPC auf. - Rust dispatcht über
DocumentEngine. UI-Code darf das Verhalten einer Engine nicht aus einem Dateinamen ableiten. - LaTeX nutzt standardmäßig das mitgelieferte Tectonic. Ein Projekt kann stattdessen pdfLaTeX, XeLaTeX oder LuaLaTeX über
latexmkwählen. Eine vollständige System-TeX-Installation hat Vorrang vor Oleaflys verwaltetem TinyTeX. Der gemeinsame Detektor verlangt die Kern-Compiler,latexmk,kpsewhichund Biber, bevor er diesen Vorrang gewährt. - Typst führt genau die Version aus, die das Projekt in
project.jsonpinnt: das mitgelieferte Sidecar, ein per Prüfsumme verifizierter Download oder ein System-typst, das diese Version meldet. Es kompiliert das ausgewählte.typ-Hauptdokument mit gut lesbaren Diagnosen und einem expliziten PDF-Ausgabepfad. Mit „Automatisch kompilieren“ hält Rust stattdessen einentypst watch-Prozess pro Projekt am Laufen (src-tauri/src/typst_watch.rs).docs/typst-toolchain.mdim Desktop-Repository behandelt Auflösung, Pins und das passende Tinymist. - Markdown ruft Pandoc direkt für
.md/.markdownauf, mit einem expliziten Ausgabepfad und--pdf-engine=<absolute bundled Tectonic path>. Pandocs Handbuch unterstützt ausdrücklich einen vollständigen PDF-Engine-Pfad. Ersetzen Sie das nicht durch ein implizites System-pdflatex, denn das paketierte Oleafly darf nicht von einer nicht deklarierten TeX-Installation abhängen. Der Prozess läuft mit dem Projektstamm als Arbeitsverzeichnis, damit relative Bilder, Bibliografiedateien und CSL-Dateien sowohl für Hauptdokumente im Stamm als auch für verschachtelte Hauptdokumente funktionieren.
Tauris Sidecar-Dokumentation (öffnet in einem neuen Tab) definiert bundle.externalBin-Eingaben mit Target-Triple-Suffixen und legt das paketierte Sidecar zur Laufzeit unter seinem Namen ohne Suffix offen. Oleaflys Pandoc-Adapter findet die gepackte ausführbare Tectonic-Datei neben der ausführbaren Datei der Anwendung, passend zum Desktop-Bundle-Layout von Tauri. Unit-Tests decken die Kandidaten App-Bundle unter macOS sowie Cargo debug/release ab, während der Release-Workflow auf jedem Ziel das bereitgestellte Gegenstück ohne Suffix prüft.
Downloads von Tectonic, Biber, Typst und Language-Servern sind versioniert und mit Prüfsummen gepinnt. Ihre Abrufskripte prüfen die Archivstruktur und entpacken nur die gesichteten ausführbaren Dateien oder Ressourcenpfade. CI und Release-Builds verwenden dieselben Skripte.
- Alle Engines streamen normalisierte Protokoll- und Fehlerereignisse. Rust gibt die Kompilier-Metadaten über JSON-IPC zurück. Das PDF selbst wird separat als rohe Binärdaten über IPC geholt, statt als Base64 in das Ergebnis eingebettet zu werden.
- Das Frontend rendert die PDF-Bytes mit pdf.js und veröffentlicht die normalisierten Diagnosen in CodeMirror.
Engine-Deskriptoren bilden die Kompilierungsrichtlinie ab, dazu Formatierungs- und Quelltext-Preflight-Profile sowie Mengen von Features, Exportformaten und Vorlagenarten. Frontend-Verbraucher nutzen den fail-closed Deskriptor des Dateispeichers, statt aus Dateiendungen zu raten. Siehe die Matrix der Dokument-Engines (öffnet in einem neuen Tab).
Typst meldet supports_synctex=true und supports_offline=true, dazu supports_isolated_compile=false. Die Synchronisierung von Quelltext und PDF läuft über das zum Projekt passende Tinymist und braucht Tinymist 0.13.30 oder neuer; darum setzt typst_toolchain::describe_project supports_synctex für ein auf Typst 0.11 oder 0.12 gepinntes Projekt auf false herab (typst_sync::supported_for_project). Der Offline-Modus blockiert Typst-Paket-Downloads, ein Kompiliervorgang nutzt dann nur den gemeinsamen Paketzwischenspeicher und den Ordner typst-packages des Projekts. Die isolierte Kompilierung bleibt LaTeX vorbehalten: der TikZ-Figurenpfad lehnt Typst-Projekte ab, und die Figuren-Werkzeuge des Assistenten rendern Typst-Schnipsel, etwa eine CeTZ-Leinwand oder ein fletcher-Diagramm, stattdessen mit render_typst_snippet. Fügen Sie Engine-Verhalten erst hinzu, wenn die Fähigkeit des Backends wahrheitsgemäß ist. Fügen Sie keine UI-Ausnahmen anhand von Dateiendungen hinzu.
Wo der Zustand liegt
Abschnitt betitelt „Wo der Zustand liegt“- Konfiguration:
~/.oleafly/config.json(0600unter Unix). Nicht vertrauliche Einstellungen liegen hier. - Secrets:
~/.oleafly/ai-secrets.jsonund~/.oleafly/app-secrets.json, verschlüsselt mit dem~/.oleafly/ai-secrets.key, das nur dem Eigentümer gehört. GitHub und MCP teilen sichapp-secrets.json. Zugangsdaten für KI-Anbieter verwendenai-secrets.json. - Projekte:
~/.oleafly/projects/<id>/, gewöhnliche Ordner mit.git. - App-Protokoll:
~/.oleafly/app.log.
Wichtige Erweiterungspunkte
Abschnitt betitelt „Wichtige Erweiterungspunkte“- KI-Anbieter hinzufügen →
crates/oleafly-agent/src/provider.rsaktualisieren und dann seine Anzeige-Metadaten inpackages/ai-core/src/providers.tsspiegeln. Der Katalog-Paritätstest hält die beiden Listen deckungsgleich. - Tauri-Befehl hinzufügen → in
src-tauri/src/*.rsdeklarieren, insrc-tauri/src/lib.rsregistrieren, insrc/lib/tauri.tskapseln. - Dokument-Engine hinzufügen →
DocumentEngineinsrc-tauri/src/document_engine.rsimplementieren, wahrheitsgemäße Fähigkeiten anzeigen, einen per Prüfsumme gepinnten Pfad für Sidecar-Abruf und Smoke-Test anlegen und den Deskriptor dann in UI-Steuerelementen verwenden. - Projektvorlage hinzufügen → einen Ordner mit einem
template.json-Manifest insrc-tauri/resources/templates/ablegen (von der Engine unabhängige Vorlagen-Metadaten sind weiterhin geplante Arbeit). - Werkzeug für die KI hinzufügen →
packages/ai-tools/src/tools.ts. App-Dienste, die es braucht, laufen überAiToolsHostinsrc/lib/ai-tools.ts. - Rail-Tab, Paletten- oder Omnibar-Befehl oder KI-Werkzeugsatz hinzufügen → in
src/contributions/registrieren (siehe Frontend-Architektur).
Interna zu Synchronisierung und GitHub
Abschnitt betitelt „Interna zu Synchronisierung und GitHub“Der OAuth-Device-Flow läuft serverseitig in Rust (src-tauri/src/github.rs), weil die OAuth-Endpunkte CORS nicht erlauben. Die API-Aufrufe (api.github.com) erfolgen vom Frontend aus.
Code-Stil
Abschnitt betitelt „Code-Stil“- TypeScript: Orientieren Sie sich am Bestehenden. Keine Kommentare, sofern nicht darum gebeten wird. Beachten Sie
noUnusedLocals/noUnusedParameters. - Rust: idiomatisch, kleine Befehle, freundlich formulierte Fehlermeldungen.
- UI: Tailwind v4 + Geist-Tokens. Verwenden Sie die Primitives
Button,TooltipundSelectwieder.
Veröffentlichen
Abschnitt betitelt „Veröffentlichen“Die Paketierung zielt auf macOS Apple Silicon, Windows x64, Linux x64 und Linux ARM64. Jeder Build lädt seine Compiler-Sidecars und die gebündelte Language-Server-Ressource herunter und prüft sie. Release-Builds unterstützen Apples Signieren und Notarisierung unter macOS sowie Azure Artifact Signing unter Windows. Siehe Veröffentlichen und Installieren für Benutzer.