建立 Boost 的自定義 Agent - Knowledge of Laravel

為什麼需要自定義 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 顯示為候選。

註冊 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 外掛的公開包實現示例

​為什麼需要自定義 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

參考連結