注意
Copilot SDK 目前处于公开预览阶段。功能和可用性可能会更改。
GitHub Copilot SDK 通过 JSON‑RPC 协议与 GitHub Copilot CLI 通信。功能必须通过该协议显式暴露，才能在 SDK 中使用。许多交互式 CLI 功能是终端特定的，无法以编程方式使用。
功能比较
在 SDK 中可用
| 功能 | SDK 方法 | 注意 |
|---|---|---|
| 会话管理 | ||
| 创建会话 | createSession() | 完整配置支持 |
| 恢复会话 | resumeSession() | 支持无限会话工作区 |
| 断开会话 | disconnect() | 释放内存资源 |
| 销毁会话 | destroy() | 请改用 disconnect() |
| 删除会话 | deleteSession() | 从存储中移除 |
| 列出会话 | listSessions() | 所有已存储的会话 |
| 获取最近的会话 | getLastSessionId() | 用于快速恢复 |
| 获取前台会话 | getForegroundSessionId() | 多会话协作 |
| 设置前台会话 | setForegroundSessionId() | 多会话协作 |
| 消息 | ||
| 发送消息 | send() | 带附件 |
| 发送并等待 | sendAndWait() | 阻塞直至完成 |
| 引导（即时模式） | send({ mode: "immediate" }) | 在不中止的情况下在回合中插入 |
| 排队（入队模式） | send({ mode: "enqueue" }) | 用于顺序处理的缓冲区（默认） |
| 文件附件 | send({ attachments: [{ type: "file", path }] }) | 图像自动编码并调整大小 |
| 目录附件 | send({ attachments: [{ type: "directory", path }] }) | 附加目录上下文 |
| 获取历史记录 | getMessages() | 所有会话事件 |
| 中止 | abort() | 取消进行中的请求 |
| 工具 | ||
| 注册自定义工具 | registerTools() | 完整 JSON Schema 支持 |
| 工具权限控制 | onPreToolUse 钩子 | 允许/拒绝/询问 |
| 工具结果修改 | onPostToolUse 钩子 | 转换结果 |
| 可用/排除的工具 | availableTools、excludedTools 配置 | 过滤工具 |
| 模型 | ||
| 列出模型 | listModels() | 包含功能、计费、策略 |
| 设置模型（创建时） | 会话配置中的 model | 每会话 |
| 切换模型（会话中） | session.setModel() | 也可通过 session.rpc.model.switchTo() |
| 获取当前模型 | session.rpc.model.getCurrent() | 查询活跃模型 |
| 推理力度 | reasoningEffort 配置 | 适用于受支持的模型 |
| 代理模式 | ||
| 获取当前模式 | session.rpc.mode.get() | 返回当前模式 |
| 设置模式 | session.rpc.mode.set() | 在模式之间切换 |
| 计划管理 | ||
| 读取计划 | session.rpc.plan.read() | 获取 plan.md 内容和路径 |
| 更新计划 | session.rpc.plan.update() | 写入 plan.md 内容 |
| 删除计划 | session.rpc.plan.delete() | 移除 plan.md |
| 工作区文件 | ||
| 列出工作区文件 | session.rpc.workspace.listFiles() | 会话工作区中的文件 |
| 读取工作区文件 | session.rpc.workspace.readFile() | 读取文件内容 |
| 创建工作区文件 | session.rpc.workspace.createFile() | 在工作区中创建文件 |
| 身份验证 | ||
| 获取认证状态 | getAuthStatus() | 检查登录状态 |
| 使用令牌 | githubToken 选项 | 编程式认证 |
| 连接性 | ||
| Ping（检测） | client.ping() | 带服务器时间戳的健康检查 |
| 获取服务器状态 | client.getStatus() | 协议版本和服务器信息 |
| MCP 服务器 | ||
| 本地/stdio 服务器 | mcpServers 配置 | 生成进程 |
| 远程 HTTP/SSE | mcpServers 配置 | 连接服务 |
| Hook | ||
| 工具使用前 | onPreToolUse | 权限，修改参数 |
| 工具使用后 | onPostToolUse | 修改结果 |
| 用户提示 | onUserPromptSubmitted | 修改提示 |
| 会话开始/结束 | onSessionStart, onSessionEnd | 带来源/原因的生命周期 |
| 错误处理 | onErrorOccurred | 自定义处理 |
| 事件 | ||
| 所有会话事件 | on(), once() | 40+ 事件类型 |
| 流式传输 | streaming: true | 增量事件 |
| 会话配置 | ||
| 自定义代理 | customAgents 配置 | 定义专用代理 |
| 系统消息 | systemMessage 配置 | 追加或替换 |
| 自定义提供者 | provider 配置 | 自带密钥（BYOK）支持 |
| 无限会话 | infiniteSessions 配置 | 自动压缩 |
| 权限处理器 | onPermissionRequest | 批准/拒绝请求 |
| 用户输入处理器 | onUserInputRequest | 处理 ask_user |
| 技能 | skillDirectories 配置 | 自定义技能 |
| 已禁用的技能 | disabledSkills 配置 | 禁用特定技能 |
| 配置目录 | configDir 配置 | 覆盖默认配置位置 |
| 客户端名称 | clientName 配置 | 在 User-Agent 中标识应用 |
| 工作目录 | workingDirectory 配置 | 设置会话工作目录 |
| 实验性 | ||
| 代理管理 | session.rpc.agent.* | 列出、选择、取消选择、获取当前代理 |
| 舰队模式 | session.rpc.fleet.start() | 并行子代理执行 |
| 手动压缩 | session.rpc.compaction.compact() | 按需触发压缩 |
SDK 中不可用（仅限 CLI）
| 功能 | CLI 命令/选项 | 原因 |
|---|---|---|
| 会话导出 | ||
| 导出到文件 | --share, /share | 协议中未包含 |
| 导出到 gist | --share-gist, /share gist | 协议中未包含 |
| 交互式 UI | ||
| 斜杠命令 | /help, /clear, /exit, etc. | 仅限终端 UI（TUI） |
| 代理选择对话框 | /agent | 交互式 UI |
| 差异模式对话框 | /diff | 交互式 UI |
| 反馈对话框 | /feedback | 交互式 UI |
| 主题选择器 | /theme | 终端 UI |
| 模型选择器 | /model | 交互式 UI（请改用 SDK setModel()） |
| 复制到剪贴板 | /copy | 终端特定 |
| 上下文管理 | /context | 交互式 UI |
| 研究与历史 | ||
| 深度研究 | /research | 带网页搜索的 TUI 工作流 |
| 会话历史工具 | /chronicle | 站立会议、技巧、改进、重新索引 |
| 终端特性 | ||
| 彩色输出 | --no-color | 终端特定 |
| 屏幕阅读器模式 | --screen-reader | 可访问性 |
| 丰富差异渲染 | --plain-diff | 终端渲染 |
| 启动横幅 | --banner | 可视元素 |
| 流式模式 | /streamer-mode | TUI 显示模式 |
| 备用屏幕缓冲区 | --alt-screen, --no-alt-screen | 终端渲染 |
| 鼠标支持 | --mouse, --no-mouse | 终端输入 |
| 路径/权限快捷方式 | ||
| 允许所有路径 | --allow-all-paths | 使用权限处理器 |
| 允许所有 URL | --allow-all-urls | 使用权限处理器 |
| 允许所有权限 | --yolo, --allow-all, /allow-all | 使用权限处理器 |
| 细粒度工具权限 | --allow-tool, --deny-tool | 使用 onPreToolUse 钩子 |
| URL 访问控制 | --allow-url, --deny-url | 使用权限处理器 |
| 重置允许的工具 | /reset-allowed-tools | TUI 命令 |
| 目录管理 | ||
| 添加目录 | /add-dir, --add-dir | 在会话中配置 |
| 列出目录 | /list-dirs | TUI 命令 |
| 切换目录 | /cwd | TUI 命令 |
| 插件/MCP 管理 | ||
| 插件命令 | /plugin | 交互式管理 |
| MCP 服务器管理 | /mcp | 交互式 UI |
| 账户管理 | ||
| 登录流程 | /login, copilot auth login | OAuth 设备流程 |
| 登出 | /logout, copilot auth logout | 直接 CLI |
| 用户信息 | /user | TUI 命令 |
| 会话操作 | ||
| 清除会话 | /clear | 仅限 TUI |
| 计划视图 | /plan | 仅限 TUI（请改用 SDK session.rpc.plan.*） |
| 会话管理 | /session, /resume, /rename | TUI 工作流 |
| 舰队模式（交互式） | /fleet | 仅限 TUI（请改用 SDK session.rpc.fleet.start()） |
| 技能管理 | ||
| 管理技能 | /skills | 交互式 UI |
| 任务管理 | ||
| 查看后台任务 | /tasks | TUI 命令 |
| 使用情况和统计 | ||
| 令牌使用量 | /usage | 订阅使用事件 |
| 代码审查 | ||
| 审查更改 | /review | TUI 命令 |
| 委派 | ||
| 委派到 PR | /delegate | TUI 工作流 |
| 终端设置 | ||
| Shell 集成 | /terminal-setup | Shell 特定 |
| 开发 | ||
| 切换实验性 | /experimental, --experimental | 运行时标志 |
| 自定义指令控制 | --no-custom-instructions | CLI 标志 |
| 诊断会话 | /diagnose | TUI 命令 |
| 查看/管理指令 | /instructions | TUI 命令 |
| 收集调试日志 | /collect-debug-logs | 诊断工具 |
| 重新索引工作区 | /reindex | TUI 命令 |
| IDE 集成 | /ide | IDE 特定工作流 |
| 非交互模式 | ||
| 提示模式 | -p, --prompt | 单次执行 |
| 交互式提示 | -i, --interactive | 自动执行后进入交互式 |
| 静默输出 | -s, --silent | 脚本友好 |
| 继续会话 | --continue | 恢复最近的会话 |
| 代理选择 | --agent <agent> | CLI 标志 |
变通方法
会话导出
SDK 不提供 --share 选项。为了解决此问题
-
手动收集事件：订阅会话事件并自行构建导出
TypeScript const events: SessionEvent[] = []; session.on((event) => events.push(event)); // ... after conversation ... const messages = await session.getMessages(); // Format as markdown yourself
const events: SessionEvent[] = []; session.on((event) => events.push(event)); // ... after conversation ... const messages = await session.getMessages(); // Format as markdown yourself -
直接使用 CLI进行一次性导出。
权限控制
SDK 使用默认拒绝的权限模型。所有权限请求（文件写入、Shell 命令、URL 获取等）默认被拒绝，除非你的应用提供 onPermissionRequest 处理器。
请不要使用 --allow-all-paths 或 --yolo，而使用权限处理器
const session = await client.createSession({
onPermissionRequest: approveAll,
});
const session = await client.createSession({
onPermissionRequest: approveAll,
});
令牌使用跟踪
请不要使用 /usage，而订阅使用事件
session.on("assistant.usage", (event) => {
console.log("Tokens used:", {
input: event.data.inputTokens,
output: event.data.outputTokens,
});
});
session.on("assistant.usage", (event) => {
console.log("Tokens used:", {
input: event.data.inputTokens,
output: event.data.outputTokens,
});
});
上下文压缩
请不要使用 /compact，而配置自动压缩或手动触发
// Automatic compaction via config
const session = await client.createSession({
infiniteSessions: {
enabled: true,
backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization
bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization
},
});
// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);
// Automatic compaction via config
const session = await client.createSession({
infiniteSessions: {
enabled: true,
backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization
bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization
},
});
// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);
注意
阈值是上下文利用率比例（0.0-1.0），而非绝对令牌计数。
计划管理
以编程方式读取和写入会话计划
// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
console.log(plan.content);
}
// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });
// Delete the plan
await session.rpc.plan.delete();
// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
console.log(plan.content);
}
// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });
// Delete the plan
await session.rpc.plan.delete();
消息引导
在不中止的情况下向当前 LLM 回合注入消息
// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });
// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });
// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });
// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });
协议限制
SDK 只能访问通过 CLI 的 JSON‑RPC 协议暴露的功能。如果你需要的 CLI 功能未提供
- 检查替代方案：许多功能拥有 SDK 等价实现（见上文 变通方法）。
- 直接使用 CLI：一次性操作时调用 CLI。
- 请求该功能：在 github/copilot-sdk 仓库中提交 issue 以请求协议支持。
版本兼容性
| SDK 协议范围 | CLI 协议版本 | 兼容性 |
|---|---|---|
| v2‑v3 | v3 | 完整支持 |
| v2‑v3 | v2 | 通过自动 v2 适配器支持 |
SDK 在启动时与 CLI 协商协议版本。SDK 支持 2 到 3 版协议。当连接到 v2 CLI 服务器时，SDK 会自动将 tool.call 与 permission.request 消息适配为 v3 事件模型，无需修改代码。
你可以在运行时检查版本
const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);
const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);