注意
Copilot SDK 当前处于 公开预览. 功能和可用性可能会发生更改。
GitHub Copilot SDK与GitHub Copilot 命令行界面 (CLI)通过 JSON-RPC 协议进行通信。 必须通过此协议显式公开功能才能在 SDK 中可用。 许多交互式 CLI 功能都是特定于终端的，不能以编程方式使用。
功能对比
在 SDK 中可用
| 功能 | SDK 方法 | 备注 |
|---|---|---|
| 会话管理 | ||
| 创建会话 | createSession() | 完全配置支持 |
| 恢复会话 | resumeSession() | 使用无限会话工作区 |
| 断开会话连接 | disconnect() | 释放内存中资源 |
| 销毁会话 | destroy() | 请改用 disconnect() |
| 删除会话 | deleteSession() | 从存储中删除 |
| 列出会话 | listSessions() | 所有存储会话 |
| 获取上一次会话 | getLastSessionId() | 用于快速恢复 |
| 获取前台会话 | getForegroundSessionId() | 多会话协调 |
| 设置前台会话 | setForegroundSessionId() | 多会话协调 |
| Messaging | ||
| 发送消息 | send() | 带有附件 |
| 发送和等待 | sendAndWait() | 在完成之前阻止 |
| 转向（即时模式） | send({ mode: "immediate" }) | 注入中间轮次而不中止 |
| 排队（入队模式） | send({ mode: "enqueue" }) | 顺序处理的缓冲区（默认值） |
| 文件附件 | send({ attachments: [{ type: "file", path }] }) | 图像自动编码和调整大小 |
| 目录附件 | send({ attachments: [{ type: "directory", path }] }) | 附加目录上下文 |
| 获取历史记录 | getMessages() | 所有会话事件 |
| 中止 | abort() | 取消正在进行的请求 |
| 工具 | ||
| 注册自定义工具 | registerTools() | 完整的 JSON 架构支持 |
| 工具权限控制 | ||
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 配置 | 连接到服务 | |
| 挂钩 | ||
| 工具使用前 | onPreToolUse | 权限，修改参数 |
| 工具使用后 | onPostToolUse | 修改结果 |
| 用户提示 | onUserPromptSubmitted | 修改提示 |
| 会话启动/结束 | ||
onSessionStart、onSessionEnd | 来源/原因的生命周期 | |
| 错误处理 | onErrorOccurred | 自定义处理 |
| 事件 | ||
| 所有会话事件 | ||
on()、once() | 40 多个事件类型 | |
| 流媒体 | streaming: true | Delta 事件 |
| 会话配置 | ||
| 自定义代理 | ||
customAgents 配置 | 定义专用代理 | |
| 系统消息 | ||
systemMessage 配置 | 追加或替换 | |
| 自定义提供程序 | ||
provider 配置 | BYOK 支持 | |
| 无限会话 | ||
infiniteSessions 配置 | 自动压缩 | |
| 权限管理器 | onPermissionRequest | 批准/拒绝请求 |
| 用户输入处理程序 | onUserInputRequest | 处理ask_user |
| 技能 | ||
skillDirectories 配置 | 自定义技能 | |
| 已禁用技能 | ||
disabledSkills 配置 | 禁用特定技能 | |
| 配置目录 | ||
configDir 配置 | 覆盖默认配置位置 | |
| 客户端名称 | ||
clientName 配置 | 识别 User-Agent 字段中的应用程序 | |
| 工作目录 | ||
workingDirectory 配置 | 设置会话 cwd | |
| 试验 | ||
| 代理管理 | 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等。 | 仅限终端 UI (TUI) | |
| 代理选取器对话框 | /agent | 交互式 UI |
| 差异模式对话框 | /diff | 交互式 UI |
| “反馈”对话框 | /feedback | 交互式 UI |
| 主题选取器 | /theme | 终端 UI |
| 模型选择器 | /model | 交互式 UI （改用 SDK setModel() ） |
| 复制到剪贴板 | /copy | 终端专用 |
| 上下文管理 | /context | 交互式 UI |
| 研究与历史 | ||
| 深入研究 | /research | 使用 Web 搜索的 TUI 工作流 |
| 会话历史记录工具 | /chronicle | 总结、提示、改进、重新编制索引 |
| 终端功能 | ||
| 颜色输出 | --no-color | 终端专用 |
| 屏幕阅读器模式 | --screen-reader | 可及性 |
| 富差异渲染 | --plain-diff | 终端渲染 |
| 启动横幅 | --banner | 视觉元素 |
| 备用屏幕缓冲区 | ||
--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 | ||
/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 标志 |
解决方法
会话导出
此选项 --share 无法通过 SDK 使用。 要解决此问题：
-
手动收集事件： 订阅会话事件并生成自己的导出：
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 使用默认拒绝权限模型。 除非应用提供 onPermissionRequest 处理程序，否则将拒绝所有权限请求（文件写入、shell 命令、URL 提取和其他请求）。
而不是 --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 存储库中提出问题以请求协议支持。
版本兼容性
| 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);