SessionConfig

透過 SessionConfig 類別可進行各種設定。使用方式如 Copilot::run(prompt: '...', config: $config) 或 Copilot::start(function (CopilotSession $session) { ... }, config: $config)。若只是想單純指定模型等,無需使用 SessionConfig 類別時,也可以以陣列形式指定,例如:Copilot::run(prompt: '...', config: ['model' => 'auto'])。

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SystemMessageConfig;
use Revolution\Copilot\Types\InfiniteSessionConfig;
use Revolution\Copilot\Types\UserInputRequest;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverride;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideSupports;
use Revolution\Copilot\Types\Rpc\ModelCapabilitiesOverrideLimits;
use Revolution\Copilot\Enums\ReasoningEffort;
use Revolution\Copilot\Enums\UIAutoModeSwitchResponse;
use Revolution\Copilot\Types\AutoModeSwitchRequest;
use Revolution\Copilot\Types\ExitPlanModeRequest;
use Revolution\Copilot\Types\ExitPlanModeResult;
use Revolution\Copilot\Types\McpAuthRequest;
use Revolution\Copilot\Types\McpAuthToken;

$config = new SessionConfig(
    // 指定要使用的模型
    model: 'auto',

    // 建立新 Session 時指定固定的 Session ID
    sessionId: 'session-123',

    // 新本地 Session 的名稱(與 cloud 併用時會被 runtime 拒絕)。
    // 具名 Session 會立即持久化,因此在任何 turn 執行前即可列出並恢復。
    // 不可為空字串,也不可包含前後空白、控制字元或雙引號。
    // 最多 100 個 UTF-16 code unit。
    name: 'issue-triage',

    clientName: 'my-app',

    // 標記為由真人操作的 Session,以啟用使用者訊息分析遙測(SDK 預設: false)。
    // 自動化訊息不列入。對 Cloud Session 及恢復執行中的 Session 時會被忽略。
    interactiveUser: true,

    // 推論等級。僅在支援的模型上可設定。
    reasoningEffort: ReasoningEffort::HIGH,

    // 覆寫模型的 capabilities。會與 runtime 的預設值進行 deep-merge。
    // modelCapabilities: new ModelCapabilitiesOverride(
    //     supports: new ModelCapabilitiesOverrideSupports(vision: true, reasoningEffort: true),
    //     limits: new ModelCapabilitiesOverrideLimits(max_prompt_tokens: 200000),
    // ),
    // 也可以用陣列指定
    // modelCapabilities: ['supports' => ['vision' => true]],

    // 覆寫 config 目錄設定
    configDirectory: '',

    // 啟用 MCP 設定或 Skill 目錄的自動探索
    // 會從 working directory 自動探索 .mcp.json 或 .vscode/mcp.json,
    // 並與明確指定的 mcpServers、skillDirectories 合併(名稱衝突時明確指定優先)
    enableConfigDiscovery: true,

    // 自訂工具
    tools: [...],

    // 系統訊息
    systemMessage: new SystemMessageConfig(
        content: 'You are a helpful assistant for Laravel developers.',
    ),

    // 系統訊息: replace 模式(完全取代系統提示)
    // systemMessage: new SystemMessageConfig(
    //     mode: 'replace',
    //     content: '完整自訂系統提示',
    // ),

    // 系統訊息: customize 模式(逐區塊覆寫)
    // systemMessage: new SystemMessageConfig(
    //     mode: 'customize',
    //     sections: [
    //         'tone' => new SectionOverride(action: SectionOverrideAction::REPLACE, content: 'Always respond in Japanese.'),
    //         'safety' => new SectionOverride(action: SectionOverrideAction::REMOVE),
    //         'custom_instructions' => new SectionOverride(action: SectionOverrideAction::APPEND, content: 'Additional instructions here.'),
    //     ],
    //     content: '與 append 模式相同的追加內容(選填)',
    // ),

    // 自訂 provider
    provider: new ProviderConfig(),

    // 每個 Session 的 GitHub Token(支援多租戶)
    // 除了 client 層級的 github_token 之外,可以在 Session 層級指定 Token
    gitHubToken: $user->github_token,

    // Remote Session 的運作模式
    // 'off' - 僅本地(預設)
    // 'export' - 將 Session 事件匯出至 GitHub(不啟用 Remote Steering)
    // 'on' - 同時啟用匯出與 Remote Steering
    remoteSession: \Revolution\Copilot\Enums\RemoteSessionMode::Export,

    // Cloud Session(在雲端而非本地建立 Session)
    // 可選擇關聯儲存庫資訊
    cloud: new \Revolution\Copilot\Types\CloudSessionOptions(
        repository: new \Revolution\Copilot\Types\CloudSessionRepository(
            owner: 'myorg',
            name: 'myrepo',
            branch: 'main',
        ),
    ),

    onPermissionRequest: function (array $request) {
        // 處理權限請求
    },

    onUserInputRequest: function (UserInputRequest $request) {
        // 處理使用者輸入請求。ask_user
    },

    // Elicitation 請求處理器
    // 設定後可接收來自 Agent 的表單式 UI 對話框請求
    onElicitationRequest: function (ElicitationContext $context) {
        // 處理 Elicitation 請求
        return ['action' => 'accept', 'content' => ['field' => 'value']];
    },

    // 當 MCP 伺服器要求 OAuth 驗證時,由主機端提供 Token
    onMcpAuthRequest: function (McpAuthRequest $request, array $context): ?McpAuthToken {
        $accessToken = $credentialProvider->tokenFor($request->serverName);

        return $accessToken === null
            ? null
            : new McpAuthToken(accessToken: $accessToken, tokenType: 'Bearer');
    },

    // Plan 模式退出請求處理器
    // 設定後可接收 Agent 退出 Plan 模式時的請求
    // 設定時 SDK 會透過 reverse RPC 回應;省略時請求會自動核准。
    onExitPlanModeRequest: function (ExitPlanModeRequest $request) {
        // 檢查 plan 內容並核准/拒絕
        return new ExitPlanModeResult(approved: true, selectedAction: $request->recommendedAction);
    },

    // 自動模式切換請求處理器
    // 可在達到 rate limit 時選擇是否允許切換至 auto 模式。省略時預設為 "no"。
    onAutoModeSwitchRequest: function (AutoModeSwitchRequest $request) {
        // 回傳 "yes"、"yes_always"、"no" 其中之一,或 UIAutoModeSwitchResponse 的 case
        return UIAutoModeSwitchResponse::Yes;
    },

    // Session Hooks
    hooks: [],

    // Working directory
    workingDirectory: '',

    // 啟用 streaming
    streaming: true,

    // 是否將 sub-agent 的 streaming 事件納入主 stream(預設: true)
    includeSubAgentStreamingEvents: true,

    // 可用的內建工具
    availableTools: ['read_file', 'write_file'],

    // 或要排除的工具
    excludedTools: ['shell'],

    // MCP 伺服器設定
    mcpServers: [
        'github' => [
            'type' => 'http',
            'url' => 'https://api.githubcopilot.com/mcp/',
        ],
    ],

    // 自訂 Agent
    customAgents: [
        [
            'name' => 'reviewer',
            'displayName' => 'Code Reviewer',
            'description' => 'Reviews code for best practices',
            'prompt' => 'You are an expert code reviewer.',
        ],
    ],

    // 預設 Agent 設定。未選取自訂 Agent 時使用的內建 Agent 設定。
    // excludedTools: 要從預設 Agent 排除的工具清單。
    // 自訂 sub-agent 仍可繼續使用。
    defaultAgent: ['excludedTools' => ['tool_name']],

    // 指定 Session 開始時要啟用的 Agent。必須與 customAgents 的 name 相符。
    agent: 'reviewer',

    // Skill、Agent、Hook 與指示檔案的明確探索根目錄
    skillDirectories: [],
    agentDirectories: [],
    hookDirectories: [],
    instructionDirectories: [],

    // 請求唯讀的 GitHub cache store
    enableGitHubCacheStore: true,

    // 停用的 Skill
    disabledSkills: [],

    // Infinite Session 設定。預設為啟用。
    infiniteSessions: new InfiniteSessionConfig(
        enabled: true,
        backgroundCompactionThreshold: 0.80, // 當 context 使用率達 80% 時開始壓縮
        bufferExhaustionThreshold: 0.95,     // 在壓縮完成前於 95% 時阻擋
    ),

    // 停用 Infinite Session
    // infiniteSessions: new InfiniteSessionConfig(enabled: false),

    // 在 Session 建立 RPC 之前註冊事件處理器。
    // 用來避免遺漏 session.start 等早期事件。
    // 等同於稍後呼叫 $session->on($handler),但註冊時機更早。
    onEvent: function (SessionEvent $event) {
        // 接收所有 Session 事件
    },
);

