Laravel Boost

• 简介
• 安装
  • 设置你的 Agents
  • 保持 Boost 资源更新
• MCP 服务器
  • 可用的 MCP 工具
  • 手动注册 MCP 服务器
• AI 指南
  • 可用的 AI 指南
  • 添加自定义 AI 指南
  • 覆盖 Boost AI 指南
  • 第三方包 AI 指南
• Agent 技能
  • 可用技能
  • 自定义技能
  • 覆盖技能
  • 第三方包技能
• 指南 vs. 技能
• 项目规则
  • 录制规则
  • 推断应用程序的约定
  • 禁用项目规则
• 文档 API
• 扩展 Boost
  • 添加对其他 IDE / AI Agents 的支持

简介

Laravel Boost 通过提供必要的指南和 Agent 技能，加速 AI 辅助开发，帮助 AI Agent 编写符合 Laravel 最佳实践的高质量 Laravel 应用程序。

Boost 还提供了一个强大的 Laravel 生态系统文档 API，它结合了内置的 MCP 工具和一个包含超过 17,000 条 Laravel 特定信息的广泛知识库，所有这些都通过使用嵌入的语义搜索功能增强了精确的、上下文感知的结果。Boost 指导像 Claude Code 和 Cursor 这样的 AI Agent 使用此 API 来了解最新的 Laravel 功能和最佳实践。

安装

Laravel Boost 可以通过 Composer 安装：

composer require laravel/boost --dev

接下来，安装 MCP 服务器和编码指南：

php artisan boost:install

boost:install 命令将为你在安装过程中选择的编码 Agent 生成相关的 Agent 指南和技能文件。

一旦 Laravel Boost 安装完成，你就可以开始使用 Cursor、Claude Code 或你选择的 AI Agent 进行编码了。

NOTE

请随意将生成的 MCP 配置文件 (.mcp.json)、指南文件 (CLAUDE.md、AGENTS.md、junie/ 等) 和 boost.json 配置文件添加到你的应用程序的 .gitignore 中，因为这些文件会在运行 boost:install 和 boost:update 时自动重新生成。

设置你的 Agents

Cursor

1. 打开命令面板 (`Cmd+Shift+P` 或 `Ctrl+Shift+P`)
2. 在 "/open MCP Settings" 上按 `enter`
3. 打开 `laravel-boost` 的开关

Claude Code

Claude Code 支持通常会自动启用。如果发现没有启用，在项目目录中打开一个 shell 并运行以下命令：

claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp

Codex

Codex 支持通常会自动启用。如果发现没有启用，在项目目录中打开一个 shell 并运行以下命令：

codex mcp add laravel-boost -- php "artisan" "boost:mcp"

Gemini CLI

Gemini CLI 支持通常会自动启用。如果发现没有启用，在项目目录中打开一个 shell 并运行以下命令：

gemini mcp add -s project -t stdio laravel-boost php artisan boost:mcp

GitHub Copilot (VS Code)

1. 打开命令面板 (`Cmd+Shift+P` 或 `Ctrl+Shift+P`)
2. 在 "MCP: List Servers" 上按 `enter`
3. 箭头移动到 `laravel-boost` 并按 `enter`
4. 选择 "Start server"

Junie

1. 按两次 `shift` 打开命令面板
2. 搜索 "MCP Settings" 并按 `enter`
3. 勾选 `laravel-boost` 旁边的复选框
4. 点击右下角的 "Apply"

保持 Boost 资源更新

你可能希望定期更新本地的 Boost 资源（AI 指南和技能），以确保它们反映你已安装的 Laravel 生态系统包的最新版本。为此，你可以使用 boost:update Artisan 命令。

php artisan boost:update

你也可以通过将其添加到 Composer 的 "post-update-cmd" 脚本来自动化此过程：

{
  "scripts": {
    "post-update-cmd": [
      "@php artisan boost:update --ansi"
    ]
  }
}

