Laravel Boost v2：让AI Agent真正读懂你的Laravel项目的MCP服务器

如果你看过 AI agent 在一个跑着 Livewire v4 的项目上自信满满地生成 Livewire v2 组件，你就已经理解了 Laravel Boost 要解决的是什么问题。没有项目特定的上下文，AI agent 只能默认使用训练数据里所谓的"正确"方案——那几乎不可能是你的技术栈、你的代码规范、或者你当前的包版本。

Laravel Boost 是官方 Laravel MCP（Model Context Protocol）服务器，2025 年 Laracon US 大会上以公开测试版发布，2026 年 1 月 26 日更新至 v2.0。它让 AI agent——Claude Code、Cursor、Windsurf、Copilot、Codex CLI——能够实时、结构化地访问你运行中的 Laravel 应用：它的 schema、日志、路由、文档，以及代码规范。本文将从头到尾走一遍 v2 工作流，包含实用命令、真实权衡，以及需要规避的具体错误。

关于生态的更全面概述（Laravel AI SDK、LarAgent、Prism PHP），请参阅父指南：Laravel Boost and AI Skills: Agentic Development for Laravel。

前提条件与版本要求

安装之前，请确认你的环境满足以下要求：

• Laravel：10、11、12 或 13
• PHP：8.1 或更高版本（Boost 本身的要求）
• AI agent / IDE：必须支持 MCP——Claude Code、Cursor、Windsurf、GitHub Copilot（Workspace）或 Codex CLI
• Laravel Boost：推荐 v2.4.0+（新增了 skill 安装时的安全审计）

重要提示：Laravel Boost 只是一个 --dev 依赖。它暴露了 Tinker（任意 PHP 执行）和直接数据库查询工具。切勿在生产环境安装，也切勿将它的 MCP 服务器暴露给不受信任的网络。

步骤 1 —— 安装 Laravel Boost

安装只需两条命令：

composer require laravel/boost --dev
php artisan boost:install

boost:install 做了三件事：

• 将 boost/ 目录发布到项目根目录，其中包含 guidelines/ 文件
• 检测 composer.json 中的包，并自动安装匹配的 skills
• 为你的 agent IDE 注册 MCP 服务器配置

安装完成后，你的 AI agent 可以访问以下内置 MCP 工具：

v2.3.0 破坏性变更：六个薄的 MCP 工具封装被移除了——list-artisan-commands、list-routes、tinker、get-config、list-available-env-vars 和 list-available-config-keys。如果你的 agent 工作流引用过这些工具名，请更新为使用 CLI 等价命令（php artisan list、php artisan route:list、php artisan config:show）。

步骤 2 —— 理解 Guidelines 与 Skills

Laravel Boost v2 将上下文分为两类：

Guidelines 在每个 agent 会话开始时加载。它们存放你项目的核心规范——认证模式、命名规则、偏好的包、编码风格。可以把它们想象成项目 README，每个 agent 在修改文件之前都会读取。Guidelines 位于 boost/guidelines/。

Skills 按需加载，用于特定任务。一个 skill 包含某个特定领域的深度知识——Livewire 组件模式、Pest 测试规范、Inertia.js 集成规则等。Skill 只在 agent 需要时才会加载，这保持了上下文窗口的精简和 token 成本的低廉。

这里最常见的错误是把所有东西都塞进 guidelines。一个 5,000 token 的 guideline 文件在每次会话中都加载，而很多任务根本不会涉及那个技术，白白浪费了上下文。如果你正在开发一个重度依赖 Livewire 的功能，就加载 Livewire skill；如果是例行 migration，就跳过它。

步骤 3 —— 安装 Skills

boost:install 运行时，会扫描 composer.json 并自动安装匹配的 skills。如果检测到 Livewire，就会自动安装 Livewire skill。Pest、Inertia、Tailwind 和其他支持的包同理。

手动添加 skills：

# 从官方 Laravel Skills 目录安装（skills.laravel.cloud）
php artisan boost:add-skill laravel/livewire-skill

# 从任意 GitHub 仓库安装
php artisan boost:add-skill https://github.com/owner/repo

# 简短写法也可以
php artisan boost:add-skill owner/repo

从 v2.4.0 开始，boost:add-skill 会在安装前对拉取的 skill 进行安全审计。这会扫描 skill 内容，查找任何以意外方式修改代码生成规范的内容——在确认安装社区 skills 之前，务必查看审计输出。