$response = Copilot::run('...', config: $config);

探索根目錄

skillDirectories、agentDirectories、hookDirectories 與 instructionDirectories 是用於 Skill、自訂 Agent、檔案 Hook 與自訂指示的僅供探索的根目錄。它們不會授予 Agent 一般的檔案存取權限。若要新增一般的檔案存取位置,請使用 additionalDirectories。無論是否啟用 enableConfigDiscovery,都可以設定探索根目錄。 SDK 會在設定時,以當下有效的 workingDirectory 為基準解析一次相對路徑。即使之後 working directory 變更,這些根目錄也不會跟著移動。省略該 key 或傳入 null 時,預設的探索來源維持不變。傳入 [] 只會清除 SDK 明確設定的根目錄。針對 Skill、Agent、Hook 與指示的個別停用設定與 Managed Settings 仍然適用。在 Session 恢復時使用 ResumeSessionConfig 類別。與 SessionConfig 幾乎相同,但略有差異。ResumeSessionConfig 只需指定想變更的項目。其他項目會沿用新 Session 開始時的設定。 SDK 會在建立與恢復的 RPC payload 中送出相同的 Session 選項。其中包含 BYOK 的 provider 與模型、memory、enableMcpApps、interactiveUser、enableGitHubCacheStore、探索根目錄,以及 onMcpAuthRequest、onExitPlanModeRequest、onAutoModeSwitchRequest 等處理器。恢復時,請透過 ResumeSessionConfig 或使用相同 key 的陣列傳入。 Closure 與 provider 物件不會被持久化,因此每次恢復時都需要重新提供。

