# 开发

搭建 Oleafly 桌面端仓库，获取固定版本的 sidecar，运行应用，并了解主要的扩展点。

Oleafly 是一个 [Tauri 2](https://tauri.app) 桌面应用。它的 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/` 之前，请先阅读[前端架构](/docs/engineering/architecture/)：它介绍了端口模式、贡献注册表和别名配置。

## 前置条件

- Node.js 22.13+ 和 pnpm 11.9+（确切的 pnpm 版本在 `package.json` 中声明）
- 通过 [rustup](https://rustup.rs) 安装的 Rust（stable）
- 适用于你的操作系统的 [Tauri 2 系统依赖](https://v2.tauri.app/start/prerequisites/)
- 搭建时可选：[pandoc](https://pandoc.org/installing.html)，用于 Markdown 的 PDF 编译和文档导出（应用可以按需安装它固定的版本）

## 首次运行

```bash
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` 可以查到主机三元组。语言服务器命令会选择当前主机，除非你通过它底层的脚本传入目标。

## 日常开发

```bash
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 之前的检查

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

```bash
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](https://github.com/Oleafly/Oleafly/blob/main/e2e/README.md)。

```bash
pnpm test:e2e:app                         # builds + launches the app, runs Playwright, tears down
```

## 编译是怎么进行的

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 文档](https://v2.tauri.app/develop/sidecar/)规定了带目标三元组后缀的 `bundle.externalBin` 输入，并在运行时以不带后缀的名称暴露打包后的 sidecar。Oleafly 的 Pandoc 适配器会在应用可执行文件旁边解析打包后的 Tectonic 可执行文件，与 Tauri 的桌面打包布局一致。单元测试覆盖了 macOS 应用包和 Cargo 的 debug/release 候选路径，发布工作流则在每个目标上检查暂存的不带后缀的同级文件。

Tectonic、Biber、Typst 和语言服务器的下载都有版本号并固定了校验和。它们的获取脚本会验证压缩包的结构，只解压经过审查的可执行文件或资源路径。CI 和发布构建使用同样的脚本。

6. 所有引擎都会输出规范化的日志和错误事件。Rust 通过 JSON IPC 返回编译元数据。PDF 本身通过原始二进制 IPC 单独获取，而不是以 base64 嵌入结果中。
7. 前端用 pdf.js 渲染 PDF 字节，并把规范化的诊断信息发布到 CodeMirror。

引擎描述符描述了编译策略、格式化和源码预检配置，以及功能、导出和模板类型的集合。前端的使用方依赖会在信息缺失时拒绝放行的 files-store 描述符，而不是根据扩展名去猜。参见[文档引擎矩阵](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md)。

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/` 中注册（参见[前端架构](/docs/engineering/architecture/#the-contribution-registry)）。

## 同步与 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。参见[发布](/docs/engineering/releasing/)和面向用户的[安装](/docs/install/)。