位于 skills.laravel.cloud 的 Laravel Skills 目录收录了 100+ 官方和社区 skills。社区 skills 质量参差不齐——安装之前请先阅读 skill 的源码，特别是那些覆盖了默认 Artisan stub 模式的 skills。

步骤 4 —— 一个真实的 Agentic 工作流

以下是结合 Boost 进行 agentic 开发的实际样子，以一个功能分支为例。

场景：你需要添加一个 document_uploads 表，包含用于语义搜索的 embedding 列，接入一个 Livewire 上传组件，并编写 Pest 测试。

4-A —— Agent 在编写 migration 之前先检查 schema

没有 Boost，agent 只能猜测你现有的表名和列规范。有了 Boost，它调用 database-schema 来读取当前结构，然后生成一个符合规范的 migration：

# Agent 内部调用这个 MCP 工具——不需要你手动运行
# database-schema → 返回所有表的列类型、索引、外键

Agent 看到你用的是 PostgreSQL，其他 timestamp 列都用了 timestamptz，于是据此编写 migration：

// database/migrations/2026_08_01_000000_create_document_uploads_table.php
return new class extends Migration {
    public function up(): void
    {
        Schema::ensureVectorExtensionExists(); // 启用 pgvector
        Schema::create('document_uploads', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('filename');
            $table->text('body')->nullable();
            $table->vector('embedding', 1536); // OpenAI ada-002 维度
            $table->timestampsTz();
        });
    }
};

数据库要求：向量列类型和 whereVectorSimilarTo 需要带有 pgvector 扩展的 PostgreSQL。在 MySQL 或 SQLite 上无法工作。如果你的项目跑在 MySQL 上，embedding 列必须存在于一个独立的 PostgreSQL 服务或专用向量存储中。

4-B —— Agent 在测试失败后检查上一个错误

你运行 php artisan test，某个测试失败了。Agent 不是自己去读日志，而是调用 last-error 和 read-log-entries。在 v2.3.0 中，Boost 新增了 JSON 日志格式自动检测，所以 Monolog 的 JsonFormatter、LogstashFormatter 和 LogglyFormatter 生成的结构化日志都能被清晰解析：

# Agent 调用 read-log-entries——返回解析后的日志条目，包含 level、message、context
# 不需要手动读日志

4-C —— Agent 在 Livewire skill 激活状态下生成 Livewire 组件

加载了 Livewire skill 后，Agent 生成的是 Livewire v3/v4 语法——wire 指令、#[On] 属性、$wire 绑定——而不是训练数据里的默认 v2 模式。

没有 skill 时：Agent 生成 @wire 和 $emit()（Livewire v2）。有 skill 时：Agent 生成 wire:model、dispatch() 和正确的生命周期钩子。

4-D —— Agent 解析命名路由

Agent 需要一个重定向的绝对 URL。它调用 get-absolute-url 并传入路由名，然后收到包含 APP_URL 前缀的完整解析 URL——无需猜测域名。

步骤 5 —— 测试与验证

验证 Boost MCP 服务器正在运行且可从你的 IDE 访问：

# 检查 Boost 是否正确注册
php artisan boost:status

# 确认可用工具（输出列出了所有已注册的 MCP 工具）
php artisan boost:list-tools

对于生成的每个 migration，在提交前先对测试数据库跑一次 dry migration：

php artisan migrate --database=testing --pretend

对于 Agent 生成的 Pest 测试：

php artisan test --filter=DocumentUploadTest

如果 Agent 在开发过程中使用了 database-query 来检查数据，请审计查询日志：

# 检查 agent 是否只运行了 SELECT 语句——而不是写操作
grep -i 'INSERT\|UPDATE\|DELETE' storage/logs/laravel.log

常见错误与限制

在生产环境安装 Boost。database-query 工具允许对你的应用数据库执行任意 SQL。这是一个仅限开发时使用的工具——它绝不能被生产服务器或不受信任的网络访问到。

在 boost:install 之前运行 boost:add-skill。Skills 扩展的是 boost:install 创建的 guidelines 基础设施。如果先运行 add-skill，skill 没有上下文框架可以依附。请务必先安装 Boost，再添加 skills。

期望所有 IDE 都支持 MCP。Boost 要求你的 IDE 或 agent 实现了 Model Context Protocol。普通的 ChatGPT、标准 VS Code Copilot（非 Workspace）以及大多数旧版 agent 配置都不支持 MCP，无法从 Boost 中受益。

