code-analysis

.NET 代码分析

诊断输出限制

保留警告/错误和简洁的结果；避免常规的冗长或诊断性控制台输出。运行测试时保留原生进度信息/ANSI 输出。失败时，仅显示相关诊断和堆栈帧，去重后每次响应最多显示 80 行 / 8 KiB。只有在问题尚未解决时，才将额外诊断信息收集到模型上下文之外、大小受限的文件中；提供链接，并检查精确的有限摘录。切勿转储完整日志/报告，也不要通过过滤隐藏命令的退出代码。

适用情形

• 仓库需要一方 .NET 分析器
• CI 应在分析器发出警告时失败
• 团队需要 AnalysisLevel 或 AnalysisMode 方面的指导
• 仓库需要逐步提升 Roslyn 警告级别的策略

不适用情形

• 单独选择第三方分析器
• 仅涉及格式化的工作

输入

• 最近的 AGENTS.md
• 项目文件或 Directory.Build.props
• 当前的分析器严重性策略

AI Agent 硬性规则

不可妥协。违反这些规则会破坏用户的明确意图。

1. 如果项目已设置 TreatWarningsAsErrors 或 WarningsAsErrors，绝不可禁用或移除它们。不要注释掉、设为 false、用条件包裹，或添加 <TreatWarningsAsErrors>false</TreatWarningsAsErrors> 来让构建通过。
2. 对于用户选择作为错误处理的警告，绝不可添加 <NoWarn> 或 #pragma warning disable，除非用户明确批准抑制。
3. 绝不可在 .editorconfig 中悄悄降低严重性（例如，从 error 降为 warning 或 none）来让构建成功。
4. 如果将警告视为错误导致构建失败，就修复代码。如果修复范围太大，应询问用户是否要暂缓处理该警告 ID。
5. 如果警告数量太多，无法一次修复完，应向用户报告数量和类别，并询问要优先处理哪些。不要擅自禁用该策略。

工作流

flowchart TD
    A[Start] --> B{New or legacy project?}
    B -->|New| C[TreatWarningsAsErrors=true immediately]
    B -->|Legacy| D[dotnet build, count warnings by ID]
    D --> E{"< 30 warnings?"}
    E -->|Yes| F[Fix all, then enable TreatWarningsAsErrors]
    E -->|No| G[Report counts to user, ask which batch first]
    G --> H[Add selected IDs to WarningsAsErrors]
    H --> I[Fix that batch, verify build]
    I --> J{More batches?}
    J -->|Yes| G
    J -->|No| F
    C --> K[Set AnalysisLevel latest-recommended]
    F --> K
    K --> L[Promote security CA3xxx/CA5xxx to error in .editorconfig]
    L --> M[Validate: build + CI green]

1. 从 SDK 分析器开始，再考虑第三方包。
2. 判断项目成熟度：新项目或现有/遗留项目。
3. 在 Directory.Build.props 中启用 EnableNETAnalyzers、AnalysisLevel 和 AnalysisMode。
4. 应用合适的警告级别提升策略（见下文）。
5. 在仓库根目录的 .editorconfig 中设置各规则的严重性。
6. 在 CI 中通过 dotnet build 作为分析器门禁。

警告级别提升策略

新项目

立即在 Directory.Build.props 中设置以下属性：

• TreatWarningsAsErrors = true
• AnalysisLevel = latest-recommended
• 在 .editorconfig 中将 Security 类别设为 error

合并前修复所有警告。

遗留项目——逐步提升

对遗留代码库一概设置 TreatWarningsAsErrors 会产生数百乃至数千个错误。Agent 无法一次性全部修复——上下文会被大量内容淹没，修复质量也会下降。应分批提升。

阶段 1：基础清理（从这里开始）

机械性修复，成本最低：

