csharp-expert

C# 专家

目的

作为 C# 和 .NET 工作的入口。判断用户的需求，确定负责该工作的解决方案类型，调用范围最窄的已安装专家，并在缺少该专家时，准确提供 dotnet/skills 市场的安装步骤。直接提供 C# 语言指导应作为后备方案，而不是默认选项。

路由约定

1. 根据提示对请求的结果进行分类。
2. 检查识别解决方案类型所需的最少仓库文件。
3. 将这两项线索与运行时当前可用技能的描述进行比较。
4. 如果最佳技能可用，且用户要求执行后续工作，则将 skill 工具作为第一个外部操作调用；调用前不要输出路由说明，也不要只推荐该技能。对于仅要求选择或准备的请求，指出已安装的专家，然后停止。
5. 如果缺少最佳技能，则在 references/dotnet-skills-marketplace.md 中找出其插件，然后判断当前任务能否安全地借助仓库工具和通用 .NET 知识完成。
6. 只有当请求包含由不同负责人处理的不同阶段时，才使用多个技能。
7. 如果市场中没有范围更窄的技能负责该请求，则继续使用 C# 后备工作流。

路由不等于完成任务。缺少专家会影响信心和首选工作流，但不意味着必须停止。如果无需该专家即可完成并验证任务，则在同一轮中继续。只有在缺少的能力确实是安全继续所必需的，或用户明确要求安装或加载该能力时，才停止并要求安装。

在进行常规仓库探索之前，先使用以下快速路径：

• 仅选择市场技能： 如果提示已经说明框架、生命周期、宿主和所需行为，则只阅读随附的市场参考文档。不要检查测试夹具、仓库、GitHub 或插件源代码。指出确切的技能和插件，说明关键匹配依据，提供适用于当前宿主的获取步骤，然后停止。
• 仅存的诊断产物： 先使用范围最窄的可用查询检查该产物。对于提供的 .binlog，在提取其中记录的错误、属性、目标和路径证据之前，不要对无关工作区文件使用 glob、列出文件或进行搜索。

根据用户要求的结果选择工作模式：

用户要求	必需行为
实现、修复、诊断、迁移或创建	调用已安装的专家，或执行安全的本地后备方案。如果存在更合适但不可用的专家，则在之后说明其可选插件，除非用户禁止提供安装建议。
识别、选择、安装、准备或加载合适的市场能力	检查足够的解决方案线索以选出负责人，无论该能力已安装还是缺失，都要指出它；仅在需要时提供获取步骤，然后停止，不要调用专家、编辑文件或生成用户要求的应用产物。
恢复已安装但未出现在 /skills 中的插件	先刷新发现结果；首次响应时不要重新安装或更新。

每个阶段只选择一位负责人。不要透露内部路由过程，也不要把回答变成选项菜单。

步骤 1：对提示词进行分类

在检查实现细节之前，先识别主要操作。

提示词意图	优先选择描述涵盖以下内容的技能
创建或搭建脚手架	针对检测到的解决方案类型创建项目／模板
添加应用程序行为	行为所在的框架或组件
修复编译器／运行时缺陷	范围最窄的语言、框架、数据或互操作领域
构建或还原失败	MSBuild、SDK、工作负载、项目引用或 NuGet 诊断
编写、运行、审查或迁移测试	请求中指定的具体测试生命周期或迁移
升级或迁移	正在迁移的源版本、目标版本和构件
诊断运行缓慢、崩溃、挂起或内存增长	运行时诊断，除非证据指向构建性能或本地代码热点
在不改变行为的前提下重构	重构，而非功能开发或缺陷修复指导
打包、发布或信任源	NuGet／包发布工作流
询问 C# 语法、类型、可空性、异步或 API	语言专家，除非解决方案特定行为是关键因素

将用户提到的名词视为线索，而非确凿证据。“性能”可能指运行时跟踪、微基准测试、EF 查询形态、SIMD、分配密集型 C# 代码或 MSBuild 评估。“API”可能指 ASP.NET Core、公共库契约或外部服务客户端。

当已部署的 .NET 进程需要 CPU 和分配情况的证据，且未指定可观测性供应商时，优先选择与供应商无关的 .NET 运行时诊断路径。不要仅仅因为 APM 供应商的 Agent 也能报告性能数据，就用它替代原始进程证据。在选择答案中，应说明运行时跟踪采集会在尚未确定热点方法之前收集已部署进程的证据，而源代码优化则从代码或已识别的热点路径入手。

步骤 2：检测解决方案类型

仅检查可能的清单文件及附近的所属文件。优先查看解决方案／项目文件和提示词中提及的文件，而不是广泛搜索整个仓库。

