# 開發

設定 Oleafly 桌面版儲存庫、取得它鎖定版本的 sidecar、執行應用程式，並了解主要的擴充點。

Oleafly 是一款 [Tauri 2](https://tauri.app) 桌面應用程式。它以 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/` 之前，請先讀 [前端架構](/docs/engineering/architecture/)：它說明了連接埠模式、貢獻註冊表，以及別名的設定方式。

## 先決條件

- Node.js 22.13 以上與 pnpm 11.9 以上（確切的 pnpm 版本宣告在 `package.json` 中）
- 透過 [rustup](https://rustup.rs) 安裝的 Rust（stable）
- 你的作業系統所需的 [Tauri 2 系統相依套件](https://v2.tauri.app/start/prerequisites/)
- 設定期間可選：用於 Markdown PDF 編譯與文件匯出的 [pandoc](https://pandoc.org/installing.html)（應用程式可以視需要安裝它鎖定的版本）

## 第一次執行

```bash
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` 可以查出主機的三元組。語言伺服器的指令預設會選用目前的主機，除非你透過它底層的腳本傳入目標。

## 日常開發

```bash
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 之前的檢查

開啟 pull request 之前，請先在本機執行相關的檢查：

```bash
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](https://github.com/Oleafly/Oleafly/blob/main/e2e/README.md)。

```bash
pnpm test:e2e:app                         # builds + launches the app, runs Playwright, tears down
```

## 編譯如何運作

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 文件](https://v2.tauri.app/develop/sidecar/) 定義了帶有目標三元組後綴的 `bundle.externalBin` 輸入，並在執行階段以不含後綴的名稱提供打包後的 sidecar。Oleafly 的 Pandoc 轉接器會在應用程式執行檔旁邊解析出打包後的 Tectonic 執行檔，與 Tauri 桌面版套件的配置一致。單元測試涵蓋 macOS 應用程式套件與 Cargo 的 debug/release 候選路徑，而發行工作流程會在每個目標上檢查暫存的、不含後綴的同層檔案。

Tectonic、Biber、Typst 和語言伺服器的下載都有版本並以檢查碼鎖定。它們的取得腳本會驗證壓縮檔結構，只解出經過審查的執行檔或資源路徑。CI 和發行建置使用相同的腳本。

6. 所有引擎都會串流輸出正規化的記錄與錯誤事件。Rust 透過 JSON IPC 回傳編譯中繼資料。PDF 本身則以原始二進位 IPC 另外取得，而不是以 base64 嵌入結果中。
7. 前端用 pdf.js 轉譯 PDF 位元組，並把正規化的診斷訊息發布到 CodeMirror。

引擎描述除了編譯策略之外，還包含格式化／原始碼預檢設定檔，以及功能、匯出和範本類型的集合。前端使用端要採用預設為拒絕（fail-closed）的檔案儲存區描述，而不要從副檔名去猜。請參閱 [文件引擎矩陣](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md)。

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/` 中註冊（請參閱 [前端架構](/docs/engineering/architecture/#the-contribution-registry)）。

## 同步與 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。請參閱 [發行](/docs/engineering/releasing/) 與使用者適用的 [安裝](/docs/install/)。
