使用 .NET 开发 GitHub Copilot Agent，如何设计架构并选择工具？

建议先确定 Copilot 的接入入口，再按职责分层：业务能力由普通 .NET 服务实现，工作流负责步骤与状态，适配器负责连接 Copilot。上下文按任务选择，测试使用可替换的适配器和少量真实集成用例。

原问题没有说明使用哪一种 Copilot 扩展机制，因此无法直接给出通用的“Copilot API”调用代码。需要先确定接入方式，再设计后端和工作流。

先确定需要扩展哪一部分

不同目标对应不同入口：

• 让 Copilot 调用已有的 .NET 业务能力：可以考虑将相关操作暴露为 MCP tools，由支持 MCP 的 Copilot 客户端调用。
• 在自己的 .NET 应用内运行 Agent：可以评估 GitHub Copilot SDK。.NET SDK 用于以编程方式控制 Copilot CLI 运行时，官方仓库提供了安装说明和示例。GitHub Copilot SDK .NET 文档
• 给现有 Copilot Agent 增加任务指导：可以使用 Agent Skills。技能通过 SKILL.md 组织说明及相关资源，具体支持范围应以目标客户端为准。GitHub Agent Skills 文档

如果找到基于 GitHub App 的旧版 Copilot Extensions 教程，需要先检查适用性。该扩展机制已于 2025 年 11 月 10 日停用，但并非所有 VS Code 客户端扩展都已停用。GitHub 停用公告

如何组织 .NET 后端和技能

可以从以下目录结构起步。规模较小时，在同一项目内分目录即可：

src/
  AgentHost/          # HTTP、CLI 或后台任务入口
  Application/        # 用例与工作流
  Domain/             # 业务规则、输入输出类型
  Infrastructure/     # Copilot、仓库访问、状态存储适配器
tests/
  UnitTests/
  IntegrationTests/
  EvaluationTests/

依赖应通过应用层接口传递，避免让业务规则直接依赖 Copilot SDK 的会话对象。更换接入方式、升级 SDK 或替换测试实现时，影响就能集中在适配层。

技能说明、可执行工具和工作流各有不同职责：

• 技能说明描述任务何时适用、需要哪些输入、遵循哪些规范，以及输出格式。
• 工具执行具体操作，例如读取文件、提取项目依赖或保存文档，并在代码中校验参数与权限。
• 工作流决定步骤顺序、失败处理和完成条件。

对于“分析系统并生成设计文档”，可以先采用固定流程：

读取项目规范
  → 收集相关代码与依赖
  → 生成带来源引用的分析结果
  → 根据分析结果生成设计文档
  → 校验必需章节和引用路径

每一步都应有明确的输入、输出和失败状态。程序集引用、项目依赖和文件路径需要精确提取，优先交给确定性代码处理，再让模型解释结果。

SKILL.md 可以指导 Agent 执行任务，但需要严格保证的顺序、权限和持久化动作，应由应用代码控制。如果后续需要多 Agent 协作或跨提供方编排，再评估 Microsoft Agent Framework；GitHub 已提供 Copilot SDK 与该框架的集成说明。官方集成文档

如何管理上下文和任务状态

SDK 与自定义中间件可以同时使用。SDK 负责其支持的会话和通信机制，应用层负责选择业务上下文、隔离用户数据和保存任务进度。

建议按以下顺序组织上下文：

1. 固定约束：适用于当前任务的开发规范、输出格式和工具使用边界。
2. 任务资料：相关目录、文件片段、依赖信息和已有设计说明。
3. 历史摘要：已确认的结论、尚未解决的问题，以及前序步骤产物的位置。

为文件片段保留路径、行号和仓库 revision，方便后续核对来源。规范较长时，先加载与任务相关的部分；代码库较大时，先用路径、符号或依赖关系缩小范围，检索需求明确后再考虑向量检索。

上下文预算还要为工具返回值和最终输出留出空间。输入超出预算时，应明确执行筛选、摘要或分步处理，避免静默截断。

任务状态建议由应用单独保存，例如：

RunId
RepositoryRevision
CurrentStep
CompletedSteps
ArtifactReferences
FailureStatus

会话历史可以帮助模型保持对话连贯，但不宜成为业务进度的唯一记录。重试生成文档时，应能够判断哪些步骤已经完成，避免重复写入。

仓库文件中的文字应按其来源和权限处理。被读取的 Markdown 或代码注释不能自行获得修改系统规则、扩大文件访问范围或调用高权限工具的能力。

如何模拟交互，避免每次在 IDE 中手动测试

先定义应用自己的 Agent 接口，再让真实 Copilot 适配器实现它。测试时注入替身，就能在不启动 IDE、不访问真实服务的情况下验证工作流。

下面使用支持 record 的 C# 语法。接口和类型均为应用自定义，不是 Copilot SDK API：

using System;
using System.Threading;
using System.Threading.Tasks;

public sealed record AnalysisRequest(
    string RepositoryRevision,
    string Guidelines,
    string SourceContext);

public sealed record AnalysisResult(string Markdown);

public interface IAnalysisAgent
{
    Task<AnalysisResult> AnalyzeAsync(
        AnalysisRequest request,
        CancellationToken cancellationToken);
}

public sealed class StubAnalysisAgent : IAnalysisAgent
{
    public AnalysisRequest LastRequest { get; private set; }
    public Exception Failure { get; set; }

    public Task<AnalysisResult> AnalyzeAsync(
        AnalysisRequest request,
        CancellationToken cancellationToken)
    {
        cancellationToken.ThrowIfCancellationRequested();
        LastRequest = request;

        if (Failure != null)
        {
            return Task.FromException<AnalysisResult>(Failure);
        }

        return Task.FromResult(new AnalysisResult(
            "## 系统分析\n\n这是用于测试工作流的固定结果。"));
    }
}

通过依赖注入将 IAnalysisAgent 替换为这个测试实现，可以检查工作流是否传递了正确的仓库版本和规范、是否保存了产物，以及发生异常后是否正确标记任务状态。

真实 SDK 的事件、工具调用和会话生命周期，应在适配器测试中单独覆盖。上述固定结果只能验证应用逻辑，不能证明真实模型会选对工具或理解技能。

测试应覆盖哪些内容

建议把验证分成三层：

行为评估应保存固定的输入资料和验收标准。例如：

• 生成文档必须包含指定章节，并能引用实际存在的文件。
• 缺少关键资料时，应指出信息不足，不能补造系统组件。
• 工具返回超时或权限错误时，应保留失败状态，不能报告任务成功。
• 重试任务时，不应重复创建同一份产物。
• 仓库资料中出现越权指令时，工具权限边界仍然有效。

对于模型输出，适合检查结构、来源和任务约束，通常不适合逐字比较整篇 Markdown。结构检查通过只说明格式符合要求，内容中的依赖关系、路径和技术结论仍需与仓库事实核对。

工具与参考项目如何选择

可以先使用适合入口的 .NET Host，通过 GitHub Copilot SDK 或 MCP 适配器连接 Agent，把状态和产物存放在应用可管理的位置，再用现有 .NET 测试框架运行单元测试与集成测试。

参考代码可以先看 GitHub Copilot SDK 官方仓库，重点检查 .NET 示例中的客户端生命周期、会话和工具调用方式。多 Agent 编排需求明确后，再参考 Microsoft Agent Framework 的集成文档。

落地时先打通“读取少量项目资料 → 生成分析 → 校验并保存结果”这一流程，再增加检索、恢复执行和复杂编排。这样更容易判断故障来自资料选择、工具执行、模型行为还是状态管理。

备注：内容仅供参考。