GitHub Copilot SDK 与 CLI 兼容性指南：功能矩阵、协议版本协商与替代实现方案

GitHub Copilot SDK 与 CLI 兼容性指南功能矩阵、协议版本协商与替代实现方案【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdkGitHub Copilot SDK 通过 JSON-RPC 协议与 Copilot CLI 运行时通信因此并非所有终端功能都能以编程方式使用。本文基于仓库中的 SDK 与 CLI 兼容性文档系统梳理「SDK 可用功能」与「CLI 独占功能」的完整对照矩阵深入讲解协议版本协商机制、关键功能的 SDK 替代实现权限控制、上下文压缩、会话导出、计划管理、消息转向等并给出可直接落地的 TypeScript 代码示例。读完本文你将能准确判断任意 Copilot CLI 功能能否在 SDK 中调用、如何在 SDK 侧用等价 API 替代 CLI 专属能力以及如何在运行时检测与诊断协议版本兼容问题。兼容性的根本前提JSON-RPC 协议边界Copilot SDK 与 CLI 之间的一切通信都经由 JSON-RPC 协议完成。SDK 客户端通过connect握手建立连接随后通过session.create、session.send、session.plan.read、session.fleet.start等方法名调用服务端能力这些方法可在 nodejs/src/generated/rpc.ts 中检索到对应实现。这一架构决定了兼容性边界只有显式暴露在协议中的功能才可被 SDK 调用。协议中不存在的方法SDK 自然无法触达大量交互式 CLI 功能是终端专属TUI的它们依赖终端渲染、键盘输入与交互对话框无法以编程方式复现因此一个功能「CLI 有、SDK 没有」并不代表缺失而是设计使然——SDK 通常提供了等价的编程式 API见下文 Workarounds 章节。SDK 可用功能全景对照表以下表格完整列出 SDK 中可直接调用的能力、对应的 SDK 方法/配置项及要点说明。这些方法均对应协议层真实存在的 RPC 方法。会话管理Session Management功能SDK 方法说明创建会话createSession()支持完整的会话配置恢复会话resumeSession()配合无限会话工作区使用断开会话disconnect()释放内存中的资源销毁会话已废弃destroy()请改用disconnect()删除会话deleteSession()从存储中移除会话列出会话listSessions()列出全部已存储会话获取最近会话getLastSessionId()用于快速恢复获取前台会话getForegroundSessionId()多会话协同设置前台会话setForegroundSessionId()多会话协同消息Messaging功能SDK 方法说明发送消息send()支持携带附件发送并等待sendAndWait()阻塞直到本轮完成转向immediate 模式send({ mode: immediate })不中断当前轮次即可注入消息排队enqueue 模式send({ mode: enqueue })缓冲至下一轮按顺序处理默认行为文件附件send({ attachments: [{ type: file, path }] })图片会自动编码并缩放目录附件send({ attachments: [{ type: directory, path }] })附加目录上下文获取历史getEvents()返回全部会话事件中止abort()取消进行中的请求工具Tools功能SDK 方法说明注册自定义工具registerTools()完整支持 JSON Schema 描述工具权限控制onPreToolUseHook允许 / 拒绝 / 询问工具结果修改onPostToolUseHook转换工具结果可用/排除工具availableTools、excludedTools配置过滤工具集合模型Models功能SDK 方法说明列出模型listModels()携带能力、计费、策略等元数据创建时指定模型会话配置中的model按会话生效会话中切换模型session.setModel()也可通过session.rpc.model.switchTo()实现获取当前模型session.rpc.model.getCurrent()查询激活模型推理强度reasoningEffort配置仅支持该选项的模型生效listModels()的实现细节值得注意在 nodejs/src/client.ts 中可以看到SDK 会缓存首次查询结果以避免触发限流并对capabilities缺失的模型如 embedding 模型自动补全supports与limits字段。Agent 模式Agent Mode功能SDK 方法说明获取当前模式session.rpc.mode.get()返回当前模式设置模式session.rpc.mode.set()在模式之间切换计划管理Plan Management功能SDK 方法说明读取计划session.rpc.plan.read()获取 plan.md 内容与路径更新计划session.rpc.plan.update()写入 plan.md 内容删除计划session.rpc.plan.delete()移除 plan.md工作区文件Workspace Files功能SDK 方法说明列出工作区文件session.rpc.workspace.listFiles()会话工作区内的文件读取工作区文件session.rpc.workspace.readFile()读取文件内容创建工作区文件session.rpc.workspace.createFile()在工作区中创建文件认证Authentication功能SDK 方法说明获取认证状态getAuthStatus()检查登录状态使用 TokengitHubToken选项编程式认证连通性Connectivity功能SDK 方法说明Pingclient.ping()健康检查返回服务器时间戳获取服务器状态client.getStatus()协议版本与服务器信息MCP 服务器功能SDK 方法说明本地 / stdio 服务器mcpServers配置由运行时派生进程远程 HTTP / SSEmcpServers配置连接远程服务Hooks功能SDK 方法说明工具调用前onPreToolUse权限控制、修改参数工具调用后成功onPostToolUse修改结果工具调用后失败onPostToolUseFailure观察失败的调用、注入重试指引用户提示词onUserPromptSubmitted修改提示词会话开始/结束onSessionStart、onSessionEnd携带来源/原因的生命周期事件错误处理onErrorOccurred自定义错误处理事件Events功能SDK 方法说明全部会话事件on()、once()40 种事件类型流式输出streaming: trueDelta 增量事件会话配置Session Config功能SDK 配置项说明自定义 AgentcustomAgents定义专用 Agent系统消息systemMessage追加或替换自定义 ProviderproviderBYOK 支持无限会话infiniteSessions自动上下文压缩权限处理器onPermissionRequest批准/拒绝请求可附加decisionContext以获得自动批准遥测用户输入处理器onUserInputRequest处理 ask_user技能目录skillDirectories自定义技能禁用技能disabledSkills禁用指定技能配置目录configDir覆盖默认配置位置客户端名称clientName在 User-Agent 中标识应用工作目录workingDirectory设置会话 cwd附加目录additionalDirectories授予工作目录之外的访问权限恢复会话时需要重新提供实验性能力Experimental功能SDK 方法说明Agent 管理session.rpc.agent.*列出、选择、取消选择、获取当前 AgentFleet 模式session.rpc.fleet.start()并行子 Agent 执行详见 Fleet 模式指南手动压缩session.rpc.history.compact()按需触发上下文压缩上下文清除session.rpc.history.clearContext()从终端工具替换对话上下文历史截断session.rpc.history.truncate()从某一点起移除事件会话分叉server.rpc.sessions.fork()在历史中的某一点分叉会话这些实验性方法在源码中有真实对应例如session.plan.read、session.fleet.start、session.history.compact等请求均可检索到 nodejs/src/generated/rpc.ts 中的发送实现。CLI 独占功能SDK 不可用一览以下功能仅存在于 CLI / TUI 中SDK 无法直接调用。表格同时给出了「不可用原因」与推荐替代方向其中标注的替代方案在下一章节有完整代码示例。会话导出Session Export功能CLI 命令/选项不可用原因导出到文件--share、/share协议中不存在导出到 gist--share-gist、/share gist协议中不存在交互式 UIInteractive UI功能CLI 命令/选项不可用原因斜杠命令/help、/clear、/exit等仅 TUIAgent 选择对话框/agent交互式 UIDiff 模式对话框/diff交互式 UI反馈对话框/feedback交互式 UI主题选择/theme终端 UI模型选择/model交互式 UI请改用 SDKsetModel()复制到剪贴板/copy终端专属上下文管理/context交互式 UI研究与历史Research History功能CLI 命令/选项不可用原因深度研究/research带网页搜索的 TUI 工作流会话历史工具/chronicle站会、技巧、改进、重建索引终端特性Terminal Features功能CLI 命令/选项不可用原因彩色输出--no-color终端专属屏幕阅读器模式--screen-reader无障碍特性富 Diff 渲染--plain-diff终端渲染启动横幅--banner视觉元素直播模式/streamer-modeTUI 显示模式备用屏幕缓冲区--alt-screen、--no-alt-screen终端渲染鼠标支持--mouse、--no-mouse终端输入路径/权限快捷方式Path/Permission Shortcuts功能CLI 命令/选项替代方向允许全部路径--allow-all-paths使用权限处理器允许全部 URL--allow-all-urls使用权限处理器允许全部权限--yolo、--allow-all、/allow-all使用权限处理器细粒度工具权限--allow-tool、--deny-tool使用onPreToolUseHookURL 访问控制--allow-url、--deny-url使用权限处理器重置已允许工具/reset-allowed-toolsTUI 命令目录管理Directory Management功能CLI 命令/选项不可用原因添加目录/add-dir、--add-dir请在会话配置中设置列出目录/list-dirsTUI 命令切换目录/cwdTUI 命令插件 / MCP 管理Plugin/MCP Management功能CLI 命令/选项不可用原因插件命令/plugin交互式管理MCP 服务器管理/mcp交互式 UI账户管理Account Management功能CLI 命令/选项不可用原因登录流程/login、copilot auth loginOAuth 设备流登出/logout、copilot auth logout直接 CLI用户信息/userTUI 命令会话操作Session Operations功能CLI 命令/选项替代方向清空对话/clear仅 TUI计划视图/plan仅 TUI请改用 SDKsession.rpc.plan.*会话管理/session、/resume、/renameTUI 工作流Fleet 模式交互式/fleet仅 TUI请改用 SDKsession.rpc.fleet.start()技能管理Skills Management功能CLI 命令/选项不可用原因管理技能/skills交互式 UI任务与统计Task Usage功能CLI 命令/选项替代方向查看后台任务/tasksTUI 命令Token 用量/usage订阅用量事件见下文代码审查与委派Code Review Delegation功能CLI 命令/选项不可用原因审查改动/reviewTUI 命令委派给 PR/delegateTUI 工作流终端设置Terminal Setup功能CLI 命令/选项不可用原因Shell 集成/terminal-setup与 Shell 相关开发与诊断Development Diagnostics功能CLI 命令/选项不可用原因切换实验特性/experimental、--experimental运行时标志自定义指令控制--no-custom-instructionsCLI 标志诊断会话/diagnoseTUI 命令查看/管理指令/instructionsTUI 命令收集调试日志/collect-debug-logs诊断工具重建工作区索引/reindexTUI 命令IDE 集成/ideIDE 专属工作流非交互模式Non-interactive Mode功能CLI 命令/选项不可用原因提示词模式-p、--prompt单次执行交互式提示-i、--interactive自动执行后进入交互静默输出-s、--silent面向脚本继续会话--continue恢复最近的会话Agent 选择--agent agentCLI 标志实战替代方案Workarounds对于上述 CLI 独占功能SDK 提供了编程式等价实现。以下代码均可直接复制运行TypeScript对应 nodejs 目录的 SDK。Fleet 模式并行子 Agent 调度Fleet 模式可通过session.rpc.fleet.start()使用适合将更大的目标拆分为相互独立的子任务并发执行再由主会话汇总结果。当多个子任务可并行且可由主会话总结时优先选用它。完整指南参见 Fleet 模式。会话导出手动收集事件--share在 SDK 中不可用可采用两种替代方式手动收集事件并自行导出——订阅会话事件累积数据最后格式化为 Markdownconst events: SessionEvent[] []; session.on((event) events.push(event)); // ... 对话进行中 ... const messages await session.getEvents(); // 自行格式化为 markdown直接使用 CLI 导出——对一次性导出需求直接以--share运行 CLI。权限控制默认拒绝模型SDK 采用默认拒绝deny-by-default的权限模型。所有权限请求文件写入、Shell 命令、URL 抓取等在你的应用未提供onPermissionRequest处理器时一律被拒绝。不要使用--allow-all-paths或--yolo请改用权限处理器const session await client.createSession({ onPermissionRequest: approveAll, });对于更细粒度的控制可配合onPreToolUseHook 实现按工具维度的 allow/deny/ask 决策onPermissionRequest还可附带decisionContext以便在自动批准场景下上报决策遥测。Token 用量追踪订阅用量事件替代/usage订阅assistant.usage事件session.on(assistant.usage, (event) { console.log(Tokens used:, { input: event.data.inputTokens, output: event.data.outputTokens, }); });assistant.usage是 SDK 的标准会话事件类型见 nodejs/src/generated/session-events.ts除 token 数外还包含成本、配额与计费信息。上下文压缩自动或手动触发替代/compact可配置自动压缩或手动触发// 通过配置自动压缩 const session await client.createSession({ infiniteSessions: { enabled: true, backgroundCompactionThreshold: 0.80, // 上下文利用率达 80% 时启动后台压缩 bufferExhaustionThreshold: 0.95, // 上下文利用率达 95% 时阻塞并压缩 }, }); // 手动压缩实验性 const result await session.rpc.history.compact(); console.log(Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages);[!NOTE] 阈值是上下文利用率比例0.0–1.0不是绝对的 token 数量。infiniteSessions配置项在 nodejs/src/types.ts 中有完整类型定义enabled、backgroundCompactionThreshold、bufferExhaustionThreshold均在此处声明。计划管理读写 plan.md编程式读取与写入会话计划// 读取当前计划 const plan await session.rpc.plan.read(); if (plan.exists) { console.log(plan.content); } // 更新计划 await session.rpc.plan.update({ content: # My Plan\n- Step 1\n- Step 2 }); // 删除计划 await session.rpc.plan.delete();消息转向不中断当前轮次注入消息// 在当前轮次中转向 await session.send({ prompt: Focus on error handling first, mode: immediate }); // 默认排队至下一轮 await session.send({ prompt: Next, add tests });mode: immediate会在不中止当前生成的情况下把消息注入本轮 LLM 上下文默认的enqueue模式则将消息排入队列按顺序在后续轮次处理。协议限制与处理策略SDK 只能访问通过 CLI 的 JSON-RPC 协议暴露的功能。如果需要的 CLI 功能在 SDK 中不可用按以下顺序处理先查找替代方案——许多功能都有 SDK 等价实现见上文 Workarounds 章节直接使用 CLI——对一次性操作直接调用 CLI 即可请求功能支持——提交 issue 请求将该功能加入协议。版本兼容性与协议协商机制版本兼容矩阵SDK 协议范围CLI 协议版本兼容性v2–v3v3完全支持v2–v3v2支持自动使用 v2 适配器协商机制与源码证据SDK 在启动时与 CLI 协商协议版本。当前仓库中 SDK 支持协议版本 2 到 3各语言实现的最新版本号均为 3见 nodejs/src/sdkProtocolVersion.ts 的SDK_PROTOCOL_VERSION 3与 go/sdk_protocol_version.go 的SDKProtocolVersion 3。当 SDK 连接 v2 的 CLI 服务器时会自动将tool.call与permission.request消息适配为 v3 事件模型无需修改任何业务代码。协议协商的底层逻辑清晰可查在 nodejs/src/client.ts 的verifyProtocolVersion()中SDK 发送connect握手请求并读取服务器返回的protocolVersion若服务器未实现connect老版本则回退到ping获取版本。随后校验服务器版本是否落在MIN_PROTOCOL_VERSION当前为 3与getSdkProtocolVersion()当前为 3之间越界即抛出「SDK protocol version mismatch」错误Go 版本在 go/client.go 中实现了完全相同的逻辑minProtocolVersion 3、GetSDKProtocolVersion()获取上限错误信息同样提示「Please update your SDK or server to ensure compatibility」协商成功后client.ping()与client.getStatus()可随时用于运行时版本检测。运行时检查版本const status await client.getStatus(); console.log(Protocol version:, status.protocolVersion);getStatus()在 nodejs/src/client.ts 中通过status.get请求实现返回包含协议版本与服务器信息的GetStatusResponse。排查兼容性问题的建议路径报错 SDK protocol version mismatch说明连接到的服务器协议版本不在 SDK 支持范围内当前为 3请升级服务器或 SDK 至匹配版本SDK 调用某方法报 MethodNotFound说明该功能未在当前服务器协议中暴露。先查阅本文章的功能对照表确认是否为 CLI 独占功能再选择替代 API 或直接调用 CLI权限请求全部被静默拒绝检查是否注册了onPermissionRequest处理器——SDK 默认拒绝一切权限请求更深入的诊断手段可参考 调试指南 与 MCP 调试指南。延伸阅读入门指南从零开始创建第一个 SDK 应用Hooks 文档深入了解 onPreToolUse、onPostToolUse 等全部生命周期 HookMCP 服务器指南配置本地与远程 MCP 服务器调试指南常见问题与解决方案Fleet 模式并行子 Agent 调度完整指南【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考