sonar-quality-gate

SonarQube — 质量门禁

仅报告 SonarQube 项目的质量门禁评估：总体状态、API 返回的每项条件，以及未通过条件的最差问题明细。不要在这里获取宽泛的度量指标仪表板——对于门禁以外的数值指标（覆盖率%、问题数量、作为度量指标的评级等），之后请使用 mcp__sonarqube__get_component_measures，并指定你关注的 metricKeys。

用法

sonar-quality-gate                       # quality gate for the current project
sonar-quality-gate my-project            # quality gate for a specific project key
sonar-quality-gate my-project --branch release/2.0
sonar-quality-gate my-project --pr 42

前置条件

此技能主要使用 sonarqube-cli 命令 sonar quality-gate status（别名 sonar qg status）——不要虚构其他命令（例如，并不存在 sonar mcp call）。优先使用它，而不是 MCP 工具：CLI 可在同一次调用中返回每项未通过条件的最差问题明细——参见步骤 5——而 MCP 工具需要另外调用（度量指标、问题）才能获取这些详细信息。

继续操作前，请确认 sonar 已加入 PATH 且已通过身份验证。如果未安装或未通过身份验证，MCP 回退方案也无济于事——SonarQube MCP Server 本身通过 sonar run mcp 启动，并共用 CLI 存储的凭据（通过 sonar-integrate 技能完成设置时始终如此；若 sonarqube MCP Server 是独立配置的，例如通过带有独立令牌的单独 Docker 容器配置，则不适用）——因此请直接跳到下方的消息并推荐 sonar-integrate 技能。只有在 sonar 可用，但 quality-gate status 本身不可用时（例如，较旧的 CLI 不认识此子命令，或命令因其他原因报错），才在步骤 3 中回退到 MCP 工具 mcp__sonarqube__get_project_quality_gate_status。

如果 MCP 回退方案也失败（例如，工具不可用，或无法解析项目密钥），请查明具体原因——检查此 Agent 的配置中是否启用了 sonarqube MCP Server。

• 未启用／未注册 → 推荐运行 sonar-integrate 技能。
• 已启用，但其工具仍不可用 → 配置正确，但 Server 启动失败。最常见的原因是容器运行时未运行——MCP Server 通过 sonar run mcp 在 Docker／Podman／Nerdctl 中启动，因此即使配置正确，守护进程停止时也不会提供任何工具。请自行运行 docker ps（如果失败，再尝试 podman ps／nerdctl ps），确认具体原因：如果命令报错，则运行时已停止；用户启动运行时后，请确认同一命令能够成功执行，再让他们重启 Agent 会话。

无论哪种情况，都向用户显示：

无法运行 sonar quality-gate status、连接 SonarQube MCP Server，或解析项目密钥。

可能的原因：

• 未安装 sonarqube-cli 或未通过身份验证——调用 sonar-integrate 技能
• MCP Server 未注册——调用 sonar-integrate 技能来配置 SonarQube MCP Server，然后重启 Agent 会话
• 容器运行时未运行——SonarQube MCP Server 在容器（Docker、Podman 或 Nerdctl）中运行；启动容器运行时，然后重启 Agent 会话
• 未配置凭据——调用 sonar-integrate 技能
• 项目密钥错误，或 MCP 配置中没有默认项目——传入明确的密钥，或检查 sonar-project.properties／为此项目重新运行 sonar-integrate 技能

然后询问用户是否现在运行 sonar-integrate 技能（是／否）。简要说明其作用：检查用户计算机上的 SonarQube 设置——安装或更新 sonarqube-cli 并验证身份验证——并为此 Agent 重新配置集成，包括 SonarQube MCP Server 和密钥扫描钩子。如果用户确认，请自行调用 sonar-integrate 技能，并在本次会话中完整执行；然后请用户确认容器运行时（Docker、Podman 或 Nerdctl）正在运行，并重启 Agent 会话，以便新 MCP 工具可用；如果用户拒绝，则停止。

说明

步骤 1：解析项目键（仅在需要时）

sonar quality-gate status 不需要 -p——与 sonar list issues 不同（后者必须提供该参数），如果未提供 -p，它会从 sonar-project.properties 中的 sonar.projectKey 解析项目。只有在必须传入项目键时才进行解析（用户指定了其他项目，或在步骤 3 中改用 MCP 工具且其架构要求提供项目键）：

• 如果用户提供了项目键，请使用该键。
• 否则，在仓库根目录的 sonar-project.properties 中查找 sonar.projectKey。
• 如果仍未找到，在命令行中省略 -p，让它自动解析。对于 MCP 回退，省略 projectKey，并使用集成的默认值。

步骤 2：解析用户提供参数中的可选筛选条件

标志	CLI 选项	MCP 参数（回退）
--branch <name>	--branch	branchKey
--pr <id>	--pull-request	pullRequestKey

--branch 和 --pr 不能同时使用——如果用户同时传入两者，请暂停并询问其意图。省略用户未提供的标志/键。如果 MCP 工具使用不同的参数名称，请遵循 SonarQube MCP 服务公开的架构。

