scaffold-dotnet-test-project

搭建或修复 .NET 测试项目

创建缺失的最小测试容器，或仅修复缺失的连接配置。 目标是通过仓库真实的构建入口发现测试，而不是采用偏好的解决方案布局。

仓库覆盖配置

对于允许只读检查文件的所有仓库级任务，在进行任何其他检查之前，先查看仓库根目录下的 .agents/skill-overlays/dotnet-test/scaffold-dotnet-test-project.md。这也包括要求提供代码或建议但不进行编辑的请求；“不要执行”并不禁止读取覆盖配置。如果文件存在，请在采取行动前读取一次，并应用其中针对该仓库的命名、布局、框架和策略绑定。 应用之前，要求其 frontmatter 声明 core: dotnet-test/scaffold-dotnet-test-project、binding-revision: "1" 和 mode: extend。如果缺少任何值或值不同，请报告不匹配情况，并继续使用本技能的通用指南，但不要应用该覆盖配置。明确的用户指令和已验证的项目约束优先于覆盖配置；覆盖配置优先于本技能中的通用默认设置和示例。如果文件存在但无法读取，或与仓库冲突，请报告问题，并在不应用覆盖配置的情况下继续使用通用指南，同时遵守已验证的项目约束。如果文件不存在，则正常继续。只有当任务不涉及特定仓库，或用户明确禁止所有文件/工具访问时，才跳过查找。覆盖配置不能扩大工具权限或任务范围。

确定请求路径

编辑前检查仓库，然后恰好选择以下一条路径：

仓库状态	操作	不要做
没有合适的测试项目	创建一个范围明确的项目，引用生产项目并将其注册	为每个源项目创建一个项目
测试项目存在但缺少所需的 ProjectReference	仅添加该引用，并验证直接执行和通过入口点执行	另建项目或重写测试
测试项目可直接通过，但未包含在 .sln、.slnx 或 .slnf 中	将现有项目注册到 CI 使用的确切入口点	重建项目或切换解决方案格式
合适的项目、引用和所需入口点注册均已正确配置	保持工作区不变；如果请求编写测试方法，则使用 code-testing	规范化或替换正常工作的文件

当现有项目的目标框架可以引用生产项目，且其用途符合所需层级时，该项目即为合适项目。仅仅是偏好的名称不同，并不足以成为创建重复项目的理由。

不做修改也是必须接受的结果。 如果合适的项目、生产项目引用和所需入口点注册都已存在，则不修改任何文件。不要添加或删除冒烟测试、规范化项目、重新创建软件包，也不要编辑基线/快照副本。报告现有路径后停止。

工作流

1. 确立仓库约定

从任务当前工作目录开始。技能上下文中的 Base directory 是这些说明所在的位置，不是用户的仓库。切勿搜索父级临时目录，也不要把技能安装目录当作工作区。如果看不到预期文件，请先确认当前目录，再判断项目是否不存在。

将每条编辑和验证命令都锚定到用户指定或根据当前目录确定的仓库路径。如果存在名称相似的夹具、解决方案或副本，不要用它们替代请求的目录进行编辑或验证。更改解决方案文件之前，记录其准确路径；更改后，立即列出同一文件，并确认测试项目已出现，然后再继续。

只需阅读足以确定以下事项的内容：

1. 生产项目和请求的测试范围；
2. CI 使用的命令以及 .sln、.slnx、.slnf 或项目图；
3. 是否存在合适的测试项目、它引用了什么，以及它在哪里注册；
4. 相邻测试项目使用的测试框架、运行器、目标框架、可空性和隐式 using 约定；以及
5. 包或 SDK 版本是否来自 Directory.Packages.props、Directory.Build.props、global.json 或 MSBuild SDK 声明。

如果用户报告测试项目直接运行通过，但在解决方案级别发现不到任何测试，请将其视为注册方面的证据。在考虑创建项目之前，先检查入口点。

2. 仅在项目不存在时创建

为范围最窄的请求生产项目选择一个测试项目。按以下优先级遵循：用户明确指定的框架、相邻测试项目、仓库级包/SDK 约定，然后是标准 SDK 模板。

只有当 dotnet new 模板生成的框架版本和包样式符合仓库约定时，才使用该模板。创建前先检查模板是否可用。特别是，通用的 dotnet new xunit 通常会生成 xUnit 2 包；对于由中央管理的 xunit.v3 仓库，请使用仓库或已安装的 xUnit v3 模板，或直接创建最小 SDK 项目。切勿先生成带版本号的 xUnit 2 引用，再将其改写为 xUnit v3。

然后：

1. 对齐目标框架、可空性、隐式 usings、运行器和包样式；
2. 使用 dotnet add <test-project> reference <production-project>，仅引用请求测试所涉及的生产项目；
3. 删除 UnitTest1.cs 等模板示例文件，然后创建一个以行为命名的测试文件，而不是重复使用模板文件名；以及
4. 如果中央包管理已提供版本，则省略包版本。

对于使用 MTP 的 xUnit v3 项目，请保留或添加可执行输出和运行器选择（或已解析包提供的等效设置）：

