SessionConfig

透過 SessionConfig 類別可進行各種設定。使用方式如 Copilot::run(prompt: '...', config: $config) 或 Copilot::start(function (CopilotSession $session) { ... }, config: $config)。若只是想單純指定模型等,無需使用 SessionConfig 類別時,也可以以陣列形式指定,例如:Copilot::run(prompt: '...', config: ['model' => 'auto'])。官方 SDK 1.0.26 已移除 remoteSession 選項。SessionConfig 與 ResumeSessionConfig 不再接受此選項。

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;
use Revolution\Copilot\Enums\MemoryMode;
use Revolution\Copilot\Enums\WorkingDirectoryTrust;
use Revolution\Copilot\Types\MemoryConfiguration;

$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,

    // Memory 設定(實驗性)
    // mode 預設為 system-prompt。使用 user-prompt 可將 memory 注入產生的使用者訊息中。
    memory: new MemoryConfiguration(
        enabled: true,
        mode: MemoryMode::UserPrompt,
    ),
    // 也可以用陣列指定
    // memory: ['enabled' => true, 'mode' => 'user-prompt'],

    // 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: '',

    // Working directory 的信任範圍。User 會持久化至之後的 Session。
    trustWorkingDirectory: WorkingDirectoryTrust::Session,

    // 啟用 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: [],

    // 停用的 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 仍然適用。

Working directory 信任

建立 Session 時設定 trustWorkingDirectory,即可將 working directory 標記為受信任。

WorkingDirectoryTrust::Session 僅在目前的 Session 中信任該目錄。
WorkingDirectoryTrust::User 會持久化信任狀態,之後的 Session 也會信任該目錄。

省略時,SDK 不會變更信任狀態。 trustWorkingDirectory 僅在建立 Session 時可用,ResumeSessionConfig 不接受此選項。

use Revolution\Copilot\Enums\WorkingDirectoryTrust;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    workingDirectory: base_path(),
    trustWorkingDirectory: WorkingDirectoryTrust::Session,
);

Memory 注入模式

Memory 設定為實驗性功能。

MemoryConfiguration 用來控制跨 Session 的 memory。其中的 mode 選項決定 runtime 將 memory 注入至何處:

MemoryMode::SystemPrompt(system-prompt)會將 memory 注入系統提示。省略 mode 時為預設值。
MemoryMode::UserPrompt(user-prompt)會將 memory 注入產生的使用者訊息。

use Revolution\Copilot\Enums\MemoryMode;
use Revolution\Copilot\Types\MemoryConfiguration;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    memory: new MemoryConfiguration(enabled: true, mode: MemoryMode::UserPrompt),
);

// 也可以用陣列指定
$config = new SessionConfig(memory: ['enabled' => true, 'mode' => 'user-prompt']);

由應用程式管理的記憶儲存區

將閉包傳給 MemoryConfiguration 的 storeMemory，即可在應用程式端接收並儲存執行階段想要儲存的記憶。閉包會接收 StoredMemory（sessionId、subject、fact、citations、reason），以及帶有可用來檢查取消狀態之 signal 的 MemoryStoreCallOptions。

use Revolution\Copilot\Types\MemoryConfiguration;
use Revolution\Copilot\Types\MemoryStoreCallOptions;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\StoredMemory;

$config = new SessionConfig(
    memory: new MemoryConfiguration(
        enabled: true,
        storeMemory: function (StoredMemory $memory, MemoryStoreCallOptions $options) use ($memoryRepository): void {
            if ($options->signal->isCancellationRequested()) {
                return;
            }

            $memoryRepository->store($memory);
        },
    ),
);

// 也可以用陣列指定。storeMemory 需傳入 Closure。
$config = new SessionConfig(memory: ['enabled' => true, 'storeMemory' => $storeMemory]);