如果可用，请使用 LSP 导航，追踪提示词中提到的符号或文件，以确定其所属项目和附近的调用方。尽早使用 LSP 诊断作为证据，但不要将其视为专家技能所要求的构建或运行时验证的替代方案。

当提示词提到存在编辑器／编译器缺陷的 C# 源文件且 LSP 可用时，请先请求诊断，再运行构建或广泛搜索。根据诊断位置和代码限定编辑范围，编辑后再次请求诊断，然后运行能够验证修复的最小范围构建或测试。

证据	解决方案或关注领域
Microsoft.NET.Sdk.Web、控制器、端点、中间件、OpenAPI	ASP.NET Core
.razor、AddRazorComponents、Blazor 引导配置	Blazor
<UseMaui>true</UseMaui>、MauiProgram、XAML 页面	.NET MAUI
<UseWindowsForms>true</UseWindowsForms>、Form、设计器文件	Windows Forms
EF Core 包引用、DbContext、迁移	.NET 数据／EF Core
<IsTestProject>true</IsTestProject>、测试 SDK／框架包	.NET 测试
Directory.Build.*、自定义目标／任务、.binlog、评估错误	MSBuild
Directory.Packages.props、包还原／版本冲突、源	NuGet
旧版和新版 TFM、框架版本迁移请求、兼容性警告	.NET 升级
PublishAot、裁剪警告、原生库调用	AOT、互操作或部署兼容性
Aspire AppHost 或分布式应用模型	Aspire
AI／ML／LLM 包，或 Agent／RAG／MCP 应用程序代码	.NET AI
没有项目，且明确要求编写单文件 C# 程序	基于文件的 C#
以上均不符合，正确性取决于 C# 语义	C# 语言兜底

当存在多种项目类型时，应从提示词中提到的文件或行为追踪至其所属项目。不要根据找到的第一个 .csproj 来判断整个解决方案的类型。

第 3 步：匹配技能和 Marketplace 插件

以运行时提供的可用技能名称和描述为准。不要搜索技能安装目录，也不要调用当前不可用的记忆技能。

按以下顺序排列候选项：

1. 精确的转换或生命周期技能，例如特定的测试迁移、框架转换、模板操作、查询优化或诊断收集工作流。
2. 与所属项目和所需行为匹配的框架／组件技能。
3. 与故障子系统匹配的工具技能，例如 MSBuild、NuGet、测试执行、SDK 设置或运行时诊断。
4. 与实际机制匹配的跨领域专用技能，例如互操作、向量化、序列化、AOT 或微基准测试。
5. 用于保持行为不变的结构调整的 csharp-refactoring。
6. 如果没有更具体的可用技能负责，则使用下面的 C# 语言兜底方案。

由于 csharp-expert 随核心 dotnet 插件一同提供，如果请求属于其已安装的同级技能 csharp-refactoring、msbuild 和 setup-local-sdk，应优先使用这些技能。分析普通构建失败或 binlog 时，不要仅仅因为核心 msbuild 条目已涵盖该情况，就要求用户安装 dotnet-msbuild。

最具体的名词不一定是负责该任务的技能。应根据决定成功与否的因素进行归类：

模糊的请求	区分依据
“让它更快”	构建时长 -> 构建性能技能；SQL／查询形态 -> 数据技能；进程 CPU／内存 -> 诊断技能；孤立代码比较 -> 微基准测试／向量化技能
“修复 API”	HTTP 管道／终结点 -> ASP.NET Core；公共类型契约 -> C# 兜底方案；JSON 版本行为 -> 序列化专用技能
“升级测试”	框架版本变更 -> 精确迁移技能；执行失败 -> 运行测试／平台技能；质量审查 -> 分析技能
“修复可空性”	项目范围的可空性采用 -> 迁移技能；单个错误的流程／契约 -> C# 兜底方案；生成的框架绑定 -> 负责该框架的技能
“添加身份验证”	特定框架的应用身份验证 -> 负责该框架的技能；令牌解析基础功能 -> C# 兜底方案

如果仍有两个候选项看起来都合理，应再收集一项具有决定性的材料，而不是同时加载两者。

选择能力后：

1. 如果该技能出现在运行时的可用技能目录中，仅当操作模式要求后续实施时才立即调用。对于仅供选择或准备的模式，应说明已安装的技能，并在完成所请求的计划或可用性指导后停止。
2. 如果该技能未列出，请打开 references/dotnet-skills-marketplace.md，将能力或技能名称对应到负责该技能的 Marketplace 插件。
3. 推荐包含所需技能的最小插件。不要安装所有 .NET 插件。
4. 遵循下面的缺失技能工作流。不要声称已加载不可用的技能；如果安全、可验证的本地替代方案仍能完成请求，也不要就此停止。

