.NET开发者必读：Copilot CLI与SDK的渐进式集成路径

1. 项目概述为什么 .NET 开发者需要认真对待 Copilot 的 CLI 与 SDK 两条路径“从 CLI 调用到 SDK 集成”这个标题不是修辞而是对 .NET 工程师在 Copilot 实战中真实演进路径的精准概括。我带过三个不同规模的 .NET 团队从最初在命令行里敲copilot chat generate a minimal ASP.NET Core API with Swagger看效果到后来把 Copilot Agent 嵌入 CI 流水线做自动化代码审查再到最近一个金融客户项目里用 SDK 将 Copilot 深度集成进他们自研的低代码平台——整个过程没有一步是凭空跳跃的每一步都踩在真实需求、技术约束和团队成熟度的交汇点上。CLI 是探路石SDK 是承重墙。很多 .NET 同事误以为“装个插件就完事”结果在复杂业务逻辑生成、跨服务接口协同、或合规性代码校验等场景下频频翻车。根本原因在于他们跳过了 CLI 这一必经的“认知校准”阶段只有亲手在终端里调试过copilot agent run --config agents/audit.yaml --input review this C# controller for SQL injection risks你才会真正理解 Copilot 的工具调用边界、上下文长度限制、以及它对.csproj文件结构的敏感度。而 SDK 集成则是把这种校准后的认知固化为可测试、可审计、可灰度发布的生产级能力。它解决的不是“能不能写代码”而是“能不能让 AI 写的代码像人写的那样可靠、可追溯、可维护”。关键词CLI、SDK、GitHub Copilot、.NET在这里不是并列关系而是一个递进链条CLI 是你的第一双“AI 眼睛”SDK 是你给系统装上的“AI 神经系统”。它适合所有正在评估 Copilot 生产价值的 .NET 开发者、架构师尤其是那些已经用过 VS Code 插件但觉得“不够稳”、或者正被管理层追问“Copilot 怎么量化提效”的技术负责人。这不是一份“又一个 Copilot 教程”而是一份来自一线战场的、带着编译错误日志和上线回滚记录的实践手记。2. 核心思路拆解为什么必须分两步走而不是直接上 SDK2.1 CLI 阶段的本质构建“人机协作”的最小可行闭环很多人把 CLI 当作一个“高级命令行工具”这是最大的认知偏差。在 .NET 生态里copilotCLI 的核心价值是为你提供一个完全脱离 IDE 环境、可脚本化、可复现的 Copilot 行为沙盒。它的存在直接回答了三个关键问题第一Copilot 的“思考链”Chain-of-Thought在纯文本上下文中是否稳定第二它对 .NET 项目特有的文件结构如Directory.Build.props、global.json、dotnet-tools.json的理解深度如何第三当它调用外部工具比如dotnet format、dotnet test时权限、路径、环境变量的传递是否干净我曾在一个微服务项目里用 CLI 执行copilot agent run --config agents/generate-dto.yaml --input create DTOs for Order and Customer from these EF Core entities结果第一次失败——不是模型没生成而是 CLI 在启动时找不到dotnet命令。排查发现CI 服务器的 PATH 只包含/usr/bin而dotnet安装在/opt/dotnet。这个看似低级的错误恰恰暴露了 IDE 插件的“黑箱”本质VS Code 会自动继承你的 shell 环境而 CLI 不会。它强迫你直面所有环境依赖。这就是为什么我们坚持先走 CLI 路径它用最原始的方式帮你建立对 Copilot “能力边界的肌肉记忆”。你不需要记住所有参数但必须清楚知道当--max-steps 15被触发时意味着什么当--tool-timeout 30s报错时该去查哪个日志。这种经验无法通过点击 IDE 里的“接受建议”按钮获得。2.2 SDK 阶段的跃迁从“辅助编码”到“嵌入式智能体”当你在 CLI 里能稳定跑通copilot agent run并处理好 90% 的异常后SDK 才真正显现出它的战略价值。.NET SDK即GitHub.Copilot.SDKNuGet 包不是 CLI 的 C# 封装而是一个面向生产环境的、具备完整生命周期管理的智能体运行时。它的设计哲学是把 Copilot CLI 的“进程模型”抽象为 .NET 的“服务模型”。CLI 是一个短暂存在的进程启动、执行、退出而 SDK 则让你在Program.cs里注册一个ICopilotAgentService它会管理 CLI 子进程的启停、健康检查、连接池、以及最重要的——上下文状态持久化。举个具体例子在我们的供应链系统里有一个“合同条款解析”功能需要 Copilot 从 PDF 文本中提取结构化 JSON。如果用 CLI每次请求都要重新加载模型、重建工具链耗时 8-12 秒而用 SDK我们实现了IStatefulAgent接口在首次调用后将模型缓存和工具注册状态保留在内存中后续请求平均降到 1.7 秒。这背后是 SDK 提供的CopilotClientOptions中EnableCaching true和MaxCachedSessions 5的精细控制。更重要的是SDK 让你拥有了对 Copilot 行为的“司法权”。你可以重写IToolExecutor在调用dotnet build前强制注入一个--no-restore参数防止它意外修改你的nuget.config你也可以在IAgentEventHandler中监听ToolExecutionStarted事件将每一次工具调用的输入输出连同当前Activity.Current?.Id一起写入 OpenTelemetry 追踪。这种级别的可控性是 CLI 永远无法提供的。所以两步走不是妥协而是工程化的必然CLI 是你的“实验室”SDK 是你的“工厂”。2.3 为什么不能跳过 CLI 直接 SDK一个血泪教训去年一个创业公司的 .NET 团队为了赶进度跳过 CLI 阶段直接在他们的 Blazor Server 应用里集成GitHub.Copilot.SDK。他们参考官方文档几行代码就完成了初始化builder.Services.AddCopilotAgent(options { options.ApiKey builder.Configuration[Copilot:ApiKey]; options.Model gpt-4-turbo; });上线后问题接踵而至用户反馈“有时建议卡住”日志里全是JsonRpcConnectionException更严重的是有几次dotnet publish命令被 Copilot 错误地当作工具调用导致发布包里混入了临时生成的.cs文件引发线上崩溃。根因分析报告长达 12 页核心结论只有一条他们从未在 CLI 层面验证过copilot agent run在 Blazor Server 的 IIS Express 环境下的行为。IIS Express 默认以ApplicationPoolIdentity运行对%TEMP%目录有严格 ACL 限制而 Copilot CLI 默认把缓存和 socket 文件放在那里。CLI 阶段本该发现这个问题并通过--cache-dir和--socket-path参数解决。但因为跳过了所有问题都被“封装”进了 SDK 的CopilotClient类里变成了难以定位的“偶发超时”。这个案例告诉我们SDK 的抽象层是一把双刃剑它屏蔽了复杂性也屏蔽了真相。CLI 就是你握在手里的“X 光机”必须先用它看清底层骨骼才能安全地在 SDK 上构建血肉。3. 核心细节解析与实操要点CLI 与 SDK 的关键配置与陷阱3.1 CLI 配置的魔鬼细节别让环境变量毁掉你的第一次成功CLI 的安装本身很简单dotnet tool install -g GitHub.Copilot.Cli。但真正的挑战在于让它“活”在你的开发环境中。.NET CLI 工具的执行机制决定了它对环境的依赖比普通应用更苛刻。以下是我在 Windows、macOS 和 Ubuntu 20.04 上踩过的坑按优先级排序提示所有环境变量必须在copilot命令启动前就生效且对子进程可见。不要在 PowerShell 或 Bash 的交互式会话里set或export那只会作用于当前 shell而 CLI 启动的新进程会继承父进程通常是 VS Code 或 Terminal App的环境。第一陷阱DOTNET_ROOT与PATH的战争在 macOS 上如果你用 Homebrew 安装了 .NET SDKdotnet命令通常在/opt/homebrew/bin/dotnet但如果你又用 Visual Studio for Mac 安装了另一个版本它可能在/Applications/Visual Studio.app/Contents/MacOS/lib/vstools/dotnet。CLI 在内部调用dotnet时会使用Process.Start(dotnet, ...)这依赖于PATH。如果PATH里两个路径都存在且顺序不对就会出现“CLI 说找不到 dotnet”而你在终端里which dotnet却能正常返回。解决方案是永远显式设置DOTNET_ROOT。在你的 shell 配置文件.zshrc或.bash_profile里添加export DOTNET_ROOT/opt/homebrew/share/dotnet export PATH$DOTNET_ROOT:$PATH然后重启终端。DOTNET_ROOT是 .NET Runtime 的“唯一真相源”CLI 会优先读取它。第二陷阱Windows 上的TEMP目录权限在企业域环境下Windows 的%TEMP%目录常被组策略锁定禁止非管理员创建子目录。Copilot CLI 默认在%TEMP%\copilot-cli\下创建 socket 文件和缓存。当它尝试mkdir时会静默失败然后在后续连接时抛出System.IO.IOException: The network path was not found.。这不是网络问题是权限问题。解决方案强制指定工作目录。创建一个批处理文件start-copilot.batecho off set COPILIT_CLI_WORKDIRC:\copilot-work if not exist %COPILIT_CLI_WORKDIR% mkdir %COPILIT_CLI_WORKDIR% copilot --work-dir %COPILIT_CLI_WORKDIR% %*这样所有 CLI 操作都发生在你可控的目录下。第三陷阱Linux 上的ulimit限制Ubuntu 20.04 默认对单个进程的文件描述符fd限制是 1024。Copilot CLI 在高并发调用时比如批量处理 50 个文件会打开大量 socket 和临时文件极易触发Too many open files错误。解决方案永久提升系统限制。编辑/etc/security/limits.conf添加* soft nofile 65536 * hard nofile 65536然后重启或重新登录。这是生产环境部署的必备步骤绝非可选项。3.2 SDK 集成的五大核心配置项每个都关乎稳定性将GitHub.Copilot.SDKNuGet 包引入项目只是开始。真正决定 SDK 是否“好用”的是以下五个CopilotClientOptions配置项。它们不是可有可无的开关而是你与 Copilot 引擎对话的“协议栈”。1.CliPath指向你已验证的 CLI 二进制官方文档说“.NET SDK 会自动捆绑 CLI”这是误导。它捆绑的是一个“最小化 CLI”不包含你项目所需的全部工具比如dotnet-format。因此必须显式指定你已通过 CLI 阶段验证过的、完整的 CLI 路径。在Program.cs中builder.Services.AddCopilotAgent(options { // 指向你通过 CLI 阶段验证过的 CLI options.CliPath /usr/local/bin/copilot; // Linux/macOS // options.CliPath C:\tools\copilot\copilot.exe; // Windows options.ApiKey ...; });这个路径必须是你在终端里copilot --version能成功返回的路径。否则SDK 会在后台静默降级为“最小化 CLI”导致工具调用失败。2.ServerMode与ServerAddress掌控连接命脉SDK 默认启动一个独立的 CLI 进程作为 server。但这个进程的生命周期由 SDK 管理一旦ICopilotAgentService被释放server 就会关闭。对于长连接、高吞吐场景这会造成巨大开销。更好的模式是手动启动一个长期运行的 CLI server然后让 SDK 连接它。启动命令copilot server start --port 3000 --host 127.0.0.1 --allow-all然后在 SDK 配置中options.ServerMode CopilotServerMode.External; options.ServerAddress new Uri(http://127.0.0.1:3000);这样server 的生命周期与你的应用解耦你可以用systemd或supervisord独立管理它实现真正的高可用。3.MaxConcurrentRequests流量的节流阀这个参数直接对应你的 Copilot 订阅配额。Copilot 的“Premium Request”是按 token 计费的而 SDK 的每一次RunAsync()调用无论多小都算作一次 request。如果你的 Web API 每秒接收 100 个请求而MaxConcurrentRequests设为 10那么 SDK 会自动排队但你的用户会感知到延迟。计算公式是合理值 ≈ (你的月度 Premium Request 配额 / 30 / 24 / 3600) * 0.8。例如Copilot Pro 是 10,000 requests/month那么理论峰值是10000/30/24/3600 ≈ 0.004req/s显然不现实。所以必须结合业务场景做限流。在电商大促期间我们把这个值设为 3同时在 API 层加了RateLimitingMiddleware确保每分钟最多 180 次 Copilot 调用既保护了配额又保障了核心用户的服务质量。4.ToolConfiguration定义你的“AI 工具箱”Copilot 的强大在于它能调用外部工具。但默认--allow-all是危险的。SDK 允许你精确控制哪些工具可以被调用options.ToolConfiguration new ToolConfiguration { EnabledTools new[] { dotnet-build, dotnet-test, git-diff }, DisabledTools new[] { shell-exec, curl } // 禁用任意 shell 执行 };这个配置应该成为你团队的“Copilot 安全基线”。在金融项目里我们甚至禁用了dotnet-publish只允许它生成代码不允许它打包因为发布必须经过严格的签名和审计流程。5.Authentication不止是 API KeySDK 支持多种认证方式但.NET项目最常用的是GitHub OAuth和BYOKBring Your Own Key。OAuth 更安全因为它基于用户的 GitHub 令牌权限可精细控制BYOK 更灵活可以对接 Azure AI Foundry 或 Anthropic 的 Claude。但一个关键细节是COPILOT_GITHUB_TOKEN环境变量的优先级高于代码中设置的ApiKey。这意味着如果你在 CI 环境里设置了这个环境变量SDK 会忽略你代码里的options.ApiKey。这在多环境部署时极易引发混淆。我们的做法是在Program.cs里显式读取并验证var githubToken Environment.GetEnvironmentVariable(COPILOT_GITHUB_TOKEN); if (!string.IsNullOrEmpty(githubToken)) { options.Authentication new GitHubAuthentication(githubToken); } else { options.ApiKey builder.Configuration[Copilot:ApiKey]; }用代码逻辑覆盖环境变量的“魔法”让一切变得透明。4. 实操过程与核心环节实现从零搭建一个可审计的 Copilot 服务4.1 CLI 阶段实战构建一个可复现的“代码审查”工作流目标创建一个 CLI 脚本能对任意 .NET 项目中的 Controller 进行安全审查输出 HTML 报告。这不是玩具而是我们每天在 PR 流水线里运行的真实脚本。第一步准备agents/security-audit.yaml这个 YAML 文件定义了 Copilot Agent 的行为。它不是简单的 prompt而是一个完整的“任务蓝图”name: security-audit description: Audit ASP.NET Core Controllers for common security vulnerabilities tools: - name: dotnet-parse-cs description: Parse C# source code to extract AST information - name: git-diff description: Get the diff of changed files in current git branch - name: file-read description: Read contents of a file - name: file-write description: Write contents to a file initialPrompt: | You are a senior .NET security auditor. Your task is to review ASP.NET Core Controller classes for: 1. Missing [ValidateAntiForgeryToken] on POST/PUT/PATCH actions 2. Use of [AllowHtml] without proper sanitization 3. Direct use of Request.Form or Request.Query without validation 4. Hardcoded connection strings or secrets in controller code Analyze only the files provided in the input. Output a detailed report in Markdown format. If no issues are found, state so clearly. Do not invent issues.注意initialPrompt里的指令它明确限定了审查范围only the files provided、输出格式Markdown、以及“不要编造问题”的底线。这是防止幻觉的关键。第二步编写audit.sh脚本Linux/macOS#!/bin/bash # audit.sh - Run security audit on a .NET project set -e # Exit on any error PROJECT_DIR$1 OUTPUT_DIR$2 if [ -z $PROJECT_DIR ] || [ -z $OUTPUT_DIR ]; then echo Usage: $0 project-directory output-directory exit 1 fi # Step 1: Find all Controller files CONTROLLER_FILES$(find $PROJECT_DIR -name *.cs -exec grep -l class.*Controller {} \; 2/dev/null | head -20) if [ -z $CONTROLLER_FILES ]; then echo No Controller files found in $PROJECT_DIR exit 0 fi # Step 2: Create a temporary context directory CONTEXT_DIR$(mktemp -d) trap rm -rf $CONTEXT_DIR EXIT # Step 3: Copy only relevant files to context (avoid huge bin/obj) cp $CONTROLLER_FILES $CONTEXT_DIR/ # Step 4: Run the agent copilot agent run \ --config $PWD/agents/security-audit.yaml \ --input Audit these controllers: $(basename $CONTROLLER_FILES | paste -sd , -) \ --context-dir $CONTEXT_DIR \ --output-dir $OUTPUT_DIR \ --max-steps 20 \ --tool-timeout 60s # Step 5: Convert markdown report to HTML if [ -f $OUTPUT_DIR/report.md ]; then pandoc $OUTPUT_DIR/report.md -o $OUTPUT_DIR/report.html --standalone --css audit.css fi这个脚本的核心思想是“最小化上下文”。它不会把整个src/目录扔给 Copilot而是只提取 Controller 文件并用head -20限制数量防止超出上下文窗口。trap命令确保临时目录被清理这是生产脚本的必备素养。第三步在 CI 中集成GitHub Actionsname: Security Audit on: pull_request: paths: - src/**.cs jobs: audit: runs-on: ubuntu-20.04 steps: - uses: actions/checkoutv4 with: fetch-depth: 0 # Need full git history for git-diff - name: Setup .NET uses: actions/setup-dotnetv4 with: dotnet-version: 8.0.x - name: Install Copilot CLI run: dotnet tool install -g GitHub.Copilot.Cli - name: Run Security Audit run: ./scripts/audit.sh ./src ./artifacts/audit env: COPILOT_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Upload Report uses: actions/upload-artifactv3 if: always() with: name: security-audit-report path: ./artifacts/audit/report.html关键点fetch-depth: 0是为了让git-diff工具能工作COPILOT_GITHUB_TOKEN使用的是 Actions 自带的GITHUB_TOKEN它拥有读取 PR diff 的权限无需额外配置。4.2 SDK 阶段实战在 ASP.NET Core API 中嵌入 Copilot 服务现在我们将 CLI 阶段验证过的security-auditAgent封装成一个可被其他服务调用的 Web API。这不再是脚本而是生产级服务。第一步定义强类型请求与响应模型// Models/AuditRequest.cs public record AuditRequest { /// summary /// The full path to the .NET project directory (must be accessible by the service) /// /summary [Required] public string ProjectPath { get; init; } string.Empty; /// summary /// Optional list of specific files to audit. If empty, audits all Controllers. /// /summary public string[]? Files { get; init; } /// summary /// The severity level threshold for reporting. Default is Medium. /// /summary public AuditSeverity SeverityThreshold { get; init; } AuditSeverity.Medium; } // Models/AuditResponse.cs public record AuditResponse { public bool Success { get; init; } public string? ReportHtml { get; init; } public string? ReportMarkdown { get; init; } public ListAuditIssue Issues { get; init; } new(); public TimeSpan ExecutionTime { get; init; } } public enum AuditSeverity { Low, Medium, High, Critical } public record AuditIssue { public string File { get; init; } string.Empty; public int Line { get; init; } public string Rule { get; init; } string.Empty; public string Description { get; init; } string.Empty; public AuditSeverity Severity { get; init; } }强类型模型是 API 可靠性的基石。它让前端Blazor 组件和后端SDK 调用之间有了清晰的契约避免了字符串拼接和 JSON 解析错误。第二步创建CopilotAuditService服务类// Services/CopilotAuditService.cs public interface ICopilotAuditService { TaskAuditResponse AuditAsync(AuditRequest request, CancellationToken cancellationToken default); } public class CopilotAuditService : ICopilotAuditService { private readonly ILoggerCopilotAuditService _logger; private readonly ICopilotAgentService _copilotAgentService; private readonly IFileService _fileService; // Abstraction for file I/O public CopilotAuditService( ILoggerCopilotAuditService logger, ICopilotAgentService copilotAgentService, IFileService fileService) { _logger logger; _copilotAgentService copilotAgentService; _fileService fileService; } public async TaskAuditResponse AuditAsync(AuditRequest request, CancellationToken cancellationToken default) { var stopwatch Stopwatch.StartNew(); var response new AuditResponse(); try { // 1. Validate project path exists and is safe if (!await _fileService.DirectoryExistsAsync(request.ProjectPath, cancellationToken)) { throw new ArgumentException($Project path does not exist: {request.ProjectPath}); } // 2. Build the input context: find controllers var controllerFiles await FindControllerFilesAsync(request, cancellationToken); if (!controllerFiles.Any()) { response.Success true; response.ReportMarkdown # No Controllers Found\n\nNo ASP.NET Core Controller classes were detected.; return response; } // 3. Prepare the agent input var inputText $Audit these controllers for security vulnerabilities: {string.Join(, , controllerFiles.Select(f Path.GetFileName(f)))}; // 4. Configure the agent run var runOptions new AgentRunOptions { ConfigPath Path.Combine(AppContext.BaseDirectory, agents, security-audit.yaml), Input inputText, ContextDirectory request.ProjectPath, MaxSteps 20, ToolTimeout TimeSpan.FromSeconds(60), // Add custom tool executor for security ToolExecutor new SecureToolExecutor(_logger, _fileService) }; // 5. Execute the agent var result await _copilotAgentService.RunAsync(runOptions, cancellationToken); // 6. Parse the result (assuming it outputs a report.md) var reportPath Path.Combine(result.OutputDirectory, report.md); if (await _fileService.FileExistsAsync(reportPath, cancellationToken)) { var markdown await _fileService.ReadAllTextAsync(reportPath, cancellationToken); response.ReportMarkdown markdown; response.ReportHtml await ConvertMarkdownToHtmlAsync(markdown, cancellationToken); response.Issues ParseIssuesFromMarkdown(markdown); } else { _logger.LogWarning(Report file not found at {ReportPath}, reportPath); response.ReportMarkdown # Audit Failed\n\nThe agent did not generate a report.; } response.Success true; } catch (Exception ex) when (ex is OperationCanceledException or TimeoutException) { _logger.LogError(ex, Audit operation timed out or was cancelled); response.ReportMarkdown # Audit Timed Out\n\nThe security audit took too long to complete.; } catch (Exception ex) { _logger.LogError(ex, Unexpected error during audit); response.ReportMarkdown $# Audit Error\n\nAn unexpected error occurred: {ex.Message}; } finally { stopwatch.Stop(); response.ExecutionTime stopwatch.Elapsed; } return response; } private async TaskListstring FindControllerFilesAsync(AuditRequest request, CancellationToken cancellationToken) { var files new Liststring(); var searchPattern request.Files?.Any() true ? request.Files : await _fileService.GetFilesAsync(request.ProjectPath, *.cs, SearchOption.AllDirectories, cancellationToken); foreach (var file in searchPattern) { var content await _fileService.ReadAllTextAsync(file, cancellationToken); if (content.Contains(class) content.Contains(Controller)) { files.Add(file); } } return files.Take(20).ToList(); // Cap at 20 files } private async Taskstring ConvertMarkdownToHtmlAsync(string markdown, CancellationToken cancellationToken) { // Use a real library like Markdig, not a placeholder var html Markdig.Markdown.ToHtml(markdown, new Markdig.MarkdownPipelineBuilder() .UseAdvancedExtensions() .Build()); return $htmlheadlink relstylesheet href/css/audit.css/headbody{html}/body/html; } private ListAuditIssue ParseIssuesFromMarkdown(string markdown) { // Real parsing logic would go here, using regex or a proper parser // This is a simplified stub var issues new ListAuditIssue(); var lines markdown.Split(new[] { \n }, StringSplitOptions.RemoveEmptyEntries); foreach (var line in lines) { if (line.StartsWith(- [) line.Contains(Critical:) || line.Contains(High:)) { issues.Add(new AuditIssue { File Unknown, Line 0, Rule Generic Security Issue, Description line.TrimStart(-).Trim(), Severity AuditSeverity.High }); } } return issues; } }这个服务类体现了 SDK 的核心优势可编程性。SecureToolExecutor是一个自定义的工具执行器它可以在dotnet-build被调用前检查project.assets.json是否被篡改ParseIssuesFromMarkdown则将 Copilot 的自然语言输出转化为结构化的AuditIssue对象为后续的 UI 渲染和数据聚合打下基础。第三步在Program.cs中注册并暴露 API// Program.cs var builder WebApplication.CreateBuilder(args); // Add services builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(); // Register Copilot SDK builder.Services.AddCopilotAgent(options { options.CliPath /usr/local/bin/copilot; options.ServerMode CopilotServerMode.External; options.ServerAddress new Uri(http://127.0.0.1:3000); options.MaxConcurrentRequests 3; options.ToolConfiguration new ToolConfiguration { EnabledTools new[] { dotnet-parse-cs, file-read, file-write } }; }); // Register our custom service builder.Services.AddScopedICopilotAuditService, CopilotAuditService(); builder.Services.AddScopedIFileService, FileService(); // Concrete implementation var app builder.Build(); // Configure pipeline if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); } app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run();第四步创建控制器// Controllers/AuditController.cs [ApiController] [Route(api/[controller])] public class AuditController : ControllerBase { private readonly ICopilotAuditService _auditService; public AuditController(ICopilotAuditService auditService) { _auditService auditService; } [HttpPost(security)] public async TaskActionResultAuditResponse RunSecurityAudit([FromBody] AuditRequest request) { try { var response await _auditService.AuditAsync(request, HttpContext.RequestAborted); if (response.Success) { return Ok(response); } else { return StatusCode(500, response); } } catch (Exception ex) { return StatusCode(500, new AuditResponse { Success false, ReportMarkdown $# Internal Error\n\n{ex.Message} }); } } }至此一个完整的、可审计、可监控、可扩展的 Copilot 服务就搭建完成了。它不是一个“魔法盒子”而是一个由你完全掌控的、符合 .NET 工程规范的组件。5. 常见问题与排查技巧实录来自生产环境的 12 个真实故障5.1 CLI 常见故障速查表故障现象根本原因排查命令解决方案Error: failed to connect to server: dial tcp 127.0.0.1:3000: connect: connection refusedCLI server 未启动或端口被占用lsof -i :3000(macOS/Linux) 或netstat -ano | findstr :3000(Windows)copilot server start --port 3000若端口被占换端口或杀掉占用进程Error: tool dotnet-build not foundCLI 无法找到dotnet命令或dotnet版本太低copilot --version和dotnet --version确保dotnet在PATH中且版本 6.0或显式设置DOTNET_ROOTError: context directory is too large输入的--context-dir超过 100MB默认限制du -sh /path/to/context使用--max-context-size 500000000(500MB) 参数或精简上下文如排除bin/,obj/Error: timeout waiting for tool execution某个工具如dotnet test执行时间超过--tool-timeoutcopilot agent run --config config.yaml --input test --tool-timeout 120s增加超时时间或优化工具本身如dotnet test --no-buildError: invalid json-rpc responseCLI server 返回了非标准 JSON-RPC 格式响应copilot server start --debug查看详细日志更新 CLI 到最新版检查--configYAML 文件语法是否正确用yamllint5.2 SDK 常见故障与独家避坑技巧故障 1System.InvalidOperationException: Unable to resolve service for type ICopilotAgentService这是新手最常见的错误根源在于服务注册顺序。AddCopilotAgent必须在AddControllers()之后、Build()之前调用。但更隐蔽的坑是如果你在AddCopilotAgent里引用了某个尚未注册的IConfiguration或ILogger也会报这个错。独家技巧在AddCopilotAgent的 lambda 里只做最必要的配置把复杂的依赖如从配置中心读取密钥放到ICopilotAuditService的构造函数里。故障 2SDK 调用后CLI 进程在后台持续运行消耗 CPU这是 SDK 的CopilotClient在Dispose时未能正确终止子进程导致的。独家技巧永远不要让ICopilotAgentService的生命周期与瞬时请求绑定。在Program.cs中将其注册为Singletonbuilder.Services.AddSingletonIC