创建 Boost 的自定义 Agent

为什么需要自定义 Agent

Laravel Boost 内置支持 Claude Code、Cursor、Codex、GitHub Copilot（VS Code）等主流 AI 编码工具。但若要适配公司内部工具、新兴 AI Agent 或独立的工作流，就需要使用 Boost 的扩展机制来实现自定义 Agent。自定义 Agent 适用的场景：

使用 Boost 尚未支持的 IDE 或 AI 工具
希望将 Boost 集成到公司内部开发流程或自有 CI/CD 流水线中
Agent 拥有独立的配置文件格式或安装步骤

Boost 的扩展架构

Agent 基类

所有 Agent 都继承 Laravel\Boost\Install\Agents\Agent。该抽象类提供的能力：

Agent 的检测（系统级 / 项目级）
MCP 服务器的安装（基于文件 / 基于 Shell 命令）
指南（Guidelines）的转换钩子（transformGuidelines）

必须实现的抽象方法有 2 个（如下表还列出了常见需要覆盖的方法）。

方法	说明
`name()`	Agent 的内部标识符（例如 `claude_code`）
`displayName()`	安装时显示的名称（例如 `Claude Code`）
`systemDetectionConfig(Platform $platform)`	系统级安装的检测配置
`projectDetectionConfig()`	项目级安装的检测配置

3 个契约

为按需启用 Boost 的功能，只需实现下面所需的契约。

契约	作用
`SupportsGuidelines`	AI 指南文件的输出路径与转换处理
`SupportsMcp`	安装 MCP 服务器配置
`SupportsSkills`	Agent Skills 的安装路径

这 3 个契约都是可选的。也可以只支持指南而不支持 MCP。

SupportsGuidelines 契约

interface SupportsGuidelines
{
    // AI 指南写入的文件路径
    public function guidelinesPath(): string;

    // 指南文件是否需要 frontmatter
    public function frontmatter(): bool;

    // 对生成的指南 Markdown 做后处理
    public function transformGuidelines(string $markdown): string;
}

guidelinesPath() 返回生成的指南要写入的路径。例如 Claude Code 是 CLAUDE.md，Cursor 是 .cursor/rules/laravel-boost.mdc，需要匹配 Agent 读取的格式。 transformGuidelines() 是对生成后的 Markdown 进行加工的钩子。可以添加 Agent 专属头部或转换为特殊格式。Agent 基类的默认实现原样返回字符串。

SupportsMcp 契约

interface SupportsMcp
{
    // MCP 命令是否使用绝对路径
    public function useAbsolutePathForMcp(): bool;

    // 返回 PHP 可执行文件的路径
    public function getPhpPath(bool $forceAbsolutePath = false): string;

    // 返回 artisan 的路径
    public function getArtisanPath(bool $forceAbsolutePath = false): string;

    // 安装 MCP 服务器配置
    public function installMcp(string $key, string $command, array $args = [], array $env = []): bool;

    // 安装通过 HTTP 使用的 MCP 服务器配置
    public function installHttpMcp(string $key, string $url): bool;
}

由于 Agent 基类已提供 installMcp() 与 installHttpMcp() 的默认实现，多数情况下只需覆盖 mcpInstallationStrategy() 与 mcpConfigPath() 即可。安装策略有两种：

`McpInstallationStrategy`	行为
`FILE`	将配置写入 JSON / TOML 文件（默认）
`SHELL`	执行 Shell 命令注册 MCP
`NONE`	跳过 MCP 安装

SupportsSkills 契约

interface SupportsSkills
{
    // 写入 Agent Skills 的目录路径
    public function skillsPath(): string;
}

返回 Agent 读取的 Skill 目录路径。例如 Claude Code 是 .claude/skills，Cursor 是 .cursor/skills，需要匹配 Agent 的规范。

创建自定义 Agent

下面我们来实现一个独立的 Agent 类。这里以嵌入自有 CI/CD 工作流的虚构 Agent「MyAgent」为例。

