guhanfei-ai/dsh-grafana ↗★ 7

dsh-grafana

Conversational Grafana operations for DeepSeek Harness: inspect live observability data and make safe, reviewable dashboard changes

包名
dsh-grafana
兼容性
待验证
Harness 依赖范围
^0.1.0-rc.6 || ^0.1.1-rc.0 || ^0.1.2-alpha.0 || ^0.1.3-alpha.0 || ^0.1.5-alpha.0 || ^0.1.7-alpha.0 || ^0.2.0-alpha.0 || ^0.2.1-alpha.0
版本
0.18.2
许可证
MIT
最近更新
2026年10月27日

安装

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:guhanfei-ai/dsh-grafana

0.17.x: settings UI and configuration migration

Hosts exposing declaration inspection and the settings.section slot provide an independent Grafana item in the Settings left navigation, with the configuration card expanded by default. Hosts without that section fall back to the Grafana plugin tab or legacy embedded card; hosts without declaration inspection retain the original compatibility registrations. Selection follows actual host capabilities, not version strings, and inspecting hosts register only one supported entry. Moving the entry does not change configuration, source UIDs or token storage.

Configuration migrates automatically. Existing named sources in the pre-upgrade settings.yaml.imported take priority over a legacy single-source credential; otherwise a single-source configuration is materialized as a named default source (same base URL, same stored token). The importer reads $DSH_HOME/settings.yaml.imported, or ~/.dsh/settings.yaml.imported when DSH_HOME is unset. This maintenance cycle keeps the optional js-yaml dependency on v4 to preserve existing aliases and ` Note: the independent section takes precedence over the plugin tab, which takes precedence over the legacy embedded card. Compatibility cards keep their collapsed default. After upgrading, the maintainer can reload the selected profile and refresh the page to load the new plugin code. Development-directory watching/HMR depends on the actual host setup; an edited source file alone does not prove the running UI has updated.

Configure:

  • Service Account Token: a Grafana service-account token such as glsa_....
  • Grafana URL: the absolute base URL, for example https://grafana.example.com or https://example.com/grafana.

The token uses DSH's privileged loopback credential RPC — write-only, the stored value is never read back or displayed. The URL is stored in the grafana settings namespace as a non-secret field, so it is read back in plaintext and shown in the card for verification. The UI supports replacing and removing each value.

HTTP and HTTPS both work out of the box — internal deployments without TLS certificates can use an http:// URL with no extra setup. Note that plain HTTP sends the service-account token in cleartext; always use HTTPS over untrusted networks. To enforce HTTPS only, disable it in plugin configuration:

allowInsecureHttp: false

Read-only mode is available for monitoring and troubleshooting roles that must never modify dashboards:

readOnly: true

When enabled, grafana_push and grafana_clone are not registered at all — no dashboard write tool exists for the model to call. The settings card shows the current mode and lets you switch it with the Read-only mode toggle at the top of the card (ON = read-only, OFF = read-write). Toggling writes the plugin-level readOnly setting only; the configured sources and the default source are untouched.

Switching to read-only takes effect immediately: even when the write tools were registered at startup, the approval gate denies them at runtime. Switching back to read-write may require restarting DSH (or reloading the plugin), depending on when the plugin was loaded: a plugin that started in read-only mode never registered the write tools, and they only come back after a restart or reload.

The settings baseUrl is the authoritative source; a legacy GRAFANA_BASE_URL credential (from earlier versions) is migrated into settings on startup and then used only as a fallback. The token reference defaults to GRAFANA_TOKEN and can be changed with tokenRef.

Multiple Grafana sources

The settings card manages a list of named Grafana sources rather than a single URL/token pair. Each source has:

  • Source name (required, unique): any language. This is the value you pass as the source argument to target that instance.
  • UID (read-only): an auto-generated, globally unique id shown in faint text right under the name. It is the stable internal key — renaming a source never changes its UID or its stored token, and it can never be edited.
  • Grafana URL and Service Account Token: independent per source. Tokens are stored write-only in the DSH credential store. New sources start with a GRAFANA_TOKEN_ reference; rotating a saved token creates a fresh reference. Migration preserves the existing reference, including custom references.

Click Add source to create one, Remove source to delete it, and Set as default to choose the source used when a tool call omits source. Save this source saves one card; Save all sources saves every card. Names and URLs are validated before writing. Removal deletes the source configuration in the current profile only; its credential is retained. Profiles may share the DSH credential store, and the current settings cannot prove that another profile no longer uses a reference. Automatic credential cleanup and its retry action are therefore disabled.

Saving requires a successfully read configuration. Failed or malformed reads leave the card read-only with a Reload button. When the host provides a configuration revision, writes carry it so stale pages cannot overwrite newer changes.

Token changes switch to a fresh credential reference in the settings write. A definite rejection leaves the old configuration active; a lost reply is not treated as proof that nothing was committed. Every path retains credentials written or possibly written and explains the retention; successful rotation also retains the old credential. Successfully saved token drafts are cleared while other unsaved edits are preserved. Retained credentials may accumulate. Removing a source does not revoke its Grafana token; revoke the relevant token in Grafana when access must end.

Token status is configured, missing (confirmed absent), or unknown (unconfirmed). A missing credential facade, failed read or malformed reply shows Status unavailable, with Reload always available; grafana_sources reports token=unknown without exposing credential values or provider errors. Configured means a credential exists, not that Grafana authentication succeeds. Draft persistence is tracked by the settings baseline, independently of token status.

Every tool accepts an optional source argument (a configured source name); omit it to use the default source. Call grafana_sources to list the configured names, UIDs, base URLs, which token is configured, and which source is the default. Write approvals always show the target source name and URL on the first line so you can confirm which instance is modified, and the write is bound to that source: if the default source changes while the approval is pending, the write is refused instead of going to whichever instance happens to resolve at execution time. A read/approval/write chain is also bound to the source's URL and credential reference, so changing a source's address invalidates snapshots taken before the change — matching id/uid/version alone does not prove two responses came from the same instance. A single-source configuration from earlier versions is migrated on startup into one source named default, keeping its custom tokenRef if it had one. allowInsecureHttp remains a global setting that applies to all sources.

Grafana permissions

Prefer least-privilege RBAC with only the required dashboard and folder scopes:

  • dashboards:read
  • dashboards:write
  • folders:read for the folders being edited
  • datasources:query plus access to the datasources queried by grafana_panel_query

When fine-grained RBAC is unavailable, Grafana's Editor role is the fallback. Avoid Admin tokens.

The exact scope each tool needs:

ToolGrafana permission
grafana_getdashboards:read
grafana_pushdashboards:read + dashboards:write
grafana_clonedashboards:read + dashboards:write
grafana_panel_querydashboards:read + datasources:query
grafana_datasourcesdatasources:read
grafana_metricdatasources:read + datasources:query
grafana_comparedatasources:read + datasources:query (per source)
grafana_trenddashboards:read + datasources:query
grafana_alertsalert.instances:read; definitions: true also needs alert.provisioning:read; ruleStates: true needs its own rules-read permission (a refusal is reported in place with the missing scope)
grafana_searchdashboards:read
grafana_statusdashboards:read (see note)
grafana_sourcesnone (reads local plugin configuration only)

A read-mostly setup is the Viewer basic role plus Grafana's fixed read-only Alerting role; add dashboards:write (or the Editor basic role) only for the token that runs grafana_push / grafana_clone. Note on grafana_status: /api/health needs no authentication, so the tool confirms the credential by calling GET /api/search and reading the instance health from the database field of /api/health (there is no status field).