Canvas provider

Canvas 支援為實驗性功能。

使用 canvases 宣告 Canvas,並以 canvasHandler 處理開啟與動作請求。當 Agent 開啟 Canvas 或呼叫其動作時,runtime 會透過 reverse RPC 呼叫你的處理器。設定 requestCanvasRenderer: true 以選擇作為 renderer,runtime 便會在此連線上向模型公開 Canvas 的 Agent 工具。此選項預設為關閉,讓無法顯示 Canvas 的 SDK 呼叫端保持乾淨。

use Revolution\Copilot\Support\CanvasError;
use Revolution\Copilot\Support\CanvasHandler;
use Revolution\Copilot\Types\CanvasDeclaration;
use Revolution\Copilot\Types\Rpc\CanvasAction;
use Revolution\Copilot\Types\Rpc\CanvasProviderInvokeActionRequest;
use Revolution\Copilot\Types\Rpc\CanvasProviderOpenRequest;
use Revolution\Copilot\Types\Rpc\CanvasProviderOpenResult;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    canvases: [
        new CanvasDeclaration(
            id: 'editor',
            displayName: 'Editor',
            description: 'Opens and edits project files.',
            actions: [
                new CanvasAction(name: 'format', description: 'Format the open file.'),
            ],
        ),
    ],
    canvasHandler: new class extends CanvasHandler
    {
        public function open(CanvasProviderOpenRequest $request): CanvasProviderOpenResult|array
        {
            return new CanvasProviderOpenResult(
                url: 'https://app.example.test/canvas/'.$request->instanceId,
                title: 'Project editor',
            );
        }

        public function invoke(CanvasProviderInvokeActionRequest $request): mixed
        {
            if ($request->actionName !== 'format') {
                throw CanvasError::noHandler();
            }

            return ['formatted' => true];
        }
    },
    requestCanvasRenderer: true,
);

相關選項:

requestExtensions: true 會選擇啟用 extension 介面。runtime 會將 extension 管理工具接入此連線上的 Session。預設為關閉。
extensionInfo: new ExtensionInfo(source: 'github-app', name: 'my-extension') 會為此連線上的 Canvas provider 設定穩定的 extension ID。runtime 會使用 ${source}:${name},而非每個連線各自的 ID。也可以傳入陣列。