默认情况下，boost:update 命令只会更新已发布在应用程序中的现有 Boost 资源。如果你希望 Boost 扫描应用程序中新安装的包，并提供发布其对应指南和技能的选项，可以使用 --discover 选项：

php artisan boost:update --discover

MCP 服务器

Laravel Boost 提供了一个 MCP（模型上下文协议）服务器，它公开了一些工具供 AI Agent 与你的 Laravel 应用程序进行交互。这些工具使 Agent 能够检查你的应用程序结构、查询数据库、执行代码等。

可用的 MCP 工具

名称	说明
应用程序信息	读取 PHP 和 Laravel 版本、数据库引擎、生态包列表及其版本，以及 Eloquent 模型
浏览器日志	从浏览器读取日志和错误
数据库连接	检查可用的数据库连接，包括默认连接
数据库查询	对数据库执行查询
数据库模式	读取数据库模式
获取绝对 URL	将相对路径 URI 转换为绝对路径，以便 Agent 生成有效的 URL
最后错误	从应用程序的日志文件中读取最后一个错误
读取日志条目	读取最后的 N 条日志条目
录制规则	将一个持久的项目规则录制到 .ai/rules 中，以便未来的代理继承它。
搜索文档	查询 Laravel 托管的文档 API 服务，根据已安装的包检索文档

手动注册 MCP 服务器

有时你可能需要手动将 Laravel Boost MCP 服务器注册到你选择的编辑器中。你应该使用以下详细信息注册 MCP 服务器：

命令	php
参数	artisan boost:mcp

JSON 示例：

{
    "mcpServers": {
        "laravel-boost": {
            "command": "php",
            "args": ["artisan", "boost:mcp"]
        }
    }
}

AI 指南

AI 指南是可组合的指令文件，预先加载以为 AI Agent 提供关于 Laravel 生态包的基本上下文。这些指南包含核心约定、最佳实践和框架特定模式，帮助 Agent 生成一致、高质量的代码。

可用的 AI 指南

Laravel Boost 包含以下包和框架的 AI 指南。core 指南为给定的包提供通用的、概括性的建议，适用于所有版本。

包	支持的版本
核心与 Boost	core
Laravel 框架	core, 10.x, 11.x, 12.x, 13.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

NOTE

要使你的 AI 指南保持最新，请参阅保持 Boost 资源更新部分。

添加自定义 AI 指南

