SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场copilot-sdk

copilot-sdk

编程与开发

查看项目

更新于 10-15 12:07

技能介绍

用途

GitHub Copilot SDK 将 Copilot CLI 智能体运行时通过 JSON-RPC 暴露出来，使应用能够以编程方式驱动 Copilot，而不必自行搭建编排层。它适合需要在自有应用、工具或服务中集成 Copilot 能力的开发者。

主要能力

  • 多语言 SDK：Node.js/TypeScript、Python、Go、.NET、Java。
  • 客户端与会话 API：客户端生命周期（start、stop、forceStop）、会话生命周期（createSession、resumeSession、disconnect）、消息收发（send、sendAndWait、abort、getMessages）、发现能力（listModels、listSessions、getStatus/ping）。
  • 事件与流式输出：最终输出通过 assistant.message 返回，流式文本通过 assistant.message_delta 返回，session.idle 是可靠的“回合完成”信号；事件系统还包含推理、工具进度、权限、elicitation、子智能体和技能事件。
  • 自定义工具：Node 使用 defineTool 配合 Zod 或原始 JSON Schema，Python 使用 @define_tool 配合 Pydantic 模型，Go 使用 DefineTool，.NET 使用 AIFunctionFactory.Create；覆盖内置工具需显式开启（如 TypeScript 的 overridesBuiltInTool: true），自定义工具还可选择 skipPermission。
  • 自定义智能体、MCP、钩子与技能：customAgents 可按会话定义子智能体，mcpServers 可挂载本地或远程 MCP 服务器，Hooks 提供 onPreToolUse、onPostToolUse、onUserPromptSubmitted 及生命周期/错误钩子，技能通过 skillDirectories 加载并用 disabledSkills 选择性禁用。
  • 附件、命令与交互：会话可发送文件、目录和图像附件；图像输入支持文件和 blob 附件，视觉能力应通过模型能力检查；进行中消息支持 mode: "immediate"（引导）和 mode: "enqueue"（排队）；SDK 可注册自定义斜杠命令；应用可通过 onUserInputRequest 回答用户问题；在连接的客户端支持时，可通过 elicitation 处理器和 session.ui 提供丰富 UI 提示。
  • 遥测与可观测性：通过 TelemetryConfig 支持 OpenTelemetry 配置，内置追踪上下文传播，Node 使用显式 onGetTraceContext 回调进行出站传播。
  • 持久化与长时任务：使用稳定的 sessionId 实现可恢复会话；使用 infiniteSessions 支持可能需要压缩的长时工作流；会话状态默认存储在 ~/.copilot/session-state/ 下，除非配置覆盖。

使用方式

安装命令：

  • 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

快速开始模式（各语言思路一致）：创建/启动客户端；创建带权限处理器的会话；如需流式或进度，在 send() 之前注册事件处理器；使用 send() 或 sendAndWait() 发送；等待 session.idle 或返回的最终消息；disconnect() 会话并 stop/dispose 客户端。

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();

设置与部署选择：本地 CLI（个人工具和开发的最简路径）、捆绑 CLI（随应用分发 CLI 二进制，用于桌面/可分发工具）、后端服务（以无头模式运行 CLI 并通过 cliUrl 连接）、扩展与多租户（共享 CLI 与每用户 CLI、共享存储、会话锁定）、Azure 托管标识（当实际需求是 Azure 认证时，使用 BYOK 配合短期 bearer 令牌而非静态 API 密钥）。

适用场景

  • 在自有应用中集成 Copilot 智能体能力。
  • 构建桌面或可分发工具并捆绑 CLI。
  • 以后端服务形式运行无头 CLI 并连接。
  • 需要多租户扩展、共享存储或会话锁定的场景。
  • 使用 Azure 托管标识 / Entra 认证的 BYOK 模式。

限制与注意事项

  • 状态：公开预览，旧示例可能快速过时。
  • 正常使用 SDK 需要 GitHub Copilot 订阅；BYOK 支持且不需要 GitHub Copilot 认证。
  • Node.js、Python、.NET 自动捆绑 Copilot CLI；Go 可使用已安装的 CLI 或通过 go 工具捆绑工作流嵌入/捆绑；Java 目前位于 github/copilot-sdk-java，需要单独安装 CLI。
  • 权限采用默认拒绝模型，实际会话应提供显式权限处理器（如 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 仅对支持的模型存在。
  • assistant.message 和 assistant.message_delta 使用 event.data.*，而非顶层 event.content；流式/事件订阅应在 send() 之前附加。
  • SDK 暴露会话、模型、计划、模式切换、工作区文件、自定义智能体、钩子、MCP、技能和遥测等编程接口；许多终端 UX 功能仍仅限 CLI，如大多数斜杠命令工作流、交互式选择器和导出/分享命令。将 CLI 工作流转换为应用代码前，应查阅兼容性指南。
  • 本技能本地参考文件：references/working-examples.md（当前入门示例，含工具和恢复模式）、references/event-system.md（事件名称、生命周期和语言访问模式）、references/cli-agents-mcp.md（自定义智能体、技能、MCP、无头 CLI 和配置位置）、references/troubleshooting.md（常见故障、调试日志、认证、权限和传输问题）。