開發
設定 Oleafly 桌面版儲存庫、取得它鎖定版本的 sidecar、執行應用程式,並了解主要的擴充點。
Oleafly 是一款 Tauri 2 (在新分頁開啟) 桌面應用程式。它以 React 和 TypeScript 寫成的前端,透過 Tauri IPC 與 Rust 溝通。Rust 負責專案檔案、編譯、機密資料、MCP 路由,以及 AI 供應商的請求。
儲存庫結構
標題為「儲存庫結構」的段落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/* 中,位於注入的連接埠(port)後面,再由應用程式外殼把它們串在一起。動手改 packages/ 之前,請先讀 前端架構:它說明了連接埠模式、貢獻註冊表,以及別名的設定方式。
先決條件
標題為「先決條件」的段落- Node.js 22.13 以上與 pnpm 11.9 以上(確切的 pnpm 版本宣告在
package.json中) - 透過 rustup (在新分頁開啟) 安裝的 Rust(stable)
- 你的作業系統所需的 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 dev若只需要單一平台,請把該平台的 Rust 目標三元組(target triple)傳給每個 shell 取得腳本。用 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這兩個 audit 指令需要連上套件庫(registry)或網路。CI 在每次程式碼變更時都會記錄它們目前的結果。離線的本機執行無法證明相依關係圖沒有任何安全公告。
若是會影響使用者的變更,也請對真實的應用程式和編譯器執行端對端測試套件。請參閱 e2e/README.md (在新分頁開啟)。
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears down編譯如何運作
標題為「編譯如何運作」的段落- 前端載入後端的
project_engine描述與它的能力旗標,然後透過 Tauri IPC 呼叫compileProject(projectId, mainDoc, offline)。 - Rust 透過
DocumentEngine分派。UI 程式碼不可以從檔名推測引擎的行為。 - LaTeX 預設使用內建的 Tectonic。專案也可以改為透過
latexmk選用 pdfLaTeX、XeLaTeX 或 LuaLaTeX。完整的系統 TeX 安裝優先於 Oleafly 管理的 TinyTeX。共用的偵測程式要求核心編譯器、latexmk、kpsewhich和 Biber 都齊全,才會給予這項優先權。 - Typst 會執行專案在
project.json中鎖定的確切版本:內建的 sidecar、經過檢查碼驗證的下載,或回報該版本的系統typst。它會編譯選定的.typ主要文件,輸出人類可讀的診斷訊息,並使用明確指定的 PDF 輸出路徑。開啟自動編譯時,Rust 改為為每個專案維持一個typst watch程序(src-tauri/src/typst_watch.rs)。桌面版儲存庫的docs/typst-toolchain.md說明了版本解析、鎖定,以及對應的 Tinymist。 - Markdown 會直接對
.md/.markdown呼叫 Pandoc,使用明確指定的輸出路徑和--pdf-engine=<absolute bundled Tectonic path>。Pandoc 的手冊明確支援完整的 PDF 引擎路徑。請不要把它換成隱含的系統pdflatex,因為打包後的 Oleafly 不能依賴未宣告的 TeX 安裝。這個程序以專案根目錄作為工作目錄,因此不論主要文件在根目錄或巢狀資料夾中,相對路徑的圖片、參考文獻檔案和 CSL 檔案都能正常運作。
Tauri 的 sidecar 文件 (在新分頁開啟) 定義了帶有目標三元組後綴的 bundle.externalBin 輸入,並在執行階段以不含後綴的名稱提供打包後的 sidecar。Oleafly 的 Pandoc 轉接器會在應用程式執行檔旁邊解析出打包後的 Tectonic 執行檔,與 Tauri 桌面版套件的配置一致。單元測試涵蓋 macOS 應用程式套件與 Cargo 的 debug/release 候選路徑,而發行工作流程會在每個目標上檢查暫存的、不含後綴的同層檔案。
Tectonic、Biber、Typst 和語言伺服器的下載都有版本並以檢查碼鎖定。它們的取得腳本會驗證壓縮檔結構,只解出經過審查的執行檔或資源路徑。CI 和發行建置使用相同的腳本。
- 所有引擎都會串流輸出正規化的記錄與錯誤事件。Rust 透過 JSON IPC 回傳編譯中繼資料。PDF 本身則以原始二進位 IPC 另外取得,而不是以 base64 嵌入結果中。
- 前端用 pdf.js 轉譯 PDF 位元組,並把正規化的診斷訊息發布到 CodeMirror。
引擎描述除了編譯策略之外,還包含格式化/原始碼預檢設定檔,以及功能、匯出和範本類型的集合。前端使用端要採用預設為拒絕(fail-closed)的檔案儲存區描述,而不要從副檔名去猜。請參閱 文件引擎矩陣 (在新分頁開啟)。
Typst 回報 supports_synctex=true 和 supports_offline=true,以及 supports_isolated_compile=false。原始碼與 PDF 的同步,是透過專案對應的 Tinymist 執行,需要 Tinymist 0.13.30 或更新版本,因此對於鎖定 Typst 0.11 或 0.12 的專案,typst_toolchain::describe_project 會把 supports_synctex 降為 false(typst_sync::supported_for_project)。離線模式會阻擋 Typst 套件下載,因此編譯時只使用共用的套件快取和專案的 typst-packages 資料夾。獨立編譯仍僅限 LaTeX:TikZ 圖片的流程會拒絕 Typst 專案,助理的圖片工具則改用 render_typst_snippet 來轉譯 Typst 片段,例如 CeTZ 畫布或 fletcher 圖表。只有在後端能力如實反映之後,才新增引擎行為。不要新增依副檔名而定的 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。目錄一致性測試會讓這兩份清單保持對齊。 - 新增 Tauri 指令 → 在
src-tauri/src/*.rs中宣告,在src-tauri/src/lib.rs中註冊,並在src/lib/tauri.ts中包裝。 - 新增文件引擎 → 在
src-tauri/src/document_engine.rs中實作DocumentEngine,如實公開能力,加上以檢查碼鎖定的 sidecar 取得與冒煙測試流程,然後在 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 裝置流程在 Rust 的伺服器端執行(src-tauri/src/github.rs),因為 OAuth 端點沒有啟用 CORS。API 呼叫(api.github.com)則由前端發出。
程式碼風格
標題為「程式碼風格」的段落- TypeScript:照著現有的寫法。除非被要求,否則不加註解。遵守
noUnusedLocals/noUnusedParameters。 - Rust:寫慣用的 Rust,指令要小,錯誤字串要友善。
- UI:Tailwind v4 加上 Geist 設計變數(token)。重複使用
Button、Tooltip和Select這些基本元件。
打包的目標平台有 macOS Apple Silicon、Windows x64、Linux x64 和 Linux ARM64。每次建置都會取得並檢查它的編譯器 sidecar 與內建的語言伺服器資源。發行建置在 macOS 上支援 Apple 簽署與公證,在 Windows 上支援 Azure Artifact Signing。請參閱 發行 與使用者適用的 安裝。