把所有东西都放进 Guidelines。如果你的 boost/guidelines/ 文件夹内容超过了 3,000–4,000 token，你每次会话都在加载过多内容。请将领域特定的规则（Livewire 规范、Pest 测试模式）移入 skills。

假设 v2.3.0 移除的工具仍然可用。被移除的六个 MCP 工具（list-artisan-commands、list-routes、tinker、get-config、list-available-env-vars、list-available-config-keys）在 Boost 中已不再存在。调用这些工具名的 agent 工作流或自动化脚本会静默失败。请改用直接的 Artisan CLI 命令。

值得了解的权衡

Boost MCP 工具 vs 纯 CLI 访问。Boost 为 agent 提供了来自 database-schema、last-error 等工具的结构化、类型化输出。纯 CLI（通过 shell）给了更多能力但结构更少——agent 收到的是原始文本，必须自己解析。Boost v2.3.0 移除了那六个薄封装，现在引导 agent 对被移除的六个命令使用 CLI，这意味着你的 agent IDE 需要具备这些特定功能的 shell 执行能力。

Skills vs 专门的 prompt 工程。Skills 在你的项目使用了有明确定义的规范的包时很有效（Livewire、Pest、Inertia）。对于高度定制的内部系统，你仍然需要编写自定义 guidelines——公共目录里的 skills 不会了解你自定义的服务架构。

单 Agent vs 多 Agent。Boost 针对做出上下文决策的单个 AI agent 做了优化。多 Agent 工作流（如官方 Laravel 博客描述的）在 agent 之间的边界处引入了 prompt 注入风险——在根据跨 agent 传递的数据行动之前，务必对其做验证和清理。

常见问题

Laravel Boost 能配合任意 AI 助手使用吗？

Laravel Boost 需要支持 Model Context Protocol（MCP）的 AI agent 或 IDE。支持的产品包括 Claude Code、Cursor、Windsurf、GitHub Copilot Workspace 和 Codex CLI。标准 ChatGPT、普通 VS Code 扩展，以及其他不支持 MCP 的 agent 都无法连接 Boost 服务器。

Laravel Boost 用于真实应用数据安全吗？

Laravel Boost 是一个仅限开发时使用的工具，必须只连接开发或预发布数据库。database-query MCP 工具执行任意 SQL，last-error 工具暴露应用内部信息。请只使用非生产凭证和隔离数据库进行配置。Laravel Boost v2.4.0 在 skill 安装流程中加入了安全审计，但该审计覆盖的是 skill 代码，而非数据库访问权限。

Boost Guideline 和 Boost Skill 的区别是什么？

Guidelines 在每个 agent 会话开始时加载，包含适用于所有任务的项目核心规范——认证模式、命名规范和项目级规则。Skills 按需加载，用于特定的领域任务，例如生成 Livewire 组件或编写 Pest 测试。用 skills 而非 guidelines 来管理领域知识，可以减少每次会话的 token 使用量，并保持 agent 上下文聚焦在当前任务上。

我可以编写自己的自定义 Boost skill 吗？

可以。Boost skill 是一个遵循 Boost schema 的结构化目录，包含 Markdown 上下文文件。你可以为内部类库、特定领域的模式或自定义 Artisan 命令创建一个私有 skill，并使用 php artisan boost:add-skill path/to/local-skill 或从私有 GitHub 仓库安装。位于 skills.laravel.cloud 的 Laravel Skills 目录也接受社区贡献。

Laravel AI SDK 需要 Laravel Boost 吗？

不需要。Laravel Boost（面向开发时 AI agent 的 MCP 服务器）和 Laravel AI SDK（laravel/ai，面向生产应用中运行时 AI 功能的包）是独立的两套包，服务于不同目的。Laravel Boost 帮助 AI agent 在开发时写出更好的 Laravel 代码。Laravel AI SDK 为你的生产应用添加了 Agent 类、工具调用、RAG 和 provider 集成。注意 Laravel AI SDK 需要 PHP 8.4，而 Boost 本身在 PHP 8.1+ 上即可工作。

如果你需要在孟买做 Laravel 开发，Mumbai Web Designer 构建生产级 Laravel 应用。

如需进一步操作，你可以考虑屏蔽此人或举报滥用。