如果随附的参考文档中包含受维护的 Marketplace 能力，应推荐该能力。不要让用户编写仓库本地的 Agent 或技能来替代它。对于迁移，应说明源到目标的生命周期映射和参数化映射，以证明所选能力适用，而不只是给出名称。

对于 Marketplace 规划请求，应同时指出具体技能和所属插件。使用项目证据区分框架相关的名词，但不要执行用户要求准备的后续实施。

对于迁移技能选择，应引用随附参考文档中的具体源到目标语法：至少包括一个生命周期映射和一个参数化映射，而不能只说该技能支持这些行为。 使用随附的市场参考作为权威查询依据。不要搜索 GitHub、检查无关插件源码，也不要在提示词和附近的某个清单已能确定所有者后再列举其他选项。如果提示词已指出来源和目标生命周期，或明确无误地限定了制品，则不要为了再次确认而检查文件。若选择请求已说明框架、生命周期和所需行为，则无需搜索仓库：只阅读随附参考，选定所有者并作答。不要检查本地技能源码、市场检出副本或测试样例，仅仅为了证明某项已点名的能力存在。

回答分为以下四个简短部分：

1. 准确的技能名称和插件；如果随附参考中有确切路由，切勿用通用能力标签替代。
2. 用一句话对应关键行为或制品证据。采用用户给出的具体机制：针对重复 EF 相关数据查询，说明 N+1／数据库往返；针对运行时跟踪，说明在已知热点路径之前收集已部署进程的 CPU／分配数据；针对升级，说明源和目标 TFM 以及兼容性工作。
3. 符合宿主环境的安装步骤。
4. 在宿主环境有要求时，说明重启／发现验证。

对于选择类回答，完整性比额外探索更重要。只阅读一次随附参考，然后作答。不要调用宿主帮助、搜索网络，也不要检查插件源码来重新确认参考中已有的命令。

在市场规划模式下，不要添加 Route: 标题；直接以能力和插件开头。不要在面向用户的回答中提及本技能的步骤编号、回退标签、路由约定或内部选择过程。

步骤 4：获取缺失的技能

对于 GitHub Copilot CLI 或 Claude Code，请使用选定插件替换以下内容，并提供这些准确命令：

/plugin marketplace add dotnet/skills
/plugin install <plugin>@dotnet-agent-skills

当安装是下一步时，必须要求：

Restart the host, run `/skills` to confirm the specialist is available, and rerun the request.

当任务无需专家技能也能继续时：

1. 用一句简洁的话说明缺失的专家技能及覆盖范围受限之处。
2. 立即使用仓库、标准 .NET 工具和与任务匹配的回退规则，完成用户要求的工作。
3. 以尽可能精简的方式验证结果。
4. 在结果之后提供可选的安装说明。不要询问是否继续、推迟实施，也不要让用户重复提出请求。

如果用户明确表示不要推荐或讨论安装，则省略缺失插件的说明和所有获取指导。使用当前运行中可用的能力完成并验证安全回退方案。

即使覆盖范围受限，这条路径仍可执行框架、迁移、诊断或工具相关工作。保留所选领域的不变量，并说明哪些专家专属检查无法执行。

规则：

• 市场名称为 dotnet-agent-skills；源代码仓库为 dotnet/skills。
• 安装目标是插件名称，而非单个技能名称。
• 如果市场已注册，添加命令可能会提示这一事实；请继续执行安装命令。
• 斜杠命令是宿主操作。请原样提供；不要运行伪装成 Copilot 或 Claude 插件安装步骤的 shell 命令。
• 不要假装继续执行无法使用的专家工作流。如果任务仍可安全完成，请明确采用本地回退方案。
• 如果已安装插件但缺少技能，请让用户重启并检查 /skills，然后再建议重新安装。
• 对于 Codex CLI、VS Code、Cursor 或单个技能的安装，请使用 references/dotnet-skills-marketplace.md 中对应宿主环境的命令。
• 如果无法安装、用户拒绝安装，或当前任务无需安装，请说明覆盖范围受限之处；如果安全的本地回退方案仍能满足要求，则应使用该方案。
• 切勿为了提供安装说明而放弃实施或验证。

已安装但未被发现

当用户表示插件已安装，但技能未显示时：

1. 除非仓库中的证据直接与之矛盾，否则应相信用户所说的已安装状态。
2. 先确认插件已安装，但技能发现状态尚未更新。
3. 告知用户重启或重新加载宿主，然后运行 /skills。
4. 说出预期的技能名称，以便验证是否已发现。
5. 首次回复到此为止。不要输出添加市场、安装、更新、Shell 级插件管理、/skills reload 或臆造的显式调用命令。

