{"meta":{"title":"SDK 和 CLI 兼容性","intro":"本文档概述了通过 SDK 提供哪些Copilot CLI 功能，以及哪些功能仅限 CLI。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos","title":"操作方法"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting","title":"故障排除"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/compatibility","title":"Compatibility"}],"documentType":"article"},"body":"# SDK 和 CLI 兼容性\n\n本文档概述了通过 SDK 提供哪些Copilot CLI 功能，以及哪些功能仅限 CLI。\n\n\n\n\n\n## 概述\n\nCopilot SDK 通过 JSON-RPC 协议与 CLI 通信。 必须通过此协议显式公开功能才能在 SDK 中可用。 许多交互式 CLI 功能都是特定于终端的，不能以编程方式使用。\n\n## 功能对比\n\n### ✅ 在 SDK 中可用\n\n| 功能 | SDK 方法 | 笔记 |\n| ----------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |\n| **会话管理** | | |\n| | | |\n| 创建会话 | `createSession()` | 完全配置支持 |\n| 恢复会话 | `resumeSession()` | 使用无限会话工作区 |\n| 断开会话连接 | `disconnect()` | 释放内存中资源 |\n| 销毁会话 *（已弃用）* | `destroy()` | 请改用 `disconnect()` |\n| 删除会话 | `deleteSession()` | 从存储中删除 |\n| 列出会话 | `listSessions()` | 所有存储会话 |\n| 获取上一次会话 | `getLastSessionId()` | 用于快速恢复 |\n| 获取前台会话 | `getForegroundSessionId()` | 多会话协调 |\n| 设置前台会话 | `setForegroundSessionId()` | 多会话协调 |\n| **Messaging** | | |\n| | | |\n| 发送消息 | `send()` | 带有附件 |\n| 发送和等待 | `sendAndWait()` | 在完成之前阻止 |\n| 转向（即时模式） | `send({ mode: \"immediate\" })` | 中途注入不中止 |\n| 排队（入队模式） | `send({ mode: \"enqueue\" })` | 顺序处理的缓冲区（默认值） |\n| 文件附件 | `send({ attachments: [{ type: \"file\", path }] })` | 图像自动编码和调整大小 |\n| 目录附件 | `send({ attachments: [{ type: \"directory\", path }] })` | 附加目录上下文 |\n| 获取历史记录 | `getEvents()` | 所有会话事件 |\n| 中止 | `abort()` | 取消正在进行的请求 |\n| **工具** | | |\n| | | |\n| 注册自定义工具 | `registerTools()` | 完整的 JSON 架构支持 |\n| 工具权限控制 | | |\n| `onPreToolUse` 钩子 | 允许/拒绝/询问 | |\n| 工具结果修改 | | |\n| `onPostToolUse` 钩子 | 转换结果 | |\n| 可用/排除的工具 | | |\n| `availableTools`，`excludedTools` 配置 | 筛选工具 | |\n| **模型** | | |\n| | | |\n| 列出模型 | `listModels()` | 功能、计费、策略 |\n| 设置模型（创建时） | | |\n| `model` 会话配置中 | 每个会话 | |\n| 切换模型（会话中途） | `session.setModel()` | 此外，通过 `session.rpc.model.switchTo()` |\n| 获取当前模型 | `session.rpc.model.getCurrent()` | 查询活动模型 |\n| 推理工作 | | |\n| `reasoningEffort` 配置 | 用于支持的模型 | |\n| **代理模式** | | |\n| | | |\n| 获取当前模式 | `session.rpc.mode.get()` | 返回当前模式 |\n| 设置模式 | `session.rpc.mode.set()` | 在模式之间切换 |\n| **计划管理** | | |\n| | | |\n| 读取计划 | `session.rpc.plan.read()` | 获取 plan.md 内容和路径 |\n| 更新计划 | `session.rpc.plan.update()` | 编写 plan.md 内容 |\n| 删除计划 | `session.rpc.plan.delete()` | 删除 plan.md |\n| **工作区文件** | | |\n| | | |\n| 列出工作区文件 | `session.rpc.workspace.listFiles()` | 会话工作区中的文件 |\n| 读取工作区文件 | `session.rpc.workspace.readFile()` | 读取文件内容 |\n| 创建工作区文件 | `session.rpc.workspace.createFile()` | 在工作区中创建文件 |\n| **Authentication** | | |\n| | | |\n| 获取身份验证状态 | `getAuthStatus()` | 检查登录状态 |\n| 使用令牌 | | |\n| `gitHubToken` 选项 | 编程身份验证 | |\n| **连接** | | |\n| | | |\n| Ping | `client.ping()` | 使用服务器时间戳进行健康检查 |\n| 获取服务器状态 | `client.getStatus()` | 协议版本和服务器信息 |\n| **MCP 服务器** | | |\n| | | |\n| 本地/stdio 服务器 | | |\n| `mcpServers` 配置 | 生成进程 | |\n| 远程 HTTP/SSE | | |\n| `mcpServers` 配置 | 连接到服务 | |\n| **钩子** | | |\n| | | |\n| 工具使用前 | `onPreToolUse` | 权限，修改参数 |\n| 工具使用后（成功） | `onPostToolUse` | 修改结果 |\n| 工具使用后（失败） | `onPostToolUseFailure` | 监测失败的工具调用，注入重试指引 |\n| 用户提示 | `onUserPromptSubmitted` | 修改提示 |\n| 会话启动/结束 | | |\n| `onSessionStart`、`onSessionEnd` | 来源/原因的生命周期 | |\n| 错误处理 | `onErrorOccurred` | 自定义处理 |\n| **Events** | | |\n| | | |\n| 所有会话事件 | | |\n| `on()`、`once()` | 40 多个事件类型 | |\n| Streaming | `streaming: true` | Delta 事件 |\n| **会话配置** | | |\n| | | |\n| 自定义代理 | | |\n| `customAgents` 配置 | 定义专用代理 | |\n| 系统消息 | | |\n| `systemMessage` 配置 | 追加或替换 | |\n| 自定义提供程序 | | |\n| `provider` 配置 | BYOK 支持 | |\n| 无限会话 | | |\n| `infiniteSessions` 配置 | 自动压缩 | |\n| 权限管理器 | `onPermissionRequest` | 批准/拒绝请求；可选择附加一个 `decisionContext` 以用于自动批准遥测 |\n| 用户输入处理程序 | `onUserInputRequest` | 处理`ask_user` |\n| 技能 | | |\n| `skillDirectories` 配置 | 自定义技能 | |\n| 已禁用技能 | | |\n| `disabledSkills` 配置 | 禁用特定技能 | |\n| 配置目录 | | |\n| `configDir` 配置 | 覆盖默认配置位置 | |\n| 客户端名称 | | |\n| `clientName` 配置 | 识别 User-Agent 字段中的应用程序 | |\n| 工作目录 | | |\n| `workingDirectory` 配置 | 设置会话 cwd | |\n| 附加目录 | | |\n| `additionalDirectories` 配置 | 授予工作目录之外的会话访问权限；在恢复时重新提供 | |\n| **试验** | | |\n| | | |\n| 代理管理 | `session.rpc.agent.*` | 列出、选择、取消选择、获取当前代理 |\n| 机队模式 | `session.rpc.fleet.start()` | 并行子代理执行;请参阅 [机队模式](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/fleet-mode) |\n| 手动压缩 | `session.rpc.history.compact()` | 按需触发压缩 |\n| 上下文清除 | `session.rpc.history.clearContext()` | 使用终端工具替换对话上下文 |\n| 历史记录截断 | `session.rpc.history.truncate()` | 从某一时间点起删除事件 |\n| 会话分叉 | `server.rpc.sessions.fork()` | 在历史某个时间点分叉会话 |\n\n### ❌ SDK 中不可用（仅限 CLI）\n\n| 功能 | CLI 命令/选项 | 原因 |\n| ----------------------------------- | -------------------------- | -------------------------------------------- |\n| **会话导出** | | |\n| | | |\n| 导出到文件 | | |\n| `--share`、`/share` | 不在协议中 | |\n| 导出到 gist | | |\n| `--share-gist`、`/share gist` | 不在协议中 | |\n| **交互式 UI** | | |\n| | | |\n| / 命令 | | |\n| `/help`、 `/clear`、 `/exit`等。 | 仅限 TUI | |\n| 代理选取器对话框 | `/agent` | 交互式 UI |\n| 差异模式对话框 | `/diff` | 交互式 UI |\n| “反馈”对话框 | `/feedback` | 交互式 UI |\n| 主题选取器 | `/theme` | 终端 UI |\n| 模型选择器 | `/model` | 交互式 UI （改用 SDK `setModel()` ） |\n| 复制到剪贴板 | `/copy` | 终端专用 |\n| 上下文管理 | `/context` | 交互式 UI |\n| **研究与历史** | | |\n| | | |\n| 深入研究 | `/research` | 使用 Web 搜索的 TUI 工作流 |\n| 会话历史记录工具 | `/chronicle` | 总结、提示、改进、重新编制索引 |\n| **终端功能** | | |\n| | | |\n| 颜色输出 | `--no-color` | 终端专用 |\n| 屏幕阅读器模式 | `--screen-reader` | Accessibility |\n| 富差异渲染 | `--plain-diff` | 终端渲染 |\n| 启动横幅 | `--banner` | 视觉元素 |\n| 主播模式 | `/streamer-mode` | TUI 显示模式 |\n| 备用屏幕缓冲区 | | |\n| `--alt-screen`、`--no-alt-screen` | 终端渲染 | |\n| 鼠标支持 | | |\n| `--mouse`、`--no-mouse` | 终端输入 | |\n| **路径/权限快捷方式** | | |\n| | | |\n| 允许所有路径 | `--allow-all-paths` | 使用权限处理程序 |\n| 允许所有 URL | `--allow-all-urls` | 使用权限处理程序 |\n| 允许所有权限 | | |\n| `--yolo`、`--allow-all`、`/allow-all` | 使用权限处理程序 | |\n| 细粒度工具权限 | | |\n| `--allow-tool`、`--deny-tool` | 使用 `onPreToolUse` 挂钩 | |\n| URL 访问控制 | | |\n| `--allow-url`、`--deny-url` | 使用权限处理程序 | |\n| 重置允许的工具 | `/reset-allowed-tools` | TUI 命令 |\n| **目录管理** | | |\n| | | |\n| 添加目录 | | |\n| `/add-dir`、`--add-dir` | 在会话中配置 | |\n| 列出目录 | `/list-dirs` | TUI 命令 |\n| 更改目录 | `/cwd` | TUI 命令 |\n| **插件/MCP 管理** | | |\n| | | |\n| 插件命令 | `/plugin` | 交互式管理 |\n| MCP 服务器管理 | `/mcp` | 交互式 UI |\n| **帐户管理** | | |\n| | | |\n| 登录流 | | |\n| `/login`、`copilot auth login` | OAuth 设备流 | |\n| Logout | | |\n| `/logout`、`copilot auth logout` | 直接 CLI（命令行界面） | |\n| 用户信息 | `/user` | TUI 命令 |\n| **会话操作** | | |\n| | | |\n| 明确对话 | `/clear` | 仅限 TUI |\n| 平面图 | `/plan` | 仅限 TUI （改用 SDK `session.rpc.plan.*` ） |\n| 会话管理 | | |\n| `/session`、`/resume`、`/rename` | TUI 工作流 | |\n| 机队模式（交互式） | `/fleet` | 仅限 TUI （改用 SDK `session.rpc.fleet.start()` ） |\n| **技能管理** | | |\n| | | |\n| 管理技能 | `/skills` | 交互式 UI |\n| **任务管理** | | |\n| | | |\n| 查看后台任务 | `/tasks` | TUI 命令 |\n| **使用情况和统计信息** | | |\n| | | |\n| 令牌使用情况 | `/usage` | 订阅使用情况事件 |\n| **代码评审** | | |\n| | | |\n| 查看更改 | `/review` | TUI 命令 |\n| **委派** | | |\n| | | |\n| 委托给 PR | `/delegate` | TUI 工作流 |\n| **终端设置** | | |\n| | | |\n| Shell 集成 | `/terminal-setup` | 特定于 Shell |\n| **发展** | | |\n| | | |\n| 切换实验功能 | | |\n| `/experimental`、`--experimental` | 运行时标志 | |\n| 自定义指令控件 | `--no-custom-instructions` | CLI 标志 |\n| 诊断会话 | `/diagnose` | TUI 命令 |\n| 查看/管理指令 | `/instructions` | TUI 命令 |\n| 收集调试日志 | `/collect-debug-logs` | 诊断工具 |\n| 重新索引工作区 | `/reindex` | TUI 命令 |\n| IDE 集成 | `/ide` | IDE 专用工作流 |\n| **非交互式模式** | | |\n| | | |\n| 提示模式 | | |\n| `-p`、`--prompt` | 单次执行 | |\n| 交互式提示 | | |\n| `-i`、`--interactive` | 自动执行，然后进行交互 | |\n| 静默输出 | | |\n| `-s`、`--silent` | 支持脚本 | |\n| 继续会话 | `--continue` | 恢复最新 |\n| 代理选择 | `--agent ` | CLI 标志 |\n\n## 解决方法\n\n### 机队模式\n\n机群模式可通过 `session.rpc.fleet.start()` 使用，适用于希望由运行时调度并行子代理以实现更大目标的 SDK 应用程序。 当独立子任务可以并发运行，然后由主会话汇总时使用它。 有关完整指南，请参阅 [机队模式](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/fleet-mode)。\n\n### 会话导出\n\n此选项 `--share` 无法通过 SDK 使用。 解决方法：\n\n1. **手动收集事件** - 订阅会话事件并构建自己的导出：\n\n ```typescript\n const events: SessionEvent[] = [];\n session.on((event) => events.push(event));\n // ... after conversation ...\n const messages = await session.getEvents();\n // Format as markdown yourself\n ```\n\n2. **直接使用 CLI 进行导出** - 运行 CLI `--share` 进行一次性导出。\n\n### 权限控制\n\nSDK 使用 **默认拒绝** 权限模型。 除非应用提供 `onPermissionRequest` 处理程序，否则将拒绝所有权限请求（文件写入、shell 命令、URL 提取等）。\n\n而不是 `--allow-all-paths` 或 `--yolo`，使用权限处理程序：\n\n```typescript\nconst session = await client.createSession({\n onPermissionRequest: approveAll,\n});\n```\n\n### 令牌使用情况跟踪\n\n订阅使用情况事件而不是 `/usage`：\n\n```typescript\nsession.on(\"assistant.usage\", (event) => {\n console.log(\"Tokens used:\", {\n input: event.data.inputTokens,\n output: event.data.outputTokens,\n });\n});\n```\n\n### 上下文压缩\n\n配置自动压缩或手动触发，而不是 `/compact`。\n\n```typescript\n// Automatic compaction via config\nconst session = await client.createSession({\n infiniteSessions: {\n enabled: true,\n backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization\n bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization\n },\n});\n\n// Manual compaction (experimental)\nconst result = await session.rpc.history.compact();\nconsole.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);\n```\n\n> \\[!NOTE]\n> 阈值是上下文利用率（0.0-1.0），而不是绝对令牌计数。\n\n### 计划管理\n\n以编程方式读取和写入会话计划：\n\n```typescript\n// Read the current plan\nconst plan = await session.rpc.plan.read();\nif (plan.exists) {\n console.log(plan.content);\n}\n\n// Update the plan\nawait session.rpc.plan.update({ content: \"# My Plan\\n- Step 1\\n- Step 2\" });\n\n// Delete the plan\nawait session.rpc.plan.delete();\n```\n\n### 消息引导\n\n在不中断当前 LLM 回合的情况下插入一条消息：\n\n```typescript\n// Steer the agent mid-turn\nawait session.send({ prompt: \"Focus on error handling first\", mode: \"immediate\" });\n\n// Default: enqueue for next turn\nawait session.send({ prompt: \"Next, add tests\" });\n```\n\n## 协议限制\n\nSDK 只能访问通过 CLI 的 JSON-RPC 协议公开的功能。 如果您需要当前不可用的 CLI 功能：\n\n1. **检查替代项** - 许多功能具有 SDK 等效项（请参阅上面的解决方法）\n2. **直接使用 CLI** - 对于一次性操作，请调用 CLI\n3. **请求功能** - 提出问题以请求协议支持\n\n## 版本兼容性\n\n| SDK 协议范围 | CLI 协议版本 | Compatibility |\n| -------- | -------- | ------------- |\n| v2–v3 | v3 | 完全支持 |\n| v2–v3 | v2 | 支持自动 v2 适配器 |\n\nSDK 在启动时与 CLI 协商协议版本。 SDK 支持协议版本 2 到 3。 连接到 v2 CLI 服务器时，SDK 会自动调整 `tool.call` 和 `permission.request` 消息到 v3 事件模型，无需更改代码。\n\n在运行时检查版本：\n\n```typescript\nconst status = await client.getStatus();\nconsole.log(\"Protocol version:\", status.protocolVersion);\n```\n\n## 另见\n\n* [构建你的第一个由 Copilot 提供支持的应用](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started)\n* [会话挂钩](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/hooks-overview)\n* [将 MCP 服务器与 GitHub Copilot SDK 配合使用](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/mcp)\n* [调试指南](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/debugging)"}