# 常見問題與疑難排解

快速解答入門、專案、編譯、助理和備份的常見問題。

## 開始使用

### 我需要帳號嗎？

不需要。下載 Oleafly，打開它，就能開始寫作。雲端 AI 供應商、GitHub 或 Dropbox 這類選用服務，使用的是它們各自的帳號。

### Oleafly 支援 LaTeX、Typst 和 Markdown 嗎？

支援。建立專案時選擇引擎。每個引擎都有自己的編輯與匯出功能。[快速入門](/docs/getting-started/) 會帶你產生第一份 PDF。

### 我可以帶入現有的論文或履歷嗎？

可以。你可以匯入專案原始碼、ZIP 壓縮檔或 Git 儲存庫。Oleafly 也提供 DOCX 和以文字為主的 PDF 的轉換途徑。請閱讀 [把現有專案帶進來](/docs/import-project/)，選出適合的方式。

### 我可以離線工作嗎？

不連上雲端，你也能寫作、整理檔案、使用本機校對，以及執行已下載的本機 AI 模型。Tectonic 可以用已快取的套件編譯。新的套件、遠端參考文獻、雲端模型、GitHub 和下載則需要網路連線。離線之前，請先讓專案成功編譯一次。

### 我的檔案在哪裡？

你的專案是本機專案庫中的一般資料夾。你可以複製它們、備份它們，或用其他工具開啟。[你的資料放在哪裡](/docs/where-your-data-lives/) 說明了專案檔案、應用程式設定和檢查點。

### 我可以用 Oleafly 寫學位論文或履歷嗎？

可以。請從 [學位論文工作流程](/docs/workflows/thesis/) 或 [履歷工作流程](/docs/workflows/resume/) 開始。兩者使用的編輯器、預覽、參考文獻和匯出工具，都與研究論文相同。

## 安裝

### 作業系統阻擋了安裝程式