使用 storeMemory 時，請將 enabled 設為 true。維持 false 會拋出例外。
storeMemory 本身不會包含在 RPC 酬載中，SDK 在建立或恢復工作階段時只會傳送 hasMemoryStore: true。
雲端工作階段無法使用。
執行階段將不再回想記憶，vote_memory 也將無法使用。請透過 systemMessage 等方式在應用程式端補足已儲存記憶的回想。
回呼的 signal 會在逾時或連線中斷時被取消，之後傳回的結果會被捨棄。

權限模式

權限模式是實驗性功能。

指定 permissionMode 後，會在建立或恢復工作階段時將權限模式傳給執行階段。省略時維持執行階段的預設值。可以使用 PermissionMode enum 或字串指定，ResumeSessionConfig 也可以同樣指定。雲端工作階段不支援。

PermissionMode::Manual（manual）以一般核准流程處理權限請求。
PermissionMode::Assisted（assisted）會為權限請求附加 LLM 的安全性建議。用戶端可以自動核准判定為沒有問題的請求。
PermissionMode::AllowAll（allow-all）會自動核准工具、路徑與 URL 的權限請求。

use Revolution\Copilot\Enums\PermissionMode;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(permissionMode: PermissionMode::Assisted);

若建立或恢復的回應中包含套用結果，可以透過 $session->permissionModeResult() 取得。success 表示是否套用成功，mode 是套用後的權限模式。回應中不包含結果時傳回 null。

自動模式的復原

指定 autoModeRecovery: true 後，會要求執行階段自動復原進行中的請求。預設值為 false。此功能必須提供 onAutoModeSwitchRequest 處理常式，否則會拋出例外。復原時的重試與倒回由執行階段處理，因此應用程式不需要重新傳送提示詞。

use Revolution\Copilot\Enums\UIAutoModeSwitchResponse;
use Revolution\Copilot\Types\AutoModeSwitchRequest;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    autoModeRecovery: true,
    onAutoModeSwitchRequest: function (AutoModeSwitchRequest $request) {
        // 若為復原提議，$request->autoModeRecovery 中包含內容脈絡
        return UIAutoModeSwitchResponse::Yes;
    },
);

autoModeRecovery 需要在建立與恢復時都指定。若執行階段沒有將 capabilities.ui.autoModeRecovery 回應為 true，工作階段會被分離並拋出例外。不使用此功能時，現有 onAutoModeSwitchRequest 針對後續訊息的切換行為維持不變。

排除 Managed Settings

使用 excludedManagedSettings 列出 runtime 應從其取得的 Managed Settings 中移除的設定路徑。這不會影響透過 managedSettings 直接注入的設定。若要在恢復後維持排除,請在 ResumeSessionConfig 中再次傳入 excludedManagedSettings。

$config = new SessionConfig(
    excludedManagedSettings: ['permissions'],
);

在 Session 恢復時使用 ResumeSessionConfig 類別。與 SessionConfig 幾乎相同,但略有差異。ResumeSessionConfig 只需指定想變更的項目。其他項目會沿用新 Session 開始時的設定。 SDK 會在建立與恢復的 RPC payload 中送出相同的 Session 選項。其中包含 BYOK 的 provider 與模型、memory、enableMcpApps、interactiveUser、autopilot、sandboxConfig、excludedManagedSettings、探索根目錄,以及 onMcpAuthRequest、onExitPlanModeRequest、onAutoModeSwitchRequest 等處理器。恢復時,請透過 ResumeSessionConfig 或使用相同 key 的陣列傳入。 Closure 與 provider 物件不會被持久化,因此每次恢復時都需要重新提供。

Autopilot 自動繼續

Autopilot 選項為實驗性功能。

使用 autopilot 設定 Autopilot 模式的自動繼續政策。它不會變更 Session 模式本身。新的 SDK Session 預設啟用自動繼續,maxContinues 為 5。將 maxContinues 設為 0 即可關閉一般的自動繼續。

use Revolution\Copilot\Types\Rpc\AutopilotOptions;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    autopilot: new AutopilotOptions(
        continuationEnabled: true,
        maxContinues: 3,
    ),
);

