自定义 GitHub Copilot 现代化

GitHub Copilot现代化是可扩展的。 代理提供多个自定义点来编码团队的升级模式，在升级期间强制实施编码标准，并定义新的升级工作流。

自定义点概述

通过聊天进行自定义

通过自然对话实时自定义代理的行为。 代理会立即应用您的指令，或者将其保存到scenario-instructions.md以供将来参考。

编辑应用场景工件

代理运行升级时，会在其中 .github/upgrades/{scenarioId}/创建一个工作区。 升级文件夹包含直接控制代理行为的可编辑项目。

scenario-instructions.md

该文件 scenario-instructions.md 是代理用于升级的永久性内存。 代理始终将此文件加载到上下文中，因此在此处编写的任何内容都会直接影响代理做出的每个决策。

添加如下部分来指导代理：

## User Preferences

### Technical Preferences
- Always prefer explicit type declarations over `var`
- Use `ILogger<T>` instead of `ILoggerFactory` for dependency injection
- Target .NET 10 for all projects
- Keep Newtonsoft.Json in the shared library (don't migrate to System.Text.Json)

### Execution Style
- **Pace**: Methodical
- **Pause Points**: After assessment, after each task group

### Custom Instructions

#### 02-common-lib
- Skip the database migration for now — it has external dependencies
- Use the connection string from `appsettings.Production.json` for testing

#### 03-data-layer
- Keep existing repository interfaces during migration
- Preserve all Entity Framework conventions

## Key Decisions Log
- 2025-01-15: Keep Newtonsoft.Json in SharedLib — third-party SDK requires it
- 2025-01-16: Skip database project — DBA team will handle separately

plan.md

该文件 plan.md 定义任务及其范围。 编辑 plan.md 为：

• 重新排序任务以更改执行序列。
• 添加代理未计划的任务。
• 删除不适用的任务。
• 添加注释以提供特定任务的上下文。

单个任务文件

每个任务 tasks/{taskId}/task.md 都包含任务规范和工作说明。 将这些文件编辑为：

• 优化任务的范围。
• 添加程序遗漏的领域特定的上下文。
• 提供所需结果的代码示例。

创建自定义技能

技能是代理的主要扩展点。 技能是具有元数据标头的 Markdown 文件，它教代理如何处理特定的升级、模式或任务。

在何处放置自定义技能

技能文件结构

每个技能文件都有两个部分：元数据标头（代理用于了解技能何时适用）和 Markdown 正文（代理遵循的说明）。

---
name: migrating-foobar-v2-to-v3
description: >
  Migrate our internal FooBar library from v2 to v3. Activates when
  FooBar.v2 NuGet package is detected, or when asked to "upgrade FooBar",
  "migrate FooBar", or "update FooBar library".
metadata:
  discovery: lazy
  traits: .NET | CSharp
---

# Migrating FooBar Library v2 to v3

## Overview

FooBar v3 introduces a new async-first API surface. This skill guides the
agent through replacing synchronous FooBar.v2 calls with their v3 async
equivalents, updating configuration, and verifying behavior.

## Workflow

1. **Identify FooBar.v2 references**
   - Search for `PackageReference` elements referencing `FooBar.v2`
   - Locate all `using FooBar.V2;` directives

2. **Update package references**
   - Replace `FooBar.v2` with `FooBar.v3` in all `.csproj` files
   - Run `dotnet restore` to verify resolution

3. **Migrate API calls**
   - Replace `FooBarClient.Send(...)` with `await FooBarClient.SendAsync(...)`
   - Replace `FooBarConfig.LoadFromFile(...)` with `FooBarConfig.LoadFromJsonAsync(...)`
   - Update method signatures to `async Task` where needed

4. **Update configuration**
   - Rename `foobar.config` to `foobar.json`
   - Migrate XML config entries to JSON format

5. **Verify**
   - Build the project: `dotnet build`
   - Run existing tests: `dotnet test`
   - Verify no remaining references to `FooBar.V2` namespace

## Success Criteria

- [ ] No references to `FooBar.v2` NuGet package remain
- [ ] All `FooBar.V2` namespace usages replaced with `FooBar.V3`
- [ ] Project builds without errors
- [ ] All existing tests pass

## Error Handling

- If `FooBar.v3` is not available in the configured NuGet feeds, instruct
  the user to add the internal feed
- If async migration causes deadlocks in legacy synchronous code paths,
  wrap calls with `.GetAwaiter().GetResult()` and add a TODO comment

元数据字段

技能创作最佳实践

• 具体说明： 包括用户可能键入的确切包名称、库名称和自然语言触发器短语。
• 包括明确的分步工作流： 对步骤进行编号。 明确要更改的文件以及要运行的命令。
• 包括成功条件： 如果没有成功条件，代理不知道何时停止。 使用复选框或清晰的可验证条件列表。
• 包括错误处理： 预测常见的故障模式，例如缺少包、生成失败或测试中断。
• 使技能专注： 每种升级或任务类型仅限一个技能。 “将 FooBar v2 升级到 v3”的技能优于“升级所有内部库”。
• 包含动名词的名称： 使用 upgrading-foobar-v2-to-v3，而不是 foobar-upgrade 或 foobar-v3。
• 使用 lazy 发现：针对大多数自定义技能使用 lazy 发现，以避免智能体的上下文窗口膨胀。

创建自定义方案

对于想要定义全新的升级工作流的高级用户，自定义方案允许你协调完整的多阶段升级管道。 应用场景是一种技能，其中 metadata.discovery: scenario 负责定义智能体遵循的阶段。

---
name: migrating-soap-to-rest-api
description: >
  Migrate legacy WCF/SOAP services to ASP.NET Core REST APIs. Activates
  when WCF service references, .svc files, or SOAP clients are detected,
  or when asked to "migrate SOAP to REST", "replace WCF", or "convert
  web services to REST".
metadata:
  discovery: scenario
  traits: .NET | CSharp
  scenarioTraitsSet: [wcf, soap, web-services]
---

# SOAP to REST API Migration

## Pre-initialization

Gather from the user:
- Which SOAP services to migrate (all or specific ones)
- Whether to maintain backward compatibility with a SOAP facade
- Authentication mechanism for the new REST APIs
- API versioning strategy (URL path, header, query string)

## Assessment

Analyze the solution for:
- `.svc` files and WCF service contracts
- WSDL files and service references
- `System.ServiceModel` usage and binding configurations
- Data contracts and their serialization requirements
- Client proxies consuming SOAP services

## Planning

Create tasks in this order:
1. Create shared DTOs — Convert `[DataContract]` types to POCOs
2. Create REST controllers — One controller per `[ServiceContract]`
3. Map operations to HTTP methods
4. Migrate service implementations
5. Update clients — Replace `ChannelFactory`/generated proxies with `HttpClient`
6. Remove WCF infrastructure
7. Add API documentation — Swagger/OpenAPI via Swashbuckle

## Execution

For each service contract:
1. Create a corresponding controller
2. Create a service interface and implementation
3. Register the service in DI
4. Map WCF operations to REST endpoints
5. Update any in-solution clients to use the new REST endpoints
6. Build and run existing tests

将方案文件放入.github/skills/或.github/upgrades/skills/目录中以便代理发现。

源代码管理和分支

智能体可处理 Git 分支，但你可以完全掌控策略：

• 分支命名： 告知代理要使用的分支名称，或让代理建议一个分支名称。
• 每个任务分支：为每个任务请求单独的分支，以便进行细粒度审核。
• 提交计时： 选择代理提交时间：在完成的每个任务（默认值）之后，仅在完整升级结束时或按需进行。
• 无源代码管理： 代理也适用于非 Git 文件夹，但建议先备份项目。

聊天说明示例：

• “对此升级使用分支名称‘upgrade/dotnet10’”
• “为每个任务创建分支，以便我可以单独查看每个分支”
• “不要提交，除非我明确要求你”
• “使用描述性消息在每个任务后提交”

技能加载优先级

当代理发现多个技能时，它会使用优先级系统解析它们。 高优先级源替代或补充低优先级源：

代理从所有源收集技能。 当技能具有重叠的范围时，优先级较高的源优先。 字段 discovery 控制技能加载时间。 lazy 表示根据需要在相关时提供，而 preload 表示始终可用。

相关内容

• 核心概念
• 场景和技能参考
• 应用自定义升级说明
• 最佳实践