MetricsReporter

通过一个 Prompt，将 C# 代码的混乱转化为 耦合度 < 5 和 复杂度 < 15。可度量。

**MetricsReporter** 是一个 .NET 8 CLI 工具，它将来自**三个独立来源**的代码覆盖率、复杂度、耦合度和分析器违规聚合成一个交互式仪表板 —— 然后让你（或你的 AI agent）通过结构化的重构循环修复所有问题。

_{▶ Watch interactive dashboard demo (GIF)}

## 问题所在 你的 C# 项目技术债务日益增加。你*感觉*代码正在变糟，但是： - **覆盖率数据**存在于 OpenCover XML 中，Roslyn 指标在另一个单独的 XML 中，SARIF 违规又在另一个文件中 - **没有单一的仪表板**能同时显示耦合度、复杂度、覆盖率和分析器违规 - **你无法衡量**某次重构是否真的有效 - **AI agent 不知道**该先修复哪个方法，也不知道修复是否成功 ## 解决方案 ``` One command. Three sources. One dashboard. Measurable improvement. ``` MetricsReporter 将 **OpenCover**（覆盖率）、**Roslyn**（复杂度和耦合度）以及 **SARIF**（分析器违规）合并为一个统一的报告。然后，它为你的 AI 编程 agent 提供一个 CLI 来查询、重构、验证 —— 循环往复 —— 直到所有指标都达标。 ## 核心功能 ### AI 驱动的重构 将一个命名空间和一个指标交给你的 AI agent。它会读取违规信息，研究代码，重构，重新构建，验证 —— 全部通过 CLI 完成。无需人工干预。 ``` # AI agent 询问：“哪里出错了？” metricsreporter read --namespace MyApp.Services --metric Coupling --symbol-kind Any # AI agent 修复代码，重新构建，然后验证： metricsreporter test --symbol MyApp.Services.OrderProcessor --metric Coupling # → { "isOk": true } ✅ ```

_{Built-in refactoring prompts for complexity, coupling, and coverage — ready for Copilot, Cursor, or any AI agent}

### 交互式 HTML 仪表板 从 Solution（解决方案）深入到 Assembly（程序集）到 Namespace（命名空间）再到 Type（类型）直到 Method（方法）。即时过滤，切换警告/错误感知，悬停查看指标详情。无框架依赖 —— 纯 JS，可处理 50k+ 符号。

_{Aggregate statistics at a glance — coverage %, complexity distribution, violation counts}

### 带细分的 SARIF 违规 准确查看每个层级触发了哪些 CA/IDE 规则。悬停查看规则描述、文件路径和行号。

_{Hover any SARIF metric to see rule-by-rule breakdown with source locations}

### ReportGenerator 集成 与 [ReportGenerator](https://github.com/danielpalme/ReportGenerator) 无缝集成，在指标仪表板旁提供交互式的逐行覆盖率可视化。

_{Line-by-line coverage maps powered by ReportGenerator, launched alongside MetricsReporter}

### 抑制（Suppression）系统 并非所有违规都需要修复。使用 `[SuppressMessage]` 标记有意为之的例外 —— 它们会在仪表板中显示原因，而不是作为误报。

_{Suppression attribute in code}

_{Suppression reflected in dashboard with justification tooltip}

### 基线与增量追踪 每次运行都会保存基线。下次运行自动计算增量。你可以看到复杂度是上升还是下降，覆盖率是否提高，是否出现了新的违规 —— 具体到每个方法。 ### CI 的阈值关卡 为每个层级的每个指标定义警告/错误阈值。CLI 以代码 `0`（通过）或非零（失败）退出 —— 可直接插入你的流水线。 ``` { "RoslynClassCoupling": { "Type": { "warning": 20, "error": 40 }, "Member": { "warning": 5, "error": 11 } }, "RoslynCyclomaticComplexity": { "Type": { "warning": 15, "error": 100 }, "Member": { "warning": 15, "error": 100 } } } ``` ### 智能协调（Reconciliation） OpenCover 将覆盖率归因于编译器生成的状态机（`d__0`）。Roslyn 缺少命名空间数据。MetricsReporter 处理所有这些问题 —— 迭代器覆盖率被转移回真实方法，命名空间通过推断得出，重复项被检测出来。

