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

# Laravel Boost

> Laravel Boost 是加速 AI 輔助開發的套件。透過 MCP 伺服器、AI 指南與 Agent Skills，讓 AI 編碼代理能深入理解你的 Laravel 應用程式。

## 簡介

Laravel Boost 是一款透過提供必要的指南與 Agent Skills，讓 AI 代理能依循 Laravel 最佳實踐撰寫高品質 Laravel 應用程式，從而加速 AI 輔助開發的套件。

Boost 同時提供強大的 Laravel 生態系文件 API，結合了包含超過 17,000 項 Laravel 特定資訊的知識庫，以及使用嵌入向量的語義搜尋。Boost 會指示 Claude Code、Cursor 等 AI 代理運用此 API，學習最新的 Laravel 功能與最佳實踐。

## 安裝

Laravel Boost 透過 Composer 進行安裝。

```shell theme={null}
composer require laravel/boost --dev
```

接著安裝 MCP 伺服器與程式撰寫指南。

```shell theme={null}
php artisan boost:install
```

`boost:install` 指令會依照安裝時選取的編碼代理，生成相對應的指南與技能檔案。

安裝完成後，你就可以透過 Cursor、Claude Code 或任何你偏好的 AI 代理開始撰寫程式碼。

<Note>
  生成的 MCP 設定檔（`.mcp.json`）、指南檔案（`CLAUDE.md`、`AGENTS.md`、`junie/` 等）以及 `boost.json` 設定檔可以加入應用程式的 `.gitignore`。這些檔案會在執行 `boost:install` 或 `boost:update` 時自動重新生成。
</Note>

### 代理設定

<Tabs>
  <Tab title="Cursor">
    1. 開啟命令面板（`Cmd+Shift+P` 或 `Ctrl+Shift+P`）
    2. 選擇 "/open MCP Settings" 並按下 `Enter`
    3. 開啟 `laravel-boost` 的切換開關
  </Tab>

  <Tab title="Claude Code">
    Claude Code 的支援通常會自動啟用。若未啟用，請在專案目錄中開啟 shell 並執行以下指令。

    ```shell theme={null}
    claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp
    ```
  </Tab>

  <Tab title="Codex">
    Codex 的支援通常會自動啟用。若未啟用，請在專案目錄中開啟 shell 並執行以下指令。

    ```shell theme={null}
    codex mcp add laravel-boost -- php "artisan" "boost:mcp"
    ```
  </Tab>

  <Tab title="Gemini CLI">
    Gemini CLI 的支援通常會自動啟用。若未啟用，請在專案目錄中開啟 shell 並執行以下指令。

    ```shell theme={null}
    gemini mcp add -s project -t stdio laravel-boost php artisan boost:mcp
    ```
  </Tab>

  <Tab title="GitHub Copilot (VS Code)">
    1. 開啟命令面板（`Cmd+Shift+P` 或 `Ctrl+Shift+P`）
    2. 選擇 "MCP: List Servers" 並按下 `Enter`
    3. 選擇 `laravel-boost` 並按下 `Enter`
    4. 選擇 "Start server"
  </Tab>

  <Tab title="Junie">
    1. 連按兩次 `Shift` 開啟命令面板
    2. 搜尋 "MCP Settings" 並按下 `Enter`
    3. 勾選 `laravel-boost` 旁的核取方塊
    4. 點擊右下角的 "Apply"
  </Tab>
</Tabs>

### 更新 Boost 資源

為了反映已安裝 Laravel 生態系套件的最新版本，建議定期更新本機的 Boost 資源（AI 指南與技能）。請使用 `boost:update` Artisan 指令。

```shell theme={null}
php artisan boost:update
```

你也可以將它加入 Composer 的 `post-update-cmd` 腳本以自動化執行。

```json theme={null}
{
  "scripts": {
    "post-update-cmd": [
      "@php artisan boost:update --ansi"
    ]
  }
}
```

預設情況下，`boost:update` 指令只會更新應用程式中已經發佈的 Boost 資源。若你希望它偵測新安裝的套件並提示發佈其指南或技能，請使用 `--discover` 選項。

