SDK 通过 JSON-RPC 与 CLI 通信，只能访问 CLI 显式暴露的功能。Session 管理、消息收发、工具注册、模型切换、MCP 服务器、Hooks 和事件流都可用；CLI 的交互式功能（slash 命令、终端 UI、会话导出、插件管理）不可用。SDK 支持 CLI 协议 v2 和 v3，自动适配。

GitHub Copilot SDK 与 CLI 功能兼容性：哪些功能可以在 SDK 中使用

SDK 可用功能

功能类别	支持内容
Session 管理	创建、恢复、断开、销毁、列出、获取 Session
消息收发	发送消息（含附件/目录）、获取历史、中止请求
工具	注册自定义工具、权限 Hook、结果 Hook、工具过滤
模型	列出/设置/切换模型、推理力度（reasoning effort）
Agent 模式	获取/设置当前模式
Plan 管理	读取/更新/删除 plan 文件
工作区文件	列出/读取/写入工作区文件
认证	获取状态、使用 token
MCP 服务器	本地/远程服务器配置
Hooks	生命周期、用户 Prompt、错误、权限、输入处理
事件	监听 40+ 种会话事件（含流式输出）
Session 配置	自定义 Agent、系统消息、Provider、Session 设置

示例：订阅 Token 用量事件

session.on('assistant.usage', (event) => {
  console.log('Token 用量:', {
    输入: event.data.inputTokens,
    输出: event.data.outputTokens
  })
})

SDK 不可用的 CLI 功能

以下功能只在 CLI 交互模式中可用，SDK 无法访问：

• 会话导出：/share 命令
• 交互式 slash 命令：/help、/agent、/diff、/research、/chronicle
• 终端专属功能：颜色、屏幕阅读器、鼠标支持
• 账户管理：/login、/logout
• 插件/技能管理：/skills
• 非交互式单次模式：-p、--prompt 参数
• 实验性标志和调试工具

替代方案

替代 Session 导出

// 手动收集事件构建自己的导出格式
const events: SessionEvent[] = []
session.on((event) => events.push(event))

// 或者直接获取消息列表
const messages = await session.getMessages()

替代 CLI 权限标志

// 用 onPermissionRequest Hook 替代 CLI 的 --allow-all 标志
const session = await client.createSession({
  onPermissionRequest: async (request) => ({ kind: 'approved' })
})

注意：自动批准所有权限请求会有安全风险，生产环境建议只批准特定工具。

追踪 Token 用量

// 订阅 assistant.usage 事件
session.on('assistant.usage', (event) => {
  metrics.record({
    inputTokens: event.data.inputTokens,
    outputTokens: event.data.outputTokens
  })
})

上下文压缩（Context Compaction）

// 方法一：配置 infiniteSessions 自动压缩
const session = await client.createSession({ infiniteSessions: true })

// 方法二：手动触发
const result = await session.rpc.compaction.compact()

Plan 管理

// 读取 plan
const plan = await session.rpc.plan.read()
if (plan.exists) console.log(plan.content)

// 更新 plan
await session.rpc.plan.update({
  content: '# 我的计划\n- 步骤 1\n- 步骤 2'
})

Steering（引导 AI 方向）

// 用 send + immediate 模式实时引导
await session.send({ 
  prompt: '先专注处理错误处理部分',
  mode: 'immediate'
})

版本兼容性

SDK 版本	CLI 协议	兼容性
v2-v3	v3	完整支持
v2-v3	v2	自动适配

SDK 在启动时协商协议版本，自动适配 v2 和 v3 的差异，无需手动处理。

检查当前协议版本：

const status = await client.getStatus()
console.log('协议版本:', status.protocolVersion)

常见问题

Q: 有没有方法在 SDK 中实现类似 /diff 的功能？

A: 可以通过工具注册来实现。注册一个 show_diff 工具，让 AI 调用时实际执行 git diff，再把结果返回给 AI 分析。核心思路是：CLI 的 slash 命令底层也是工具调用，在 SDK 中可以等价替换。

Q: SDK 和 CLI 版本不匹配会怎样？

A: SDK v2-v3 支持 CLI 协议 v2 和 v3，会自动适配 tool.call 和 permission.request 消息格式的差异，无需修改代码。如果 CLI 版本太旧，某些新功能可能不可用，但基础功能仍然正常。

Q: 如何知道某个功能是 SDK 支持的？

A: 查看 @github/copilot-sdk 的 TypeScript 类型定义是最可靠的方式，所有暴露的方法和事件都有完整的类型签名。