> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Sessions

> 說明 Cloud Sessions 的用法：不使用本機的 Copilot CLI，而是在 GitHub 託管環境中執行 session。

## Cloud Sessions

Cloud Sessions 是不透過本機的 Copilot CLI 程序，而是於 GitHub 端的託管環境執行 session 的功能。任務會在 Mission Control 中預約，由雲端的 `copilot-agent` 連線並執行處理。

一般的 Remote Sessions 是「讓在本機執行的 session 能被 GitHub Web/行動裝置看見」的功能。若希望執行位置本身位於 GitHub 託管環境，則使用 Cloud Sessions。

## 前置條件

* 使用者具備可使用 Cloud Agent 的 Copilot 權限
* 可透過 GitHub token 或已登入的 Copilot CLI 使用者進行認證
* 若可能，請關聯 GitHub 儲存庫資訊
* 組織政策允許雲端執行與遠端瀏覽

## 基本用法

於 `SessionConfig` 的 `cloud` 中指定 `CloudSessionOptions`。儲存庫資訊在 SDK 型別上為選填，但為向 Mission Control 與雲端 agent 傳遞脈絡，建議指定。

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\CloudSessionOptions;
use Revolution\Copilot\Types\CloudSessionRepository;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session): void {
    $session->sendAndWait(prompt: '請摘要 README');
}, config: new SessionConfig(
    onPermissionRequest: PermissionHandler::approveSafety(),
    cloud: new CloudSessionOptions(
        repository: new CloudSessionRepository(
            owner: 'myorg',
            name: 'myrepo',
            branch: 'main',
        ),
    ),
));
```

也可以以陣列指定。

```php theme={null}
Copilot::run(
    prompt: '請確認這個儲存庫的測試方針',
    config: [
        'cloud' => [
            'repository' => [
                'owner' => 'myorg',
                'name' => 'myrepo',
                'branch' => 'main',
            ],
        ],
    ],
);
```

## 送出第一個 prompt 的時機

Cloud Session 是分兩階段初始化。`session.create` 會在 Mission Control 預約任務時就回傳，但雲端的 `copilot-agent` 連線並發出 `session.start` 之前還會有一段時間。

為確保首個 prompt 能可靠送達，請先訂閱事件，並在 `producer` 確認 `copilot-agent` 的 `session.start` 之後再送出。

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\CloudSessionOptions;
use Revolution\Copilot\Types\CloudSessionRepository;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    streaming: true,
    onPermissionRequest: PermissionHandler::approveSafety(),
    cloud: new CloudSessionOptions(
        repository: new CloudSessionRepository(owner: 'myorg', name: 'myrepo'),
    ),
);

Copilot::start(function (CopilotSession $session): void {
    $cloudAgentStarted = false;

    foreach ($session->stream(timeout: 30.0) as $event) {
        if (
            $event->is(SessionEventType::SESSION_START)
            && $event->data('producer') === 'copilot-agent'
        ) {
            $cloudAgentStarted = true;
            break;
        }
    }

    if (! $cloudAgentStarted) {
        throw new RuntimeException('Cloud session did not become ready.');
    }

    $session->sendAndWait(prompt: '請摘要 README');
}, config: $config);
```

在實際應用中，將於佇列或非同步處理端「確認 `session.start` 後再送出 prompt」的架構會更易於管理。

## 與 Remote Sessions 的差異

| 功能              | 執行位置        | 主要用途                              |
| --------------- | ----------- | --------------------------------- |
| Remote Sessions | 本機或自建伺服器    | 從 Web/行動裝置檢視、操作既有 session         |
| Cloud Sessions  | GitHub 託管環境 | 不需在使用者裝置或自建伺服器啟動 Copilot CLI 即可處理 |

## 注意事項

* Cloud Sessions 會受權限與組織政策影響
* 設定 `streaming: true` 後即可接收 `assistant.message_delta` 等即時事件
* 權限請求的處理方式與一般 session 相同。透過 Laravel 版 Facade 時預設為 deny-all，如有需要請指定 `PermissionHandler::approveSafety()` 等

## 參考

* [Remote Sessions](/zh-TW/packages/laravel-copilot-sdk/remote-sessions)
* [SessionConfig](/zh-TW/packages/laravel-copilot-sdk/session-config)
* [串流事件](/zh-TW/packages/laravel-copilot-sdk/streaming-events)

<Info>
  最新資訊請參考 [GitHub 儲存庫](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [Remote Sessions](/zh-TW/packages/laravel-copilot-sdk/remote-sessions.md)
- [SessionConfig](/zh-TW/packages/laravel-copilot-sdk/session-config.md)
- [Streaming Events](/zh-TW/packages/laravel-copilot-sdk/streaming-events.md)
- [Session](/zh-TW/session.md)
- [GitHub Copilot SDK for Laravel](/zh-TW/packages/laravel-copilot-sdk/index.md)