```shell theme={null}
php artisan boost:update --discover
```

## MCP 伺服器

Laravel Boost 提供 MCP（Model Context Protocol）伺服器，並公開一組讓 AI 代理與 Laravel 應用程式互動的工具。透過這些工具，代理可以檢視應用程式結構、查詢資料庫或執行程式碼。

### 可用的 MCP 工具

| 工具名稱                 | 說明                                                    |
| -------------------- | ----------------------------------------------------- |
| Application Info     | 讀取 PHP 與 Laravel 版本、資料庫引擎、附版本號的生態系套件清單，以及 Eloquent 模型 |
| Browser Logs         | 讀取來自瀏覽器的日誌與錯誤                                         |
| Database Connections | 檢視可用的資料庫連線，包含預設連線                                     |
| Database Query       | 對資料庫執行查詢                                              |
| Database Schema      | 讀取資料庫綱要                                               |
| Get Absolute URL     | 將相對路徑 URI 轉換為絕對 URL，讓代理能生成有效的 URL                     |
| Last Error           | 從應用程式的日誌檔案讀取最後一筆錯誤                                    |
| Read Log Entries     | 讀取最後 N 筆日誌條目                                          |
| Search Docs          | 依照已安裝的套件，查詢 Laravel 託管型文件 API 服務                      |

### 手動註冊 MCP 伺服器

某些編輯器可能需要手動註冊 Laravel Boost MCP 伺服器。請使用以下資訊註冊 MCP 伺服器。

| 項目          | 值                   |
| ----------- | ------------------- |
| **Command** | `php`               |
| **Args**    | `artisan boost:mcp` |

JSON 格式的範例：

```json theme={null}
{
    "mcpServers": {
        "laravel-boost": {
            "command": "php",
            "args": ["artisan", "boost:mcp"]
        }
    }
}
```

## AI 指南

AI 指南是預先載入的指令檔案，用來提供 AI 代理有關 Laravel 生態系套件的重要脈絡。這些指南包含核心慣例、最佳實踐與框架特定模式，有助於代理產生一致且高品質的程式碼。

### 可用的指南

Laravel Boost 提供以下套件與框架的 AI 指南。`core` 指南提供與版本無關、通用的建議。

| 套件                | 支援版本                   |
| ----------------- | ---------------------- |
| Core & Boost      | core                   |
| Laravel Framework | core, 10.x, 11.x, 12.x |
| Livewire          | core, 2.x, 3.x, 4.x    |
| Flux UI           | core, free, pro        |
| Folio             | core                   |
| Herd              | core                   |
| Inertia Laravel   | core, 1.x, 2.x, 3.x    |
| Inertia React     | core, 1.x, 2.x, 3.x    |
| Inertia Vue       | core, 1.x, 2.x, 3.x    |
| Inertia Svelte    | core, 1.x, 2.x, 3.x    |
| MCP               | core                   |
| Pennant           | core                   |
| Pest              | core, 3.x, 4.x         |
| PHPUnit           | core                   |
| Pint              | core                   |
| Sail              | core                   |
| Tailwind CSS      | core, 3.x, 4.x         |
| Livewire Volt     | core                   |
| Wayfinder         | core                   |
| Enforce Tests     | conditional            |