步骤 3：运行 sonar quality-gate status

运行命令前，验证即将插入的值——项目键必须匹配 ^[a-zA-Z0-9_\-\.:]+$，--branch 必须匹配 ^[a-zA-Z0-9_\-\./]+$，--pull-request 只能包含数字（规则与 sonar-list-issues 技能相同）。如果任何值不符合要求，请停止，并告知用户哪些值被拒绝，而不要运行命令。

sonar quality-gate status [-p <project-key>] [--branch <name> | --pull-request <id>] --format json

始终使用 --format json 并解析输出——不要将 CLI 默认的 table 输出直接转给用户；应将解析后的结果交由步骤 4 进行格式化。

命令会返回顶层 status（OK、ERROR 或服务器使用的其他值）以及一个 conditions 数组。每个条件通常包含：

字段	含义
metricKey	SonarQube 门禁条件的指标标识符
status	单个条件的结果（OK、ERROR、……）
errorThreshold	门禁定义了界限时所要求的界限值（某些类型可能没有此字段）
actualValue	SonarQube 用于与界限值比较的值

支持此功能的新版 CLI 在同一次调用中还会为每个失败的条件返回 breakdown——参见步骤 5，不要单独获取；如果没有 breakdown，应将其视为“不可用”，而不是错误。

示例（所有条件均为 OK）——响应结构：

{
  "status": "OK",
  "conditions": [
    {
      "metricKey": "reliability_rating",
      "status": "OK",
      "errorThreshold": "2",
      "actualValue": "1"
    },
    {
      "metricKey": "security_rating",
      "status": "OK",
      "errorThreshold": "1",
      "actualValue": "1"
    },
    {
      "metricKey": "new_duplicated_lines_density",
      "status": "OK",
      "errorThreshold": "3",
      "actualValue": "0.0"
    }
  ]
}

示例（门禁未通过）——某些条件缺少 errorThreshold 属于正常情况：

{
  "status": "ERROR",
  "conditions": [
    {
      "metricKey": "new_coverage",
      "status": "ERROR",
      "errorThreshold": "85",
      "actualValue": "82.50562381034781"
    },
    {
      "metricKey": "new_blocker_violations",
      "status": "ERROR",
      "errorThreshold": "0",
      "actualValue": "14"
    },
    {
      "metricKey": "new_sqale_debt_ratio",
      "status": "OK",
      "errorThreshold": "5",
      "actualValue": "0.6562109862671661"
    },
    {
      "metricKey": "reopened_issues",
      "status": "OK",
      "actualValue": "0"
    },
    {
      "metricKey": "open_issues",
      "status": "ERROR",
      "actualValue": "17"
    }
  ]
}

如果 sonar quality-gate status 不可用（较旧 CLI 不识别该子命令，或命令因 CLI 缺失或未通过身份验证以外的原因失败），请改用 mcp__sonarqube__get_project_quality_gate_status。 如果未安装 sonar 或未通过身份验证，请不要尝试使用 MCP 工具——MCP 服务通过 sonar run mcp 运行，并共享 CLI 的凭据，因此它也将不可用——除非 sonarqube MCP 服务是独立配置的（例如，通过带有独立令牌的独立 Docker 容器配置），这种情况下 MCP 工具仍可能可用，因此请尝试使用；在先决条件中显示该消息，并建议改用 sonar-integrate。仅当你在步骤 1 中解析出了 projectKey 且该工具要求提供时，才在请求中包含它；否则省略，使用集成默认值。请求示例：

{
  "projectKey": "<only-if-required>",
  "branchKey": "<name, if --branch was given>",
  "pullRequestKey": "<id, if --pr was given instead>"
}

仅当提供了 --branch 时才包含 branchKey，仅当提供了 --pr 时才包含 pullRequestKey——绝不要同时包含两者（参见步骤 2）。当适用集成默认值时，从请求中省略 projectKey。省略未使用的键。

该工具返回与上述相同的 status/conditions 结构，但不包含 breakdown——参见步骤 5。

步骤 4：整理结果

提供一份简洁的报告：

1. 标题 — 将顶层 status 转换为通俗说法（例如，OK → 通过，ERROR → 失败）。如果已知，请包含项目键和分支/PR 上下文。

2. 条件表 — conditions 中的每个元素占一行，至少包含以下列：

   • 指标 — metricKey（如果知道其名称，可稍作易读化处理；否则保留原键）。
   • 条件状态 — status。
   • 阈值 — 有 errorThreshold 时使用该值；缺失时使用 —。
   • 实际值 — 有 actualValue 时使用该值；缺失时使用 —。

   排序时将失败的条件（ERROR 或按服务端规则判定为非 OK 的条件）放在通过的条件之前。

3. 评级 — 对于 reliability_rating / security_rating 这类键，SonarQube 通常会在 API 中用数字表示等级（例如，1 = A、5 = E）。在有助于用户理解时说明这一点。

4. 不查询额外指标 — 除非用户在同一轮明确要求了解更深入的指标，否则不要在此技能中调用 get_component_measures。需要更多详情时，告知用户下一步该怎么做（见步骤 6）。

