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