跳到內容
Oleaflyv0.4.12

設定 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/ 之前,請先讀 前端架構:它說明了連接埠模式、貢獻註冊表,以及別名的設定方式。

終端機視窗
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 目標三元組(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

開啟 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

這兩個 audit 指令需要連上套件庫(registry)或網路。CI 在每次程式碼變更時都會記錄它們目前的結果。離線的本機執行無法證明相依關係圖沒有任何安全公告。

若是會影響使用者的變更,也請對真實的應用程式和編譯器執行端對端測試套件。請參閱 e2e/README.md (在新分頁開啟)。

終端機視窗
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears down
一次編譯如何在應用程式中流動前端透過 Tauri IPC 呼叫 compileProject。在 Rust 中,DocumentEngine 會選出專案的引擎:Tectonic、latexmk、Typst,或 Pandoc 搭配 Tectonic。PDF 以原始二進位 IPC 回到 pdf.js 檢視器,串流的記錄事件則在 CodeMirror 中變成診斷訊息。前端Rust, src-tauri編譯請求compileProject()pdf.js 檢視器顯示 PDFCodeMirror診斷DocumentEngine選擇引擎TectoniclatexmkTypstPandoc, TectonicTauri IPCPDF 位元組串流記錄一次編譯如何在應用程式中流動前端透過 Tauri IPC 呼叫 compileProject。在 Rust 中,DocumentEngine 會選出專案的引擎:Tectonic、latexmk、Typst,或 Pandoc 搭配 Tectonic。PDF 以原始二進位 IPC 回到 pdf.js 檢視器,串流的記錄事件則在 CodeMirror 中變成診斷訊息。前端compileProject()DocumentEngine在 Rust 中引擎Tectonic, latexmk,Typst 或 Pandocpdf.js顯示 PDFCodeMirror診斷Tauri IPCPDF記錄檔
前端要求 Rust 編譯,由 DocumentEngine 執行專案的引擎。PDF 以二進位 IPC 傳回,串流的記錄則變成診斷訊息。
  1. 前端載入後端的 project_engine 描述與它的能力旗標,然後透過 Tauri IPC 呼叫 compileProject(projectId, mainDoc, offline)。
  2. Rust 透過 DocumentEngine 分派。UI 程式碼不可以從檔名推測引擎的行為。
  3. LaTeX 預設使用內建的 Tectonic。專案也可以改為透過 latexmk 選用 pdfLaTeX、XeLaTeX 或 LuaLaTeX。完整的系統 TeX 安裝優先於 Oleafly 管理的 TinyTeX。共用的偵測程式要求核心編譯器、latexmk、kpsewhich 和 Biber 都齊全,才會給予這項優先權。
  4. Typst 會執行專案在 project.json 中鎖定的確切版本:內建的 sidecar、經過檢查碼驗證的下載,或回報該版本的系統 typst。它會編譯選定的 .typ 主要文件,輸出人類可讀的診斷訊息,並使用明確指定的 PDF 輸出路徑。開啟自動編譯時,Rust 改為為每個專案維持一個 typst watch 程序(src-tauri/src/typst_watch.rs)。桌面版儲存庫的 docs/typst-toolchain.md 說明了版本解析、鎖定,以及對應的 Tinymist。
  5. 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 和發行建置使用相同的腳本。

  1. 所有引擎都會串流輸出正規化的記錄與錯誤事件。Rust 透過 JSON IPC 回傳編譯中繼資料。PDF 本身則以原始二進位 IPC 另外取得,而不是以 base64 嵌入結果中。
  2. 前端用 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/ 中註冊(請參閱 前端架構)。

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。請參閱 發行 與使用者適用的 安裝。

圖片預覽

無法載入 AI 回答

請再試一次,或搜尋文件。