Bỏ qua để đến nội dung
Oleaflyv0.4.12

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.

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.

Cửa sổ terminal
pnpm install
./scripts/fetch-tectonic.sh all
./scripts/fetch-biber.sh all
./scripts/fetch-typst.sh all
pnpm language-servers:fetch
pnpm 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ửa sổ terminal
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

Chạy các kiểm tra cục bộ liên quan trước khi mở pull request:

Cửa sổ terminal
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

Hai 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).

Cửa sổ terminal
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears down

Mộ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”
Một lần biên dịch đi qua ứng dụng thế nàoFrontend gọi compileProject qua Tauri IPC. Trong Rust, DocumentEngine chọn engine của dự án: Tectonic, latexmk, Typst, hoặc Pandoc với Tectonic. PDF quay về trình xem pdf.js dưới dạng IPC nhị phân thô, và các sự kiện nhật ký được truyền dòng trở thành chẩn đoán trong CodeMirror.FrontendRust, src-tauriYêu cầu biên dịchcompileProject()Trình xem pdf.jsHiển thị PDFCodeMirrorChẩn đoánDocumentEngineChọn engineTectoniclatexmkTypstPandoc, TectonicTauri IPCByte PDFNhật ký truyền dòngMột lần biên dịch đi qua ứng dụng thế nàoFrontend gọi compileProject qua Tauri IPC. Trong Rust, DocumentEngine chọn engine của dự án: Tectonic, latexmk, Typst, hoặc Pandoc với Tectonic. PDF quay về trình xem pdf.js dưới dạng IPC nhị phân thô, và các sự kiện nhật ký được truyền dòng trở thành chẩn đoán trong CodeMirror.FrontendcompileProject()DocumentEngineTrong RustEngineTectonic, latexmk,Typst hoặc Pandocpdf.jsHiển thị PDFCodeMirrorChẩn đoánTauri IPCPDFNhật ký
Frontend yêu cầu Rust biên dịch, và DocumentEngine chạy engine của dự án. PDF quay về dưới dạng IPC nhị phân, còn nhật ký truyền dòng biến thành chẩn đoán.
  1. Frontend tải descriptor project_engine từ backend cùng các cờ capability của nó, rồi gọi compileProject(projectId, mainDoc, offline) qua Tauri IPC.
  2. Rust điều phối qua DocumentEngine. Code UI không được suy đoán hành vi engine từ tên tệp.
  3. 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, kpsewhich và Biber trước khi trao quyền ưu tiên đó.
  4. 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ột typst hệ 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ình typst watch cho mỗi dự án (src-tauri/src/typst_watch.rs). Tài liệu docs/typst-toolchain.md của kho desktop trình bày việc phân giải, ghim phiên bản và Tinymist tương ứng.
  5. 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ột pdflatex hệ 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 đó.

  1. 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ả.
  2. 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.

  • Cấu hình: ~/.oleafly/config.json (0600 trê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.json và ~/.oleafly/app-secrets.json, được mã hóa bằng ~/.oleafly/ai-secrets.key chỉ chủ sở hữu mới dùng được. GitHub và MCP dùng chung app-secrets.json. Thông tin đăng nhập của nhà cung cấp AI dùng ai-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.
  • 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ó trong packages/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ý trong src-tauri/src/lib.rs, bọc trong src/lib/tauri.ts.
  • Thêm một document engine → hiện thực DocumentEngine trong src-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.json vào src-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 qua AiToolsHost trong src/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).

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.

  • 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, Tooltip và Select.

Đó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.

Xem trước hình ảnh

Không tải được câu trả lời AI

Hãy thử lại, hoặc tìm trong tài liệu.