copilot-sdk

GitHub Copilot SDK

概述

GitHub Copilot SDK 通过 JSON-RPC 暴露相同的 Copilot CLI Agent 运行时，因此应用可以通过编程方式驱动 Copilot，而无需构建自己的编排层。

**状态：**公开预览
**SDK：**Node.js/TypeScript、Python、Go、.NET、Java
**架构：**应用 -> SDK 客户端 -> JSON-RPC -> Copilot CLI

如何使用此技能

在协助使用 Copilot SDK 时：

1. 优先查阅官方文档索引和特定语言的 README，而不是依赖记忆。
2. 将顶层 SDK README 和 docs/ 视为共享行为的权威来源。
3. 当稳定性或重大变更相关时，说明其预览状态。
4. 如果可以通过 listModels() 在运行时发现模型，请避免将模型列表硬编码。
5. 留意有关权限、生命周期方法和事件名称的过时指导。

当前权威来源

核心 SDK 文档

• GitHub Copilot SDK 仓库
• 文档索引
• 入门指南
• 设置指南
• 本地 CLI 设置
• 捆绑 CLI 设置
• 后端服务设置
• 扩缩容与多租户
• 使用 BYOK 的 Azure 托管标识
• 身份验证
• BYOK
• 功能索引
• 图像输入
• 引导与排队
• OpenTelemetry 插桩
• 故障排除
• SDK/CLI 兼容性

特定语言的文档

• Node.js / TypeScript README
• Python README
• Go README
• .NET README
• Java SDK 仓库

Copilot CLI 和 GitHub 文档

• 关于 GitHub Copilot CLI
• 使用 GitHub Copilot CLI
• 自定义 Agent 配置参考
• 通过 MCP 增强 Agent 模式
• 支持的模型

配方与示例

• Copilot SDK 实用手册
• Node.js 示例
• Go 示例
• .NET 示例

---

高价值信息

身份验证和先决条件

• 正常使用 SDK 需要订阅 GitHub Copilot。
• 支持 BYOK，且无需通过 GitHub Copilot 进行身份验证。
• Node.js、Python 和 .NET 会自动捆绑 Copilot CLI。
• Go 可以使用已安装的 CLI，也可以通过 go tool bundler 工作流嵌入或捆绑 CLI。
• Java 目前位于 github/copilot-sdk-java，并要求单独安装 CLI。
• 支持 Azure Managed Identity / Entra 身份验证；文档中介绍的 BYOK 模式是通过 DefaultAzureCredential 传递短期有效的 bearer token。

权限

• SDK 使用默认拒绝的权限模型。
• 实际使用中，创建或恢复会话时应提供明确的权限处理程序，例如：
  • TypeScript：approveAll
  • Python：PermissionHandler.approve_all
  • Go：copilot.PermissionHandler.ApproveAll
  • .NET：PermissionHandler.ApproveAll
  • Java：PermissionHandler.APPROVE_ALL

会话生命周期

• 首选清理方法：disconnect()
• 已弃用的清理方法：destroy()
• 如需可靠地恢复会话，创建会话时请提供自己的 sessionId。
• 恢复会话时必须再次提供 BYOK 提供商配置，因为密钥不会持久化。

传输和部署

• 默认传输方式是 stdio，由 SDK 管理 CLI 进程。
• 可以通过 cliUrl 连接外部无头 CLI 服务。
• 当前外部服务文档使用：

copilot --headless --port 4321

模型

• 除非用户明确需要固定列表，否则不要硬编码模型支持情况。
• 优先使用 client.listModels() 和官方支持的模型页面。
• 支持相关模型的 reasoningEffort。

---

安装

SDK	安装
Node.js / TypeScript	npm install @github/copilot-sdk
Python	pip install github-copilot-sdk
Go	go get github.com/github/copilot-sdk/go
.NET	dotnet add package GitHub.Copilot.SDK
Java	Maven/Gradle 包 com.github:copilot-sdk-java

设置和部署选项

选择适合应用形态的设置方式：

• 本地 CLI - 个人工具和开发的最简单选择。
• 捆绑 CLI - 将 CLI 二进制文件随应用一起发布，用于桌面或可分发工具。
• 后端服务 - 以无头模式运行 CLI，并通过 cliUrl 连接。
• 扩展和多租户 - 在共享 CLI 与每用户一个 CLI、共享存储和会话锁定之间进行选择。
• Azure Managed Identity - 如果实际需求是 Azure 身份验证，请使用带短期有效 bearer token 的 BYOK，而非静态 API 密钥。

快速入门模式

所有语言都遵循相同的基本思路：

1. 创建并启动客户端。
2. 创建带有权限处理程序的会话。
3. 如果需要流式输出或进度信息，请在调用 send() 前注册事件处理程序。
4. 使用 send() 或 sendAndWait() 发送消息。
5. 等待 session.idle 或返回的最终消息。
6. 对会话调用 disconnect()，并停止或释放客户端。

TypeScript 示例

import { CopilotClient, approveAll } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
  model: "gpt-5",
  streaming: true,
  onPermissionRequest: approveAll,
});

