quality-ci

.NET 质量 CI

适用场景

• 在 CI 中添加或加强 .NET 代码质量门禁
• 为 .NET 仓库选择分析器、覆盖率、变异测试或架构测试工具
• 统一 .editorconfig、dotnet format 和警告策略

价值

• 产出具体的项目变更：代码、文档、配置、测试、CI 或评审材料
• 通过明确的规划、验证和最终检查，减少歧义
• 留下可复用的项目上下文，让后续任务更快、更安全

不适用场景

• 非 .NET 仓库
• 不涉及 .NET 质量栈决策的通用 CI/CD 指导
• 不涉及质量门禁变更的框架专属测试编写

输入

• 最近的 AGENTS.md
• 当前仓库根目录的 .editorconfig 和 MSBuild 属性
• 当前 CI 工作流和包引用
• 正在使用的测试运行器模式：VSTest 或 Microsoft.Testing.Platform

快速开始

1. 阅读最近的 AGENTS.md，确认范围和约束。
2. 持续通过 Ralph Loop 执行此技能的 Workflow，直到结果符合要求。
3. 按照 Required Result Format 返回具体产物和验证证据。

工作流

1. 从仓库原生基线着手：
   • 仓库根目录的 .editorconfig
   • dotnet format --verify-no-changes
   • 明确设置 EnableNETAnalyzers、AnalysisLevel 和警告策略的 SDK 分析器
2. 仅在确实能弥补差距时添加第三方分析器：
   • StyleCopAnalyzers
   • Roslynator
   • Meziantou.Analyzer
   • xUnit、MSTest 或 TUnit 分析器等框架分析器
3. 按用途拆分质量门禁：
   • 格式和样式
   • 正确性和静态分析
   • 覆盖率和报告
   • 架构规则
   • 安全扫描
   • 变异测试
4. 复杂度控制采用组合方案：
   • 设置 CA1502 阈值
   • 在 AGENTS.md 中设定可维护性限制
   • 架构测试
   • 在风险合理时使用覆盖率和变异测试
5. 在 AGENTS.md 和 CI 中明确责任归属：
   • 哪条命令负责格式化
   • 哪条命令负责分析
   • 哪条命令负责测量覆盖率
   • 测试使用哪种运行器模式
6. 任何 .NET 代码变更后，Agent 都必须能够运行仓库的质量检查流程：
   • 格式化
   • 构建
   • 分析
   • 重点测试
   • 更广泛的测试
   • 已配置时生成覆盖率和报告
   • 仅运行仓库实际启用的其他门禁
7. 尽可能通过专用技能处理工具特定的设置：
   • format
   • code-analysis
   • analyzer-config
   • 分析器包技能，例如 stylecop-analyzers、roslynator 和 meziantou-analyzer
   • 混合使用 .NET 和 Node 的仓库中的前端资源质量技能，例如 eslint、stylelint、htmlhint、webhint、biome、sonarjs、metalint 和 chous
   • 覆盖率和报告技能，例如 coverlet 和 reportgenerator
   • 架构和安全技能，例如 netarchtest、archunitnet 和 codeql
8. 避免使用责任归属重叠且相互冲突的工具。如果添加了具有明确风格偏好的格式化工具，请说明它是替代还是补充 dotnet format。

测试输出预算

• 保持原生运行器的进度显示和 ANSI 启用（对于支持的 MTP/TUnit 运行器，使用 --progress on --ansi on）；在本地使用 PTY。不要将进度重绘内容重新输出到模型上下文中。使用检测到的运行器对应的标志，不要在 VSTest 上使用 MTP 开关。
• 显示警告和错误，以及一条最终摘要（数量、耗时、退出代码）。将测试自身的控制台日志记录级别设为 Warning；不要将 Information/Debug/Trace、成功测试输出以及预期的负向测试噪声输出到上下文中。仅降低构建详细程度无法过滤应用程序日志。
• 出现失败、崩溃、启动错误或超时时，显示失败的测试/资源、根异常和相关堆栈帧。去重；每个诊断工具响应最多 80 行 / 8 KiB，以先达到者为准。绝不要自动转储 stdout/stderr、主机日志、浏览器控制台历史记录、DOM/HTML、TRX 或崩溃产物。
• 将必要的诊断信息保存在有大小限制或采用轮替机制的产物中，并提供链接。按确切的失败/关联标识搜索；只读取有界摘录，绝不读取完整日志。在交付给工具前捕获并过滤噪声输出，保留真实退出代码，并说明内容是否已截断。监控实际活动；仅仅没有输出并不能证明进程卡住了。

缺少配置时的引导

如果请求的质量门禁尚未配置，请使用以下启用流程：

1. 检查 .csproj、Directory.Build.*、.editorconfig、工具清单和 CI 工作流文件，检测当前状态。
2. 每个门禁类别（格式化、分析、测试、覆盖率、架构、安全、变异测试）仅选择一个负责命令。
3. 安装所需的最小软件包或工具，并提交纳入版本控制的配置文件。
4. 使用明确的命令，将门禁接入 AGENTS.md 和 CI。
5. 执行首次验证，修复可处理的问题，然后重新运行。
6. 如果是新启用且通过，则返回 status: configured；如果仍有问题但基线已有改善，则返回 status: improved。
7. 仅当该门禁明确不在此代码库的范围内时，才返回 status: not_applicable。

交付内容

• 有文档说明的 .NET 质量基线
• 明确且可复现的 CI 命令
• 符合代码库运行器模式的分析器和覆盖率方案
• 有文档说明、供 Agent 和 CI 执行的变更后质量检查
• 默认选择开源且免费的工具，并明确说明相关注意事项

验证

• 代码库根目录中的 .editorconfig 是各规则严重级别的默认事实来源
• 格式化、分析和覆盖率命令与运行器兼容
• 新增工具应弥补不同的缺口，而非彼此重复
• 复杂度和架构策略应明确规定，而非仅仅暗示
• 配置质量门禁后，.NET 代码变更应通过的不只是测试
• 在将任何许可或托管方面的注意事项设为默认门禁之前，必须记录在案

Ralph Loop

对每项任务都使用 Ralph Loop，包括文档、架构、测试和工具相关工作。

1. 先规划（必须）：
   • 分析当前状态
   • 明确目标结果、约束和风险
   • 编写详细的执行计划
   • 列出最后要运行的验证技能，并注明顺序和原因
2. 执行一个计划步骤，并产出具体变更。
3. 审查结果并记录发现的问题，以及可执行的后续修复措施。
4. 分批进行小幅修复，并重新运行相关检查或审查步骤。
5. 每次迭代后更新计划。
6. 重复上述步骤，直至结果达到可接受标准，或只剩明确的例外情况。
7. 如果缺少依赖项，则引导安装依赖项；或者返回 status: not_applicable，并说明具体原因和备用方案。

必需的结果格式

• status：complete | clean | improved | configured | not_applicable | blocked
• plan：简洁的计划和当前迭代步骤
• actions_taken：已进行的具体更改
• validation_skills：最终运行的技能，或说明跳过及原因
• verification：命令、检查或审查证据摘要
• remaining：尚未解决的主要事项，或 none

对于未执行操作的纯设置请求，返回 status: configured 和准确的后续命令。

加载参考资料

• references/editorconfig-and-ci.md
• references/quality-toolchain.md
• references/workflows.md
• references/checklist.md

示例请求

• “为这个 .NET 仓库定义最佳 OSS CI 技术栈。”
• “为我们的 .NET 解决方案添加分析器、覆盖率和变异测试指南。”
• “让 .editorconfig 与 CI 在我们的 .NET 解决方案中保持一致。”