GitHub Copilot SDK 初体验：用 C# 把 CLI 能力接进自己的工具链

1. 从 CLI 到 SDK为什么要在 C# 工具链里嵌入 Copilot 能力GitHub Copilot SDK 是 GitHub 官方对 Copilot CLI 后端引擎的一层封装它把原本只能在命令行里交互的 agentic 工作流变成了可以在你自己的 C# 应用里直接调用的编程接口。简单说以前你得开个终端敲copilot命令现在你可以在 Blazor、WebAPI、控制台工具里用几行 C# 代码把同样的能力接进来。它适合谁适合那些已经有一套自研工具链、想让 AI 帮忙查数据库、调内部 API、跑自动化脚本但又不想把用户赶到终端里去的开发者。我试过在一个订单查询的小工具里接入这套 SDK整体感受是链路清晰但前置依赖比想象中多。你的应用不是直接跟模型说话而是走这样一条链路Your Application → SDK Client → (JSON-RPC) → Copilot CLI (server mode) → Model这意味着 SDK 本身不包含模型推理能力它只是客户端真正干活的是本机安装的 Copilot CLI。所以第一步不是写代码而是把 CLI 装好、认证好。当前 SDK 还处于 technical preview 阶段支持 C#、Node.js、Python、Go 四种语言C# 这边通过 NuGet 包引入即可。另一个现实问题是Copilot CLI 默认走 GitHub 账号认证如果你在团队内部想统一管理 Key、统一出口、统一看日志就需要一个能接管 API 通道的方案。我在实践里用 TaoToken 来做这层统一把 Base URL、Key、Model ID 三件套收敛到一处SDK 侧只改配置不改代码。下面按“准备 → 配置 → 调用 → 验证 → 排障”的顺序走一遍。2. 前置准备Copilot CLI 安装、认证与 TaoToken 通道配置2.1 安装 Copilot CLI 并确认版本SDK 依赖 CLI 的 server mode所以 CLI 必须先装好。在 Windows 上可以用 wingetmacOS 用 brew或者直接 npm 全局安装npm install -g github/copilot-cli copilot --version装完后确认copilot在 PATH 里因为 SDK 启动时会去拉起这个可执行文件。如果你在 CI 或容器里跑记得把 CLI 的安装步骤写进镜像。2.2 GitHub 身份认证CLI 首次运行会要求登录 GitHub 账号copilot auth login浏览器会弹出授权页完成后本地会缓存 token。这一步是 SDK 能跑起来的前提。如果你不想用 GitHub 账号认证可以走 BYOKBring Your Own Key方式直接提供模型端点和 Key跳过 Copilot 身份认证。这也是我推荐在团队工具链里用的方式因为 Key 可以集中管理。2.3 用 TaoToken 统一 Key 与 API 通道TaoToken 在这里的角色是统一入口你把模型请求的 Base URL 指向它Key 用它签发的Model ID 按它支持的列表填。这样 SDK、CLI、其他工具都共用一套凭证换模型或换通道时只改一处。先在控制台创建一个 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite拿到 Key 后把它写进环境变量避免硬编码进代码# Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的Key # macOS / Linux export TAOTOKEN_API_KEYsk-你的KeyBase URL 统一用https://taotoken.net/api注意这个地址不带任何查询参数。Model ID 按你实际要用的填比如gpt-4.1或claude-sonnet-4-5具体以文档里的模型列表为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite2.4 安装 C# SDK 包在项目里加 NuGet 包dotnet add package GitHub.Copilot.SDK --prerelease因为是 preview 阶段必须带--prerelease否则找不到包。装完后在.csproj里能看到对应的 PackageReference。3. 可复制配置settings.json 与 C# 会话初始化3.1 配置文件片段SDK 读取配置的方式和 CLI 一致推荐在项目根目录放一个copilot-settings.json把端点、Key、模型写进去。路径和字段名要和 CLI 的约定保持一致否则 SDK 拉起 CLI 时会读不到{ apiBaseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, model: gpt-4.1, cliPath: copilot, logLevel: debug }${TAOTOKEN_API_KEY}这种写法表示从环境变量读取避免把 Key 提交到仓库。logLevel设成debug是为了后面验证调用链路时能看到 JSON-RPC 的往返日志。如果你更习惯用 TOML等价写法是api_base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4.1 cli_path copilot log_level debug两种格式 SDK 都认选你项目里已有的那种就行。3.2 C# 会话初始化代码下面是一个最小可运行的调用示例。核心是创建CopilotClient然后用CreateSessionAsync开一个会话把工具、系统提示、权限处理器都配好using GitHub.Copilot.SDK; var client new CopilotClient(new CopilotClientOptions { ApiBaseUrl https://taotoken.net/api, ApiKey Environment.GetEnvironmentVariable(TAOTOKEN_API_KEY), Model gpt-4.1 }); var tools new[] { AIFunctionFactory.Create(GetOrderDetails, GetOrderDetails, 根据订单号查询订单详情) }; await using var session await client.CreateSessionAsync(new SessionConfig { Model gpt-4.1, SystemMessage new SystemMessageConfig { Mode SystemMessageMode.Replace, Content 你是一个订单查询助手只回答订单相关问题。 }, Tools tools, InfiniteSessions new InfiniteSessionConfig { Enabled false }, OnPermissionRequest PermissionHandler.ApproveAll }); session.On(evt { switch (evt) { case AssistantMessageEvent msg: Console.WriteLine($[助手] {msg.Content}); break; case SessionIdleEvent: Console.WriteLine([会话空闲]); break; case SessionErrorEvent err: Console.WriteLine($[错误] {err.Message}); break; } }); await session.SendAsync(帮我查一下订单 A1001 的状态);这里有几个关键点。OnPermissionRequest PermissionHandler.ApproveAll必须设置否则工具调用会被权限拦截程序直接卡住或报错。InfiniteSessions关掉是因为我们只做单轮查询不需要无限会话。AIFunctionFactory.Create把普通 C# 方法包装成模型可调用的 tool方法签名里的参数会被自动映射。3.3 工具方法定义被包装的方法长这样返回字符串即可static string GetOrderDetails(string orderId) { // 实际项目里走 EF Core 查 SQLite return orderId switch { A1001 订单 A1001已发货预计 3 天内送达, A1002 订单 A1002待付款, _ $未找到订单 {orderId} }; }模型会根据用户问题决定是否调用这个 tool调用结果再回传给模型生成自然语言回答。4. 验证请求跑起来并确认调用链路打通4.1 运行与观察日志用dotnet run启动程序在控制台或 Blazor 界面输入“查一下订单 A1001”。如果一切正常你会先看到 CLI 被拉起然后是一串 JSON-RPC 日志最后是助手回复。日志里重点看三样东西。第一apiBaseUrl是否指向https://taotoken.net/api确认请求没走错端点。第二有没有tool_call相关的记录说明GetOrderDetails被调用了。第三SessionIdleEvent是否出现表示这一轮结束。一个健康的调用链路日志大致是这样[debug] spawning copilot cli: copilot --server [debug] jsonrpc - initialize [debug] jsonrpc - initialized [debug] tool_call: GetOrderDetails({orderId:A1001}) [debug] tool_result: 订单 A1001已发货预计 3 天内送达 [助手] 订单 A1001 已发货预计 3 天内送达。 [会话空闲]4.2 用模型对话页做旁路验证如果 SDK 侧日志看不明白可以先用模型对话页单独验证 Key 和端点是否可用https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite在对话页里发一条消息能正常返回就说明 Key、Base URL、Model ID 三件套没问题问题就缩小到 SDK 或 CLI 侧了。这个分流排查法比盯着日志猜要快得多。4.3 确认工具调用真的发生有时候模型会“假装”调用了工具实际是直接编答案。要确认真的调用了可以在GetOrderDetails里加一行Console.WriteLine或者在日志里搜tool_call。如果用户问的是订单但日志里没有tool_call说明系统提示或工具描述写得不够明确模型没意识到该用工具。5. 常见报错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常见的就是 Key 没读到或写错了。先确认环境变量在当前 shell 里真的存在echo $env:TAOTOKEN_API_KEY # PowerShell echo $TAOTOKEN_API_KEY # bash如果为空说明环境变量没设上或者设在了另一个终端会话里。另一个原因是配置文件里写了${TAOTOKEN_API_KEY}但 SDK 没做变量替换这种情况直接把 Key 填进去测试确认是替换问题后再改回环境变量。5.2 local proxy failed这个报错通常出现在 CLI 启动阶段意思是 SDK 尝试拉起 CLI 的 server mode 失败了。原因可能是copilot不在 PATH 里或者 CLI 版本太旧不支持 server mode。先跑copilot --version确认能执行再跑copilot --server看能不能手动启动。如果手动能起、SDK 起不来检查cliPath配置是不是写成了绝对路径但路径里有空格。5.3 reading choices 相关错误这个报错一般出现在解析模型响应时说明返回的 JSON 结构跟 SDK 预期的不一致。常见原因是 Base URL 指向了一个不兼容 OpenAI 格式的端点或者 Model ID 填错了导致返回了错误结构。把 Base URL 确认为https://taotoken.net/apiModel ID 对照文档里的列表填不要自己拼。5.4 OAuth 认证失败如果你走的是 GitHub 账号认证而不是 BYOKOAuth 失败通常是 token 过期或缓存损坏。重新跑一次copilot auth login或者清掉本地缓存目录再登录。如果团队里统一用 BYOK这类问题基本不会遇到这也是我推荐 BYOK 的原因之一。5.5 工具没被调用程序跑起来了模型也回复了但回复是编的日志里没有tool_call。检查两点一是Tools数组真的传进SessionConfig了二是工具的描述文字够清楚。描述太模糊模型会忽略工具改成“根据订单号查询订单详情返回发货状态”这种具体描述命中率会高很多。6. 把 SDK 接进长期工具链Coding Plan 与后续扩展单次调用跑通只是起点。如果你打算把这套能力长期嵌进自研工具链比如做成内部的订单助手、代码审查机器人、自动化运维入口那需要考虑的是凭证管理、额度规划和多工具协同。凭证管理上统一走 TaoToken 的 Key所有工具共用一套换模型时只改配置。额度规划上如果调用量比较大可以看下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它适合长期编码和 Agent 类场景比按次调用更可控。接入文档在这里里面有各语言的完整示例和字段说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite扩展方向上SDK 的Tools数组可以塞多个AIFunctionFactory.Create把数据库查询、内部 API 调用、文件操作都包装成工具模型会自己决定调哪个。系统提示里把边界写清楚比如“只能查询订单不能修改订单”配合PermissionHandler做细粒度控制比一刀切ApproveAll更安全。最后提醒一句SDK 还在 previewAPI 签名可能变升级 NuGet 包后先跑一遍最小示例确认没破坏性变更。日志级别在生产环境调回info别一直开着debug不然 JSON-RPC 日志会把磁盘写满。