sonar-integrate

集成 SonarQube

引导用户安装 sonarqube-cli（如有需要）、在已安装时更新到最新版本、完成身份验证，并进行针对特定 Agent 的集成。假设 SonarQube 本身已完成设置；此技能仅负责接入助手。

说明

交互规则：对于每个有限选项，始终提供预先设定的选择器选项（根据情况使用单选或多选），不要要求用户自由输入。如果用户的回答无效，请重新显示相同的选择器。

步骤 1 — 检查 sonarqube-cli 并更新

自行运行 which sonar（macOS/Linux）或 Get-Command sonar（Windows），检查 sonar 是否在 PATH 中可用。

**如果已找到：**首先确定它的安装方式，因为升级路径不同：

• 由软件包或版本管理器管理（例如通过 Homebrew 或 mise 安装——二进制文件位于管理器的前缀目录下，而不是 ~/.local/share/sonarqube-cli/bin）：不要运行 sonar update，因为这会与管理器冲突。自行运行管理器的升级命令（Homebrew：brew upgrade --cask sonarqube-cli；mise：mise upgrade aqua:SonarSource/sonarqube-cli），然后转到步骤 2。如果升级失败，显示输出，但只要 sonar 仍可用，就继续步骤 2。
• **通过 shell/PowerShell 脚本安装，或不确定安装方式：**自行运行 sonar update 并等待其完成。
  • **如果成功：**简要告知用户 CLI 已是最新版本（或已升级），然后转到步骤 2。
  • 如果失败：显示相关输出，建议用户手动运行 sonar update（例如，网络离线或遇到网络问题时），然后只要 sonar 仍可用，就继续步骤 2——除非二进制文件缺失或损坏，否则不要阻止后续流程。

**如果未找到：**从下表选择一条安装命令，显示给用户，并在运行前征求明确确认。用户确认之前，不要执行该命令。

shell/PowerShell 脚本是默认方式，适用于所有环境。如果用户已经使用 Homebrew 或 mise 管理 CLI，则优先采用相应方式，以便后续升级继续由该工具管理——此时步骤 1 中的更新操作将交由管理器处理。

平台／方式	安装命令
macOS / Linux（脚本）	curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash
macOS / Linux（Homebrew）	brew install --cask sonarqube-cli
任意操作系统（mise）	mise use -g aqua:SonarSource/sonarqube-cli
Windows（PowerShell）	irm https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.ps1 | iex

**如果用户确认：**使用 shell 命令自行运行该命令。命令完成后，再次自行检查 PATH（运行 which sonar 或 Get-Command sonar），确认无误后再继续。

**如果用户拒绝：**停止此技能，并请用户手动安装 sonarqube-cli，然后重新调用 sonar-integrate 技能。

---

步骤 2 — 检查身份验证状态

使用 shell 命令自行运行 sonar auth status。

**如果已完成身份验证：**根据输出说明已连接的服务和组织， 然后直接跳到步骤 4。

**如果尚未完成身份验证：**继续步骤 3。

---

步骤 3 — 身份验证（sonar auth login）

此步骤需要用户交互——不要自行运行。

首先，使用单选选择器确定连接类型，选项如下：

1. SonarQube Cloud - EU（默认）
2. SonarQube Cloud - US
3. 自托管的 SonarQube Server

不要通过开放式文本问题询问此项选择。

收集：

场景	所需信息
SonarQube Cloud — EU（默认）	组织密钥（例如 my-org）
SonarQube Cloud — US	组织密钥 + 确认 US 区域（https://sonarqube.us）
SonarQube Server	服务 URL（例如 https://sonarqube.yourcompany.com）

构建登录命令并展示给用户：

场景	命令
SonarQube Cloud — EU	sonar auth login -o <org-key>
SonarQube Cloud — US	sonar auth login -o <org-key> -s https://sonarqube.us
SonarQube Server	sonar auth login -s <server-url>

告诉用户：

“运行下面的命令——它会打开浏览器供你登录。令牌会安全地存储在系统钥匙串中，绝不会出现在此聊天中。”

等待用户确认已登录，然后自行运行 sonar auth status 进行验证，再继续。

---

步骤 4 — 针对 Agent 的集成

容器运行时要求： SonarQube MCP Server 在容器内运行，由 sonar run mcp 启动（该命令会检测 Docker、Podman 或 Nerdctl）。必须安装并运行容器运行时，MCP 工具才能加载——否则集成可能成功完成，但会话中不会出现任何 mcp__sonarqube__* 工具。**自行验证：**运行 docker ps（如果失败，则尝试 podman ps / nerdctl ps）。如果其中一条命令成功，则运行时已启动——继续操作。如果全部失败，请告知用户容器运行时未运行并让他们启动，然后说明他们之后必须重启 Agent 会话，工具才能加载（启动守护进程和重启会话是仅有的无法代为完成的步骤）。

根据你所使用的 Agent，严格选择以下一个分支。不要运行其他分支。

• Claude Code -> 4.a
• Copilot CLI -> 4.b
• Codex -> 4.c
• Cursor -> 4.d
• Antigravity -> 4.e
• Gemini CLI -> 4.f
• Factory Droid -> 4.g

4.a — Claude Code（sonar integrate claude）

运行 sonar integrate claude，该命令会配置 SonarQube MCP Server、secrets-scanning hooks，以及 CLI 支持的其他集成。

它会将 MCP（用于 sonar-quality-gate、sonar-analyze、sonar-coverage、sonar-duplication、sonar-dependency-risks 等技能）和 secrets-scanning hooks 接入用户的 Claude Code 配置，并应用于此计算机上的所有 Claude Code 会话。如果可用，还会安装 SonarQube Vortex 分析钩子。

