# 快速開始

本指南將幫助您在幾分鐘內完成 BoosApi 的安裝、設定和首次對話。

## 安裝

前往 [下載頁面](/zh-tw/download) 取得最新安裝套件，選擇與您系統相符的版本。

### macOS

BoosApi 提供兩種架構的 `.dmg` 安裝套件：

- **Apple Silicon**（M1/M2/M3/M4）— `BoosApi_x.x.x_aarch64.dmg`
- **Intel** — `BoosApi_x.x.x_x64.dmg`

下載後雙擊 `.dmg` 檔案，將 BoosApi 拖入「應用程式」資料夾即可。

::: warning macOS 安全提示
由於 BoosApi 尚未進行 Apple 公證簽名，首次開啟時系統可能彈出以下提示：

- **「BoosApi 已損毀，無法開啟」** 或 **「無法驗證開發者」**

請在終端機中執行以下指令後重新開啟：

```bash
xattr -cr /Applications/BoosApi.app
```

該指令會移除系統新增的隔離屬性，不會影響應用程式本身。
:::

### Windows

- **x64** — `BoosApi_x.x.x_x64-setup.exe`
- **ARM64** — `BoosApi_x.x.x_arm64-setup.exe`

雙擊安裝程式並依照精靈完成安裝。系統需求為 Windows 10（1803）或更高版本。

### Linux

根據您的發行版和架構選擇：

| 格式 | 架構 | 適用場景 |
|------|------|---------|
| `.deb` | amd64 / arm64 | Debian、Ubuntu 及其衍生版 |
| `.rpm` | x86_64 / aarch64 | Fedora、openSUSE 等 |
| `.AppImage` | x86_64 / aarch64 | 任意發行版，無需安裝 |

`.deb` 安裝範例：

```bash
sudo dpkg -i BoosApi_x.x.x_amd64.deb
```

`.AppImage` 需要先賦予執行權限：

```bash
chmod +x BoosApi_x.x.x_amd64.AppImage
./BoosApi_x.x.x_amd64.AppImage
```

## 首次設定

安裝完成後，依照以下步驟完成初始設定。

### 1. 進入設定

啟動 BoosApi 後，點擊左側邊欄底部的齒輪圖示進入 **設定** 頁面。

### 2. 新增服務供應商

進入 **設定 → 服務供應商**，點擊左下角的 **+** 按鈕新增一個服務供應商。以 OpenAI 為例：

1. 輸入服務供應商名稱，如 `OpenAI`
2. 選擇服務供應商類型為 **OpenAI**
3. 填入您的 **API 金鑰**
4. **Base URL** 保持預設 `https://api.openai.com`，若使用第三方中繼服務則填寫其位址

