> ## 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 托管环境中运行会话。

## Cloud Sessions

Cloud Sessions 是一项功能，它不使用本地 Copilot CLI 进程，而是在 GitHub 侧的托管环境中运行会话。任务会在 Mission Control 上被预约，云端的 `copilot-agent` 会连接进来推进处理。

普通的 Remote Sessions 是「让本地运行的会话能从 GitHub Web/移动端看到」的功能。如果你想让执行位置本身也位于 GitHub 托管环境，请使用 Cloud Sessions。

## 前置条件

* 用户拥有可以使用 Cloud Agent 的 Copilot 权限
* 可以通过 GitHub token 或已登录的 Copilot CLI 用户进行认证
* 尽可能关联 GitHub 仓库信息
* 组织策略允许云端执行与远程查看

## 基本使用方式

在 `SessionConfig` 的 `cloud` 字段中指定 `CloudSessionOptions`。仓库信息在 SDK 类型上是可选的，但为了向 Mission Control 和云端代理传递上下文，建议指定。

```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/移动端查看和操作已有会话                 |
| Cloud Sessions  | GitHub 托管环境 | 不在用户终端或自建服务器上运行 Copilot CLI，直接进行处理 |

## 注意事项

* Cloud Sessions 会受到权限与组织策略的影响
* 设置为 `streaming: true` 后，可以接收 `assistant.message_delta` 等实时事件
* 权限请求的处理与普通会话相同。通过 Laravel 版 Facade 时默认是 deny-all，因此请根据需要指定 `PermissionHandler::approveSafety()` 等

## 参考

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

<Info>
  最新信息请参考 [GitHub 仓库](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

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