SDK 多租户与会话隔离

共享服务的应用层负责登录、路由与授权；runtime 提供会话级身份和状态。不同 session ID 是必要的标识，不是自动完成访问控制的安全边界。

以 empty 模式开始

多用户或共享场景必须使用 mode: "empty"，不要使用默认 mode: "copilot-cli"。后者会带入 CLI 风格能力，可能通过环境工具访问宿主文件系统。

import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk";

const client = new CopilotClient({
    mode: "empty",
    connection: RuntimeConnection.forUri(process.env.COPILOT_RUNTIME_URL!),
});

empty 模式默认禁用可选 CLI 行为。内置 Skills 默认不具备资格，SDK 在 create/resume 后的选项 patch 中发送空 includedBuiltinSkills 与 installedPlugins；需要内置 Skill 时显式允许。应用自己的 Skill 目录仍可按需启用。

每个会话明确工具与身份

通过 availableTools 提供来源限定的允许列表，例如 custom:lookupOrder、custom:createTicket、custom:* 或 mcp:search_docs。允许名称不会自动实现或注册业务工具；应用仍需提供相应能力与业务授权。

给每个会话传 gitHubToken，或优先为短期凭据使用令牌 provider。它影响用户内容排除、模型路由、配额和 Copilot 访问，区别于 runtime 进程的 client 级身份。

应用生成唯一 session ID，并在数据库保存 owner/tenant 元数据。每次 resume、delete 和涉及 session ID 的 UI 操作都检查归属，不凭 ID 字符串前缀直接信任用户。

runtime 目录与空闲清理

baseDirectory 为 SDK 启动的 runtime 设置 COPILOT_HOME，状态位于其 session-state/{sessionId}。不同进程、pod 或租户边界通常使用独立目录；有意共享存储时另行处理并发。

sessionIdleTimeoutSeconds 控制空闲清理。专题建议聊天服务可从 15–30 分钟开始评估，这是调优建议而非默认值。外部 URI 连接忽略 client baseDirectory，进程级目录和 timeout 应配置在 runtime 服务上。

sessionFs

sessionFs 让会话文件 I/O 通过应用提供的存储接口处理，适合短暂磁盘、对象存储或租户路径控制。client 级配置示例字段为 initialCwd、sessionStatePath 和 conventions: "posix"，还需在创建或恢复时提供对应语言的会话 provider。

官方已列出 TypeScript、Python、Go、.NET、Rust 的公开接口；Java 在该专题中没有已验证的公开 sessionFs 选项，不补写 Java 样例。

集成标识

runtime 环境变量 GITHUB_COPILOT_INTEGRATION_ID 会成为请求头 Copilot-Integration-Id，默认 copilot-developer-cli。目前不是一等 SDK 配置选项；SDK 启动子进程时通过 env 传递，外部 runtime 则在服务器进程设置。

隔离范围

模型列表缓存、会话状态和会话级 GitHub 身份按 session 隔离；若允许宿主文件工具，宿主文件系统仍由 runtime 进程共享。empty 模式与显式工具注册使共享方式可行，但不等于每个 session 都有独立操作系统进程或沙箱。

需要更强的资源边界、负载分配或协作会话时，阅读扩展与存储。