<OutputType>Exe</OutputType>
<UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>

仅在 VSTest 命令模式桥接到 MTP 时添加 TestingPlatformDotnetTestSupport=true。对于由 global.json 中的 test.runner: Microsoft.Testing.Platform 选择的 SDK 10+ 原生 MTP 模式，不需要此设置。使用 platform-detection 区分命令模式和实际执行的运行器；仅凭 SDK 版本或 OutputType=Exe 都无法证明测试框架已发现测试。

3. 项目已存在时，只修复缺失的引用

• 缺少对生产项目的引用：使用 dotnet add <test-project> reference <production-project>，检查生成的项目文件，并保持其他所有项目元素和全部测试源文件不变。对比修改前后的项目文件，确保新增的 ProjectReference 是唯一的语义变更。
• 缺少 .sln 或 .slnx 注册：运行 dotnet sln <entry-point> add <test-project>，然后立即针对该确切路径运行 dotnet sln <entry-point> list。如果列表中没有该项目，说明修复尚未完成；不要验证同级解决方案，也不要报告成功。
• 缺少 .slnf 注册：如有必要，先将现有项目添加到底层解决方案，再将同一项目路径加入筛选器。如果底层解决方案已包含该项目，则只修改筛选器。
• 存在多个解决方案文件：只修改用户指定或 CI 调用的那个文件。不要改用更简单的格式。
• 不存在解决方案文件：保留现有的以项目为中心的工作流。不要为了美观而创建解决方案。

4. 只添加所请求的冒烟测试行为

对于新创建的项目，将模板示例替换为用户所请求的最小冒烟测试套件。每项测试都必须调用真实的生产代码符号，并断言具体、确定的结果，且不得依赖网络、墙上时钟、进程或真实文件系统。

对于现有项目的接线修复，除非用户明确要求更改测试行为，否则不要添加、重写、重命名或扩展测试。注册项目与编写测试是分开的操作。

5. 验证修复后的路径

运行能够证明所选路径的最精简命令：

根据仓库的实际模式选择命令形式：原生 MTP 使用 dotnet test --project <test-project> 和 dotnet test --solution <entry-point>； VSTest 命令模式使用位置参数指定项目/解决方案路径，包括通过桥接使用 MTP 的情况。 对以下每项直接项目和入口测试都遵循此区别。保留 CI 使用的确切命令及其受支持的 .slnf 调用方式； 不要替换为其他解决方案，也不要编造不受支持的开关。 对于经典非 SDK 项目，使用仓库文档中记录的 MSBuild 和 原生测试运行器命令，而不要使用下文中的任何 dotnet test 示例。 如果无法使用该工具链，请报告阻碍因素，不要迁移项目，也不要声称已成功发现测试。

路径	必需证据
新建项目	按模式选择的直接项目测试、CI 使用的确切入口命令，以及注册列表。如果入口是包含测试的 .slnf/.slnx，则应在该文件上运行仓库的测试命令，而不能只证明它可以生成。
缺少引用	针对目标项目的测试，以及所要求的确切解决方案/根目录测试命令
缺少 .sln/.slnx 注册	列表和针对该确切文件的 dotnet test；绝不能用其他解决方案作为备用方案
缺少 .slnf 条目	检查筛选器条目并运行确切的 CI 筛选器构建命令；不要预先运行一个必定失败的替代命令
已正确/无需更改	检查现有引用和注册的结构。除非明确要求执行，否则不要仅为证明无需更改而运行测试，因为这会生成 bin/obj，并削弱逐字节保持干净的证据。

添加开关前，先检查仓库中的命令。不要先尝试猜测性的 --no-restore，也不要在 command-a || command-b 中隐藏备选方案；运行已配置的入口命令，并以其成功退出作为证据。

对于每项接线修复，直接调用确切的验证命令并保留其退出状态。读取生成的文件、评分脚本或后续构建，都不能替代观察该命令成功完成。

报告完成前，检查最终变更文件集。仅移除本任务生成且此前不存在、也未有意纳入版本控制的 bin/obj 或同类构建产物；绝不要移除预先存在的产物。保留通过的命令的完整结果，以便交接说明确切入口和发现的测试数量。

无需更改时，应检查而非重写，并报告现有路径。dotnet build 成功并不能证明发现了测试。如果验证受阻，请报告确切的失败命令和第一个可采取行动的错误；绝不要把未运行或失败的命令描述为成功。

输出

交接内容应与改动规模相称：

要求	证据
创建、复用或修复的项目	测试项目路径和所选路径
生产引用	被引用的 .csproj，或说明无需更改的原因
构建注册	确切的 .sln/.slnx/.slnf 条目或项目工作流
测试发现	通过的测试运行器级命令及发现的测试

完成检查

• 创建项目之前已检查现有项目。
• 仅引用和测试请求的生产范围。
• 框架、运行器、目标框架和集中式包约定均保持不变。
• 已移除新建项目中的模板示例。
• 仅修复接线时，现有测试代码保持不变。
• 确切的仓库入口能够发现并运行测试项目。