SDK 和 CLI 兼容性

注意

          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 无法通过 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，使用权限处理程序：

TypeScript

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

令牌使用情况跟踪

而不是执行/usage，请订阅使用情况事件。

TypeScript

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。

TypeScript

// 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），而不是绝对令牌计数。

计划管理

以编程方式读取和写入会话计划：

TypeScript

// 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 回合的情况下插入一条消息：

TypeScript

// 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 等效项（请参阅上面的 [解决方法](#workarounds) ）。

        **直接使用 CLI：** 对于一次性操作，请调用 CLI。

        **请求该功能：** 在 [github/copilot-sdk](https://github.com/github/copilot-sdk/issues) 存储库中提出问题以请求协议支持。

版本兼容性

SDK 协议范围	CLI 协议版本	兼容性
v2-v3	v3	完全支持
v2-v3	v2	支持自动 v2 适配器

SDK 在启动时与 CLI 协商协议版本。 SDK 支持协议版本 2 到 3。连接到 v2 CLI 服务器时，SDK 会自动调整 tool.call 和 permission.request 消息到 v3 事件模型，无需更改代码。

可以在运行时检查版本：

TypeScript

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

谁可以使用此功能？

在本文中

功能对比

在 SDK 中可用

SDK 中不可用（仅限 CLI）

解决方法

会话导出

权限控制

令牌使用情况跟踪

上下文压缩

计划管理

消息引导

协议限制

版本兼容性