SonarQube Skill 是一个面向 OpenCode 的代码质检 AI 辅助工具。通过本地 Python 脚本调用 SonarQube Web API，自动推断当前 Git 分支与 pom.xml 项目名，一键查询质量阈状态、核心度量指标、问题列表及规则详情，并尝试自动修复代码问题。
仅通过手动输入 /sonarqube 唤起，不会在编码过程中自动触发。
当前仅支持 Java Maven 项目结构，SonarQube 项目名称需与 pom.xml 的 artifactId 一致
支持按分支（branch）或 Pull Request 两种维度进行质检分析
适用于 PR 合入前的质量卡控、日常代码巡检、技术债务盘点等场景
| 能力 | 说明 |
|---|---|
| 自动项目识别 | 从 pom.xml 解析 artifactId（跳过 parent，自动去除 -cloud 后缀） |
| 自动分支推断 | 读取当前 Git 分支，自动匹配 SonarQube 对应分支或 PR |
| 一键质检报告 | report 命令聚合质量阈 + 核心度量 + Top 问题，输出精简 JSON |
| 质量阈检查 | 查询质量门状态及未通过的阈值条件 |
| 问题列表查询 | 支持按严重级别、问题类型、状态等过滤 |
| 规则详情 | 获取规则描述，自动剥离 HTML 标签，截断至 1500 字符 |
| 度量指标 | 获取 Bug 数、漏洞数、异味数、覆盖率、重复率等核心指标 |
| 自动代码修复 | 对可自动修复的问题类型（如未使用 import、空 catch 块等）直接修改源文件 |
| 三层配置优先级 | 默认配置 → 用户级配置 → 环境变量覆盖 |
sonarqube/ ├── config/ │ └── settings.json # 项目级配置（可覆盖默认 SonarQube 地址和 Token） ├── docs/ │ └── img/ # 文档图片 ├── scripts/ │ ├── config_loader.py # 配置加载器：默认值 → 用户配置 → 环境变量 │ └── sonar_client.py # 核心客户端：封装所有 SonarQube Web API 调用 ├── SKILL.md # Skill 定义文件（OpenCode 工作流描述） └── README.md # 本文件
项目为 Java Maven 结构，根目录存在 pom.xml
已配置代码仓库（通过 git branch --show-current 获取当前分支）
SonarQube 服务可访问，且项目已在该服务上完成过扫描
在 OpenCode 对话框中直接输入：
/sonarqube
等价于执行：
python scripts/sonar_client.py report
脚本自动完成以下步骤：
获取当前 Git 分支
从 pom.xml 提取 artifactId（跳过 -cloud 后缀）作为项目 Key
查询质量阈状态及失败条件
获取核心度量指标（Bug、漏洞、异味、覆盖率、重复率）
拉取 Top 30 问题列表（BLOCKER / CRITICAL / MAJOR，状态 OPEN / CONFIRMED / REOPENED）
返回精简 JSON 供 AI 分析并尝试自动修复
所有命令均通过 scripts/sonar_client.py 执行。
python scripts/sonar_client.py project-info
返回当前分支、项目 Key、匹配的 PR ID 及 Dashboard 链接。
# 按分支维度 python scripts/sonar_client.py report --limit 30 # 按 Pull Request 维度 python scripts/sonar_client.py report --mr # 手动指定项目与分支 python scripts/sonar_client.py report --project my-project --branch feature/xxx
返回 qualityGate（质量阈状态及失败条件）、measures（核心度量）、topIssues（Top 问题列表）。
python scripts/sonar_client.py qualitygate --project [--branch ]
返回质量阈整体状态（OK / ERROR）及未通过的具体条件项。
python scripts/sonar_client.py issues --project [--branch ] \ --severities BLOCKER,CRITICAL,MAJOR \ --types BUG,VULNERABILITY,CODE_SMELL \ --statuses OPEN,CONFIRMED,REOPENED \ --ps 50 --page 1
| 参数 | 说明 | 默认值 |
|---|---|---|
--project | 项目 Key（必填） | — |
--branch | 分支名 | — |
--severities | 严重级别 | BLOCKER,CRITICAL,MAJOR |
--types | 问题类型 | BUG,VULNERABILITY,CODE_SMELL |
--statuses | 问题状态 | OPEN,CONFIRMED,REOPENED |
--ps | 每页数量 | 50 |
--page | 页码 | 1 |
每条 issue 仅保留 key / rule / severity / type / component / line / message / status 等精简字段。
python scripts/sonar_client.py rule --key java:S1488
返回规则编号、名称、类型、严重级别、语言及清洁版描述（HTML 已剥离，描述截断 1500 字符）。
python scripts/sonar_client.py measures --project [--branch ] \ --metrics bugs,vulnerabilities,code_smells,coverage,duplicated_lines_density
返回各度量项的当前值。
# 查看所有分支 python scripts/sonar_client.py branches --project # 查看所有 Pull Request python scripts/sonar_client.py pull-requests --project # 匹配当前分支对应的 PR ID python scripts/sonar_client.py sonar-pr
配置加载遵循三层优先级（由低到高）：
默认硬编码值 → config/settings.json → ~/.config/opencode/sonar-config.json → 环境变量
{
"sonar_endpoint": "https://your-sonarqube.example.com",
"sonar_token": "your-sonar-token",
"sonar_author": "your-username"
}| 变量 | 说明 |
|---|---|
SONAR_BASE_URL | SonarQube 服务地址（最高优先级） |
SONAR_TOKEN | 认证 Token（最高优先级） |
SONAR_AUTHOR | 认证用户名 |
不配置以上任一项时，脚本将使用内置默认值。 若脚本返回
_error: true，请检查projectKey/branch参数或网络连通性。
/sonarqube
对于需要更详细规则说明的问题：
python scripts/sonar_client.py rule --key java:S2095
AI 根据 issue 的 component（文件路径）和 line（行号）精确定位代码位置，结合规则描述选择修复策略。
修复前会自动读取源文件上下文，修复后建议本地编译验证。
AI 最终输出结构化报告，格式如下：
## 质量阈: 通过 / 未通过 | 失败项: xxx ## 核心指标: Bug x | 漏洞 x | 异味 x | 覆盖率 x% | 重复率 x% ## 已修复 x 个 | 待人工确认 x 个
在对话框中输入 /sonarqube 修复质检问题，Skill 会自行分析并修复当前代码：
| 问题类型 | 示例规则 | 修复方式 |
|---|---|---|
| 未使用的 import | java:S1128 | 删除多余 import 语句 |
| 空 catch 块 | java:S1166 | 添加日志或注释说明 |
== 比较字符串 | java:S4973 | 替换为 .equals() |
| 资源未关闭 | java:S2095 | 添加 try-with-resources |
| 魔法数字 | java:S109 | 提取为命名常量 |
| 命名不规范 | java:S00114 | 按规范重命名 |
| 问题类型 | 原因 |
|---|---|
| 架构调整 | 涉及模块拆分、依赖重组 |
| 复杂逻辑重构 | 涉及多文件、业务流程 |
| 业务理解相关 | 需要领域知识判断 |
脚本输出为纯 JSON，可直接在自动化流程中解析使用
report 和 issues 命令已对响应做精简过滤，降低 token 消耗
rule 命令返回的描述已剥离 HTML 标签，最大 1500 字符
HTTP 请求内置自动重试机制（最多 3 次，502/503/504 时指数退避）
部分子命令的结果已缓存（如 Git 分支、pom.xml 解析），避免重复开销
所有 API 调用必须通过 scripts/sonar_client.py 执行，不要手工构造 HTTP 请求