session.on("assistant.message_delta", (event) => {
  process.stdout.write(event.data.deltaContent ?? "");
});

await session.sendAndWait({ prompt: "What is 2+2?" });

await session.disconnect();
await client.stop();

---

需要牢记的核心功能

客户端和会话 API

各 SDK 中的常见操作：

• 客户端生命周期：start()、stop()、forceStop()
• 会话生命周期：createSession()、resumeSession()、disconnect()
• 消息：send()、sendAndWait()、abort()、getMessages()
• 发现：listModels()、listSessions()、getStatus() / ping()

事件和流式输出

• 最终助手输出通过 assistant.message 到达。
• 流式文本通过 assistant.message_delta 到达。
• session.idle 是可靠的“轮次完成”信号。
• 事件系统现在包含推理、工具进度、权限、信息征询、子 Agent 和技能事件。

参见 references/event-system.md。

自定义工具

• Node 使用带有 Zod 或原始 JSON Schema 的 defineTool(...)。
• Python 使用搭配 Pydantic 模型的 @define_tool。
• Go 优先使用 DefineTool(...)。
• .NET 使用 AIFunctionFactory.Create(...)。
• 覆盖内置工具始终需要明确选择启用：
  • TypeScript：overridesBuiltInTool: true
  • Python：overrides_built_in_tool=True
  • Go：OverridesBuiltInTool = true
  • .NET：AdditionalProperties["is_override"] = true
• 自定义工具也可以选择启用 skipPermission。

自定义 Agent、MCP、钩子和技能

• customAgents 可让你为每个会话定义子 Agent。
• mcpServers 用于连接本地或远程 MCP 服务。
• 钩子提供控制点，例如 onPreToolUse、onPostToolUse、onUserPromptSubmitted，以及生命周期和错误钩子。
• 使用 skillDirectories 加载技能；使用 disabledSkills 按需禁用技能。

请参阅 references/cli-agents-mcp.md。

附件、命令和交互

• 会话可以发送文件、目录和图像附件。
• 图像输入支持文件和 blob 附件，应通过模型能力检查视觉支持情况。
• 进行中的消息支持使用 mode: "immediate" 进行引导，以及使用 mode: "enqueue" 进行排队。
• SDK 可以注册自定义斜杠 commands。
• 应用可以通过 onUserInputRequest 回答用户问题。
• 连接的客户端支持时，可通过引导处理程序和 session.ui 使用丰富的 UI 提示。

遥测和可观测性

• SDK 支持通过 TelemetryConfig 配置 OpenTelemetry。
• 内置了跟踪上下文传播；Node 使用显式的 onGetTraceContext 回调进行出站传播。

持久化和长时间运行的工作

• 使用稳定的 sessionId 来恢复会话。
• 对于可能需要压缩的长时间运行工作流，请使用 infiniteSessions。
• 除非配置中另有指定，会话状态会存储在 ~/.copilot/session-state/ 下。

SDK 与仅限 CLI 的功能

• SDK 提供了用于会话、模型、计划、模式切换、工作区文件、自定义 Agent、钩子、MCP、技能和遥测的编程接口。
• 许多终端 UX 功能仍仅限 CLI 使用，例如大多数斜杠命令工作流、交互式选择器以及导出／分享命令。
• 将 CLI 工作流转换为应用代码时，请先查看兼容性指南，再假定某个斜杠命令有对应的 SDK 功能。

---

语言约定

概念	TypeScript	Python	Go	.NET	Java
创建会话	createSession()	create_session()	CreateSession()	CreateSessionAsync()	createSession()
恢复会话	resumeSession()	resume_session()	ResumeSession()	ResumeSessionAsync()	resumeSession()
最终内容	event.data.content	event.data.content	*event.Data.Content	evt.Data.Content	event.getData().content()
增量内容	event.data.deltaContent	event.data.delta_content	*event.Data.DeltaContent	evt.Data.DeltaContent	event.getData().deltaContent()
技能字段	skillDirectories	skill_directories	SkillDirectories	SkillDirectories	setSkillDirectories(...)

---

常见问题

• SDK 目前为公开预览版，因此旧示例很快就会过时。
• 硬编码的模型列表会过时；优先使用运行时发现。
• 旧示例中仍会出现 destroy()，但当前方法是 disconnect()。
• 缺少权限处理程序很快就会造成困扰；实际会话中应将其视为必需项。
• assistant.message 和 assistant.message_delta 使用 event.data.*，而不是顶层的 event.content。
• 应在调用 send() 之前附加流式传输／事件订阅。
• 恢复会话时若未提供调用方指定的 sessionId，在实际操作中会很不方便。

---

此技能中的本地参考文件

• references/working-examples.md - 当前的入门示例，包括工具和恢复模式
• references/event-system.md - 事件名称、生命周期和语言访问模式
• references/cli-agents-mcp.md - 自定义 Agent、技能、MCP、无头 CLI 和配置位置
• references/troubleshooting.md - 常见故障、调试日志、身份验证、权限和传输问题