开发
搭建 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/ 之前,请先阅读前端架构:它介绍了端口模式、贡献注册表和别名配置。
前置条件
标题为“前置条件”的部分- Node.js 22.13+ 和 pnpm 11.9+(确切的 pnpm 版本在
package.json中声明) - 通过 rustup (在新标签页中打开) 安装的 Rust(stable)
- 适用于你的操作系统的 Tauri 2 系统依赖 (在新标签页中打开)
- 搭建时可选:pandoc (在新标签页中打开),用于 Markdown 的 PDF 编译和文档导出(应用可以按需安装它固定的版本)
首次运行
标题为“首次运行”的部分pnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm 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提交 PR 之前的检查
标题为“提交 PR 之前的检查”的部分提交拉取请求之前,先运行相关的本地检查:
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 sources这两条 audit 命令需要访问注册表和网络。CI 会在每次代码变更时记录它们当前的结果。离线的本地运行无法证明依赖图没有安全公告。
对于面向用户的改动,还要针对真实的应用和编译器运行端到端测试套件。参见 e2e/README.md (在新标签页中打开)。
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears down编译是怎么进行的
标题为“编译是怎么进行的”的部分- 前端加载后端的
project_engine描述符及其能力标志,然后通过 Tauri IPC 调用compileProject(projectId, mainDoc, offline)。 - Rust 通过
DocumentEngine分发。UI 代码不得根据文件名推断引擎行为。 - LaTeX 默认使用内置的 Tectonic。项目也可以改为通过
latexmk选择 pdfLaTeX、XeLaTeX 或 LuaLaTeX。完整的系统 TeX 安装优先于 Oleafly 管理的 TinyTeX。共享的检测器要求核心编译器、latexmk、kpsewhich和 Biber 都齐备,才会给予这一优先权。 - Typst 运行项目在
project.json中固定的确切版本:内置的 sidecar、经过校验和验证的下载,或者报告该版本的系统typst。它编译所选的.typ主文档,输出便于阅读的诊断信息,并使用显式的 PDF 输出路径。开启自动编译后,Rust 改为为每个项目保留一个typst watch进程(src-tauri/src/typst_watch.rs)。桌面端仓库的docs/typst-toolchain.md介绍了版本解析、固定版本以及与之匹配的 Tinymist。 - 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 和发布构建使用同样的脚本。
- 所有引擎都会输出规范化的日志和错误事件。Rust 通过 JSON IPC 返回编译元数据。PDF 本身通过原始二进制 IPC 单独获取,而不是以 base64 嵌入结果中。
- 前端用 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/中注册(参见前端架构)。
同步与 GitHub 内部实现
标题为“同步与 GitHub 内部实现”的部分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。参见发布和面向用户的安装。