恢復時,請再次傳入 canvases 與 canvasHandler。 canvasHandler 僅在 PHP 程序內執行,SDK 只會在 RPC payload 中送出宣告的 metadata。 ResumeSessionConfig 也接受 openCanvases,即 Session 停止時已開啟之 Canvas 的快照。 runtime 會以此重建 Canvas 狀態,因此不需要重新開啟。可透過 $session->openCanvases() 取得目前開啟的 Canvas。SDK 會依據 session.canvas.opened 與 session.canvas.closed 事件保持此清單同步。

Session 檔案系統 provider

Skill 與檔案系統 callback

使用 skillProvider 從應用程式自有的來源載入 Skill。這些 callback 屬於該 Session,不會被序列化至 Copilot runtime。 Cloud Session 不支援自訂 Skill provider。

use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SkillProviderCallOptions;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    skillProvider: [
        'listSkills' => fn (SkillProviderCallOptions $options) => [
            ['name' => 'deployment', 'description' => 'Safe application deployments'],
        ],
        'readSkill' => fn (string $name, SkillProviderCallOptions $options) =>
            $name === 'deployment' ? '# Deployment checklist' : null,
    ],
);

SkillProviderCallOptions::$signal 提供 callback 的取消 token。取消採協作式,你的 callback 應自行監看 signal 並取消進行中的工作。也可以實作 Revolution\Copilot\Contracts\SkillProvider 來取代 callback 陣列。 sessionFsProvider 使用相同的 Session 範圍設定。文字 callback 為 readFile(path) 與 writeFile(path, content, mode)。若要支援二進位檔案,請同時提供 readFileBytes(path) 與 writeFileBytes(path, bytes, mode),或實作 SessionFsBinaryProvider。這些 callback 接收與回傳的都是原始 byte,JSON-RPC 傳輸上的 base64 編碼由 SDK 處理。請將檔案系統存取限制在應用程式打算公開的路徑內。

use Illuminate\Support\Facades\Storage;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    sessionFsProvider: [
        'readFile' => fn (string $path) => Storage::disk('local')->get($path),
        'writeFile' => fn (string $path, string $content, ?int $mode = null) =>
            Storage::disk('local')->put($path, $content),
        'readFileBytes' => fn (string $path) => Storage::disk('local')->get($path),
        'writeFileBytes' => fn (string $path, string $bytes, ?int $mode = null) =>
            Storage::disk('local')->put($path, $bytes),
    ],
);

使用 `sessionFs` 委派所有 Session 狀態

設定 client 選項 sessionFs(別名 session_fs),即可將 Copilot CLI 的整個 Session 狀態(包含 session-state 檔案與每個 Session 的 SQLite 資料庫)移至你自己的儲存空間。設定後,每個 Session 設定都必須提供 createSessionFsProvider factory。 SDK 會在 createSession() 與 resumeSession() 時,於得知 Session ID 之後、將請求送至 runtime 之前呼叫此 factory。

use Revolution\Copilot\Client;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\SessionConfig;

$client = new Client(['sessionFs' => [
    'initialCwd' => '/workspace',
    'sessionStatePath' => '/session-state',
    'conventions' => 'posix', // 或 windows
    'capabilities' => ['sqlite' => true, 'binary' => true], // 選填
]]);

$session = $client->createSession(new SessionConfig(
    onPermissionRequest: PermissionHandler::approveAll(),
    createSessionFsProvider: fn (CopilotSession $session) => new MySessionFsProvider($session->id()),
));

使用 Copilot facade 時,請在 config/copilot.php 中設定 session_fs。 initialCwd、sessionStatePath 與 conventions(posix 或 windows)為必填。缺少欄位或 conventions 值無效時,會拋出 InvalidArgumentException。 createSessionFsProvider 是 Closure,在 SessionConfig 與 ResumeSessionConfig 的陣列、fromArray() 與 toArray() 中同樣可用。它回傳的 provider 可以是物件或 callable 陣列。每項選用能力各有對應的介面:

介面	新增項目
`SessionFsProvider`	`readFile`、`writeFile`
`SessionFsBinaryProvider`	`readFileBytes`、`writeFileBytes`(`capabilities.binary` 需要)
`SessionFsFilesystemProvider`	`appendFile`、`exists`、`stat`、`mkdir`、`readdir`、`readdirWithTypes`、`rm`、`rename`
`SessionFsSqliteCapableProvider`	回傳 `SessionFsSqliteProvider`(`query`、`exists`)的 `sqlite()`。`capabilities.sqlite` 需要
`SessionFsSqliteTransactionProvider`	SQLite provider 上的 `transaction()`

若 provider 不符合宣告的能力,SDK 會拋出 InvalidArgumentException。呼叫 provider 不支援的操作時,會回傳 UNKNOWN 錯誤。 provider 透過拋出例外來表示失敗。code 為 ENOENT(或 errno 2)的例外會轉為 ENOENT,其他則轉為 UNKNOWN。從 transaction() 拋出 SessionFsSqliteTransactionFailure 即可回報 errorClass(busyOrLocked、fatal 或 postCommitAmbiguous)。未設定 client 的 sessionFs 選項時,SDK 不會呼叫 createSessionFsProvider,既有的 sessionFsProvider(readFile 與 writeFile)仍可照常運作。

多租戶應用程式的 empty 模式

將 client 的 mode 設為 empty,即可預設停用依賴 Copilot CLI 主機環境或跨 Session 狀態的功能。預設值為 copilot-cli,會維持既有行為。在 empty 模式下,必須設定一個持久化目標:base_directory、session_fs 或外部伺服器的 url。

// config/copilot.php
'mode' => env('COPILOT_MODE', 'copilot-cli'),
'base_directory' => storage_path('app/copilot'),

empty 模式下的每個 Session 都必須設定 availableTools。使用 ToolSet 建立帶有來源前綴的工具篩選條件(builtin:、custom:、mcp:)。 BuiltInTools::Isolated 只允許侷限於單一 Session 的內建工具,不可存取主機檔案系統、環境變數、網路或跨 Session 資源。

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\BuiltInTools;
use Revolution\Copilot\Support\ToolSet;

$response = Copilot::run(
    prompt: 'Summarize this text.',
    config: [
        'availableTools' => (new ToolSet)
            ->addBuiltIn(BuiltInTools::Isolated)
            ->addCustom('lookup_order')
            ->addMcp('search'),
    ],
);

工具名稱必須符合 /^[a-zA-Z0-9_-]+$/ 或為萬用字元 *,否則 ToolSet 會拋出 InvalidArgumentException。 empty 模式會對 Session 遙測、持久化的 MCP OAuth Token 儲存、embedding 檢索與快取、指示探索、檔案 Hook、主機 git 操作、session store、GitHub cache store、Skill、memory 以及實驗模式套用安全的預設值。明確設定的 Session 選項會優先於這些預設值。 replace 模式的 systemMessage 會原樣使用;其他模式則會移除 environment_context 區塊。 SDK 也會為 CLI 程序設定 COPILOT_DISABLE_KEYTAR=1。

GitHub cache store

設定 enableGitHubCacheStore: true 以請求唯讀的 GitHub cache store。只有在 CLI 的 GITHUB_CACHE_STORE feature flag 啟用時,才會註冊 github_sql 工具。

$config = new SessionConfig(enableGitHubCacheStore: true);

雲端執行請參閱 Cloud Sessions,Plugin Directory 請參閱 Plugin Directories。

最新資訊請參閱 GitHub 儲存庫。

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

SessionConfig

SessionConfig

探索根目錄

Canvas provider

Session 檔案系統 provider

Skill 與檔案系統 callback

使用 `sessionFs` 委派所有 Session 狀態

多租戶應用程式的 empty 模式

GitHub cache store

​SessionConfig

​探索根目錄

​Canvas provider

​Session 檔案系統 provider

​Skill 與檔案系統 callback

​使用 sessionFs 委派所有 Session 狀態

​多租戶應用程式的 empty 模式

​GitHub cache store

SessionConfig

探索根目錄

Canvas provider

Session 檔案系統 provider

Skill 與檔案系統 callback

使用 `sessionFs` 委派所有 Session 狀態

多租戶應用程式的 empty 模式

GitHub cache store