使用 shell 命令自行运行此命令：

sonar integrate claude --non-interactive

4.b — Copilot CLI（sonar integrate copilot）

运行 sonar integrate copilot，该命令会配置 SonarQube MCP Server、secrets-scanning hooks，以及 CLI 支持的其他集成。

它会将 MCP（用于 sonar-quality-gate、sonar-analyze、sonar-coverage、sonar-duplication、sonar-dependency-risks 等技能）和 secrets-scanning hooks 接入用户的 Copilot CLI 配置，并应用于此计算机上的所有 Copilot CLI 会话。

使用 shell 命令自行运行此命令：

sonar integrate copilot --non-interactive

4.c — Codex（sonar integrate codex）

运行 sonar integrate codex，配置 SonarQube MCP Server 和 secrets-scanning hooks；如果你的 SonarQube Cloud 组织启用了 Vortex 分析，还会在 apply_patch 上配置 PostToolUse hook，在编辑后以内联方式显示检测结果。此配置适用于这台机器上的所有 Codex 会话。

请自行使用 shell 命令运行此命令：

sonar integrate codex --non-interactive

4.d — Cursor（sonar integrate cursor）

运行 sonar integrate cursor，配置 secrets-scanning hooks（beforeSubmitPrompt、beforeReadFile 和 preToolUse）、MCP、Context Augmentation（满足授权条件时）和 Vortex 分析指令（满足授权条件时）。此配置适用于这台机器上的所有 Cursor 会话。注意：Cursor 的云端/后台 Agent 只会使用安装在项目中的 hooks，不会使用机器范围内的 hooks，因此这些 Agent 无法使用已安装的 hooks。

请自行使用 shell 命令运行此命令：

sonar integrate cursor --non-interactive

集成完成后，告知用户需在 Cursor 中手动启用 MCP 服务：打开 Settings → MCP，找到 sonarqube 条目并将其启用。同时告知用户确保容器运行时（Docker、Podman 或 Nerdctl）正在运行。可能需要重启 Cursor 会话，工具才会显示。

4.e — Antigravity（sonar integrate antigravity）

运行 sonar integrate antigravity，在 Antigravity harness 中配置 secrets-scanning hooks、prompt-secrets 和 Vortex 分析指令、Context Augmentation（满足授权条件时）以及 MCP。此配置适用于这台机器上的所有 Antigravity 会话。

请自行使用 shell 命令运行此命令：

sonar integrate antigravity --non-interactive

告知用户确保容器运行时（Docker、Podman 或 Nerdctl）正在运行；如果集成完成后 MCP 工具没有显示，请重启 Antigravity 会话。

4.f — Gemini CLI（旧版）

Gemini CLI 通过 sonar run mcp 启动 SonarQube MCP Server，该命令会自动检测容器运行时（Docker、Podman、Nerdctl）并完成身份验证。身份验证已在步骤 2–3 中完成。

确认集成已就绪 — Gemini CLI 读取 gemini-extension.json 时，MCP 服务将自动启动。

建议迁移到 Antigravity（4.e）：运行 agy plugin import gemini，然后运行 sonar integrate antigravity。Gemini CLI 不支持 SonarQube hooks 或 Vortex 分析集成。

4.g — Factory Droid

Factory Droid 通过插件的 mcp.json 调用 sonar run mcp 启动 SonarQube MCP Server，该命令会自动检测容器运行时（Docker、Podman、Nerdctl）并完成身份验证。身份验证已在步骤 2–3 中完成。

Factory Droid 不适用任何 sonar integrate 命令。Factory Droid 不支持 SonarQube hooks 或 Vortex 分析集成。

---

总结消息

所有步骤完成后，打印一条总结：

✅ SonarQube integration is ready.

  sonarqube-cli:     up to date
  Authentication:    token stored in system keychain
  MCP Server:        configured (ensure a container runtime (Docker, Podman, or Nerdctl) is running, then restart the agent session if tools do not appear)

You can verify at any time with:  sonar auth status
To refresh CLI + wiring later:    invoke the sonar-integrate skill again

如果采用了路径 4.a（Claude Code），在总结中添加此行：

  Secrets scanning:  hooks registered via sonar integrate claude

如果采用了路径 4.b（Copilot CLI），在总结中添加此行：

  Secrets scanning:  hooks registered via sonar integrate copilot

如果采用了路径 4.c（Codex），在总结中添加此行：

  Hooks & MCP:       wired via sonar integrate codex

如果采用了路径 4.d（Cursor），在总结中添加以下行：

  CLI integrate:     wired via sonar integrate cursor
  MCP Server:        enable manually in Cursor Settings → MCP (ensure a container runtime (Docker, Podman, or Nerdctl) is running; restart may be needed)

并省略默认的 MCP Server 行（由上面的 Cursor 专用行替代）。

如果采用了路径 4.e（Antigravity），在总结中添加以下行：

  CLI integrate:     wired via sonar integrate antigravity

如果采用了路径 4.f（Gemini CLI），除默认 MCP 总结外，无需添加其他行。

如果采用了路径 4.g（Factory Droid），除默认 MCP 总结外，无需添加其他行。

如果在步骤 1 中全新安装了 sonarqube-cli，将总结中的 sonarqube-cli 行替换为 sonarqube-cli: installed。

如果步骤 1 中 sonar update 失败，请调整总结：省略 sonarqube-cli 行，或说明 CLI 未更新，并建议在终端中运行 sonar update。

如果其他任何步骤失败，请明确说明，并建议相应的修复操作。