請確認檔案來自 [官方發行版本](https://github.com/Oleafly/Oleafly/releases/latest)，且符合你的平台。第一次啟動時的步驟，請依照 [安裝指南](/docs/install/#first-launch) 中該平台的說明。

### 我該用哪個 Linux 套件？

請選擇符合你電腦架構的版本，再選 AppImage、Debian 套件或 RPM。系統需求請參閱 [Linux 安裝](/docs/install/#linux)。

## 編譯

### 我第一次編譯很慢

Tectonic 可能需要下載這份文件用到的套件，而且這台電腦的第一次編譯也會一次取得一批常用的套件。它們會快取起來供之後的建置使用。套件還在下載時，編譯可以超過平常的五分鐘限制。開啟 [記錄檔](/docs/compiling/#reading-the-logs) 就能看到目前的進度。

### 缺少某個套件

如果離線模式已開啟，請在訊息中選擇 **關閉並編譯**，或先為一次編譯關閉它，以取得套件。使用系統 TeX 工具鏈時，請使用錯誤訊息中的 **尋找並安裝**。來自 Debian、Ubuntu 或 Fedora 的 TeX Live，其套件要透過 `apt` 或 `dnf` 取得。請參閱 [LaTeX 引擎與套件](/docs/latex-engines/#recover-from-a-missing-file)。

### 我選了 pdfLaTeX，Oleafly 要求我安裝 TeX 發行版

pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 和 pLaTeX 都在你電腦上安裝的 TeX 發行版中執行。沒有發行版時，選擇其中任何一個，都會在開始編譯之前先開啟一個對話方塊。選擇 **下載並使用 TinyTeX** 來安裝一個，或選擇 **切換回 Tectonic** 回到內建引擎。編譯失敗之後，預覽會以 **下載並使用 TinyTeX** 和 **使用 Tectonic** 提供同樣的選擇。請參閱[沒有安裝 TeX 時](/docs/latex-engines/#when-no-tex-is-installed)。

### MiKTeX 顯示 latexmk 需要 Perl

MiKTeX 的 `latexmk` 要靠 Perl 執行，而 MiKTeX 不含 Perl。請安裝 Strawberry Perl，或從 **設定 → 引擎 → LaTeX** 安裝 TinyTeX，它自帶 Perl，並會接手 MiKTeX 的編譯。請參閱 [MiKTeX 與 Perl](/docs/latex-engines/#miktex-and-perl)。

### 我的 PDF 中缺少文字

字型沒有這些字元的字形。這最常發生在韓文、中文和日文文字，TeX 會直接略過這些字元而不讓編譯失敗。Oleafly 會警告你，並在記錄檔中列出它們。在 LaTeX 中，請貼上警告為你的文字所提供的設定。在 Typst 中，請下載通知提供的字型包，或把含有這些字元的字型加入專案的 `fonts` 資料夾。在 Markdown 中，請在 YAML 標頭中把 `mainfont` 或 `CJKmainfont` 設為含有它們的字型。請參閱[PDF 中缺少的字元](/docs/latex-engines/#characters-missing-from-the-pdf)和[顯示為方框的字元](/docs/typst/#characters-that-show-as-boxes)。

### Oleafly 因為編譯太久而停止了我的編譯

一次編譯可以執行 5 分鐘。套件還在下載時，限制最多會延長到 30 分鐘。Markdown 轉 PDF 有 15 分鐘，Quarto 和 Calepin 有一小時。請再編譯一次：下載會從停下來的地方繼續。在 Tectonic 上編譯很長的草稿時，請在編譯選單中把 **編譯模式** 設為 **快速**。

### 新專案可以使用我自己的 TeX 安裝嗎？

可以。開啟 **設定 → 引擎 → LaTeX**，把 **預設編譯引擎** 設為 **latexmk（系統 TeX）**。之後新建、匯入和轉換的 LaTeX 專案都會從它開始。請參閱 [為新專案設定預設值](/docs/engines/#set-a-default-for-new-projects)。

### 我的文件使用 minted 或 PythonTeX

這些套件會在文件編譯時執行其他程式，Oleafly 預設會阻擋這點。它們需要系統 LaTeX。如果你信任專案中的每個檔案，請在編輯器上方的橫幅中選擇 **允許外部命令**。請參閱 [允許外部命令](/docs/latex-engines/#allow-external-commands)。

### 編譯完成但有警告

開啟 **記錄檔**，先檢查未定義的引用和參照。[預檢](/docs/preflight/) 能幫你在匯出之前找出受影響的原始碼位置。

### 我看不懂建置錯誤

請助理讀取記錄、修正錯誤，然後再編譯一次。如果你想在過程中審閱建議的動作，請使用 **要求核准**。你也可以把記錄貼到 [Discord](/discord) 的說明論壇。

### 為什麼少了某個匯出格式？

可用的格式取決於引擎和文件類型。請查看 [匯出表](/docs/export/#editable-formats)。

## AI 助理

### 我可以使用哪個助理？

你可以連接模型供應商、使用本機模型，或選擇 [CLI 代理程式](/docs/cli-agents/)。[設定 AI](/docs/ai-setup/) 涵蓋每一種做法。

### 使用編輯器一定要有 AI 嗎？

不需要。寫作、編譯、引用、預覽、圖表、專案歷史記錄和匯出，沒有助理也都能使用。

### 助理能做什麼？

它可以處理專案檔案、查找來源、檢視 PDF、建立圖片、執行工具，並協助修復建置。請選擇適合這項工作的方案和核准政策。請參閱 [聊天與工具](/docs/ai-chat/)。

### 模型旁邊的「已驗證」是什麼意思？

這表示該模型通過了工具呼叫的探測。它能幫你選出適合執行專案動作的模型；並不評估它的寫作或研究品質。請參閱 [設定 AI](/docs/ai-setup/)。

### 為什麼用量顯示為「未知」？

有些供應商和 CLI 代理程式不回報用量。「未知」表示取不到這個數值。請閱讀 [用量與預算](/docs/ai-usage/)。

### 我可以連接外部助理嗎？

可以。使用內建的 [CLI 代理程式連線](/docs/cli-agents/)，啟用 Oleafly 的本機 [MCP 伺服器](/docs/mcp/)，或把你的代理程式連接到 [`oleafly` 指令](/docs/cli/)，它在應用程式關閉時也能使用。

## 歷史記錄與協作

### 如何還原較早的版本？

開啟 [檢查點](/docs/checkpoints/)，比較成功建置的原始碼並還原某個版本。你自己管理的 Git 提交，請使用 [原始檔控制](/docs/git-history/)。

### 我可以和共同作者一起工作嗎？

可以。透過 [即時協作](/docs/collaboration/)，你和共同作者可以經由你們團隊自己架設的協作伺服器，同時編輯同一個專案。你們每個人仍把專案以檔案的形式保存在自己的電腦上。你也可以分享原始碼壓縮檔，或使用 [GitHub 同步](/docs/github-sync/) 來交換提交。

### 我可以在兩台電腦上使用我的專案嗎？

可以。[雲端同步](/docs/cloud-sync/) 會把你專案庫中的專案和設定保存在你自己的 Dropbox 中，你連接的每台電腦都可以下載它們。開啟 **設定 → 資料儲存 → 雲端同步** 即可連接。你也可以用 [GitHub 同步](/docs/github-sync/) 在電腦之間移動專案。

### 匯出原始碼就等於備份所有東西嗎？

它備份的是專案原始碼。自動檢查點、應用程式偏好設定和憑證是分開存放的。請依照 [備份指南](/docs/where-your-data-lives/#back-up-your-work)，把你需要的部分也一併備份。

## 回報問題

開啟 **設定 → 說明與關於 → 複製資訊**，並把這些資訊連同簡短的說明、重現問題的步驟和相關記錄一併附上。請在 [Issues](https://github.com/Oleafly/Oleafly/issues) 回報；問題與工作流程方面的協助，請到 [Discord 社群](/discord)。