_{Iterator state machine coverage automatically attributed to the real method}

快速开始

### 安装 ``` dotnet tool install --global MetricsReporter.Tool ``` ### 生成你的第一份报告 ``` metricsreporter generate ` --opencover coverage.xml ` --roslyn metrics.xml ` --sarif analyzers.sarif ` --output-json report.json ` --output-html report.html ` --thresholds-file thresholds.json ``` ### 或使用配置驱动模式 在你的代码库根目录创建 `.metricsreporter.json`（[配置参考](docs/3-reference/3.1%20-%20configuration-options.md)）： ``` { "metricsDir": "Metrics", "openCover": ["Metrics/OpenCover/coverage.xml"], "roslyn": ["Metrics/Roslyn/SolutionMetrics.g.xml"], "sarif": ["Metrics/Sarif/ca.sarif"], "outputJson": "Metrics/MetricsReport.g.json", "outputHtml": "Metrics/MetricsReport.html", "thresholdsFile": "Metrics/MetricsRules/MetricsReporterThresholds.json" } ``` 然后只需： ``` metricsreporter generate ``` ### 从 CLI 查询指标 ``` # 查找 namespace 中的首个 coupling violation metricsreporter read --namespace MyApp.Services --metric Coupling # 验证特定符号通过阈值 metricsreporter test --symbol MyApp.Services.OrderService.Process --metric Complexity # 列出所有 coverage violation，按类型分组 metricsreporter read --namespace MyApp --metric OpenCoverBranchCoverage --group-by type ```

AI Agent 工作流

MetricsReporter 附带了开箱即用的 AI agent 提示词文件： | Prompt | Agent 执行的操作 | |--------|-------------------| | [`refactor-complex.md`](Metrics/Agent/refactor-complexity.md) | 将圈复杂度降低至阈值以下 | | [`refactor-coupling.md`](Metrics/Agent/refactor-coupling.md) | 通过 DI、接口、DTO 降低类耦合 | | [`refactor-coverage.md`](Metrics/Agent/refactor-coverage.md) | 编写测试直到分支覆盖率达标 | | [`refactor-sarif.md`](Metrics/Agent/refactor-sarif.md) | 修复 CA/IDE 分析器违规 | **循环很简单：** ``` 1. metricsreporter read → find violation 2. Study code → plan refactoring 3. Refactor + build → apply changes 4. metricsreporter test → verify fix 5. Repeat until clean ``` Agent 自主工作 —— 步骤之间无需人工介入。 ## 指标来源 | 来源 | 指标 | |--------|---------| | **OpenCover** | 序列覆盖率, 分支覆盖率, 圈复杂度, NPath 复杂度 | | **Roslyn** | 可维护性指数, 圈复杂度, 类耦合, 继承深度, 代码行数 | | **SARIF** | CA 前缀, IDE 前缀分析器违规及规则级别细分 | ## 文档 完整的 [Diataxis 结构文档](docs/README.md)： - **[教程](docs/1-tutorials/1.0%20-%20README.md)** — 让你的第一个仪表板运行起来 - **[操作指南](docs/2-how-to-guides/2.0%20-%20README.md)** — 配置文件、脚本、发布更新 - **[参考](docs/3-reference/3.0%20-%20README.md)** — CLI 命令、配置模式、报告格式、抑制规则 - **[解释](docs/4-explanation/4.0%20-%20README.md)** — 架构、覆盖率管道、命名空间推断 ## 贡献 ``` git clone https://github.com/baidakovil/metricsreporter.git cd metricsreporter dotnet restore && dotnet build && dotnet test ``` 请参阅 [从源码运行](docs/2-how-to-guides/2.1%20-%20run-from-source.md) 了解开发工作流。 ## 许可证 [MIT](LICENSE)

标签：AI代理, NuGet包, OpenCover, Roslyn, SARIF, 代码复杂度, 代码度量, 代码耦合度, 仪表盘, 单元测试覆盖率, 可视化报告, 开源框架, 技术债务, 持续集成, 文档结构分析, 自动化重构, 错误基检测, 静态代码分析