要使用你自己的自定义 AI 指南增强 Laravel Boost，请将 .blade.php 或 .md 文件添加到你的应用程序的 .ai/guidelines/* 目录中。当你运行 boost:install 时，这些文件将自动与 Laravel Boost 的指南一起包含在内。

覆盖 Boost AI 指南

你可以通过创建自己的具有匹配文件路径的自定义指南来覆盖 Boost 的内置 AI 指南。当你创建的自定义指南与现有的 Boost 指南路径匹配时，Boost 将使用你的自定义版本而不是内置版本。

例如，要覆盖 Boost 的 "Inertia React v2 Form Guidance" 指南，请在 .ai/guidelines/inertia-react/2/forms.blade.php 创建一个文件。当你运行 boost:install 时，Boost 将包含你的自定义指南而不是默认指南。

第三方包 AI 指南

如果你维护一个第三方包，并希望 Boost 为其包含 AI 指南，你可以通过将 resources/boost/guidelines/core.blade.php 文件添加到你的包中来实现。当你包的用户运行 php artisan boost:install 时，Boost 将自动加载你的指南。

AI 指南应简要概述你的包的功能，概述任何必需的文件结构或约定，并解释如何创建或使用其主要功能（附有示例命令或代码片段）。保持简洁、可操作，并专注于最佳实践，以便 AI 能为你的用户生成正确的代码。以下是一个示例：

## 包名称

该包提供 [功能的简要描述]。

### 功能

- 功能1：[清晰简短的描述]。
- 功能2：[清晰简短的描述]。示例用法：

@verbatim
<code-snippet name="如何使用功能2" lang="php">
$result = PackageName::featureTwo($param1, $param2);
</code-snippet>
@endverbatim

Agent 技能

Agent 技能 是轻量级、有针对性的知识模块，Agent 在处理特定领域时可以按需激活。与预先加载的指南不同，技能允许仅在相关时加载详细的模式和最佳实践，从而减少上下文膨胀并提高 AI 生成代码的相关性。

当您运行 boost:install 并选择技能作为一项功能时，技能会根据在 composer.json 中检测到的包自动安装。例如，如果您的项目包含 livewire/livewire，则 livewire-development 技能将被自动安装。Boost 自带的技能，如 infer-conventions，无论您安装了哪些包都会安装。

可用技能

技能	包
fluxui-development	Flux UI
folio-routing	Folio
infer-conventions	Boost
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

NOTE

要使你的技能保持最新，请参阅保持 Boost 资源更新部分。

自定义技能

要创建你自己的自定义技能，请将 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 技能格式，并且应结构化为一个文件夹，其中包含一个带有 YAML 前置元数据和 Markdown 指令的 SKILL.md 文件。SKILL.md 文件必须包含必需的前置元数据（name 和 description），并且可以可选地包含脚本、模板和参考资料。

技能应概述任何必需的文件结构或约定，并解释如何创建或使用其主要功能（附有示例命令或代码片段）。保持简洁、可操作，并专注于最佳实践，以便 AI 能为你的用户生成正确的代码：

---
name: package-name-development
description: 构建和处理 PackageName 功能，包括组件和工作流程。
---

# 包名开发

## 何时使用此技能
在处理 PackageName 功能时使用此技能...

## 功能

- 功能1：[清晰简短的描述]。
- 功能2：[清晰简短的描述]。示例用法：

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

指南 vs. 技能

Laravel Boost 提供了两种不同的方式向 AI Agent 提供有关你的应用程序的上下文：指南和技能。

指南 在 AI Agent 启动时预先加载，提供关于广泛适用于你的代码库的 Laravel 约定和最佳实践的基本上下文。

技能 在处理特定任务时按需激活，包含特定领域（如 Livewire 组件或 Pest 测试）的详细模式。仅在相关时加载技能可以减少上下文膨胀并提高代码质量。

方面	指南	技能
加载方式	预先加载，始终存在	按需加载，相关时激活
范围	广泛，基础性	专注，特定于任务
目的	核心约定和最佳实践	详细的实现模式

指南和技能都描述了 Laravel 生态系统。要捕捉您自己应用程序的约定，您应该使用项目规则。

项目规则

指南和技能教代理如何编写 Laravel 代码，而项目规则则教他们如何编写您的应用程序。规则是您原本需要在每个新会话中反复解释的任何内容：

• 您、您的代理或您的团队成员在此过程中做出的决定。
• 难以让代理遵循的风格指南和偏好。
• 无法从周围代码推断出的陷阱和限制。

规则以 Markdown 文件的形式存储在您应用程序的 .ai/rules 目录中，并应提交到源代码管理。与代理自己的记忆（属于个人且限定于会话范围内）不同，您的规则会在您的团队以及参与应用程序开发的每个代理之间共享。

每个规则文件在其前置元数据中声明它所适用的文件 glob 模式：

---
paths:
  - app/Http/Controllers/**
---

# Http 控制器

## 继承 BaseController 以实现租户范围限定

所有控制器都必须继承 `App\Http\Controllers\BaseController`，该基类会应用当前租户的查询范围。直接继承 Laravel 的基础控制器将会导致数据在租户间泄露。

此外，Boost 维护着一个 .ai/rules/index.md 文件，该文件将 glob 模式映射到相应的规则文件。代理在规划或编辑任何文件之前都会被指示查阅此索引，因此只有在规则相关时才会被加载：

# 项目规则索引

在规划或编辑之前，找到 glob 模式与文件路径匹配的行，并阅读该规则文件。

| 适用于 | 规则文件 |
| --- | --- |
| app/Http/Controllers/** | .ai/rules/controllers.md |
| app/Models/** | .ai/rules/models.md |

NOTE

与 .mcp.json 和生成的指南文件不同，.ai/rules 目录应提交到源代码管理，以便与您的团队共享规则。

录制规则

要录制一条规则，您只需让您的代理记住它：

请记住，所有货币值都以整数形式存储（单位：分），绝不使用浮点数。

代理将调用 Boost 的 record-rule MCP 工具，并传入一个 glob 模式、一个简短的 title 和一个 note。然后，Boost 会将这条规则归档到匹配的区域下，必要时会创建规则文件，并更新索引。

您应该始终使用 record-rule 工具来录制规则，而不是手动创建规则文件。Boost 会在录制规则的过程中重新生成 .ai/rules/index.md，而代理依赖该索引来发现哪些规则适用于他们正在处理的文件。手动添加的规则文件在下一次索引重新生成之前不会被发现。

推断应用程序的约定

逐条录制规则对于以后的开发很有效；然而，一个现有的应用程序已经包含了多年的约定。infer-conventions 技能将从您已经编写的代码中引导生成规则。要开始使用，请让您的代理使用该技能：

使用 infer-conventions 技能

该技能将按照一份 Laravel 约定维度的检查清单来扫描您的应用程序，包括验证、控制器、授权、模型、架构、测试、前端、数据库和控制台，随后还会进行一次开放式的遍历，以发现诸如基类、共享 trait 和模块布局等模式。

该技能记录的是您的代码实际所做的事情，而不是它应该做的事情。它只记录有充分依据的、非默认的约定，跳过框架默认值以及 Pint 或 Rector 已经强制执行的任何内容，并报告真正混合的模式，而不将其记录为规则。在写入任何规则之前，该技能会展示它发现的每一项约定及其支持证据，以供您批准。如果您希望该技能在未经确认的情况下记录所有发现的约定，您可以告诉它“yolo”。

禁用项目规则

项目规则默认启用。要完全禁用它们，请定义以下环境变量。这将移除 record-rule MCP 工具，并阻止 Boost 管理 .ai/rules 目录：

BOOST_RULES_ENABLED=false

文档 API

Laravel Boost 包含一个文档 API，为 AI Agent 提供了访问包含超过 17,000 条 Laravel 特定信息的广泛知识库的途径。该 API 使用带有嵌入的语义搜索来提供精确的、上下文感知的结果。

Search Docs MCP 工具允许 Agent 查询 Laravel 托管的文档 API 服务，以根据你已安装的包检索文档。Boost 的 AI 指南和技能将自动指导你的编码 Agent 使用此 API。

包	支持的版本
Laravel 框架	10.x, 11.x, 12.x, 13.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 Agent。如果你的编码工具尚不支持，你可以创建自己的 Agent 并将其与 Boost 集成。

添加对其他 IDE / AI Agents 的支持

要为新的 IDE 或 AI Agent 添加支持，请创建一个扩展 Laravel\Boost\Install\Agents\Agent 的类，并根据需要实现以下一个或多个契约：

• Laravel\Boost\Contracts\SupportsGuidelines - 添加对 AI 指南的支持。
• Laravel\Boost\Contracts\SupportsMcp - 添加对 MCP 的支持。
• Laravel\Boost\Contracts\SupportsSkills - 添加对 Agent 技能的支持。

编写 Agent

<?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
{
    // 你的实现...
}

有关示例实现，请参阅 ClaudeCode.php。

注册 Agent

在你的应用程序的 App\Providers\AppServiceProvider 的 boot 方法中注册你的自定义 Agent：

use Laravel\Boost\Boost;

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

注册后，你的 Agent 将在运行 php artisan boost:install 时可供选择。