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 上可以用 winget，macOS 用 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 账号认证，可以走 BYOK（Bring Your Own Key）方式，直接提供模型端点和 Key，跳过 Copilot 身份认证。这也是我推荐在团队工具链里用的方式，因为 Key 可以集中管理。
2.3 用 TaoToken 统一 Key 与 API 通道
TaoToken 在这里的角色是统一入口：你把模型请求的 Base URL 指向它，Key 用它签发的，Model ID 按它支持的列表填。这样 SDK、CLI、其他工具都共用一套凭证，换模型或换通道时只改一处。
先在控制台创建一个 API Key：
https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite拿到 Key 后，把它写进环境变量，避免硬编码进代码：
# Windows PowerShell $env:TAOTOKEN_API_KEY="sk-你的Key" # macOS / Linux export TAOTOKEN_API_KEY="sk-你的Key"Base URL 统一用https://taotoken.net/api，注意这个地址不带任何查询参数。Model ID 按你实际要用的填，比如gpt-4.1或claude-sonnet-4-5，具体以文档里的模型列表为准：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite2.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_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite在对话页里发一条消息，能正常返回就说明 Key、Base URL、Model ID 三件套没问题，问题就缩小到 SDK 或 CLI 侧了。这个分流排查法比盯着日志猜要快得多。
4.3 确认工具调用真的发生
有时候模型会“假装”调用了工具，实际是直接编答案。要确认真的调用了，可以在GetOrderDetails里加一行Console.WriteLine，或者在日志里搜tool_call。如果用户问的是订单，但日志里没有tool_call，说明系统提示或工具描述写得不够明确，模型没意识到该用工具。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
5.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/api，Model ID 对照文档里的列表填，不要自己拼。
5.4 OAuth 认证失败
如果你走的是 GitHub 账号认证而不是 BYOK，OAuth 失败通常是 token 过期或缓存损坏。重新跑一次copilot auth login，或者清掉本地缓存目录再登录。如果团队里统一用 BYOK，这类问题基本不会遇到，这也是我推荐 BYOK 的原因之一。
5.5 工具没被调用
程序跑起来了，模型也回复了，但回复是编的，日志里没有tool_call。检查两点：一是Tools数组真的传进SessionConfig了，二是工具的描述文字够清楚。描述太模糊模型会忽略工具，改成“根据订单号查询订单详情，返回发货状态”这种具体描述，命中率会高很多。
6. 把 SDK 接进长期工具链：Coding Plan 与后续扩展
单次调用跑通只是起点。如果你打算把这套能力长期嵌进自研工具链，比如做成内部的订单助手、代码审查机器人、自动化运维入口，那需要考虑的是凭证管理、额度规划和多工具协同。
凭证管理上，统一走 TaoToken 的 Key，所有工具共用一套，换模型时只改配置。额度规划上，如果调用量比较大，可以看下 Coding Plan：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite它适合长期编码和 Agent 类场景，比按次调用更可控。接入文档在这里，里面有各语言的完整示例和字段说明：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite扩展方向上，SDK 的Tools数组可以塞多个AIFunctionFactory.Create，把数据库查询、内部 API 调用、文件操作都包装成工具，模型会自己决定调哪个。系统提示里把边界写清楚，比如“只能查询订单，不能修改订单”，配合PermissionHandler做细粒度控制，比一刀切ApproveAll更安全。
最后提醒一句：SDK 还在 preview，API 签名可能变，升级 NuGet 包后先跑一遍最小示例确认没破坏性变更。日志级别在生产环境调回info，别一直开着debug，不然 JSON-RPC 日志会把磁盘写满。
