# SDK 和 CLI 兼容性 本文档概述了通过 SDK 提供哪些Copilot CLI 功能，以及哪些功能仅限 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()` | 并行子代理执行;请参阅 [机队模式](/zh/copilot/how-tos/copilot-sdk/features/fleet-mode) | | 手动压缩 | `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 标志 | | 查看/管理指令 | `/instructions` | TUI 命令 | | 重新索引工作区 | `/reindex` | TUI 命令 | | IDE 集成 | `/ide` | IDE 专用工作流 | | **非交互式模式** | | | | | | | | 提示模式 | | | | `-p`、`--prompt` | 单次执行 | | | 交互式提示 | | | | `-i`、`--interactive` | 自动执行，然后进行交互 | | | 静默输出 | | | | `-s`、`--silent` | 支持脚本 | | | 继续会话 | `--continue` | 恢复最新 | | 代理选择 | `--agent ` | CLI 标志 | ## 解决方法 ### 机队模式 机群模式可通过 `session.rpc.fleet.start()` 使用，适用于希望由运行时调度并行子代理以实现更大目标的 SDK 应用程序。 当独立子任务可以并发运行，然后由主会话汇总时使用它。 有关完整指南，请参阅 [机队模式](/zh/copilot/how-tos/copilot-sdk/features/fleet-mode)。 ### 会话导出 此选项 `--share` 无法通过 SDK 使用。 解决方法： 1. **手动收集事件** - 订阅会话事件并生成自己的导出： ```typescript const events: SessionEvent[] = []; session.on((event) => events.push(event)); // ... after conversation ... const messages = await session.getEvents(); // Format as markdown yourself ``` 2. **直接使用 CLI 进行导出** - 运行 CLI `--share` 进行一次性导出。 ### 权限控制 SDK 使用 **默认拒绝** 权限模型。 除非应用提供 `onPermissionRequest` 处理程序，否则将拒绝所有权限请求（文件写入、shell 命令、URL 提取等）。 而不是 `--allow-all-paths` 或 `--yolo`，使用权限处理程序： ```typescript 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, }); }); ``` ### 上下文压缩 请配置自动压缩或手动触发，而不是`/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.history.compact(); console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`); ``` > \[!NOTE] > 阈值是上下文利用率（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(); ``` ### 消息引导 在不中断当前 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" }); ``` ## 协议限制 SDK 只能访问通过 CLI 的 JSON-RPC 协议公开的功能。 如果您需要当前不可用的 CLI 功能： 1. **检查替代项** - 许多功能具有 SDK 等效项（请参阅上面的解决方法） 2. **直接使用 CLI** - 对于一次性操作，请调用 CLI 3. **请求功能** - 提出问题以请求协议支持 ## 版本兼容性 | SDK 协议范围 | CLI 协议版本 | Compatibility | | -------- | -------- | ------------- | | 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); ``` ## 另见 * [构建你的第一个由 Copilot 提供支持的应用](/zh/copilot/how-tos/copilot-sdk/getting-started) * [会话挂钩](/zh/copilot/how-tos/copilot-sdk/hooks/hooks-overview) * [Using MCP servers with the GitHub Copilot SDK](/zh/copilot/how-tos/copilot-sdk/features/mcp) * [调试指南](/zh/copilot/how-tos/copilot-sdk/troubleshooting/debugging)