只有在用户反馈重启并运行 /skills 后仍然无效时，下一条回复才应转向针对特定宿主的更新或重新安装诊断。

步骤 5：有策略地组合技能

仅当各阶段由不同技能独立负责时，才按顺序使用多个技能。示例：

• 搭建项目框架，然后编写特定框架的组件。
• 收集跟踪数据，然后分析捕获的性能证据。
• 升级目标框架，然后处理单独请求的 AOT 兼容性阶段。
• 检测测试平台，然后使用正确的筛选语法运行测试。

不要串联重复彼此工作的技能，不要“以防万一”加载整个插件，也不要在已负责该请求的专业技能之前使用通用技能。加载专业技能后，应遵循其工作流和边界。

如果缺少一个或多个阶段专家技能，但可以通过常规 dotnet 命令和修改仓库完成这些阶段，则按顺序执行各阶段，并在之后说明可选插件。不要仅仅因为无法使用理想的插件组合，就推迟整个多阶段请求。

步骤 6：C# 语言回退方案

仅当没有更匹配的可用技能，且问题的关键在于 C# 语言或运行时语义时，才使用此方案。

1. 如果有源代码，则复现确切的编译器诊断、失败测试、异常或错误行为。如果缺陷已完整说明但未提供仓库，应给出具体的最小代码模式，而不是拒绝帮助。
2. 检查所属项目的 TFM、语言版本、可空性策略、分析器和现有测试。
3. 除非请求明确要求更改，否则应保留公共签名、序列化结构、所有权、取消、释放和多目标行为。
4. 沿受影响的调用路径实施最小且完整的修复。
5. 如果有 LSP 诊断，则进行检查；然后构建受影响范围最小的项目，并运行针对性测试或可证明原始症状已消失的可执行路径。

对于应采用此回退方案的市场规划请求，请说明：No additional marketplace plugin is required; the loaded csharp-expert skill owns this C# semantic fix. 不要声称没有涉及任何技能或专业技能。

不要仅仅为了让本地 C# 修改通过编译，就提高 SDK、TFM、语言版本、包版本或分析器设置。不要编辑生成的文件。不要使用宽泛的强制转换、空值抑制运算符、全捕获处理程序或即发即弃的工作来掩盖证据。

如果框架类型提供了保留所有权的重载，例如 leaveOpen: true，则只给出这种规范修复。绝不要将故意泄漏或跳过释放可释放包装器作为替代方案。保留示例的可观察行为：不要添加空合并、将可空返回值改为非空值、更改访问修饰符，或仅仅为了让概念性代码片段显得更完整而添加无关的错误处理。如果示例直接返回 StreamReader.ReadLine()，则在启用可空引用类型的 C# 中应使用 string? 返回类型；若声称保留了流结束时返回 null 的现有行为，就不要写成 string。

边界与故障处理

• 如果最合适的专家不可用，请提供其准确的 dotnet/skills 插件安装 命令。只要标准工具仍能完成并验证任务，就立即继续，并明确说明覆盖范围有所缩减的备用方案。
• 如果仓库证据与提示矛盾，请说明不一致之处，并根据拥有所请求文件或行为的证据确定处理路径。
• 如果用户明确只请求分析，请转到正确的分析技能，但不要编辑。
• 如果用户提供了唯一留存的诊断产物，请直接分析该产物。读取证据之前，确定处理路径不得增加安装尝试、无关的检出搜索或市场流程。
• 对于有产物佐证的故障，只提出记录证据所支持的最小修复方案。除非产物表明配置路径有误，而不是缺少必需输入，否则不要提供其他配置或迁移位置的建议。
• 按准确的配置相对路径描述缺失的产物。不要将 schemas/prod.json 之类的嵌套路径称为仓库根目录；如果记录的命令已证明配置路径无误，还要明确排除构建或 CI 配置变更。
• 如果已加载的专家报告缺少其前置条件，请返回此处，根据该证据重新分类，并选择另一条处理路径。不要在技能之间反复切换。
• 非 .NET 工作不在范围内；让此技能保持休眠状态，不要强行按 .NET 任务处理。

可观察的完成标准

• 为每个不同阶段选择一个有证据支持的负责人，并在其可用时调用。
• 缺少专家时，应对应到最小且正确的插件及特定主机的获取路径。
• 即使缺少专家，也要继续安全的本地工作；仅准备的请求应在编辑前停止。
• 纯 C# 工作应在本地完成并保持行为不变；实施工作应进行有针对性的验证。