> ## 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 功能与最佳实践。

## 安装

通过 Composer 安装 Laravel Boost：

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

然后安装 MCP 服务器与编码指南：

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

`boost:install` 命令会为安装时选定的编码代理生成对应的指南与 Skills 文件。

安装完成后，你就可以使用 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" 并回车
    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 theme={null}
    codex mcp add laravel-boost -- php "artisan" "boost:mcp"
    ```
  </Tab>

  <Tab title="Gemini CLI">
    Gemini CLI 通常会自动启用。若未生效，请在项目目录执行：

    ```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" 并回车
    3. 选择 `laravel-boost` 并回车
    4. 选择 "Start server"
  </Tab>

  <Tab title="Junie">
    1. 按两次 `Shift` 打开命令面板
    2. 搜索 "MCP Settings" 并回车
    3. 勾选 `laravel-boost` 前的复选框
    4. 点击右下的 "Apply"
  </Tab>
</Tabs>

### 更新 Boost 资源

为了反映已安装的 Laravel 生态包的最新版本，建议定期更新本地 Boost 资源（AI 指南与 Skills）。使用 `boost:update` 命令：

```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 资源。若希望它检测新安装的包并提示发布对应指南或 Skills，请使用 `--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 服务器：

| 项           | 值                   |
| ----------- | ------------------- |
| **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>

### 添加自定义指南

若要添加自定义的 AI 指南，请在应用的 `.ai/guidelines/*` 目录下放置 `.blade.php` 或 `.md` 文件。运行 `boost:install` 时，这些文件会自动与 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 能为用户生成正确代码。

```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) 是轻量、聚焦的知识模块，代理在具体领域下按需启用。与指南（预加载）不同，Skills 仅在相关时加载详细模式和最佳实践，避免上下文膨胀，提高 AI 生成代码的质量。

在 `boost:install` 中启用 Skills 后，会根据 `composer.json` 识别的包自动安装对应 Skills。例如项目里有 `livewire/livewire`，就会自动安装 `livewire-development` Skill。

### 可用 Skills

| Skill                      | 包              |
| -------------------------- | -------------- |
| 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>
  要保持 Skills 为最新，请参阅[更新 Boost 资源](#更新-boost-资源)。
</Tip>

### 创建自定义 Skill

要创建自定义 Skill，请在应用的 `.ai/skills/{skill-name}/` 目录下放置 `SKILL.md`。执行 `boost:update` 时，自定义 Skill 会随 Boost 内置 Skills 一起安装。

例如，为应用特有的领域逻辑创建自定义 Skill：

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

### 覆盖 Skill

创建同名的自定义 Skill 就能覆盖 Boost 内置 Skill。若与内置名字一致，Boost 会用你的自定义版本代替默认。

例如覆盖 Boost 的 `livewire-development` Skill，可在 `.ai/skills/livewire-development/SKILL.md` 创建文件。运行 `boost:update` 时 Boost 会使用自定义版。

### 第三方包的 Skills

若维护第三方包并希望通过 Boost 提供 Skills，可在包内添加 `resources/boost/skills/{skill-name}/SKILL.md`。用户执行 `php artisan boost:install` 时，Boost 会根据用户意愿自动安装。

Boost 的 Skills 遵循 Agent Skills 格式，需以文件夹形式存储包含 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);
```

## 指南与 Skills 的对比

Laravel Boost 提供两种向 AI 代理提供应用上下文的方式：**指南**与 **Skills**。

**指南**会在 AI 代理启动时预加载，用于提供广泛适用的 Laravel 约定和最佳实践。

**Skills**在处理具体任务时按需启用，包含特定领域（如 Livewire 组件、Pest 测试）的详细模式。仅在必要时加载可以减少上下文膨胀、提高质量。

| 维度       | 指南        | Skills   |
| -------- | --------- | -------- |
| **加载时机** | 预加载，始终存在  | 按需，仅在相关时 |
| **作用范围** | 广泛、基础     | 聚焦、任务专属  |
| **目的**   | 核心约定与最佳实践 | 详细的实现模式  |

## 文档 API

Laravel Boost 提供了一个文档 API，向 AI 代理开放包含 17,000+ 条 Laravel 专属信息的知识库。该 API 采用基于向量的语义搜索，能给出精准且上下文相关的结果。

通过 `Search Docs` MCP 工具，代理可依据已安装的包向 Laravel 托管的文档 API 发起查询。Boost 的 AI 指南与 Skills 会自动指导编码代理使用该 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 代理的支持

创建继承 `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/ai.md)
- [创建 Boost 的自定义 Agent](/zh/advanced/boost-custom-agent.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/zh/packages/laravel-boost-copilot-cli.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/zh/packages/laravel-boost-phpstorm-copilot.md)
- [Laravel MCP](/zh/mcp.md)