// 也可以用陣列指定
$config = new SessionConfig(autopilot: [
    'continuationEnabled' => false,
    'maxContinues' => 0,
]);

恢復時,請在 ResumeSessionConfig 或陣列中傳入相同的 autopilot key。 warm resume 時,省略的欄位會保留目前的值。 runtime 重新啟動後(cold resume),請重新傳入這些設定。

Sandbox 設定

Sandbox 設定為實驗性功能。

使用 sandboxConfig 為 Session 設定 CLI sandbox。 SDK 會在建立與恢復請求中都轉送此設定。為了相容既有程式碼,SDK 也接受 sandbox 作為別名。兩者同時設定時,以非 null 的 sandboxConfig 為優先。

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    sandboxConfig: [
        'enabled' => true,
        'userPolicy' => [
            'filesystem' => ['readwritePaths' => [storage_path('app/workspace')]],
            'network' => [
                'allowedHosts' => ['api.example.com'],
                'blockedHosts' => ['untrusted.example.com'],
            ],
        ],
    ],
);

使用 auth 與 credentials,可讓 sandbox 內的程序使用憑證而不暴露其值:

auth 會為 git 與 gh 啟用憑證注入。
credentials.envVars 將環境變數名稱對應到允許接收其遮罩值的 HTTPS 主機(injectHosts)。請勿將憑證值本身寫入設定中。

$config = new SessionConfig(
    sandboxConfig: [
        'enabled' => true,
        'auth' => ['git' => true, 'gh' => true],
        'credentials' => [
            'envVars' => [
                'APP_CREDENTIAL' => ['injectHosts' => ['registry.example.com']],
            ],
        ],
        'userPolicy' => [
            'experimental' => ['seatbelt' => ['keychainAccess' => true]],
        ],
    ],
);

也可以使用 Revolution\Copilot\Types\Rpc 命名空間中的 SandboxConfig、SandboxConfigAuth、SandboxCredentialsConfig、SandboxMaskedEnvVar、SandboxConfigUserPolicyExperimental 與 SandboxConfigUserPolicyExperimentalSeatbelt 等具型別物件。網路的允許與封鎖規則取決於 CLI sandbox 的功能與版本。

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、Skill、memory 以及實驗模式套用安全的預設值。明確設定的 Session 選項會優先於這些預設值。 GitHub cache store 既不是 empty 模式的預設值,也不是 Session 選項。SDK 不再於 Session 建立或恢復請求中送出 enableGitHubCacheStore,若陣列設定中仍保留此 key,也會被忽略。 replace 模式的 systemMessage 會原樣使用;其他模式則會移除 environment_context 區塊。 SDK 也會為 CLI 程序設定 COPILOT_DISABLE_KEYTAR=1。雲端執行請參閱 Cloud Sessions,Plugin Directory 請參閱 Plugin Directories。

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

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

SessionConfig

SessionConfig

探索根目錄

Working directory 信任

Memory 注入模式

由應用程式管理的記憶儲存區

權限模式

自動模式的復原

排除 Managed Settings

Autopilot 自動繼續

Sandbox 設定

Canvas provider

Session 檔案系統 provider

Skill 與檔案系統 callback

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

多租戶應用程式的 empty 模式

​SessionConfig

​探索根目錄

​Working directory 信任

​Memory 注入模式

​由應用程式管理的記憶儲存區

​權限模式

​自動模式的復原

​排除 Managed Settings

​Autopilot 自動繼續

​Sandbox 設定

​Canvas provider

​Session 檔案系統 provider

​Skill 與檔案系統 callback

​使用 sessionFs 委派所有 Session 狀態

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

SessionConfig

探索根目錄

Working directory 信任

Memory 注入模式

由應用程式管理的記憶儲存區

權限模式

自動模式的復原

排除 Managed Settings

Autopilot 自動繼續

Sandbox 設定

Canvas provider

Session 檔案系統 provider

Skill 與檔案系統 callback

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

多租戶應用程式的 empty 模式