::: tip 取得 API 金鑰
前往 [OpenAI API Keys](https://platform.openai.com/api-keys) 頁面建立金鑰。其他服務供應商的金鑰取得方式請參考各自官方文件。
:::

### 3. 取得模型

服務供應商新增完成後，點擊 **取得模型** 按鈕，BoosApi 會自動從 API 拉取可用模型清單。您也可以在模型 ID 輸入框中手動新增模型。

### 4. 設定預設模型

進入 **設定 → 預設模型**，選擇您最常用的模型作為預設助手模型和話題命名模型。新建對話時將自動使用預設模型。

## 開始第一次對話

### 新建對話

點擊左側邊欄頂部的 **新建對話** 按鈕，或使用快捷鍵 `Cmd/Ctrl+N`。

### 選擇模型

在對話頂部的模型選擇器中選取您想使用的模型。如果您已設定了預設模型，會自動填充。

### 傳送訊息

在底部輸入框中輸入您的問題，按 `Enter` 傳送。BoosApi 使用串流輸出，您會看到模型的回答逐字呈現。

::: info 關於 Thinking 區塊
部分模型（如 Claude、DeepSeek R1）支援輸出推理過程。當模型包含 thinking 區塊時，BoosApi 會將其折疊顯示，點擊即可展開查看完整推理鏈。
:::

## 核心概念

### 對話分支

BoosApi 支援對話分支功能。當您在某條訊息基礎上重新生成或編輯提問時，系統會建立一個新的分支而非覆蓋原內容。您可以隨時在不同分支之間切換，比較不同的對話走向。

### 訊息版本

每條訊息可以擁有多個版本。重新生成助手回覆時，新版本會自動新增到同一訊息位置。透過訊息旁的左右箭頭可以在版本間快速切換。

### 上下文掛載

在對話中，您可以透過附件功能掛載額外的上下文資訊：

- **檔案** — 上傳圖片或文件作為對話上下文
- **搜尋** — 關聯本機知識庫搜尋結果
- **工具** — 啟用 MCP 工具讓模型呼叫外部能力

## 快捷鍵

BoosApi 內建了一套常用快捷鍵，提升操作效率：

| 快捷鍵 | 功能 |
|-------|------|
| `CmdOrCtrl+Shift+A` | 顯示/隱藏目前視窗 |
| `CmdOrCtrl+Shift+Z` | 顯示/隱藏所有視窗 |
| `Cmd/Ctrl+N` | 新建對話 |
| `Cmd/Ctrl+,` | 開啟設定 |
| `Cmd/Ctrl+F` | 搜尋對話 |

::: tip 自訂快捷鍵
以上快捷鍵均可在 **設定 → 快捷鍵** 中自訂修改，包括全域快捷鍵和應用程式內快捷鍵。
:::

## 桌面設定

在 **設定** 中可以調整各項桌面偏好：

### 外觀

- **主題** — 支援深色、淺色和跟隨系統三種模式
- **主題色** — 從 12 種預設色中選擇，也支援自訂顏色
- **字型** — 可調整字型大小（12–20px）、字重和字型家族

### 語言

支援繁體中文、簡體中文和英文介面切換，在 **設定 → 一般** 中修改。

### 系統行為

- **系統托盤** — 關閉視窗後保持在系統托盤執行
- **開機自啟** — 設定系統登入時自動啟動 BoosApi
- **視窗置頂** — 將 BoosApi 視窗始終置於最前

### 代理設定

如果您需要透過代理存取 API，在 **設定 → 代理** 中設定：

- **代理類型** — 支援 HTTP 和 SOCKS5
- **代理位址** — 代理伺服器的 IP 或網域名稱
- **代理連接埠** — 預設為 7890

設定完成後可以點擊 **測試** 按鈕驗證連通性，會顯示延遲結果。

## 資料與備份

### 資料目錄

BoosApi 使用兩個目錄分別儲存不同類型的資料：

| 目錄 | 用途 |
|------|------|
| `~/.boosapi/` | 應用狀態：資料庫、加密金鑰、向量資料庫、SSL 憑證 |
| `~/Documents/boosapi/` | 使用者檔案：圖片、文件附件、備份 |

### 自動備份

在 **設定 → 備份** 中開啟自動備份。支援以下備份目標：

- **本機** — 預設儲存到 `~/Documents/boosapi/backups/`
- **WebDAV** — 同步到支援 WebDAV 的網路磁碟機

可設定備份間隔（小時）和保留的最大備份數量。

### 手動備份與還原

隨時可以透過 **設定 → 備份** 手動觸發完整備份。還原時選擇備份檔案即可還原所有資料。

### 對話匯出

在對話頁面中，可以將目前對話匯出為多種格式：

- **PNG** — 長圖截圖，適合分享
- **Markdown** — 結構化文字，方便二次編輯
- **純文字** — 簡潔格式
- **JSON** — 包含完整中繼資料，方便程式處理

## 下一步

基礎設定完成後，您可以繼續探索 BoosApi 的進階功能：

- [設定服務供應商](./providers) — 多服務供應商、多金鑰、自訂端點
- [MCP 伺服器](./mcp) — 連接外部工具擴展 AI 能力
- [API 閘道](./gateway) — 將 BoosApi 作為 API 代理伺服器