5. 明细（仅限 CLI 路径） — 条件包含 breakdown 时（步骤 3 的主要 CLI 路径中，且 CLI 版本足够新），在该条件对应的行下方以简短缩进列表呈现，并使用与其类别相关的字段（各类别的结构见步骤 5）。如果缺少 breakdown，或使用的是 MCP 回退路径，则完全跳过此项。

如果缺少质量门禁负载，或分析尚未运行，请明确说明，不要编造数据。

第 5 步：按类别处理未通过的条件

未通过的质量门通常不会只是一张平铺的列表——应根据每项指标的类型分别处理。在主要 CLI 路径上，这几乎不费吹灰之力：sonar quality-gate status 已会将每项未通过条件中最严重的问题归纳到 breakdown 中。（如果使用的 CLI 版本较旧，尚未提供这项增强功能，则完全不会有 breakdown 字段——应将其视为“不可用”，而不是错误。）在 MCP 回退路径上，工具只会返回 conditions，没有 breakdown——根据指标键按下方说明分类，然后交由对应的技能进一步处理。

未通过的覆盖率条件对应的 breakdown 示例（CLI 路径）：

{
  "metricKey": "new_coverage",
  "status": "ERROR",
  "errorThreshold": "85",
  "actualValue": "82.5",
  "breakdown": [
    { "file": "src/auth/login.py", "coverage": "42.0" },
    { "file": "src/utils/helpers.py", "coverage": "58.3" }
  ]
}

按指标键分组：

• 覆盖率（coverage、new_coverage、branch_coverage、line_coverage 等）——breakdown 会列出覆盖率最低的文件。告诉用户哪些文件最需要补充测试。如需查看特定文件的行级详情，请交由 sonar-coverage 处理。
• 重复代码（duplicated_lines_density、new_duplicated_lines_density、duplicated_blocks 等）——breakdown 会列出重复代码最多的文件，以及各文件的重复代码块数量和重复对象文件。建议提取共享辅助函数。如需查看完整的重复代码块，请交由 sonar-duplication 处理。
• 问题与安全（violations、bugs、code_smells、reliability_rating、sqale_rating/new_maintainability_rating，以及在支持该功能的较新 CLI 版本中提供的 vulnerabilities/security_rating）——breakdown 已列出实际导致未通过的问题（文件、行号、键、规则、消息），通常足以直接采取行动。如需更广泛的筛选（严重程度、状态、其他文件），请交由 sonar-list-issues 处理。
• 依赖风险（以 sca_ 开头的指标键，例如 sca_count_*、sca_rating_*、sca_severity_*）——breakdown 会以平铺列表的形式列出包、版本、严重程度和类型，不包含文件位置：SCA 风险属于项目级别，不与特定文件或行关联。它反映的是服务端已知的未解决风险。如需重新扫描清单文件或查看 CVE 级别的详情，请交由 sonar-dependency-risks 处理。

如果你使用主要 CLI 路径，且只需关注某个类别（例如用户专门询问“为什么覆盖率未通过？”），请重新运行 sonar quality-gate status，并添加 --category <coverage|duplications|issues|dependency-risks>（可选值与上述指标分组相对应；是否支持取决于 CLI 版本）；--top <n> 用于控制每个 breakdown 包含的条目数。不添加 --category 时，就像第 3 步那样，会一次性返回所有类别的 breakdown——只有在用户提出要求时才缩小范围。在 MCP 回退路径上，无法重新运行 CLI 命令：请交由上述对应的技能处理。

第 6 步：深入查看指标（get_component_measures）

如果要查看质量门以外的指标（例如整体覆盖率、行覆盖率、错误计数、详细评级），请在适用时使用相同的分支/PR 上下文调用 mcp__sonarqube__get_component_measures，并通过 metricKeys 传入所需的指标。只有在工具要求提供 projectKey 且你已解析出该值时，才添加 projectKey；否则依赖集成默认值（可以从未通过的 metricKey 值或 SonarQube metric keys 文档着手）。

如果工具不可用，请改用 sonar api（此命令确实要求提供已解析的项目键——与第 3 步中会从 sonar-project.properties 自动解析的 sonar quality-gate status 不同；如果第 1 步未解析出项目键，请询问用户或调用 sonar-list-projects，然后停止）：

sonar api get "/api/measures/component?component=<project-key>&metricKeys=<comma-separated-keys>[&branch=<name>][&pullRequest=<id>]"

如果这一步也失败，请显示上方的标准消息——不要再猜测其他命令。

步骤 7：相关技能

仅在需要获取超出步骤 5 的分析结果所提供的信息时使用：

• sonar-list-issues — 按严重程度、状态筛选问题／安全发现，或查看已显示的排名靠前条目之外的内容。
• sonar-coverage — 查看特定文件逐行覆盖率的详细信息。
• sonar-duplication — 查看特定文件中的完整重复代码块。
• sonar-dependency-risks — 重新扫描依赖风险，或深入了解 CVE 详情。