開発
Oleafly デスクトップのリポジトリをセットアップし、バージョンが固定されたサイドカーを取得し、アプリを実行して、主な拡張ポイントを理解します。
Oleafly は Tauri 2 (新しいタブで開きます) のデスクトップアプリです。React と TypeScript のフロントエンドが、Tauri IPC を通じて Rust と通信します。プロジェクトのファイル、コンパイル、シークレット、MCP のルーティング、AI プロバイダへのリクエストは、Rust が担当します。
リポジトリの構成
「リポジトリの構成」セクション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に宣言されています) - rustup (新しいタブで開きます) 経由の Rust(stable)
- お使いの OS 向けの Tauri 2 のシステム依存関係 (新しいタブで開きます)
- セットアップ時は任意: Markdown の PDF コンパイルと文書の書き出しに使う pandoc (新しいタブで開きます)(アプリが、固定バージョンのビルドを必要に応じてインストールできます)
初回の実行
「初回の実行」セクションpnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri dev1 つのプラットフォームだけを対象にするには、各シェルの取得スクリプトに、その 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 bundlePR を開く前のチェック
「PR を開く前のチェック」セクションプルリクエストを開く前に、該当するローカルのチェックを実行します。
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 sources2 つの audit コマンドには、レジストリ/ネットワークへのアクセスが必要です。CI は、コードを変更するたびに、それらの最新の結果を記録します。オフラインのローカル実行では、依存関係のグラフにアドバイザリがないことを保証できません。
ユーザーに見える変更では、実際のアプリとコンパイラに対するエンドツーエンドのスイートも実行します。e2e/README.md (新しいタブで開きます)を参照してください。
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downコンパイルの仕組み
「コンパイルの仕組み」セクション- フロントエンドは、バックエンドの
project_engineディスクリプタとその capability フラグを読み込み、Tauri IPC を通じてcompileProject(projectId, mainDoc, offline)を呼び出します。 - Rust は
DocumentEngineを通じて処理を振り分けます。UI のコードが、ファイル名からエンジンの動作を推測してはいけません。 - LaTeX は既定で、同梱の Tectonic を使います。プロジェクトは代わりに、
latexmk経由で pdfLaTeX、XeLaTeX、LuaLaTeX を選べます。完全なシステムの TeX インストールは、Oleafly が管理する TinyTeX より優先されます。共有の検出処理は、その優先を認める前に、中核となるコンパイラ、latexmk、kpsewhich、Biber がそろっていることを要求します。 - Typst は、プロジェクトが
project.jsonで固定した正確なバージョンを実行します。同梱のサイドカー、チェックサム検証済みのダウンロード、またはそのバージョンを報告するシステムのtypstのいずれかです。選択された.typのメイン文書を、人が読める診断と、明示的な PDF の出力パスでコンパイルします。自動コンパイルがオンの場合は、代わりに Rust がプロジェクトごとに 1 つのtypst watchプロセスを保持します(src-tauri/src/typst_watch.rs)。バージョンの解決、固定、対応する Tinymist については、デスクトップのリポジトリのdocs/typst-toolchain.mdで説明しています。 - Markdown は、
.md/.markdownに対して Pandoc を直接呼び出し、明示的な出力パスと--pdf-engine=<absolute bundled Tectonic path>を指定します。Pandoc のマニュアルは、PDF エンジンのフルパスを明示的にサポートしています。これを、暗黙のシステムのpdflatexに置き換えてはいけません。パッケージ化された Oleafly が、宣言されていない TeX のインストールに依存してはならないからです。プロセスはプロジェクトのルートを作業ディレクトリとして実行されるため、相対パスの画像、参考文献ファイル、CSL ファイルが、ルートにあるメイン文書でも、入れ子の場所にあるメイン文書でも動作します。
Tauri のサイドカーのドキュメント (新しいタブで開きます)は、ターゲットトリプルの接尾辞が付いた bundle.externalBin の入力を定義し、実行時には、パッケージ化されたサイドカーを接尾辞なしの名前で公開します。Oleafly の Pandoc アダプターは、Tauri のデスクトップバンドルの構成に合わせて、パッケージ化された Tectonic の実行ファイルを、アプリケーションの実行ファイルの隣から解決します。ユニットテストは、macOS のアプリバンドルと Cargo の debug/release の候補をカバーし、リリースのワークフローは、すべてのターゲットで、ステージされた接尾辞なしの兄弟ファイルを検査します。
Tectonic、Biber、Typst、言語サーバーのダウンロードは、バージョンとチェックサムが固定されています。取得スクリプトは、アーカイブの構造を検証し、レビュー済みの実行ファイルまたはリソースのパスだけを展開します。CI とリリースのビルドも、同じスクリプトを使います。
- すべてのエンジンが、正規化されたログ/エラーのイベントをストリーミングします。Rust は、コンパイルのメタデータを JSON IPC で返します。PDF 自体は、結果に base64 で埋め込むのではなく、生のバイナリ IPC として別に取得されます。
- フロントエンドは、pdf.js で PDF のバイト列を描画し、正規化された診断を CodeMirror に渡します。
エンジンのディスクリプタは、コンパイルのポリシーに加えて、整形/ソースのプリフライトのプロファイルと、機能/書き出し/テンプレート種別の集合を表現します。フロントエンドの利用側は、拡張子から推測するのではなく、フェイルクローズドな files ストアのディスクリプタを使います。ドキュメントエンジンの対応表 (新しいタブで開きます)を参照してください。
Typst は supports_synctex=true と supports_offline=true を報告し、supports_isolated_compile=false とします。ソースと PDF の同期は、プロジェクトに対応する Tinymist を通じて動作し、Tinymist 0.13.30 以降が必要です。そのため、typst_toolchain::describe_project は、Typst 0.11 または 0.12 に固定されたプロジェクトでは supports_synctex を false に下げます(typst_sync::supported_for_project)。オフラインモードは Typst のパッケージのダウンロードをブロックするので、コンパイルは、共有のパッケージキャッシュとプロジェクトの typst-packages フォルダだけを使います。分離したコンパイルは LaTeX 専用のままです。TikZ の図の経路は Typst プロジェクトを拒否し、アシスタントの図のツールは、CeTZ のキャンバスや fletcher のダイアグラムといった Typst のスニペットを、代わりに render_typst_snippet で描画します。エンジンの動作を追加するのは、バックエンドの capability が実態に合ってからにしてください。拡張子に基づく UI の例外を追加してはいけません。
状態の置き場所
「状態の置き場所」セクション- 設定:
~/.oleafly/config.json(Unix では0600)。シークレットではない環境設定は、ここに置かれます。 - シークレット:
~/.oleafly/ai-secrets.jsonと~/.oleafly/app-secrets.json。所有者だけが読める~/.oleafly/ai-secrets.keyで暗号化されます。GitHub と MCP はapp-secrets.jsonを共有します。AI プロバイダの認証情報はai-secrets.jsonを使います。 - プロジェクト:
~/.oleafly/projects/<id>/。.gitを持つふつうのフォルダです。 - アプリのログ:
~/.oleafly/app.log。
主な拡張ポイント
「主な拡張ポイント」セクション- AI プロバイダを追加する →
crates/oleafly-agent/src/provider.rsを更新し、その表示用メタデータをpackages/ai-core/src/providers.tsに反映します。カタログのパリティテストが、2 つの一覧の一致を保ちます。 - Tauri コマンドを追加する →
src-tauri/src/*.rsで宣言し、src-tauri/src/lib.rsに登録し、src/lib/tauri.tsでラップします。 - ドキュメントエンジンを追加する →
src-tauri/src/document_engine.rsでDocumentEngineを実装し、実態に合った capability を公開し、チェックサムを固定したサイドカーの取得/スモークテストの経路を追加してから、UI のコントロールでディスクリプタを利用します。 - プロジェクトのテンプレートを追加する →
template.jsonのマニフェストを持つフォルダをsrc-tauri/resources/templates/に置きます(エンジンを問わない汎用のテンプレートメタデータは、今後の作業として残っています)。 - AI 用のツールを追加する →
packages/ai-tools/src/tools.ts。ツールが必要とするアプリのサービスは、src/lib/ai-tools.tsのAiToolsHostを通します。 - レールのタブ/パレットまたはオムニバーのコマンド/AI ツールセットを追加する →
src/contributions/に登録します(フロントエンドのアーキテクチャを参照)。
同期と GitHub の内部
「同期と GitHub の内部」セクションOAuth のデバイスフローは、OAuth のエンドポイントが CORS に対応していないため、Rust 側(src-tauri/src/github.rs)で実行されます。API の呼び出し(api.github.com)は、フロントエンドから行われます。
コーディングスタイル
「コーディングスタイル」セクション- TypeScript: 既存のコードに合わせます。頼まれない限り、コメントは書きません。
noUnusedLocals/noUnusedParametersを守ります。 - Rust: 慣用的な書き方で、コマンドは小さく、エラーメッセージは親しみやすくします。
- UI: Tailwind v4 と Geist のトークン。
Button、Tooltip、Selectのプリミティブを再利用します。
リリース
「リリース」セクションパッケージ化の対象は、macOS Apple Silicon、Windows x64、Linux x64、Linux ARM64 です。各ビルドは、コンパイラのサイドカーと、同梱の言語サーバーのリソースを取得して検査します。リリースビルドは、macOS では Apple の署名と公証、Windows では Azure Artifact Signing に対応しています。リリースと、ユーザー向けのインストールを参照してください。