企业官网建设流程全解析

GitHub Copilot SDK 文档全景指南：从首个 Agent 应用到生产级部署

【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk

本指南以 Copilot SDK 的官方文档索引（docs/README.md）为骨架，为读者梳理这条完整的成长路径：先通过 Getting Started 用五分钟构建第一个 Copilot 应用，再按生产场景选择部署与认证方案，随后在 Features 与 Hooks 参考中掌握流式事件、自定义工具、MCP、Skills、会话钩子等核心能力，最后借助故障排查、可观测性与集成指南将应用打磨到可上线状态。读完本文，你将掌握如何在 Node.js/TypeScript、Python、Go、.NET、Java、Rust 六种语言中定位并使用 SDK 的全部能力，同时理解其底层 JSON-RPC 架构与源码实现。

文档地图：30 秒找到你需要的指南

docs/README.md是官方文档的总入口，它把全部资料按"目标场景"组织成一张导航表。无论你处于哪个阶段，都可以直接定位：

在目录结构上，仓库将文档分为八个一级模块：docs/getting-started.md（入门教程）、docs/setup/（部署配置）、docs/auth/（认证）、docs/features/（功能指南）、docs/hooks/（钩子 API 参考）、docs/troubleshooting/（故障排查）、docs/observability/（可观测性）与docs/integrations/（第三方集成）。下面逐一展开。

从零开始：Getting Started 教程

入门教程是官方推荐的起点。教程带你构建一个命令行天气助手：用户可以询问"西雅图天气怎么样"，Copilot 调用你自定义的get_weather工具返回结果。完成教程后你会掌握三条核心能力：发送消息、流式接收响应、让 Copilot 调用你的代码。

环境准备

• Copilot CLI：Node.js、Python、.NET SDK 会随包自动携带 CLI（见 Bundled CLI）；Go、Java、Rust 需要手动安装 CLI 或使用各自的应用级 CLI 打包能力。
• 语言运行时：各 SDK 在自身 README 的 Prerequisites 小节声明最低版本要求——Node.js（Node.js ^20.19.0 或 >=22.12.0）、Python（Python 3.11+）、Go、Rust、Java、.NET。

安装后验证 CLI 可用：

copilot --version

安装 SDK（六种语言）

# Node.js / TypeScript npm install @github/copilot-sdk tsx # Python pip install github-copilot-sdk # Go go get github.com/github/copilot-sdk/go # Rust（示例还需 tokio、serde、schemars） cargo add github-copilot-sdk --features derive # .NET dotnet add package GitHub.Copilot.SDK # Java（Maven） # <dependency> # <groupId>com.github</groupId> # <artifactId>copilot-sdk-java</artifactId> # <version>${copilot.sdk.version}</version> # </dependency>

第一条消息：约 5 行代码

以 Node.js/TypeScript 为例，createSession({ model: "auto" })创建会话，sendAndWait同步等待完整回复：

import { CopilotClient } from "@github/copilot-sdk"; const client = new CopilotClient(); const session = await client.createSession({ model: "auto" }); const response = await session.sendAndWait({ prompt: "What is 2 + 2?" }); console.log(response?.data.content); await client.stop(); process.exit(0);

Python 版本在此基础上需要显式传入权限处理器（PermissionHandler.approve_all），因为工具执行始终受各 SDK 权限处理器约束：

import asyncio from copilot import CopilotClient from copilot.session import PermissionHandler async def main(): client = CopilotClient() await client.start() session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="auto") response = await session.send_and_wait("What is 2 + 2?") print(response.data.content) await client.stop() asyncio.run(main())

Go、Rust、.NET、Java 的等价代码均收录在入门教程中：Go 通过copilot.NewClient(nil)+client.Start(ctx)启动；Rust 使用Client::start(ClientOptions::default())与ApproveAllHandler；.NET 使用await using var client = new CopilotClient()；Java 通过new CopilotClient()与PermissionHandler.APPROVE_ALL完成同样的调用链。六种语言运行后都应输出4。

流式响应：让回复逐字出现

