# 库

你的主屏幕：以书本呈现的项目、书签、悬停预览、复刻，以及使用 GitHub 搜索语法的项目搜索。

库是 Oleafly 的主屏幕。每个项目都以一本书的形式摆在书架上，最近活跃的排在最前面，管理项目所需的一切都在这里。

![悬停在项目封面上会预览它的第一页，随后搜索和筛选逐步缩小库中的项目范围。](https://cdn.oleafly.com/images/gifs/desktop/library.gif?v=2)

## 书架

每张卡片显示项目的名称和封面颜色。封面还会说明这是哪一类项目：文档、图片、图表，或者对就地打开的文件夹显示“外部”。卡片下方是引擎（LaTeX、Typst 或 Markdown）和最近一次更改的时间。打开项目即可回到它的源码和预览。

右上角的按钮在网格和列表之间切换，网格显示封面，列表更便于浏览。

库为空时，欢迎界面会提供 **新建项目** 和 **打开文件夹**。

## 创建项目

点击 **新建项目**，并选择如何开始：

- **使用模板**，用于论文、学位论文、简历、演示文稿或空白文档。浏览[模板库](/docs/templates/)，选择模板，并为项目命名。
- **导入项目**，带入已有的文件。各种格式请参阅[导入指南](/docs/import-project/)。
- **研究项目**，用来组织带有文档、来源和任务的[研究工作区](/docs/research-workspace/)。

如果不选封面颜色，新项目会从调色板中随机获得一种。Oleafly 还会把项目的文件记录为名为“Create project”的第一次 Git 提交。参见 [Git 与源代码管理](/docs/git-history/#the-first-commit)。

你也可以通过搜索栏在任何地方打开模板库：按 ⌘⇧F（Ctrl+Shift+F）并输入 `/create`。

## 就地打开的文件夹

**打开文件夹**（⌘⇧O / Ctrl+Shift+O）让你直接在文件夹原来的位置上工作，而不用把它复制进库。该文件夹的构建、设置、检查点和聊天都存放在 Oleafly 自己的数据文件夹里，所以你的文件夹里不会被添加任何东西。该文件夹会在书架上被标记为“外部”，当文件夹丢失或所在驱动器未连接时，它的卡片会告诉你。

Oleafly 会限制以这种方式打开的文件夹中的一些功能，例如 Git、外部代理，以及通过 `latexmk` 使用系统 LaTeX。编辑器上方的横幅提供 **信任此文件夹** 来开启它们。只信任你了解其内容的文件夹。在此之前，该文件夹使用内置的 Tectonic 引擎编译。信任之后，没有自己引擎的文件夹会跟随[默认编译引擎](/docs/engines/#set-a-default-for-new-projects)。此后外部命令仍然需要它们自己的[权限](/docs/latex-engines/#allow-external-commands)。

[云同步](/docs/cloud-sync/)只备份库中的项目，所以就地打开的文件夹不会被同步。

右键点击“外部”卡片，可以在文件管理器中显示该文件夹、用 **复制到库** 创建一个归你所有的项目，或者 **从 Oleafly 中移除**（文件仍留在原处）。你也可以从 Finder、文件资源管理器或终端打开文件夹；参见[系统集成](/docs/settings/general/#system-integration)。

## 悬停预览

把鼠标悬停在一本书上，它最近一次编译的 PDF 的第一页就会滑过封面，让你一眼就能分清自己的论文。预览来自真实的编译输出并会被缓存，所以书架保持流畅。

如果不想看到它们，请在 **设置 → 外观 → PDF 预览** 中关闭 **悬停时预览 PDF**。

## 书签

把鼠标悬停在一本书上，点击它的书签图标即可收藏该项目。要只显示已收藏的项目，请在搜索框中输入 `is:bookmarked`，或在高级筛选中把 **收藏** 设为 **已收藏**。

![为重新投稿复刻一篇论文，并给副本设置了自己的封面颜色。](https://cdn.oleafly.com/images/gifs/desktop/fork-color.gif?v=2)

## 右键菜单

右键点击任意一本书：

- **打开项目**
- **项目详情**：名称、ID、引擎、类型、主文档、日期，以及搜索所用的其他元数据。
- **导出历史**：你从这个项目导出过的文件。
- **项目颜色**：十一种封面色板（蓝色、奶油色、蜜桃色、玫瑰色、粉色、丁香紫、天蓝色、水绿色、青色、薄荷绿、春绿色）。颜色存储在项目本身中，所以把项目同步到另一台机器时，颜色也会跟着走。
- **复刻项目**：把项目及其完整的 Git 历史复制为一个新项目。对话框建议使用 `<name> (copy)`；你可以随意命名。用副本来尝试简历或论文的另一个版本。副本从没有检查点开始。
- **删除项目**：把项目移到回收站，可以从那里恢复。

## 重命名项目

打开项目，点击顶部工具栏中的标题。它会变成可原地编辑的状态：输入新名称并按 Enter。重命名会保存到项目自己的元数据中。

## 搜索你的项目

主屏幕顶部的搜索框会在你输入时筛选书架。它使用与 GitHub 的议题和拉取请求搜索相同的语法。普通词语会匹配项目名称、ID、主文件、文件夹路径、导出记录、引擎、类型和封面颜色。限定符可以缩小列表：

| 限定符 | 示例 | 匹配内容 |
| --- | --- | --- |
| `is:` | `is:bookmarked`、`is:folder`、`is:library`、`is:forked` | 已收藏的项目、就地打开的文件夹、存储在 Oleafly 中的项目、复刻的项目 |
| `has:` 和 `no:` | `has:preview`、`no:exports` | 有或没有已编译的 PDF 预览或导出记录的项目 |
| `engine:` | `engine:typst`、`engine:latex` | LaTeX、Typst 或 Markdown |
| `kind:` | `kind:image` | 文档、图片或图表项目 |
| `color:` | `color:mint` | 封面颜色，按色板名称 |
| `created:`、`updated:`、`opened:` | `created:>2026-01-01`、`updated:>@today-1w` | 创建、最近更改或最近打开的日期 |
| `in:` | `draft in:name` | 把词语限定在 `name`、`id`、`file`、`path` 或 `export` 中 |
| `sort:` | `sort:name-asc`、`sort:created` | 书架的排序 |

`engine:latex` 会找到所有 LaTeX 项目，无论它使用哪种 LaTeX 引擎。较早的 `engine:tectonic` 仍然有效，找到的项目相同。

### 组合条件

规则与 GitHub 的相同：

- 空格表示 AND。大写的 `AND` 和 `OR` 以及括号可以对条件分组，最多嵌套五层。AND 的优先级高于 OR。
- 逗号列出备选项：`engine:typst,markdown` 匹配任一引擎。重复同一个限定符表示两者都要满足，所以 `engine:typst engine:markdown` 什么也匹配不到。
- 开头的 `-` 表示排除：`-kind:image`、`-is:bookmarked`。`NOT` 同样可用，而 `-word` 会排除包含该词的项目。
- 引号可以把空格保留在一起：`"lab notes"`、`in:path "My Papers"`。

```text
(engine:typst OR engine:markdown) is:bookmarked -kind:image sort:updated-desc
```

### 日期与排序

日期可以使用 `>`、`>=`、`<` 和 `<=`，也可以使用 `2026-01-01..2026-03-31` 这样的范围（用 `*` 表示开放的一端），以及相对日期：`@today`、`@today-7d`、`@today-2w`、`@today-1m` 或 `@today-1y`。`created:>@today-1w` 表示过去七天。

`sort:` 接受 `activity`、`updated`、`created`、`opened` 或 `name`，每个都可以带 `-asc` 或 `-desc`。不带方向时按降序排序。默认是最近活动。

### 建议与警告

搜索框为空时点击它，会有一个下拉列表列出限定符。输入时，它会建议限定符、它们的值、AND、OR 和排除。用方向键在其中移动，按 Enter 采纳建议。Tab 或 Escape 会关闭它而不采纳任何内容。

输入时，限定符和值会以彩色显示。出现错误时会带有琥珀色底色和一条简短的说明，指出问题所在：比如括号没有闭合，或者限定符不接受的某个值。未知的限定符会按普通文本搜索，无效的值会被忽略。

### 高级筛选

搜索框旁边的滑块按钮会打开 **高级筛选**，其中的菜单包括引擎、项目类型、收藏、PDF 预览、创建时间、修改时间和排序方式。一旦你就地打开过文件夹，还会多出一个位置菜单。每个菜单都会编辑搜索文本，所以搜索框和面板始终保持一致。当面板无法把你的查询显示为单个选项时，菜单显示为 **自定义**。**重置** 会移除限定符，保留你的普通词语。

## 搜索全部内容

搜索栏（⌘⇧F / Ctrl+Shift+F，或程序坞中的 **搜索文档**）会搜索项目元数据，以及每个项目中每份文档的全文。它会直接跳转到匹配的项目、文件和行。输入 `/` 可使用 `/projects`、`/docs` 或 `/create` 之类限定范围的命令。

搜索栏有它自己更简单的筛选条件，例如 `name:resume` 或 `bookmark:yes`。上面介绍的 GitHub 风格语法属于主屏幕上的搜索框。

## 主屏幕程序坞

主屏幕上的一个小程序坞收纳了所有不属于项目的东西：

- **新建项目**：从模板开始、导入文件，或创建研究工作区。
- **搜索文档**：搜索栏（⌘⇧F / Ctrl+Shift+F）。
- **图表编排器**：[图表编排器](/docs/figures-diagrams/)，无需先打开项目。它会询问这幅图表用于什么：**TikZ 图表**、**Typst 图表** 或 **Mermaid 图表**。
- **笔记**：打开[笔记](/docs/notes/)。当 **设置 → 实验功能** 中的 **笔记** 开启时才会显示。
- **Oleafly 工具**：可搜索的文档实用工具库（见下文）。
- **外观**：在浅色、深色和系统之间切换。
- **设置**：齿轮图标，或 ⌘,（Ctrl+,），打开完整的[设置](/docs/settings/)窗口。

## Oleafly 工具

在 **设置 → 实验功能** 中打开 **LaTeX 工具**，即可显示 **Oleafly 工具** 库。其中包括 LaTeX、Typst、Markdown、Word、HTML 和图片之间的转换器，以及参考文献生成器、校验器、研究查询、统计计算器和写作辅助工具。[Oleafly 工具指南](/docs/tools/)介绍了其中的每一个。

## 书架在磁盘上的位置

每本书都是 `~/.oleafly/projects/` 下的一个普通文件夹，名称是人类可读的随机名称，例如 `flying-pink-pikachu`。库没有任何专有的东西：参见[数据存放在哪里](/docs/where-your-data-lives/)。

## 回收站

被删除的项目会留在回收站中，直到你恢复它或永久删除它。这两个操作都在 **设置 → 数据存储** 中。参见[存储与回收站](/docs/settings/storage/#recycle-bin)。