• CS8019 — 不必要的 using 指令（删除）
• CS0219 — 变量已赋值但从未使用（删除）
• CS0168 — 已声明但从未使用的变量（删除）
• CS1591 — 公共成员缺少 XML 注释（添加注释，或对内部代码禁用该规则）
• CS0612 — 使用了已弃用的成员，且未提供消息（替换为未弃用的 API）
• CS0618 — 使用了已弃用的成员，且提供了消息（遵循迁移指南）

将以下内容添加到 WarningsAsErrors：CS8019;CS0219;CS0168。全部修复后，进入阶段 2。

阶段 2：代码质量（询问用户选择哪些类别）

• CA2000 — 在对象超出作用域前将其释放（可靠性）
• CA1062 — 验证公共方法参数（设计）
• CA1822 — 将成员标记为 static（性能）
• CA1860 — 长度检查时避免使用 Enumerable.Any()（性能）
• CA1861 — 避免将常量数组用作参数（性能）
• CA2007 — 考虑调用 ConfigureAwait（可靠性）
• CS8600–CS8610 — 可空引用类型警告（可空性）

询问：“接下来处理哪些类别——可空性、性能还是可靠性？”将选定的 ID 添加到 WarningsAsErrors，修复后重复此过程。

阶段 3：安全性（始终尽早提升级别）

无论项目成熟度如何，都在 .editorconfig 中设置：

[*.cs]
dotnet_analyzer_diagnostic.category-Security.severity = error

涵盖 CA3001（SQL 注入）、CA3002（XSS）、CA3003（路径注入）、CA3075（不安全的 DTD）、CA5350/CA5351（弱加密）、CA5394（不安全的随机数）。

阶段 4：全面覆盖

所有批次通过后，切换为：

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<WarningsNotAsErrors>CA1707</WarningsNotAsErrors> 

交互协议（旧版代码库）

1. 运行 dotnet build，按 ID 统计警告数量。
2. 报告摘要：“发现 47 个 CS8019、23 个 CA1822、12 个 CA2000、8 个 CS8600。”
3. 询问要处理哪个批次。建议从阶段 1 开始。
4. 修复选定批次，并验证构建。
5. 将这些 ID 添加到 WarningsAsErrors。
6. 汇报结果，并询问下一个批次。

绝不跳过询问步骤。由用户决定进度。

缺少配置时的引导

1. 检测当前状态：
   • dotnet --info
   • rg -n "EnableNETAnalyzers|AnalysisLevel|AnalysisMode|TreatWarningsAsErrors|WarningsAsErrors" -g '*.csproj' -g 'Directory.Build.*' .
   • dotnet build SOLUTION_OR_PROJECT 2>&1 — 按 ID 统计警告数量
2. 分类：新项目（警告很少或没有）与旧项目（警告很多）。
3. 在 MSBuild 配置中启用 EnableNETAnalyzers、AnalysisLevel、AnalysisMode。
4. 根据项目成熟度采用相应的提升策略。
5. 在仓库根目录的 .editorconfig 中设置各规则的严重性。
6. 运行 dotnet build，返回 status: configured 或 status: improved。
7. 如果仓库将分析器策略交由其他构建层管理，则返回 status: not_applicable。

交付内容

• 明确且可审查的第一方分析器策略
• 在 CI 中执行构建时分析器
• 与项目成熟度相匹配的警告提升计划

验证

• 分析器行为由仓库配置驱动，而非 IDE 默认设置
• CI 与本地复现相同的警告和错误
• 未经用户批准，不移除或降低 TreatWarningsAsErrors、WarningsAsErrors 或严重性设置
• 提升后的警告会导致构建错误，而不只是 IDE 提示

Ralph 循环

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

加载参考资料

• references/rules.md
• references/config.md
• references/code-analysis.md

请求示例

• “启用内置 .NET 分析器。”
• “让分析器警告导致构建失败。”
• “为此仓库设置合适的 AnalysisLevel。”
• “开始将未使用的 using 指令和未使用的变量视为错误。”
• “帮助我逐步提升旧项目中的 Roslyn 警告级别。”
• “接下来应该将哪些警告提升为错误？”