将streaming: true传入会话配置，并订阅会话事件即可实时渲染回复。Node.js/TypeScript 写法：

const session = await client.createSession({ model: "auto", streaming: true }); session.on("assistant.message_delta", (event) => { process.stdout.write(event.data.deltaContent); }); session.on("session.idle", () => console.log());

SDK 提供三种事件订阅方法：on(handler)订阅全部事件（返回取消订阅函数）、on(eventType, handler)订阅指定类型（Node.js/TypeScript 专属）、Rust 的subscribe()返回事件流后按event_type过滤。各语言的事件过滤方式各异：Go 用类型断言switch d := event.Data.(type)，.NET 用switch (ev)模式匹配，Java 用session.on(AssistantMessageDeltaEvent.class, ...)按类型注册。

自定义工具：让 Copilot 调用你的代码

定义工具是 SDK 最具价值的能力之一。以天气工具为例，Node.js/TypeScript 使用defineTool声明名称、描述、JSON Schema 参数与处理器：

import { CopilotClient, defineTool } from "@github/copilot-sdk"; const getWeather = defineTool("get_weather", { description: "Get the current weather for a city", parameters: { type: "object", properties: { city: { type: "string", description: "The city name" } }, required: ["city"], }, handler: async (args: { city: string }) => { // 真实应用中在此调用天气 API return { city: args.city, temperature: "62°F", condition: "sunny" }; }, }); const session = await client.createSession({ model: "auto", streaming: true, tools: [getWeather] });

其他语言的定义方式体现了各自的类型系统：Python 用@define_tool(description=...)装饰器配合 Pydantic 参数模型；Go 用copilot.DefineTool("get_weather", "description", func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error))并以结构体标签jsonschema:"The city name"描述参数；Rust 用define_tool配合#[derive(Deserialize, JsonSchema)]；.NET 用CopilotTool.DefineTool包装Microsoft.Extensions.AI的AIFunctionFactoryOptions；Java 用ToolDefinition.create(name, description, Map, invocation -> ...)。

组装成交互式助手

教程最后把以上能力组装为可交互的 REPL 式助手：循环读取用户输入 →sendAndWait发送 → 流式打印回复，输入exit退出。完整的 Node.js/TypeScript 与 Python 实现在教程中均可直接运行，仓库中 nodejs/samples/chat.ts、python/samples/chat.py、go/samples/chat.go、dotnet/samples/Chat.cs、rust/examples/chat.rs 还提供了更完整的独立可运行示例。

Setup：按部署形态选择接入方式

Setup 指南覆盖从本地开发到大规模生产部署的完整形态，首篇 choosing-a-setup-path 提供架构、角色画像与决策矩阵，帮助你先选路再动手：

• 默认方案（Bundled CLI）：SDK 自动包含 CLI，无需单独安装——这是 Node.js、Python、.NET 的默认形态，见 bundled-cli.md。从 Python README 可以看到具体机制：安装后会通过python -m copilot download-runtime下载平台发布包，并用官方SHA256SUMS.txt校验后直接落地copilot-runtime与相邻的runtime.node，缓存路径按平台分别位于~/.cache/github-copilot-sdk/cli/<version>/prebuilds/（Linux）、~/Library/Caches/...（macOS）、%LOCALAPPDATA%\...（Windows）；若跳过下载，SDK 会在首次托管 stdio/TCP 使用时自动执行同样的 staging。
• 本地 CLI：使用你自己的 CLI 二进制或已运行的实例，适合已有 CLI 环境的场景，见 local-cli.md。Node.js SDK 支持通过COPILOT_CLI_PATH环境变量或连接配置的path覆盖内置运行时。
• 后端服务：以无头（headless）CLI 通过 TCP 提供服务端部署，见 backend-services.md。
• 进程内运行时（实验性）：把运行时以原生 C ABI（FFI）方式宿主在你的应用进程内，见 in-process-runtime.md。需注意：因为运行时共享进程，env、telemetry、workingDirectory在该传输方式下会被拒绝，应设置在主进程上；Python 需通过python -m copilot download-runtime --in-process预先准备 FFI 所需的原生库。
• GitHub OAuth：实现完整 OAuth 登录流程，见 github-oauth.md。
• Azure Managed Identity：配合 Microsoft Foundry 走 BYOK 路线，见 azure-managed-identity.md。
• 横向扩展与多租户：水平扩展、隔离模式见 scaling.md；多用户服务端部署的mode: "empty"、会话隔离、integration ID、sessionFs 等选项见 multi-tenancy.md。Node.js SDK 中mode?: "empty" | "copilot-cli"即为默认策略开关，多用户服务端模式应使用"empty"。

Node.js SDK 的连接方式由RuntimeConnection工厂函数抽象：forStdio()（默认，spawn 运行时走 stdin/stdout）、forTcp({ port, connectionToken, ... })（spawn 为 TCP 服务器）、forUri(url, { connectionToken })（连接已运行的实例，与gitHubToken/useLoggedInUser互斥）、forInProcess()（实验性 FFI）。

Authentication：认证方式与优先级

认证文档要求按部署场景选择认证方式，并明确给出了认证优先级：同时配置多份凭据时，显式 SDK token 优先，其次是直接 Copilot API 环境认证、环境变量 GitHub token、已存储的 Copilot CLI 凭据，最后才是 GitHub CLI 凭据；服务端到服务端安装 token 走环境变量路径。

• 认证总览：方法清单、优先级顺序与示例见 authenticate.md。
• 服务端到服务端认证：使用 GitHub Actions 或 GitHub App 安装 token 实现组织归属的自动化任务，见 server-to-server-tokens.md。
• BYOK（Bring Your Own Key）：配置 OpenAI、Azure、Anthropic 等自有 API 密钥，无需 GitHub 认证即可使用 SDK，见 byok.md。注意 BYOK 仅支持密钥认证，不支持 Microsoft Entra ID（Azure AD）、托管身份与第三方身份提供者。

多用户服务端模式下，需要为每个会话传入gitHubToken，确保每个会话以正确的 GitHub 身份运行（见 multi-tenancy.md）。项目根 README 汇总了全部认证途径：已登录 GitHub 用户（复用copilotCLI 登录的 OAuth 凭据）、OAuth GitHub App（透传用户 token）、环境变量（COPILOT_GITHUB_TOKEN、GH_TOKEN、GITHUB_TOKEN）与 BYOK。

Features：SDK 功能全景

功能指南是 SDK 能力最集中的模块，每个功能都有对应实战文档（语言示例覆盖 TypeScript、Python、Go、.NET、Java、Rust）：

从源码结构可以印证这些能力的落点：Python SDK 的 tools.py 承载工具定义、session_events.py 定义事件类型、client.py 实现客户端与会话生命周期；Node.js 对应 src/toolSet.ts、src/session.ts、src/client.ts。MCP 工具的运行时名称为<server-key>-<tool-name>形式，在availableTools/excludedTools中建议用new ToolSet().addMcp("<server-key>-<tool-name>")或原生mcp:<server-key>-<tool-name>形式（Node.js README）。

Hooks Reference：会话钩子 API 参考

Hooks 参考提供每个会话钩子的详细 API 文档，用于在会话关键节点注入自定义逻辑：

• Hooks overview：快速上手、常见模式与钩子调用上下文
• Pre-tool use：批准、拒绝或修改工具调用
• Post-tool use：转换工具结果
• User prompt submitted：修改或过滤用户消息
• User prompt transformed：检查或替换模型面提示词
• Session lifecycle：会话开始与结束
• Error handling：自定义错误处理

这与权限处理器的职责相呼应：SDK 默认暴露 Copilot CLI 的第一方工具（类似 CLI 的--allow-all），但工具执行仍受各 SDK 权限处理器约束，应用可以批准、拒绝或定制工具调用（见根 README 的 FAQ）。仓库测试对该机制有大量覆盖，例如 Python test_hooks_e2e.py、Node.js e2e 测试目录、Go hooks_e2e_test.go 与 .NET HookLifecycleAndOutputE2ETests.cs。

Troubleshooting：故障排查

排查指南包含三个入口：

• 调试指南：常见问题与解决方案
• MCP 调试：MCP 专属问题排查
• 兼容性矩阵：SDK 与 CLI 功能对照表

Observability：可观测性

可观测性文档聚焦 OpenTelemetry 插桩：SDK 内置TelemetryConfig与 trace context 传播，详见 opentelemetry.md。Python 用户可通过pip install "github-copilot-sdk[telemetry]"启用遥测扩展。此外，订阅assistant.usage事件并检查apiEndpoint（AssistantUsageApiEndpoint）即可进行成本归因与端点级分析（参考 streaming-events.md）。仓库中对应实现包括 python/copilot/_telemetry.py、nodejs/src/telemetry.ts、go/telemetry.go、dotnet/src/Telemetry.cs。

Integrations：第三方平台集成

集成指南目前收录 Microsoft Agent Framework，介绍如何在 MAF 多 Agent 工作流中使用 SDK。

源码级洞察：JSON-RPC 架构与多语言实现

理解 SDK 的底层架构有助于用好上述全部功能。项目根 README 明确了核心架构：所有语言的 SDK 都通过 JSON-RPC 与 Copilot CLI 服务器通信：

Your Application ↓ SDK Client ↓ JSON-RPC Copilot CLI (server mode)

SDK 自动管理 CLI 进程生命周期，也可以连接外部 CLI 服务器（详见 getting-started.md 的 server 模式说明）。各语言的通信与协议层实现位置如下：

• Python：client.py 客户端、_jsonrpc.py 协议层、rpc.py 与 session_events.py 生成的事件模型（python/copilot/generated/下为代码生成产物）
• Node.js / TypeScript：src/client.ts、src/ffiRuntimeHost.ts、src/generated/
• Go：client.go、copilot_request_handler.go、zrpc.go（协议层）
• .NET：src/Client.cs、src/JsonRpc.cs、src/Generated/
• Rust：src/lib.rs、src/jsonrpc.rs、src/rpc.rs
• Java：sdk/src/（约 1890 个 Java 文件，含生成的协议类型）

这些协议层与事件类型大量由 scripts/codegen/ 下的生成器（csharp.ts、go.ts、python.ts、rust.ts、typescript.ts）统一产出，保证六个 SDK 的行为一致，这也是"六种语言同一套事件语义"的工程基础。

FAQ：高频问题速览

根 README 对常见问题给出了明确回答，可直接作为决策依据：

• 需要 Copilot 订阅吗？需要，除非使用 BYOK——配置自有 LLM 提供商 API 密钥后可脱离 GitHub 认证使用 SDK。
• 计费方式？与 Copilot CLI 一致，每条 prompt 计入使用额度。
• 需要单独安装 CLI 吗？Node.js、Python、.NET 自动捆绑；Go、Java、Rust 需手动安装或使用应用级 CLI 打包能力，也可通过COPILOT_CLI_PATH覆盖二进制或连接外部服务器。
• 默认启用哪些工具？SDK 暴露 Copilot CLI 的第一方工具（类似--allow-all），工具执行仍受各 SDK 权限处理器约束，可通过客户端选项启用/禁用特定工具。
• 支持自定义 Agent、Skills、工具吗？支持，各语言 SDK 均可定义自定义 agent、skills 与 tools。
• 支持哪些模型？所有 Copilot CLI 可用模型均受支持，SDK 还提供运行时查询可用模型的方法。
• 生产可用吗？SDK 已 GA（一般可用）并遵循语义化版本控制，发布记录见 CHANGELOG.md。

结语：按需取用的完整文档体系

这份文档地图的价值在于"分层取用"：初学从 Getting Started 走完第一遍全流程；做架构决策时对照 Setup 与 Auth；为应用叠加能力时翻阅 Features；深入调优时参考 Hooks 与 Observability；遇到问题则回到 Troubleshooting。配合各语言目录下的 SDK README（nodejs/README.md、python/README.md、go/README.md、dotnet/README.md、rust/README.md、java/README.md）与 CHANGELOG.md，即可覆盖从首个 Demo 到生产集群的完整生命周期。

【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk