maxmilian/dsh-sonarqube

dsh-sonarqube

dsh-sonarqube 是一款免费、开源、只读的 DeepSeek Harness plugin，用于集成 SonarQube
Community Build Web API。它让 agent 能够检查 Quality Gate、issues、Security Hotspots、
coverage、重复代码和其他项目 measures，而不会更改 SonarQube 状态。

当 API 提供相关数据时，issue 和 hotspot 结果会加入标准化的 location 对象，其中包含
SonarQube component key、源文件 filePath、行号和文本范围。

工具

| 工具 | 用途 |
| --- | --- |
| sonarqube_system_status | 读取 instance 状态和版本。 |
| sonarqube_quality_gate | 读取项目主分析、branch 或 pull request 的 Quality Gate。 |
| sonarqube_search_issues | 按类型、严重程度、状态、branch 或 pull request 搜索 issues。 |
| sonarqube_search_hotspots | 按状态、branch 或 pull request 搜索 Security Hotspots。 |
| sonarqube_get_hotspot | 读取单个 Security Hotspot 的完整内容。 |
| sonarqube_get_measures | 读取 coverage、重复代码、issue 数量、hotspots 或指定 metrics。 |

所有工具均为只读。v0.1 不会分配、确认、解决、重新打开或以其他方式修改 issues 或
hotspots。

要求

- DeepSeek Harness，且 @deepseek-ai/dsh-tools API 版本兼容
- Node.js 22.19 以上的 22.x 版本，或 Node.js 24 以上版本
- 从 GitHub source 安装或在本地开发时，需要 Bun 1.3.5 或更高版本
- SonarQube Community Build URL，以及有权访问目标项目的 token

已于 2026-08-24 使用 SonarQube Community Build 26.8.0.126808 和 SonarScanner CLI
8.0.1.6346 进行人工兼容性验证。这不代表与所有 SonarQube 版本均兼容；在 CI 中采用前，
请先使用自己的 instance 验证。

实机验证涵盖 system status、Quality Gate、包含源文件和行号映射的 issue 搜索、默认
measures、空的 Security Hotspot 搜索结果，以及安全的 hotspot 404 处理。Community Build
26.8.0.126808 未提供 SECURITY_HOTSPOT 规则，因此成功的
sonarqube_get_hotspot 响应由 mock API 测试覆盖，而不是该次实机验证。

配置

建议使用环境变量，避免 credential 出现在 profile patch 中：

export SONARQUBE_URL='https://sonarqube.example.com'
export SONARQUBE_TOKEN='your-token'

Plugin config 的优先级高于环境变量：

| Config | 环境变量 fallback | 默认值 |
| --- | --- | --- |
| baseUrl | SONARQUBE_URL | 必填 |
| token | SONARQUBE_TOKEN | 必填 |
| requestTimeoutMs | 无 | 30000 |
| maxResponseBytes | 无 | 5242880（5 MiB） |

请勿将 token 写入 cordis.patch.yml。如果需要覆盖非敏感设置，可以添加位置更靠后的
profile patch（后面的 row 会替换该 row 的完整 config）：

- id: dsh-sonarqube
name: dsh-sonarqube
config:
baseUrl: 'https://sonarqube.example.com'
requestTimeoutMs: 30000
maxResponseBytes: 5242880

软件包内置的 bundle 会挂载 plugin，但不包含 credential：

- insert:
- id: dsh-sonarqube
name: dsh-sonarqube

安装

从未来的 npm release 或本地 tarball 安装：

dsh plugin --profile web add dsh-sonarqube
dsh plugin --profile web add ./dsh-sonarqube-0.1.0.tgz

从 GitHub source 安装：

dsh plugin --profile web add github:maxmilian/dsh-sonarqube#PINNED_COMMIT

Git 安装获取的是 source，而不是 lib，因此软件包包含使用 Bun build 的 prepare script。
Profile installer 可能要求明确允许 dependency 的 build script。请先审查 source、固定
commit，并且仅在信任它时允许 build。

安装后请重新启动所选 DSH profile。可以在不启动 profile 的情况下检查组合后的配置：

dsh --profile web --dump-config

使用示例

可以向 agent 提出：

Use sonarqube_quality_gate for project acme-api on branch main.
Search open CRITICAL issues in acme-api, 50 per page.
Get coverage and duplicated_lines_density for acme-api.
Show the full Security Hotspot with key AX_example.

branch 和 pull_request 互斥。每页结果限制为 1..100，且 page × page_size 必须位于
前 10,000 条结果内。Measures request 最多接受 20 个 metric keys，每个最长 100 个字符。
未指定 metric 列表时，将查询：

coverage, duplicated_lines_density, bugs, vulnerabilities, code_smells, security_hotspots

国际化

Schemastery config 描述支持英语、繁体中文、简体中文和日语。Locale map 包含 DSH 当前的
en 和 zh ID，以及常见的地区 ID：en-US、zh-CN、zh-TW、ja 和 ja-JP。
只有 DSH host 已注册的 locale 才能被选择；当前 core UI 内置 en 和 zh。

当前 @deepseek-ai/dsh-tools API 对每个 tool 和 parameter 只接受一个提供给模型的
description 字符串，因此这些描述保持英语，避免声称 DSH 尚无法使用的 runtime
localization。Repository 文档可以通过每份 README 顶部的语言链接切换。

安全和错误处理

- 使用 Authorization: Bearer ...，并且绝不返回或记录 token。
- 遵循 DSH tool 的 AbortSignal、单次请求超时和最大 response size。
- 将 HTTP 401、403、404、429 和 5xx 响应转换为安全的结构化错误。
- 保留安全的 Retry-After 和 SonarQube-Authentication-Token-Expiration metadata。
- 错误不包含 SonarQube response body。
- v0.1 不支持禁用 TLS 验证或跳过 self-signed certificate 检查。

SonarQube Web API 正逐步转向 API v2。Endpoints 有意集中在 src/client.ts，而不是分散在
tool definitions 中，使后续 migration 保持局部化。

开发

本项目仅使用 Bun：

bun install --frozen-lockfile
bun run lint
bun run typecheck
bun run test --coverage
bun run build
bun pm pack

测试使用 Vitest 和 mocked fetch，不依赖真实 SonarQube server。Lines、statements、
functions 和 branches 的 coverage gates 均至少为 80%。

许可证

MIT