> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor

> Cursor 程式碼編輯器集成指南

## 一、產品簡介

Cursor 是一款 AI 驅動的程式碼編輯器，通過 MixRoute，可在編寫程式碼時獲得強大的 AI 輔助功能，支援智能程式碼生成、補全、解釋及優化。MixRoute 現已兼容 Cursor 的 Agent 能力（Auto Apply / 多文件編輯等），配置得當即可啟用。

## 二、快速配置步驟

<Warning>
  **重要提示**：目前 Cursor 官方限制，使用第三方 API Key（包括 MixRoute 的 API Key）需要滿足以下條件：

  * 必須開通 Pro Plan（付費訂閱），Free Plan 無法使用第三方 API Key
  * 需要配置科學上網（VPN/代理）才能正常連接第三方 API 服務
  * 這是 Cursor 官方的政策限制，並非 MixRoute API 的限制
</Warning>

### 1. 打開設定

點擊右上角的齒輪圖標 ⚙️，選擇 Models 選項。

### 2. 配置 API

* **OpenAI API Key**：輸入您的 MixRoute 密鑰
* **Override OpenAI Base URL**：勾選並輸入 `https://api.mixroute.ai/v1`
* 點擊 **Verify** 驗證配置

<Note>
  - GPT 系列模型需在模型名加前綴 `openai/`，例如使用 `gpt-5.5` 時需填寫 `openai/gpt-5.5`。其餘渠道按原模型 ID 配置。
  - MixRoute API 已兼容 Cursor Agent（Auto Apply 等）。若希望啟用 Agent，請在模型選擇中使用支援 Agent 的模型。
</Note>

### 3. Agent 模式使用提示

* 使用支援 Agent 的模型（如 Claude、DeepSeek、Grok、以及帶 `openai/` 前綴的 GPT 系列等）
* 確保 Base URL 為 `https://api.mixroute.ai/v1`
* 首次啟用時可在 Cursor 側邊欄執行一次簡單改動驗證自動應用
* 若模型不支援 Agent，可改為 Chat 方式手動 Apply

## 三、模型配置

### 添加自訂模型

在 Cursor 設定中添加：

```text theme={null}
claude-opus-4-8
gpt-5.5
gemini-3.5-flash
```

## 四、使用模式說明

### Chat 模式工作流程

1. **對話生成程式碼**：`Ctrl/Cmd + L` 打開聊天窗口，描述需求
2. **手動應用程式碼**：複製程式碼貼到目標文件，或使用 "Apply" 按鈕
3. **迭代優化**：繼續對話要求修改

### 替代方案對比

| 工具                 | Agent 模式 | 優勢          | 劣勢          |
| ------------------ | -------- | ----------- | ----------- |
| Cursor             | ❌        | 界面優雅，補全體驗好  | 無 Agent 模式  |
| Cline (VS Code)    | ✅        | 完整 Agent 功能 | 需依賴 VS Code |
| RooCode (VS Code)  | ✅        | 支援多文件編輯     | 較新，功能完善中    |
| Continue (VS Code) | ✅        | 開源，可定製性強    | 配置較複雜       |

## 五、核心功能

### 智能程式碼補全

* **Tab 補全**：按 Tab 接受 AI 建議
* **多行補全**：支援函數級別程式碼生成
* **上下文感知**：基於專案結構提供精準建議

### AI 對話

* `Ctrl/Cmd + K`：打開命令面板
* `Ctrl/Cmd + L`：打開側邊欄對話
* **程式碼解釋**：選中程式碼後詢問 AI

### 程式碼編輯

* **生成程式碼**：描述需求，AI 自動生成
* **重構建議**：獲取程式碼優化方案
* **錯誤修復**：AI 協助定位修復錯誤

## 六、快捷鍵

| 快捷鍵            | 功能          |
| -------------- | ----------- |
| `Ctrl/Cmd + K` | 打開 AI 命令面板  |
| `Ctrl/Cmd + L` | 打開 AI 對話側邊欄 |
| `Tab`          | 接受程式碼建議     |
| `Esc`          | 取消當前建議      |

## 七、使用技巧

### 提供清晰的上下文

```javascript theme={null}
// @context: React組件，用於用戶認證
// @requirements: 需要支援OAuth2登入
// @constraints: 兼容NextJS 13+
```

### 優化提示詞

* **不佳**：`"修復這個函數"`
* **優質**：`"修復calculateTotal函數中的浮點數精度問題，確保金額計算準確到小數點後兩位"`

## 八、故障排除

<AccordionGroup>
  <Accordion title="連接超時">
    * 檢查網路連接
    * 確認 API 地址為 `https://api.mixroute.ai/v1`
    * 驗證 API 密鑰有效性
  </Accordion>

  <Accordion title="模型不回應">
    * 檢查帳戶餘額
    * 嘗試切換其他模型
    * 重啟 Cursor 客戶端
  </Accordion>

  <Accordion title="程式碼建議品質差">
    * 提供更多專案上下文
    * 使用更具體的提示詞
    * 切換性能更優的模型
  </Accordion>
</AccordionGroup>

## 九、最佳實踐

### 專案級配置

在專案根目錄創建 `.cursor-settings.json`：

```json theme={null}
{
  "model": "gpt-5.5",
  "temperature": 0.7,
  "contextFiles": ["README.md", "package.json"],
  "rules": [
    "使用TypeScript嚴格模式",
    "遵循ESLint規範",
    "添加適當的註釋"
  ]
}
```

### 程式碼審查

```text theme={null}
請審查這段程式碼，關注：
1. 性能問題
2. 安全漏洞
3. 程式碼規範
4. 最佳實踐
```

## 十、關於 Agent 模式

若需要 AI 自動修改多文件、執行複雜重構任務，推薦：

* **Cline**：VS Code 插件，支援完整 Agent 功能
* **RooCode**：新興 VS Code AI Agent 插件