Phát triển
Thiết lập kho mã desktop Oleafly, tải các sidecar đã ghim phiên bản, chạy ứng dụng và hiểu các điểm mở rộng chính.
Oleafly là một ứng dụng desktop Tauri 2 (mở trong thẻ mới). Phần frontend viết bằng React và TypeScript giao tiếp với Rust qua Tauri IPC. Rust quản lý tệp dự án, biên dịch, thông tin mật, định tuyến MCP và các yêu cầu tới nhà cung cấp AI.
Bố cục kho mã
Phần tiêu đề “Bố cục kho mã”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/Phần frontend là một pnpm workspace. Các tính năng dùng lại được nằm trong packages/* đằng sau các port được tiêm vào, và app shell nối chúng lại với nhau. Hãy đọc Kiến trúc frontend trước khi đụng vào packages/: bài viết đó trình bày mẫu hình port, contribution registry và cách nối alias.
Yêu cầu trước
Phần tiêu đề “Yêu cầu trước”- Node.js 22.13+ và pnpm 11.9+ (phiên bản pnpm chính xác được khai báo trong
package.json) - Rust (bản stable) cài qua rustup (mở trong thẻ mới)
- Các phụ thuộc hệ thống của Tauri 2 (mở trong thẻ mới) cho hệ điều hành của bạn
- Tùy chọn khi cài đặt: pandoc (mở trong thẻ mới) để biên dịch PDF từ Markdown và xuất tài liệu (ứng dụng có thể cài bản đã ghim khi cần)
Chạy lần đầu
Phần tiêu đề “Chạy lần đầu”pnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri devĐối với một nền tảng duy nhất, hãy truyền Rust target triple của nền tảng đó vào từng script fetch dạng shell. Dùng rustc -vV để tìm host triple. Lệnh language-server chọn host hiện tại trừ khi bạn truyền target qua script bên dưới của nó.
Công việc hằng ngày
Phần tiêu đề “Công việc hằng ngày”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 bundleCác kiểm tra trước khi mở PR
Phần tiêu đề “Các kiểm tra trước khi mở PR”Chạy các kiểm tra cục bộ liên quan trước khi mở 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 sourcesHai lệnh audit cần truy cập registry/mạng. CI ghi lại kết quả hiện tại của chúng ở mỗi thay đổi mã. Một lần chạy cục bộ ngoại tuyến không thể chứng nhận rằng đồ thị phụ thuộc không chứa advisory nào.
Với các thay đổi hướng tới người dùng, hãy chạy thêm bộ kiểm thử end-to-end trên ứng dụng và trình biên dịch thật. Xem e2e/README.md (mở trong thẻ mới).
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downMột lần biên dịch hoạt động như thế nào
Phần tiêu đề “Một lần biên dịch hoạt động như thế nào”- Frontend tải descriptor
project_enginetừ backend cùng các cờ capability của nó, rồi gọicompileProject(projectId, mainDoc, offline)qua Tauri IPC. - Rust điều phối qua
DocumentEngine. Code UI không được suy đoán hành vi engine từ tên tệp. - LaTeX dùng Tectonic đi kèm theo mặc định. Một dự án có thể thay vào đó chọn pdfLaTeX, XeLaTeX hoặc LuaLaTeX qua
latexmk. Một bản cài TeX hệ thống hoàn chỉnh được ưu tiên hơn TinyTeX do Oleafly quản lý. Bộ dò chung yêu cầu có các trình biên dịch lõi,latexmk,kpsewhichvà Biber trước khi trao quyền ưu tiên đó. - Typst chạy đúng phiên bản mà dự án ghim trong
project.json: sidecar đi kèm, một bản tải về được kiểm tra checksum, hoặc mộttypsthệ thống báo đúng phiên bản đó. Nó biên dịch tệp chính.typđược chọn với các chẩn đoán dễ đọc và một đường dẫn xuất PDF tường minh. Khi Auto compile bật, Rust thay vào đó giữ một tiến trìnhtypst watchcho mỗi dự án (src-tauri/src/typst_watch.rs). Tài liệudocs/typst-toolchain.mdcủa kho desktop trình bày việc phân giải, ghim phiên bản và Tinymist tương ứng. - Markdown gọi Pandoc trực tiếp trên
.md/.markdown, với một đường dẫn xuất tường minh và--pdf-engine=<absolute bundled Tectonic path>. Tài liệu hướng dẫn của Pandoc hỗ trợ tường minh một đường dẫn PDF-engine đầy đủ. Đừng thay thế điều này bằng mộtpdflatexhệ thống ngầm định, vì bản đóng gói của Oleafly không được phụ thuộc vào một bản cài TeX không được khai báo. Tiến trình chạy với thư mục gốc của dự án làm thư mục làm việc, nên các ảnh dùng đường dẫn tương đối, tệp tài liệu tham khảo và tệp CSL đều hoạt động cho cả tài liệu chính ở gốc lẫn tài liệu chính nằm lồng trong.
Tài liệu sidecar của Tauri (mở trong thẻ mới) định nghĩa các đầu vào
bundle.externalBin với hậu tố target-triple và đưa sidecar đã đóng gói ra dưới tên không
hậu tố khi chạy. Adapter Pandoc của Oleafly phân giải tệp thực thi Tectonic đã đóng gói nằm
cạnh tệp thực thi của ứng dụng, đúng với bố cục bundle desktop của Tauri. Unit test bao phủ
các ứng viên app-bundle macOS và debug/release của Cargo, trong khi workflow phát hành kiểm
tra tệp anh em không hậu tố đã dựng ở mọi target.
Các bản tải Tectonic, Biber, Typst và language-server đều được đánh phiên bản và ghim checksum. Các script fetch của chúng kiểm tra tính hợp lệ của cấu trúc archive và chỉ giải nén các đường dẫn tệp thực thi hay tài nguyên đã được soát. CI và các bản build phát hành dùng chính các script đó.
- Mọi engine đều phát trực tuyến các sự kiện log/lỗi đã chuẩn hóa. Rust trả về metadata biên dịch qua JSON IPC. Bản thân tệp PDF được lấy riêng qua IPC nhị phân thô thay vì nhúng dạng base64 trong kết quả.
- Frontend dựng các byte PDF bằng pdf.js và công bố các chẩn đoán đã chuẩn hóa lên CodeMirror.
Descriptor của engine mô hình hóa chính sách biên dịch cùng các profile định dạng/source-preflight và các tập hợp tính năng/xuất/loại-mẫu. Các bên dùng ở frontend sử dụng descriptor fail-closed từ files-store thay vì đoán theo phần mở rộng tệp. Xem ma trận document engine (mở trong thẻ mới).
Typst báo supports_synctex=true và supports_offline=true, cùng
supports_isolated_compile=false. Đồng bộ source và PDF chạy qua Tinymist khớp với dự án và
cần Tinymist 0.13.30 trở lên, nên typst_toolchain::describe_project hạ supports_synctex
xuống false cho dự án ghim Typst 0.11 hoặc 0.12 (typst_sync::supported_for_project).
Chế độ Offline chặn việc tải gói Typst, nên khi đó một lần biên dịch chỉ dùng bộ nhớ đệm gói
dùng chung và thư mục typst-packages của dự án. Biên dịch cô lập vẫn chỉ dành cho LaTeX:
đường vẽ hình TikZ từ chối dự án Typst, và các công cụ hình của trợ lý dựng các đoạn Typst,
chẳng hạn canvas CeTZ hay sơ đồ fletcher, bằng render_typst_snippet thay thế. Chỉ thêm hành
vi engine sau khi capability của backend trở nên trung thực. Đừng thêm ngoại lệ UI dựa trên
phần mở rộng tệp.
Trạng thái nằm ở đâu
Phần tiêu đề “Trạng thái nằm ở đâu”- Cấu hình:
~/.oleafly/config.json(0600trên Unix). Các tùy chọn không chứa thông tin mật nằm ở đây. - Thông tin mật:
~/.oleafly/ai-secrets.jsonvà~/.oleafly/app-secrets.json, được mã hóa bằng~/.oleafly/ai-secrets.keychỉ chủ sở hữu mới dùng được. GitHub và MCP dùng chungapp-secrets.json. Thông tin đăng nhập của nhà cung cấp AI dùngai-secrets.json. - Dự án:
~/.oleafly/projects/<id>/, là các thư mục thường kèm.git. - Nhật ký ứng dụng:
~/.oleafly/app.log.
Các điểm mở rộng chính
Phần tiêu đề “Các điểm mở rộng chính”- Thêm một nhà cung cấp AI → cập nhật
crates/oleafly-agent/src/provider.rs, rồi phản chiếu metadata hiển thị của nó trongpackages/ai-core/src/providers.ts. Test đối chiếu catalog giữ cho hai danh sách khớp nhau. - Thêm một lệnh Tauri → khai báo trong
src-tauri/src/*.rs, đăng ký trongsrc-tauri/src/lib.rs, bọc trongsrc/lib/tauri.ts. - Thêm một document engine → hiện thực
DocumentEnginetrongsrc-tauri/src/document_engine.rs, công bố các capability trung thực, thêm đường fetch/smoke cho sidecar được ghim checksum, rồi dùng descriptor trong các điều khiển UI. - Thêm một mẫu dự án → thả một thư mục kèm manifest
template.jsonvàosrc-tauri/resources/templates/(metadata mẫu chung cho mọi engine vẫn là việc đã lên kế hoạch). - Thêm một công cụ cho AI →
packages/ai-tools/src/tools.ts. Các dịch vụ ứng dụng mà nó cần đi quaAiToolsHosttrongsrc/lib/ai-tools.ts. - Thêm một thẻ rail / lệnh palette hoặc omnibar / bộ công cụ AI → đăng ký trong
src/contributions/(xem Kiến trúc frontend).
Bên trong đồng bộ và GitHub
Phần tiêu đề “Bên trong đồng bộ và GitHub”OAuth device flow chạy phía server bằng Rust (src-tauri/src/github.rs) vì các endpoint OAuth không bật CORS. Các lượt gọi API (api.github.com) diễn ra từ frontend.
Phong cách viết mã
Phần tiêu đề “Phong cách viết mã”- TypeScript: theo những gì đã có sẵn. Không ghi chú giải trừ khi được yêu cầu. Tôn trọng
noUnusedLocals/noUnusedParameters. - Rust: idiomatic, lệnh nhỏ gọn, chuỗi lỗi thân thiện.
- UI: Tailwind v4 + token Geist. Tái sử dụng các primitive
Button,TooltipvàSelect.
Phát hành
Phần tiêu đề “Phát hành”Đóng gói nhắm tới macOS Apple Silicon, Windows x64, Linux x64 và Linux ARM64. Mỗi bản build tải về và kiểm tra các sidecar trình biên dịch cùng tài nguyên language-server đi kèm. Các bản build phát hành hỗ trợ ký và notarization của Apple trên macOS và Azure Artifact Signing trên Windows. Xem phát hành và cài đặt cho người dùng.