> ## 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 PAO — 針對 AI Agent 的輸出最佳化工具

> 介紹 laravel/pao。將 PHPUnit、Pest、PHPStan、Artisan 的輸出於 AI Agent 環境下壓縮為 JSON，最多可減少 99.8% token 消耗的 Laravel 官方套件。

## 前言

[laravel/pao](https://github.com/laravel/pao) 是為 AI Agent 最佳化 PHP 開發工具輸出的套件。**PAO（PHP Agent-Optimized output）** 會將 PHPUnit、Pest、Paratest、PHPStan、Laravel Artisan 冗長的輸出自動轉換為結構化的簡潔 JSON。

由於包含 GitHub Copilot 在內的許多 AI Agent 已轉為以 token 數計費，減少工具輸出可直接降低成本。PAO 就是為解決此問題而設計，並預計成為 Laravel 啟動套件的預設相依。

```mermaid theme={null}
graph TD
    A["工具執行<br>(PHPUnit/Pest/PHPStan/Artisan)"] --> B{"AI Agent<br>環境?"}
    B -->|Yes| C["壓縮為 JSON 輸出"]
    B -->|No| D["一般輸出<br>(不變)"]
    C --> E["AI Agent 節省 token<br>並處理"]
    D --> F["人類照常確認"]
```

## 為何重要

AI Agent 深度融入開發流程之際，工具的輸出 token 數直接影響成本與回應速度。

擁有 1,000 個測試的專案，PHPUnit 輸出可能達數千行，但 AI Agent 需要的資訊只有「成功、失敗、件數、失敗處」。PAO 會將這些資訊壓縮為單位數字元的 JSON 物件。

* **測試輸出**：最多可減少 99.8% token
* **PHPStan 輸出**：以結構化 JSON 僅提供必要資訊
* **Artisan 輸出**：移除 ANSI 代碼、框線、空白，最多減少 75%

## 安裝

要求 PHP 8.3 以上、PHPUnit 12-13 / Pest 4-5 / Paratest / PHPStan / Laravel 12 以上。

```bash theme={null}
composer require laravel/pao --dev
```

只要安裝就會運作。PAO 透過 Composer autoloader 自動 hook 至 PHPUnit、Pest、Paratest、PHPStan。在 Laravel 專案中 Service Provider 會被自動偵測，Artisan 輸出的最佳化也一併啟用。

<Info>
  PAO 僅在偵測到 AI Agent 環境時才啟用。若人類在終端直接執行則完全停用，保持原本輸出。
</Info>

## 支援的 AI Agent

PAO 自動偵測以下 AI Agent。

| Agent          | 偵測方式                         |
| -------------- | ---------------------------- |
| GitHub Copilot | `COPILOT_MODEL` 等環境變數        |
| Claude Code    | `CLAUDECODE` 或 `CLAUDE_CODE` |
| Cursor         | `CURSOR_AGENT`               |
| Gemini CLI     | `GEMINI_CLI`                 |
| Devin          | `/opt/.devin` 檔案             |
| Codex          | `CODEX_SANDBOX` 等環境變數        |

## Before / After

### 測試輸出（PHPUnit / Pest）

1,000 個測試套組會被轉換如下。

**Before（未使用 PAO）**

```
PHPUnit 12.5.14 by Sebastian Bergmann and contributors.

.............................................................   61 / 1002 (  6%)
.............................................................  122 / 1002 ( 12%)
...
..........................                                    1002 / 1002 (100%)

Time: 00:00.321, Memory: 46.50 MB

OK (1002 tests, 1002 assertions)
```

**After（使用 PAO）**

```json theme={null}
{
  "tool": "phpunit",
  "result": "passed",
  "tests": 1002,
  "passed": 1002,
  "duration_ms": 321
}
```

不論測試多少，輸出大小恆定。若測試失敗會包含檔案路徑、行號與失敗訊息。

### Coverage 等 plugin 輸出

`--coverage` 或 `--profile` 等 Pest plugin 的追加輸出，會在移除 ANSI 代碼與裝飾後放入 `raw` 陣列。

```json theme={null}
{
  "tool": "pest",
  "result": "passed",
  "tests": 1002,
  "passed": 1002,
  "duration_ms": 1520,
  "raw": [
    "Http/Controllers/Controller 100.0%",
    "Models/User 0.0%",
    "Total: 33.3 %"
  ]
}
```

### PHPStan 輸出

```json theme={null}
{
  "tool": "phpstan",
  "result": "failed",
  "errors": 2,
  "error_details": {
    "/app/Http/Controllers/Controller.php": [
      {
        "line": 9,
        "message": "Method Controller::index() should return int but returns string.",
        "identifier": "return.type"
      },
      {
        "line": 14,
        "message": "Call to an undefined method Controller::doesNotExist().",
        "identifier": "method.notFound"
      }
    ]
  }
}
```

### Laravel Artisan 輸出

`php artisan about` 等指令的輸出會移除 ANSI 代碼、框線、點狀分隔與空白。

**Before（未使用 PAO）— 2,111 字元**

```
  Environment ................................................................
  Application Name ................................................... Laravel
  Laravel Version ..................................................... 13.3.0
  PHP Version .......................................................... 8.5.4
  Debug Mode ......................................................... ENABLED
```

**After（使用 PAO）— 535 字元**

```
 Environment ..
 Application Name .. Laravel
 Laravel Version .. 13.3.0
 PHP Version .. 8.5.4
 Debug Mode .. ENABLED
```

`about`、`db:show`、`migrate:status` 等指令可望減少 75% token。

## 整合到 Laravel 啟動套件

PAO 預計成為 Laravel 啟動套件的預設相依。新建專案時會自動安裝，用 AI Agent 開發時就能以較低 token 成本立刻開始。

## 總結

`laravel/pao` 只要安裝就能運作，且僅於 AI Agent 環境啟用，不會影響既有開發流程。想降低 AI Agent 開發成本的所有 PHP、Laravel 專案，都值得考量導入。

<Card title="laravel/pao 儲存庫" icon="github" href="https://github.com/laravel/pao">
  原始碼與最新的支援工具與 Agent 清單請見此處。
</Card>


## Related topics

- [部落格](/zh-TW/blog/index.md)
- [Laravel Doctor — 應用診斷工具](/zh-TW/blog/laravel-doctor-introduction.md)
- [AI Agent 從「正確」的程式碼邁向「有 Laravel 風格」的程式碼 - Boost Benchmarks 的下一步](/zh-TW/blog/boost-benchmarks-idiomatic-laravel.md)
- [laravel/agent-skills — Laravel 官方 AI Agent 技能集](/zh-TW/blog/agent-skills-introduction.md)
- [自訂 Agent](/zh-TW/packages/laravel-copilot-sdk/custom-agents.md)