创建 Agent 类

创建 app/Boost/MyAgent.php。

<?php

declare(strict_types=1);

namespace App\Boost;

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

class MyAgent extends Agent implements SupportsGuidelines, SupportsMcp, SupportsSkills
{
    public function name(): string
    {
        return 'my_agent';
    }

    public function displayName(): string
    {
        return 'MyAgent';
    }

    public function systemDetectionConfig(Platform $platform): array
    {
        return match ($platform) {
            Platform::Darwin, Platform::Linux => [
                'command' => 'command -v myagent',
            ],
            Platform::Windows => [
                'command' => 'cmd /c where myagent 2>nul',
            ],
        };
    }

    public function projectDetectionConfig(): array
    {
        return [
            'files' => ['.myagent.json'],
        ];
    }

    // --- SupportsGuidelines ---

    public function guidelinesPath(): string
    {
        return 'MYAGENT.md';
    }

    // frontmatter() 使用 Agent 基类默认（false）
    // transformGuidelines() 也使用基类默认（原样返回）

    // --- SupportsMcp ---

    // useAbsolutePathForMcp()、getPhpPath()、getArtisanPath()、
    // installMcp()、installHttpMcp() 都由 Agent 基类实现

    public function mcpInstallationStrategy(): McpInstallationStrategy
    {
        return McpInstallationStrategy::FILE;
    }

    public function mcpConfigPath(): string
    {
        return '.myagent.json';
    }

    // --- SupportsSkills ---

    public function skillsPath(): string
    {
        return '.myagent/skills';
    }
}

systemDetectionConfig() 与 projectDetectionConfig() 用于 Boost 在系统与项目中自动检测 Agent。执行 boost:install 时会自动把匹配的 Agent 显示为候选。

在 App\Providers\AppServiceProvider 的 boot 方法中注册自定义 Agent。

<?php

namespace App\Providers;

use App\Boost\MyAgent;
use Illuminate\Support\ServiceProvider;
use Laravel\Boost\Boost;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Boost::registerAgent('my_agent', MyAgent::class);
    }
}

注册后执行 php artisan boost:install，MyAgent 就会出现在选项中。

验证

php artisan boost:install

在选择安装目标 Agent 的界面会显示 MyAgent。选择后会生成 MYAGENT.md、.myagent.json 与 .myagent/skills/。

指南的自定义

guidelinesPath 的设置

不同 Agent 读取指南文件的位置不同。

// 作为单文件输出时
public function guidelinesPath(): string
{
    return 'MYAGENT.md';
}

若允许通过配置文件覆盖，会更灵活。

public function guidelinesPath(): string
{
    return config('boost.agents.my_agent.guidelines_path', 'MYAGENT.md');
}

需要 frontmatter 的 Agent

