跳转到内容
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)使用外部能力,由 app shell 把它们接在一起。在修改 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

如果只针对单个平台,请给每个 shell 获取脚本传入该平台的 Rust 目标三元组。用 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

提交拉取请求之前,先运行相关的本地检查:

终端窗口
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 命令需要访问注册表和网络。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 直接调用 Pandoc 处理 .md/.markdown,使用显式的输出路径和 --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。

引擎描述符描述了编译策略、格式化和源码预检配置,以及功能、导出和模板类型的集合。前端的使用方依赖会在信息缺失时拒绝放行的 files-store 描述符,而不是根据扩展名去猜。参见文档引擎矩阵 (在新标签页中打开)。

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 提供。
  • 添加侧栏标签页 / 命令面板或 omnibar 命令 / AI 工具集 → 在 src/contributions/ 中注册(参见前端架构)。

OAuth 设备流程在 Rust 中于服务端运行(src-tauri/src/github.rs),因为 OAuth 端点没有启用 CORS。API 调用(api.github.com)则从前端发出。

  • TypeScript:沿用现有写法。除非被要求,否则不写注释。遵守 noUnusedLocals/noUnusedParameters。
  • Rust:写法地道,命令保持小而精,错误信息要友好。
  • UI:Tailwind v4 + Geist 设计令牌。复用 Button、Tooltip 和 Select 这些基础组件。

打包目标为 macOS Apple Silicon、Windows x64、Linux x64 和 Linux ARM64。每次构建都会获取并检查它的编译器 sidecar 和内置的语言服务器资源。发布构建支持 macOS 上的 Apple 签名与公证,以及 Windows 上的 Azure Artifact Signing。参见发布和面向用户的安装。

图片预览

无法加载 AI 回答

请重试,或搜索文档。