<Tip>
  如需將 AI 指南保持在最新狀態，請參閱[更新 Boost 資源](#更新-boost-資源)。
</Tip>

### 新增自訂指南

若要在 Laravel Boost 中加入自訂的 AI 指南，請將 `.blade.php` 或 `.md` 檔案放入應用程式的 `.ai/guidelines/*` 目錄。執行 `boost:install` 時，這些檔案會自動與 Laravel Boost 的指南結合。

### 覆寫 Boost 指南

你可以建立與檔案路徑相符的自訂指南，來覆寫 Boost 內建的指南。當你建立的自訂指南路徑與現有 Boost 指南相符時，Boost 會使用自訂版本取代內建指南。

例如，要覆寫 Boost 的 "Inertia React v2 Form Guidance" 指南，請在 `.ai/guidelines/inertia-react/2/forms.blade.php` 建立檔案。執行 `boost:install` 後，Boost 便會以自訂指南取代預設指南。

### 第三方套件的指南

若你維護第三方套件，並希望在 Boost 中包含該套件的 AI 指南，請於套件中加入 `resources/boost/guidelines/core.blade.php` 檔案。當使用者執行 `php artisan boost:install` 時，Boost 會自動載入該指南。

AI 指南應包含套件概述、必要的檔案結構與慣例說明，以及主要功能的建立與使用方式（含指令與程式碼片段範例）。內容應簡潔並以行動為導向，聚焦於最佳實踐，才能讓 AI 為使用者產生正確的程式碼。

```php theme={null}
## Package Name

This package provides [brief description of functionality].

### Features

- Feature 1: [clear & short description].
- Feature 2: [clear & short description]. Example usage:

@verbatim
<code-snippet name="How to use Feature 2" lang="php">
$result = PackageName::featureTwo($param1, $param2);
</code-snippet>
@endverbatim
```

## Agent Skills

[Agent Skills](https://agentskills.io/home) 是輕量、焦點明確的知識模組，代理在特定領域工作時可依需求啟用。與指南不同，指南是預先載入的，而技能只在相關時才載入詳細模式與最佳實踐，能避免脈絡膨脹並提升 AI 生成程式碼的品質。

執行 `boost:install` 並選擇將技能作為功能安裝後，Boost 會依 `composer.json` 中偵測到的套件自動安裝相應技能。例如，若專案包含 `livewire/livewire`，`livewire-development` 技能會被自動安裝。

### 可用的技能

| 技能                         | 套件             |
| -------------------------- | -------------- |
| fluxui-development         | Flux UI        |
| folio-routing              | Folio          |
| inertia-react-development  | Inertia React  |
| inertia-svelte-development | Inertia Svelte |
| inertia-vue-development    | Inertia Vue    |
| livewire-development       | Livewire       |
| mcp-development            | MCP            |
| pennant-development        | Pennant        |
| pest-testing               | Pest           |
| tailwindcss-development    | Tailwind CSS   |
| volt-development           | Volt           |
| wayfinder-development      | Wayfinder      |

<Tip>
  如需將技能保持在最新狀態，請參閱[更新 Boost 資源](#更新-boost-資源)。
</Tip>

### 建立自訂技能

若要建立自訂技能，請將 `SKILL.md` 檔案放入應用程式的 `.ai/skills/{skill-name}/` 目錄。執行 `boost:update` 後，自訂技能將與 Boost 內建技能一同安裝。

例如，為應用程式特定的網域邏輯建立自訂技能：

```
.ai/skills/creating-invoices/SKILL.md
```

### 覆寫技能

你可以建立與名稱相符的自訂技能，來覆寫 Boost 內建的技能。當你建立的自訂技能名稱與現有 Boost 技能相符時，Boost 會以自訂版本取代內建技能。

例如，要覆寫 Boost 的 `livewire-development` 技能，請在 `.ai/skills/livewire-development/SKILL.md` 建立檔案。執行 `boost:update` 後，Boost 便會以自訂技能取代預設技能。

### 第三方套件的技能

若你維護第三方套件，並希望在 Boost 中包含該套件的技能，請於套件中加入 `resources/boost/skills/{skill-name}/SKILL.md` 檔案。當使用者執行 `php artisan boost:install` 時，Boost 會依使用者的意願自動安裝該技能。

Boost 的技能支援 Agent Skills 格式，須組織成內含 `SKILL.md` 檔案的資料夾，該檔案包含 YAML frontmatter 與 Markdown 指令。`SKILL.md` 檔案須包含必要的 frontmatter（`name` 與 `description`），並可選擇性地包含腳本、範本與參考資料。

```markdown theme={null}
---
name: package-name-development
description: Build and work with PackageName features, including components and workflows.
---

# Package Name Development

## When to use this skill
Use this skill when working with PackageName features...

## Features

- Feature 1: [clear & short description].
- Feature 2: [clear & short description]. Example usage:

$result = PackageName::featureTwo($param1, $param2);
```

## 指南與技能的比較

Laravel Boost 提供兩種不同的方式來為 AI 代理提供關於應用程式的脈絡：**指南**與**技能**。

**指南**會在 AI 代理啟動時預先載入，提供廣泛適用於整個程式碼庫的 Laravel 慣例與最佳實踐等重要脈絡。

**技能**則在處理特定任務時依需求啟用，包含特定領域（例如 Livewire 元件或 Pest 測試）的詳細模式。只在需要時載入技能，可以避免脈絡膨脹並提升程式碼品質。

| 面向       | 指南        | 技能        |
| -------- | --------- | --------- |
| **載入時機** | 預先，永遠存在   | 依需求，僅在相關時 |
| **範疇**   | 廣泛、基礎性    | 聚焦、任務特定   |
| **目的**   | 核心慣例與最佳實踐 | 詳細的實作模式   |

## 文件 API

Laravel Boost 附帶一個文件 API，讓 AI 代理能存取包含超過 17,000 項 Laravel 特定資訊的知識庫。此 API 使用嵌入向量進行語義搜尋，提供精確且具上下文感知的結果。

透過 `Search Docs` MCP 工具，代理可依照已安裝的套件查詢 Laravel 託管型文件 API 服務。Boost 的 AI 指南與技能會自動指示編碼代理使用此 API。

| 套件                | 支援版本               |
| ----------------- | ------------------ |
| Laravel Framework | 10.x, 11.x, 12.x   |
| Filament          | 2.x, 3.x, 4.x, 5.x |
| Flux UI           | 2.x Free, 2.x Pro  |
| Inertia           | 1.x, 2.x           |
| Livewire          | 1.x, 2.x, 3.x, 4.x |
| Nova              | 4.x, 5.x           |
| Pest              | 3.x, 4.x           |
| Tailwind CSS      | 3.x, 4.x           |

## 擴充 Boost

Boost 對於許多常見的 IDE 與 AI 代理都可以直接使用。若你使用的編碼工具尚未支援，你可以建立自訂代理並與 Boost 整合。

### 新增對其他 IDE / AI 代理的支援

若要新增對新的 IDE 或 AI 代理的支援，請建立一個繼承 `Laravel\Boost\Install\Agents\Agent` 的類別，並依需求實作以下一個或多個介面（contract）。

* `Laravel\Boost\Contracts\SupportsGuidelines` — 新增對 AI 指南的支援
* `Laravel\Boost\Contracts\SupportsMcp` — 新增對 MCP 的支援
* `Laravel\Boost\Contracts\SupportsSkills` — 新增對 Agent Skills 的支援

#### 實作代理

```php theme={null}
<?php

declare(strict_types=1);

namespace App;

use Laravel\Boost\Contracts\SupportsGuidelines;
use Laravel\Boost\Contracts\SupportsMcp;
use Laravel\Boost\Contracts\SupportsSkills;
use Laravel\Boost\Install\Agents\Agent;

class CustomAgent extends Agent implements SupportsGuidelines, SupportsMcp, SupportsSkills
{
    // Your implementation...
}
```

實作範例請參閱 [ClaudeCode.php](https://github.com/laravel/boost/blob/main/src/Install/Agents/ClaudeCode.php)。

#### 註冊代理

將自訂代理註冊到應用程式的 `App\Providers\AppServiceProvider` 的 `boot` 方法中。

```php theme={null}
use Laravel\Boost\Boost;

public function boot(): void
{
    Boost::registerAgent('customagent', CustomAgent::class);
}
```

註冊後，執行 `php artisan boost:install` 時，代理會出現在可選項目中。


## Related topics

- [Laravel 與 AI 開發](/zh-TW/ai.md)
- [建立 Boost 的自定義 Agent](/zh-TW/advanced/boost-custom-agent.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/zh-TW/packages/laravel-boost-copilot-cli.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/zh-TW/packages/laravel-boost-phpstorm-copilot.md)
- [AI Agent 從「正確」的程式碼邁向「有 Laravel 風格」的程式碼 - Boost Benchmarks 的下一步](/zh-TW/blog/boost-benchmarks-idiomatic-laravel.md)