SDK 和 CLI 兼容性

概述

Copilot SDK 通过 JSON-RPC 协议与 CLI 通信。必须通过此协议显式公开功能才能在 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 }] })`	附加目录上下文
获取历史记录	`getEvents()`	所有会话事件
中止	`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()`	在工作区中创建文件
Authentication
获取身份验证状态	`getAuthStatus()`	检查登录状态
使用令牌
`gitHubToken` 选项	编程身份验证
连接
Ping	`client.ping()`	使用服务器时间戳进行健康检查
获取服务器状态	`client.getStatus()`	协议版本和服务器信息
MCP 服务器
本地/stdio 服务器
`mcpServers` 配置	生成进程
远程 HTTP/SSE
`mcpServers` 配置	连接到服务
钩子
使用前的工具	`onPreToolUse`	权限，修改参数
工具后使用（成功）	`onPostToolUse`	修改结果
工具后使用（失败）	`onPostToolUseFailure`	监测失败的工具调用，注入重试指引
用户提示	`onUserPromptSubmitted`	修改提示
会话启动/结束
`onSessionStart`、`onSessionEnd`	来源/原因的生命周期
错误处理	`onErrorOccurred`	自定义处理
Events
所有会话事件
`on()`、`once()`	40 多个事件类型
Streaming	`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.history.compact()`	按需触发压缩
历史记录截断	`session.rpc.history.truncate()`	从某一时间点起删除事件
会话分叉	`server.rpc.sessions.fork()`	在历史记录中某个点分叉会话

❌ SDK 中不可用（仅限 CLI）

功能	CLI 命令/选项	原因
会话导出
导出到文件
`--share`、`/share`	不在协议中
导出到 GitHub Gist
`--share-gist`、`/share gist`	不在协议中
交互式 UI
/ 命令
`/help`、 `/clear`、 `/exit`等。	仅限 TUI
代理选取器对话框	`/agent`	交互式 UI
差异模式对话框	`/diff`	交互式 UI
“反馈”对话框	`/feedback`	交互式 UI
主题选取器	`/theme`	终端 UI
模型选择器	`/model`	交互式 UI （改用 SDK `setModel()` ）
复制到剪贴板	`/copy`	终端专用
上下文管理	`/context`	交互式 UI
研究与历史
深入研究	`/research`	使用 Web 搜索的 TUI 工作流
会话历史记录工具	`/chronicle`	站立、提示、改进、重新编制索引
终端功能
颜色输出	`--no-color`	终端专用
屏幕阅读器模式	`--screen-reader`	Accessibility
丰富的差异呈现	`--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
`/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 标志

解决方法

机队模式

机群模式可通过 session.rpc.fleet.start() 使用，适用于希望由运行时调度并行子代理以实现更大目标的 SDK 应用程序。当独立子任务可以并发运行，然后由主会话汇总时使用它。有关完整指南，请参阅机队模式。

会话导出

此选项 --share 无法通过 SDK 使用。解决方法：

手动收集事件 - 订阅会话事件并生成自己的导出：

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getEvents();
// Format as markdown yourself

直接使用 CLI 进行导出 - 运行 CLI --share 进行一次性导出。

权限控制

SDK 使用 默认拒绝 权限模型。除非应用提供 onPermissionRequest 处理程序，否则将拒绝所有权限请求（文件写入、shell 命令、URL 提取等）。

而不是 --allow-all-paths 或 --yolo，使用权限处理程序：

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,
  });
});

上下文压缩

请配置自动压缩或手动触发，而不是/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.history.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();

消息引导

在不中断当前 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" });

协议限制

SDK 只能访问通过 CLI 的 JSON-RPC 协议公开的功能。如果您需要当前不可用的 CLI 功能：

检查替代项 - 许多功能具有 SDK 等效项（请参阅上面的解决方法）
直接使用 CLI - 对于一次性操作，请调用 CLI
请求功能 - 提出问题以请求协议支持

版本兼容性

SDK 协议范围	CLI 协议版本	Compatibility
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);

在本文中

概述