DeepSeek Harness 插件：dsh-grafana-query（只读 Grafana 查询工具）

在开发 DeepSeek Harness 智能体时，让 Agent 读取 Grafana 的指标和告警状态是常见需求。直接调用 Grafana API 往往涉及繁琐的鉴权逻辑，而现有的部分 DSH 插件侧重于仪表板编辑（写操作）。dsh-grafana-query 提供了一个只读的解决方案，允许 Agent 通过 Grafana 的数据源代理运行 PromQL 查询，并读取统一告警状态，且不会对 Grafana 实例产生任何变更。

插件介绍¶

插件名称：dsh-grafana-query
维护者：maxmilian
许可证：MIT

这是一个开源的 DeepSeek Harness 插件，专注于 Grafana 的只读操作。它利用 Grafana 的 /api/datasources/proxy/uid/:uid/* 接口，使智能体能够像操作本地数据源一样查询 Prometheus 等监控系统的指标，同时通过统一的告警接口获取告警状态。

核心功能¶

该插件提供以下 6 个工具，全部为只读操作：

grafana_health
检查 Grafana 实例是否可达，并返回版本信息。
grafana_list_datasources
列出数据源，包含 UID、类型和访问模式。这是查询前的必要步骤。
grafana_query
通过数据源代理执行即时 PromQL 查询，获取当前值。
grafana_query_range
执行时间范围 PromQL 查询。插件会强制执行步长限制和点数预算，防止返回过多数据。
grafana_alert_state
读取当前统一告警规则的状态（如 firing, pending, unknown）。
grafana_list_alert_rules
列出已配置的告警规则定义。

安装与启用¶

安装前请确保环境满足以下要求：
* Node.js：22.19 或 22.x 系列的更新版本，或 24 及以上版本。
* Grafana：9.0 或更高版本（仅支持基于 UID 的数据源代理，不支持旧的数字 ID 路径）。

使用 Bun 安装插件：

bun add dsh-grafana-query

插件通过 package.json 中的 dsh.bundle.patch 声明，DeepSeek Harness 注册表会自动加载其默认配置。

典型用法¶

1. 获取数据源 UID¶

在使用查询工具前，需要先找到目标数据源的 UID。通过过滤类型为 prometheus 的数据源获取：

{
  "type": "prometheus"
}

2. 执行即时查询¶

获取某个指标（如 up）的当前值：

{
  "datasource_uid": "prom-1",
  "query": "up"
}

3. 执行范围查询（趋势）¶

查询 CPU 使用率趋势。省略 step 参数时，插件会自动选择步长以保证每条序列的点数不超过默认上限。

{
  "datasource_uid": "prom-1",
  "query": "rate(node_cpu_seconds_total[5m])",
  "start": "2026-09-29T00:00:00Z",
  "end": "2026-09-30T00:00:00Z"
}

4. 查看告警状态¶

不带参数调用可查看当前触发的告警规则：

{}

配置与权限¶

环境变量配置¶

插件依赖环境变量进行配置，优先级低于代码内的显式配置：

export GRAFANA_URL='https://grafana.example.com'
export GRAFANA_TOKEN='glsa_your_service_account_token'

配置项	环境变量	默认值	说明
baseUrl	`GRAFANA_URL`	必填	Grafana 地址，需为 HTTP(S) URL
token	`GRAFANA_TOKEN`	必填	Grafana 服务账户令牌
locale	—	`en`	语言环境
maxResponseBytes	—	`5242880`	响应体最大字节

权限要求¶

该插件需要特定的 Grafana 权限才能正常工作。建议使用 Grafana 服务账户令牌（glsa_ 前缀）。

所需权限范围：
* datasources:read：用于列出数据源和查询元数据。
* datasources:query：用于执行 PromQL 查询。
* alert.rules:read：用于读取告警状态。
* alert.provisioning:read：用于列出告警规则定义。

权限设置建议：
在 Grafana 中创建服务账户时，建议组合使用以下角色：
1. 基础角色：Viewer（覆盖 datasources:read 和 datasources:query）。
2. 固定角色：Alerting → Full read-only access（覆盖 alert.rules:read 和 alert.provisioning:read）。

注意：不要使用 Grafana Cloud 的 Access Policy 令牌（glc_），它仅适用于云数据端点，不支持此 API。

限制与行为¶

插件在客户端强制执行了多项限制，以防止返回过多数据导致性能问题：

点数限制：默认 max_points 为 200，最大 500。grafana_query_range 的点数计算公式为 floor(n / s) + 1。
系列限制：默认 maxSeries 为 100。
响应大小：默认 maxResponseBytes 为 5MB。
时间范围：grafana_query_range 的最大时长为 31 天。
安全策略：错误信息中绝不会包含 Token、请求头或原始响应体。仅在 Prometheus 返回 HTTP 400 时，会将结构化的 error 字段传递给 Agent，且长度不超过 200 字符。
只读原则：版本 0.1 永远不会创建、编辑、删除、静默、确认或暂停 Grafana 中的任何内容。

适用场景与注意¶

适用场景：监控大盘搭建、智能体自动巡检、基于指标的自动化运维决策。
注意：此插件与 dsh-grafana（负责编辑仪表板 JSON）功能相反。本文档介绍的插件仅用于查询，不涉及仪表板定义的读写。

结语¶

dsh-grafana-query 为 DeepSeek Harness 提供了标准化的 Grafana 只读访问能力，简化了智能体与监控系统的集成成本。通过严格的权限控制和限制策略，它可以在保障安全的前提下，让 Agent 获取必要的监控数据。

插件目录：dsh-grafana-query
源代码：GitHub