sonar-analyze

SonarQube — 代码分析

使用 SonarQube MCP Server 分析代码质量和安全问题。

用法

sonar-analyze                        # analyze the file currently in context
sonar-analyze src/auth/login.py      # analyze a specific file

前提条件

此技能要求配置 SonarQube MCP Server，并且当前会话至少可用以下工具之一：mcp__sonarqube__run_advanced_code_analysis 或 mcp__sonarqube__analyze_file_list。

继续之前，请确认至少可以访问其中一个工具。如果都不可用，请先尝试第 3 步中的 CLI 回退方案，再考虑放弃——不要臆造其他 CLI 命令（例如，不存在 sonar mcp call）。

如果 CLI 回退方案也失败或不适用，请进一步排查原因——检查此 Agent 的配置中是否启用了 sonarqube MCP 服务。

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

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

无法连接 SonarQube MCP Server。

可能的原因：

• MCP 服务未注册 — 调用 sonar-integrate 技能以配置 SonarQube MCP Server，然后重启 Agent 会话
• 容器运行时未运行 — SonarQube MCP Server 在容器（Docker、Podman 或 Nerdctl）中运行；请启动容器运行时，然后重启 Agent 会话
• 未配置凭据 — 调用 sonar-integrate 技能
• 项目密钥缺失或无效 — 如有需要，请传入显式密钥，检查 sonar-project.properties，或为此项目重新运行 sonar-integrate 技能

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

说明

第 1 步：确定要分析的内容

两个分析工具都一次处理一个文件。确定单个文件路径：

• 如果用户提供了文件路径，则使用该路径。
• 如果未提供路径，请查看当前对话上下文中最近提到或编辑的文件。
• 如果无法确定，请询问：“你想让我分析哪个文件？”

不要接受目录作为输入。如果用户提供了目录，请让他们指定单个文件。

第 2 步：读取文件并确定其范围

1. 读取文件的完整内容——仅当 run_advanced_code_analysis 的 fileContent 参数需要回退方案时才需要（见第 3 步）。
2. 确定文件范围："TEST" 或 "MAIN"。根据文件路径推断范围。例如，如果文件路径包含 test、spec 或 __tests__，则其范围很可能是 "TEST"。

步骤 3：调用适当的分析工具

运行 sonar-integrate 技能后，SonarQube MCP Server 通常会为此工作区设置一个默认项目，因此有时不需要 projectKey——只有当工具架构要求提供该参数，或用户指定了其他项目时才传入。

根据连接的组织是否符合 Vortex 分析的资格，可能会提供以下两种工具：

先尝试 mcp__sonarqube__run_advanced_code_analysis（组织符合 Vortex 分析资格时可用）。

调用前，使用 git branch --show-current 检测当前分支名称。如果 git 不可用，则使用 main 作为备用值。

然后调用时传入：

• projectKey — 除非工具要求，否则省略（初始 MCP 配置通常会提供默认项目）；如果是必填项，则使用用户参数中提供的值，否则使用仓库根目录下 sonar-project.properties 中的 sonar.projectKey
• branchName — 检测到的分支名称
• filePath — 相对于项目的文件路径（例如 src/auth/login.py）
• fileContent — 完整文件内容；只有工具要求时才传入（如果 MCP 服务已挂载，它会直接读取文件，无需此参数）
• fileScope — ["TEST"] 或 ["MAIN"]

如果该工具不可用，则改用 mcp__sonarqube__analyze_file_list（需要正在运行的 SonarQube for IDE 实例桥接到此会话）：

• file_absolute_paths — 包含文件绝对路径的数组（例如 ["/home/user/project/src/auth/login.py"]）；根据步骤 1 中找到的文件路径解析

如果这两个 MCP 工具都不可用，则改用 CLI 的 Vortex 分析：

sonar analyze agentic --file <file-path> [--file <other-file-path> ...] --format json [--branch <branch-name>] [-p <project-key>]

使用的后端与 run_advanced_code_analysis 相同（重复使用 --file 也支持多个文件），同时也是 analyze_file_list 的实用备用方案——后者没有直接对应的 CLI 命令，但此方法可以达到相同目的。

需要组织符合 Vortex 分析资格。如果组织不符合资格，或未安装/认证 sonar，请显示 Prerequisites 中的标准消息——不要进一步猜测要运行什么命令。

步骤 4：整理结果

如果发现问题，请按行号排序，并以表格形式呈现：

## SonarQube Analysis — `src/auth/login.py`

Found **3 issue(s)**:

| Line | Severity  | Rule         | Message                                               |
| ---- | --------- | ------------ | ----------------------------------------------------- |
| 12   | 🔴 Blocker | python:S2077 | Make sure that executing this SQL query is safe here. |
| 34   | 🟠 Major   | python:S1481 | Remove the unused local variable "token".             |
| 67   | 🟡 Minor   | python:S1135 | Complete the task associated to this "TODO" comment.  |

严重性图标（标签取决于服务端版本）：

• 🔴 阻断
• 🟠 严重 / 高
• 🟡 主要 / 中
• 🔵 次要 / 低
• ⚪ 信息

如果未发现问题：

## SonarQube Analysis — `src/auth/login.py`

✅ No issues found.

步骤 5：后续步骤

结果之后，始终添加：

• 如果发现问题："调用 sonar-fix-issue 技能，并提供 <rule> <file>:<line>，即可修复特定问题；也可以让我全部修复。"
• 如果用户想分析其他文件：提醒他们调用 sonar-analyze 技能并提供文件路径。