对于像 Cursor 的 .cursor/rules/*.mdc 这种需要 frontmatter 的格式，让 frontmatter() 返回 true。

public function frontmatter(): bool
{
    return true;
}

指南的后处理

可以使用 transformGuidelines() 加工生成后的 Markdown。

public function transformGuidelines(string $markdown): string
{
    // 添加 Agent 专属头部
    $header = "<!-- Generated by Laravel Boost for MyAgent -->\n\n";

    return $header . $markdown;
}

添加自定义 AI 指南

要向 Boost 的指南中追加项目特有的规则，可以把 Blade 文件放入 .ai/guidelines/ 目录。

.ai/
└── guidelines/
    ├── my-domain-rules.blade.php
    └── coding-standards.blade.php

示例文件：

## 项目专属规则

本项目遵循以下约定：

- 模型必须放置在 `App\Models\` 命名空间下
- 所有 API 端点都创建在 `App\Http\Controllers\Api\` 之下
- 数据库事务使用 `DB::transaction()` 并封装在 Service 类内部

@verbatim
<code-snippet name="Service 类中的事务示例" lang="php">
DB::transaction(function () use ($data) {
    $order = Order::create($data);
    $order->items()->createMany($data['items']);
    event(new OrderCreated($order));
});
</code-snippet>
@endverbatim

执行 boost:install 后，这些指南会自动与 Boost 内置指南合并输出。

覆盖内置指南

若把自定义文件放在与 Boost 内置指南相同的路径下，将优先使用你的文件。

# 覆盖 Boost 的 "Inertia React v2 Form Guidance"
.ai/guidelines/inertia-react/2/forms.blade.php

添加自定义 Skill

创建 SKILL.md

在 .ai/skills/{Skill 名}/SKILL.md 中定义 Skill。

.ai/
└── skills/
    └── creating-invoices/
        └── SKILL.md

SKILL.md 由 YAML frontmatter 与 Markdown 指令构成。

---
name: creating-invoices
description: 实现发票（Invoice）的创建、更新、发送相关处理时使用的 Skill。
---

# 发票创建 Skill

## 何时使用此 Skill

用于实现发票模型创建、发票 PDF 生成、邮件发送等场景。

## 文件结构

- `app/Models/Invoice.php` — 发票模型
- `app/Services/InvoiceService.php` — 业务逻辑
- `app/Jobs/SendInvoiceEmail.php` — 邮件发送 Job

## 实现模式

### 创建发票

```php
// $items 是从 Controller 或其他 Service 传入的数组
$invoice = InvoiceService::create([
    'user_id' => $user->id,
    'items' => $items,
    'due_date' => now()->addDays(30),
]);

生成发票 PDF

PDF 通过 barryvdh/laravel-dompdf 生成：

use Barryvdh\DomPDF\Facade\Pdf;
use Illuminate\Support\Facades\Storage;

$pdf = Pdf::loadView('invoices.pdf', ['invoice' => $invoice]);
Storage::put("invoices/{$invoice->id}.pdf", $pdf->output());

Skill 的设计理念是「按需加载」。将始终需要的信息放在指南中，任务专属的详细模式放在 Skill 中，可以优化 AI 的上下文使用。

覆盖内置 Skill

如果使用与 Boost 内置 Skill 相同名字创建自定义 Skill，将覆盖内置版本。

# 自定义 livewire-development Skill
.ai/skills/livewire-development/SKILL.md

为第三方包添加 Boost 支持

要为自己的包添加 Boost 支持，将配置文件放到包的 resources/boost/ 目录下即可。

添加指南

resources/
└── boost/
    └── guidelines/
        └── core.blade.php

## MyPackage

本包提供 [功能概述]。

### 基本用法

@verbatim
<code-snippet name="MyPackage 的初始化" lang="php">
$result = MyPackage::create([
    'option' => 'value',
]);
</code-snippet>
@endverbatim

添加 Skill

resources/
└── boost/
    └── skills/
        └── mypackage-development/
            └── SKILL.md

---
name: mypackage-development
description: 使用 MyPackage 功能实现时使用的 Skill。
---

# MyPackage Development

## 何时使用此 Skill
在使用 MyPackage 实现功能时使用。

## 主要功能

- 功能 1：...
- 功能 2：...

当包用户执行 php artisan boost:install 时，这些指南与 Skill 会自动被检测并展示为可安装对象。

实战示例：面向自研 CI/CD Agent 的自定义 Agent

下面是嵌入公司 CI/CD 流水线的虚构 Agent「PipelineAgent」的完整实现示例。该 Agent 仅支持指南，不支持 MCP 与 Skill。

<?php

declare(strict_types=1);

namespace App\Boost;

use Laravel\Boost\Contracts\SupportsGuidelines;
use Laravel\Boost\Install\Agents\Agent;
use Laravel\Boost\Install\Enums\Platform;

class PipelineAgent extends Agent implements SupportsGuidelines
{
    public function name(): string
    {
        return 'pipeline_agent';
    }

    public function displayName(): string
    {
        return 'Pipeline Agent (CI/CD)';
    }

    public function systemDetectionConfig(Platform $platform): array
    {
        // 通过 CI 环境变量检测存在性
        return [
            'command' => match ($platform) {
                Platform::Windows => 'cmd /c echo %CI_AGENT_VERSION% 2>nul',
                default => 'echo $CI_AGENT_VERSION',
            },
        ];
    }

    public function projectDetectionConfig(): array
    {
        // 通过项目根的配置文件检测
        return [
            'files' => ['.pipeline-agent.yml'],
        ];
    }

    public function guidelinesPath(): string
    {
        // CI/CD Agent 读取规则的路径
        return '.pipeline/CODING_GUIDELINES.md';
    }

    public function frontmatter(): bool
    {
        return false;
    }

    public function transformGuidelines(string $markdown): string
    {
        // 添加流水线元数据头
        $timestamp = now()->toIso8601String();

        return "<!-- Generated by Laravel Boost at {$timestamp} -->\n\n{$markdown}";
    }
}

在 AppServiceProvider 中注册：

use App\Boost\PipelineAgent;
use Laravel\Boost\Boost;

public function boot(): void
{
    Boost::registerAgent('pipeline_agent', PipelineAgent::class);
}

在 CI 环境中可以通过下面的命令只生成指南：

php artisan boost:install --agent=pipeline_agent

参考链接

ClaudeCode.php — 官方实现示例

可从源码查看随 Boost 附带的 ClaudeCode Agent 的完整实现。

Agent Skills

可参考 SKILL.md 的格式规范与最佳实践。

Laravel Boost Custom Agent for GitHub Copilot CLI

同时支持 Copilot CLI 与 Testbench 的公开包实现示例

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

面向 PhpStorm GitHub Copilot 插件的公开包实现示例

AI 开发

设计模式

包开发

应用结构

Laravel 13 新特性

Eloquent 深入

验证扩展

认证扩展

安全

测试

为什么需要自定义 Agent

Boost 的扩展架构

Agent 基类

3 个契约

SupportsGuidelines 契约

SupportsMcp 契约

SupportsSkills 契约

创建自定义 Agent

指南的自定义

guidelinesPath 的设置

需要 frontmatter 的 Agent

指南的后处理

添加自定义 AI 指南

覆盖内置指南

添加自定义 Skill

创建 SKILL.md

生成发票 PDF

覆盖内置 Skill

为第三方包添加 Boost 支持

添加指南

添加 Skill

实战示例：面向自研 CI/CD Agent 的自定义 Agent

参考链接

ClaudeCode.php — 官方实现示例

Agent Skills

Laravel Boost Custom Agent for GitHub Copilot CLI

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

​为什么需要自定义 Agent

​Boost 的扩展架构

​Agent 基类

​3 个契约

​SupportsGuidelines 契约

​SupportsMcp 契约

​SupportsSkills 契约

​创建自定义 Agent

​指南的自定义

​guidelinesPath 的设置

​需要 frontmatter 的 Agent

​指南的后处理

​添加自定义 AI 指南

​覆盖内置指南

​添加自定义 Skill

​创建 SKILL.md

​生成发票 PDF

​覆盖内置 Skill

​为第三方包添加 Boost 支持

​添加指南

​添加 Skill

​实战示例：面向自研 CI/CD Agent 的自定义 Agent

​参考链接

ClaudeCode.php — 官方实现示例

Agent Skills

Laravel Boost Custom Agent for GitHub Copilot CLI

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

为什么需要自定义 Agent

Boost 的扩展架构

Agent 基类

3 个契约

SupportsGuidelines 契约

SupportsMcp 契约

SupportsSkills 契约

创建自定义 Agent

指南的自定义

guidelinesPath 的设置

需要 frontmatter 的 Agent

指南的后处理

添加自定义 AI 指南

覆盖内置指南

添加自定义 Skill

创建 SKILL.md

生成发票 PDF

覆盖内置 Skill

为第三方包添加 Boost 支持

添加指南

添加 Skill

实战示例：面向自研 CI/CD Agent 的自定义 Agent

参考链接