maxmilian/dsh-grafana-query

dsh-grafana-query

dsh-grafana-query 是一个免费开源、只读的 DeepSeek Harness Grafana 插件。
它让 agent 通过 Grafana 的 datasource proxy 执行 PromQL，并读取 Grafana unified alerting
的当前状态，全程不改动 Grafana 的任何数据。

请勿与 npm 上的 dsh-grafana 混淆——那是一个写入型的 dashboard 编辑器，会把 dashboard JSON
推回 Grafana。本插件做的是相反的事：只读的指标查询与告警状态。dashboard 与 panel JSON 明确不在范围内。

Tools

| 工具 | 用途 |
| --- | --- |
| grafana_health | 确认实例可连接并返回版本。 |
| grafana_list_datasources | 列出 datasource 的 uid、type 与 access 模式。请先调用这个。 |
| grafana_query | 通过 datasource proxy 执行 instant PromQL 查询。 |
| grafana_query_range | 执行区间 PromQL 查询，强制套用 step 与点数上限。 |
| grafana_alert_state | 读取 unified alerting 规则的当前状态。 |
| grafana_list_alert_rules | 列出已配置的告警规则定义。 |

所有工具均为只读。v0.1 不会在 Grafana 创建、修改、删除、silence、ack 或暂停任何东西。

硬性上限

以下上限均由插件本身强制，与 Grafana 无关。任何一处被截断时，meta.truncated 与截断前的总数都会标示出来。

| 项目 | 值 |
| --- | --- |
| 每条 series 的点数（max_points） | 默认 200、上限 500。Prometheus 两端都会返回，因此 n 秒的区间搭配 step s 会得到 floor(n / s) + 1 个点 |
| 区间长度（grafana_query_range） | 31 天 |
| 单次区间查询的总点数 | 20000；超出的 series 会被整条丢弃，不会砍成半截 |
| 单次查询的 series 数 | maxSeries，默认 100 |
| 告警规则条数（grafana_alert_state、grafana_list_alert_rules） | 匹配条件的前 500 条；其余无法通过翻页获取，请用筛选参数 |
| 每条规则的告警 instance | 默认 10、上限 50 |
| 每页条数 | 默认 20、上限 100 |
| 上游错误文本 | 200 字符，且仅 HTTP 400 才透出 |

grafana_alert_state 默认只返回 firing、pending 与 unknown 的规则——inactive 规则默认不会出现，
需要时请用 state 明确指定。

Requirements

- 具备兼容 @deepseek-ai/dsh-tools API 的 DeepSeek Harness
- Node.js 22.19 以上（22.x 系列）或 Node.js 24 以上
- Grafana 9.0 以上——只支持 uid 版 datasource proxy（/api/datasources/proxy/uid/:uid/*），
不支持已 deprecated 的数字 id 路径

Configuration

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

| 字段 | 环境变量 | 默认 | 范围 |
| --- | --- | --- | --- |
| baseUrl | GRAFANA_URL | 必填 | http(s) URL，不可内嵌账号密码、不可带 query 或 fragment；可含 sub-path |
| token | GRAFANA_TOKEN | 必填 | 不可为空 |
| locale | — | en | en、zh-TW、zh-CN、ja |
| requestTimeoutMs | — | 30000 | 1 – 300000 |
| maxResponseBytes | — | 5242880 | 1 – 52428800 |
| maxSeries | — | 100 | 1 – 1000 |

plugin 配置的优先级高于环境变量。

Permissions

Grafana service account token（推荐）与旧版 API key 都可以用——两者都走同一个
Authorization: Bearer header。Grafana Cloud 的 Access Policy token（glc_）是给 Cloud
数据端点用的，不适用于这个 API。

实际在 Grafana 上怎么设

下表的 scope 名称是 Grafana 内部检查用的，UI 上并不是这样勾。创建 service account 时可行的组合是：

1. basic role 选 Viewer——涵盖 datasources:read 与 datasources:query。
2. 再加 fixed role Alerting → Full read-only access——涵盖 alert.rules:read 与
alert.provisioning:read。

已于 2026-08-27 在 Grafana Cloud 用这个组合实测，六个工具全部可用。
详见验证记录。

用最小权限的 token 不会让工具变难用：Grafana 对 GET /api/datasources 是返回过滤后的列表，
而不是返回 403。因此只被授予单一 datasource Query 权限的 token，grafana_list_datasources
就只会列出那一个——2026-08-27 实测：Viewer token 拿到 26 条，受限 token 拿到 1 条。你不会看到一堆
查下去就 403 的条目。（datasource 层级的 Query 权限也隐含允许读该 datasource 的 metadata，
因此不存在“查得动但读不到”的状态。）

Scope 对照

| 工具 | 所需权限 |
| --- | --- |
| grafana_health | 无——/api/health 不需要认证，因此本工具无法判断 token 是否有效；要验证 token 请用 grafana_list_datasources。 |
| grafana_list_datasources | datasources:read |
| grafana_query、grafana_query_range | datasources:query（另有 datasources:read 才能做前置类型检查） |
| grafana_alert_state | alert.rules:read |
| grafana_list_alert_rules | alert.provisioning:read |

Grafana Cloud

baseUrl 指向 stack 本身，并使用在该 stack 创建的 service account token：

export GRAFANA_URL='https://your-stack.grafana.net'
export GRAFANA_TOKEN='glsa_your_service_account_token'

这里不要用 glc_ 开头的 Access Policy token。Cloud stack 内置大量 datasource，
请善用 grafana_list_datasources 的 type 与 name_contains 筛选以缩短列表。

Install

bun add dsh-grafana-query

包内含 cordis.patch.yml，并通过 package.json 的 dsh.bundle.patch 声明，
让 DeepSeek Harness registry 能以默认配置加载本插件。

Examples

1. grafana_list_datasources 带 {"type": "prometheus"} 获取 uid。
2. grafana_query 带 {"datasource_uid": "prom-1", "query": "up"} 查当前值。
3. grafana_query_range 带 {"datasource_uid": "prom-1", "query": "rate(node_cpu_seconds_total[5m])", "start": "...", "end": "..."}
查趋势。省略 step 时插件会自动挑一个，使每条 series 的点数不超过 max_points。
4. grafana_alert_state 不带参数，看现在有什么在告警。

Internationalization

把 locale 设为 en、zh-TW、zh-CN 或 ja，可切换模型看到的工具与参数描述。
工具名称一律保持英文，错误信息也一律是英文。

Security and error behavior

- 每个工具都是只读。
- 错误永远不会夹带 token、Authorization header 或原始 response body。
- 唯一的例外：当 Prometheus 以 HTTP 400 拒绝查询时，会把结构化的 error 字段透出，
让 agent 能修正自己的 PromQL。上限 200 字符，且事前会先跑一次敏感信息过滤。
其他状态码一律返回静态信息。
- 响应大小受 maxResponseBytes、maxSeries 以及每条 series 的点数上限三重限制。
任何裁剪都会在 meta.truncated 与裁剪前的总数留下记录。

Development

bun install
bun run lint
bun run typecheck
bun run test
bun run build

License

MIT