Oleafly/Oleafly · 上手攻略

  • 仓库：Oleafly/Oleafly
  • 链接：https://github.com/Oleafly/Oleafly
  • 分类：academic-writing
  • 作者：Jay
  • 更新：2026-08-22

这是什么

Oleafly 是一款本地优先的 AI 辅助科研写作桌面应用，面向撰写学术论文、学位论文、技术报告的作者。它把编辑器、编译器、PDF 预览、Git 版本管理、文献工具和 AI 助手整合到一个应用里，同时让项目文件保持开放——任何时候都可以脱离 Oleafly、用任意编辑器或命令行工具继续工作。

它的定位是「Overleaf 的本地离线版 + Git 原生 + 更强的 AI 集成」，但不上传到云端多人协作。

解决什么问题

学术写作工具链通常分散在多个独立工具之间：LaTeX 编辑器、编译器、PDF 阅读器、参考文献管理器、Git、AI 对话窗口。它们之间没有统一上下文，AI 看不到你的实际项目文件，Git 历史和编译日志分布在不同窗口。Oleafly 把这些环节集中到一个窗口，减少切换损耗。

快速安装

下载发行版（推荐）

从 GitHub Releases 下载对应平台的安装包：

平台 安装包
macOS Apple Silicon .dmg
Windows x86_64 .msi 或 -setup.exe
Linux x86_64 .AppImage 或 .deb
Linux ARM64 .AppImage 或 .deb

Linux 包需要 glibc 2.39+。首次编译 LaTeX 时会下载所需宏包，Tectonic 会缓存它们以供离线使用。

从源码运行（开发者）

git clone https://github.com/Oleafly/Oleafly.git
cd Oleafly
pnpm install
./scripts/fetch-tectonic.sh all
./scripts/fetch-biber.sh all
./scripts/fetch-typst.sh all
pnpm language-servers:fetch
pnpm tauri dev

CLI 工具（无需桌面）

oleaflyc 是纯命令行版，无需启动桌面 app：

cargo run -p oleafly-cli --bin oleaflyc -- init
cargo run -p oleafly-cli --bin oleaflyc -- doctor
cargo run -p oleafly-cli --bin oleaflyc -- build
cargo run -p oleafly-cli --bin oleaflyc -- project info --json

核心用法

编辑与编译

  • 支持 LaTeX、Typst、Markdown 三种文档引擎，切换时 Code 视图和 Visual 视图可互换
  • LaTeX 默认使用捆绑的 Tectonic 引擎；也可配置为 latexmk + pdfLaTeX / XeLaTeX / LuaLaTeX
  • 编译错误直接显示为编辑器诊断信息和可读的错误卡片，无需翻原始日志
  • Typst 使用捆绑引擎，无需安装完整 TeX 发行版

PDF 预览

  • 侧边实时预览，连续滚动，带虚拟化页面渲染
  • 支持单页/双页布局、缩放、全屏；可选分离预览窗口
  • SyncTeX 双向跳转：编辑器点击跳转 PDF，PDF 内 Ctrl/Cmd+点击跳转源码

Git 版本管理

  • 每个项目即一个真实 Git 仓库；Oleafly 在编译成功或安静编辑后自动 commit
  • 在应用内查看提交时间线、side-by-side diff；可还原单个文件而不影响其他文件
  • 支持 stage/discard/commit/push/pull；可直接发布到 GitHub 或连接已有仓库

AI 助手集成

  • 可连接本地 Ollama 模型或托管 AI 提供商（如 OpenAI、Anthropic 等），API Key 仅存储在本地，Rust 后端解密，Webview 收不到明文密钥
  • AI 能读取/编辑文件、搜索项目、编译、检查日志、从 PDF 提取文字验证结果
  • 文件变更以 diff 形式展示，有「批准」或「拒绝」控制；可设「始终允许」会话内普通写入
  • 还可作为 MCP 服务器暴露给 Claude Desktop、Claude Code、Cursor、Codex 等外部 AI 应用

文献与引用

  • 从 DOI、arXiv ID、URL 或标题搜索添加引用，自动去重并插入 BibTeX 条目
  • 引用 picker 直接读取项目 .bib 文件，显示作者、年份、标题和定义行号
  • 项目地图（Project Map）索引所有章节、标签、引用键和环境，供跨文件跳转和重命名

预检（Preflight）

六项独立检查：编译/布局问题、出版配置文件（会议/期刊）、ATS 解析、可访问性、参考文献与资源、盲审隐私。检测结果标注为「已验证」或「建议审查」，不保证接收或正式可访问性证书。

导出

  • PDF 和 PDF 源码压缩包、Word、HTML、Markdown、纯文本、PowerPoint、EPUB（取决于文档引擎和项目类型）
  • 可导入 Word 文档（Pandoc）、从 PDF 重建可编辑 LaTeX 项目、导入 Overleaf ZIP、从公式图片转录

典型适用场景

  • 研究生写论文/学位论文：多文件 LaTeX 项目、复杂图表、参考文献管理、Git 备份一条龙
  • 科研人员日常写作：本地离线可用，无需 Overleaf 账号；与同事通过 GitHub 协作
  • 技术报告撰写：Typst 或 Markdown 输出，支持图表、公式、代码高亮
  • 会议/期刊投稿：预检工具提前发现格式问题，盲审模式提取 reader view

坑与注意

  1. macOS Windows 版签名：macOS 发布已签名公证，Windows 在 release signing 配置好后使用 Authenticode；仅从官方 Releases 页下载，勿用其他来源。
  2. glibc 版本：Linux 版需要 glibc 2.39 以上，部分旧发行版（如 Ubuntu 20.04）不满足，需要用 AppImage 自包含包或从源码编译。
  3. 首 次编译下载宏包：Tectonic 首次编译会下载所需宏包，无网时用 Offline 模式限制为缓存内容；若文档使用未缓存宏包会失败。
  4. 系统 TeX 的沙盒限制：Oleafly 检测到 MacTeX / TeX Live / MiKTeX / TinyTeX 时可使用；但系统 TeX 不完全沙盒化，只用于信任的项目。
  5. 多人协作：目前不支持 Overleaf 式多人同时编辑云端文档，协作靠 Git/GitHub，适合习惯 Git 工作流的团队。
  6. 高级宏包兼容性：项目自述为「still moving quickly」，高级 LaTeX 宏包兼容性和平台集成仍在完善中，生产重要文档前先测试。

与同类对比

Oleafly Overleaf TeXShop / VS Code LaTeX Workshop
部署方式 本地桌面 云端 本地编辑器
Git 集成 原生自动 commit 有限（付费版） 插件依赖
AI 集成 MCP + 内置助手 无原生 AI 依赖外部 ChatGPT 等
多文件 LaTeX 原生多文件支持 支持但大项目慢 需配置
离线可用 完全离线 需要联网 完全离线
多人协作 Git 协作 原生多用户 无
平台 macOS/Win/Linux 浏览器 跨平台

Oleafly 的优势在于本地 + AI + Git 三位一体，Overleaf 优势在云端多人实时协作。对于习惯本地工作、数据不上云的科研用户，Oleafly 是更强选择。

一句话推荐结论

科研写作者追求本地离线 + Git 备份 + AI 辅助 + 出版预检一条龙的，Oleafly 是目前最好的桌面端选择，尤其适合 LaTeX 多文件项目和需要严格版本控制的学位论文写作。