dsh-grafana

dsh plugin --profile web add dsh-grafana

dsh-grafana

[English](./README.md)

一个面向 Agent 的 Grafana 可观测 DeepSeek Harness 插件——读取大盘、查询实时指标、跟踪趋势与告警、跨源对比调查，并能安全、可审查地写回大盘。插件直接操作 Grafana API 与 Dashboard JSON，不需要截图。

项目状态：1.0 前版本。核心写回路径已经具备安全保护和自动化测试，但尚未完成 Grafana 12+ 兼容性认证。

核心能力

• 通过浏览器 URL 或 UID 获取大盘；超大盘可改用结构化摘要模式，只返回面板/查询/阈值/变量骨架。
• 按标题和标签搜索大盘。
• 粘贴大盘或面板视图 URL，直接查询面板背后的真实数据。
• 把大盘复制为全新大盘，并返回新大盘地址。
• 通过对话调整面板、查询、阈值、变量和布局。
• 写回时自动保持大盘所在文件夹。
• 写入前检测并发修改。
• 每次写入都必须经过 DSH 原生用户审批。
• Service Account 凭证只保存在本机 DSH 凭证库。
• 可配置多个具名 Grafana 源站，每次工具调用按名称指定目标。

环境要求

组件 · 已支持基线

Node.js · 20.11 或更高版本

DeepSeek Harness · 默认开发依赖为 dsh-tools@0.2.0-rc.2；另覆盖 0.2.1-alpha.1 的自动化依赖兼容检查。历史基线：0.1.0-rc.6、0.1.1-rc.2、0.1.2-rc.1、0.1.3-alpha.2、0.1.5-rc.1、0.1.7-rc.2。真实宿主与浏览器验收另见 INTEGRATION.md。

Grafana · Grafana 10/11 文档中的传统 Dashboard HTTP API

Grafana 12 引入了新 Dashboard API。旧接口可能仍然可用，但 Grafana 12+ 暂未进入本插件的正式兼容矩阵。

标准 npm 依赖解析与 DSH 宿主预检采用不同的预发布匹配方式：宿主 0.2.0-rc.2 和 0.2.1-alpha.1 的预检启用 includePrerelease。插件仍显式声明 0.2.1 元组，供标准依赖解析使用；这不表示已完成 alpha 宿主、桌面端或浏览器认证。

本插件无构建步骤：纯 ESM JavaScript，安装即可加载，无需编译或打包。

安装

正式使用应安装不可变的 Release tag：

dsh plugin --profile <profile> add github:guhanfei-ai/dsh-grafana#v<version>

仅在测试时安装会持续变化的默认分支：

dsh plugin --profile <profile> add github:guhanfei-ai/dsh-grafana

本地开发：

npm ci
dsh plugin --profile <profile> add link:/绝对路径/dsh-grafana

安装后重启对应 DSH profile。

Windows 可使用 link:C:/path/to/dsh-grafana 形式的绝对路径。插件运行本身支持跨平台。

升级说明

0.12.0：工具改名与旧宿主界面

两个工具改名。 grafana_query 改为 grafana_panel_query，grafana_health 改为 grafana_status。参数、输出、超时与审批行为均不变。

旧名 · 新名

grafana_query · grafana_panel_query

grafana_health · grafana_status

旧名仍以「只报错」的转发 stub 保留在工具列表中：调用 grafana_query 或 grafana_health 会立即失败并指名新工具，进行中的对话一步即可自愈。自定义 prompt 与保存的工作流仍建议改用新名；按代理配置的工具白名单需要换成新名。

浏览器设置卡片需要 DSH 0.1.2 及以上。 在更旧的宿主（0.1.0–0.1.1）上，卡片会显示明确的「宿主过旧」提示而非源站列表——这是版本门槛，不是配置丢失。宿主侧全部工具在这些版本上照常可用，插件本身也仍可安装在 0.1.0-rc.6 及以上。

0.17.x：设置页与配置迁移

支持槽位声明探测及 settings.section 的宿主，在设置页左侧提供独立 Grafana 导航项，进入后配置卡片默认展开。没有独立分区的宿主回退到插件区 Grafana tab 或旧版内嵌卡片；没有声明探测接口的旧宿主沿用原有兼容注册。入口选择按实际宿主能力，不仅凭版本号；支持探测的宿主始终只注册一个可用入口。此次入口调整不改变配置、源站 UID 或令牌存储。

配置自动迁移。 升级前 settings.yaml.imported 中的具名源站优先于旧单源凭证；否则旧单源配置会物化为名为 default 的源站（Base URL 与已存令牌不变）。导入文件位于 $DSH_HOME/settings.yaml.imported，未设置 DSH_HOME 时位于 ~/.dsh/settings.yaml.imported。本次维护继续使用可选依赖 js-yaml v4，以保留旧 YAML 的锚点与 << 合并语义；仅该依赖本身缺失时，才由内置解析器处理已知的基础 Grafana 段结构。

文件读取、YAML 解析或导入写入失败时，迁移停止并输出脱敏原因；不会再推断单源配置、修改凭证或改写导入文件。请修复配置或依赖后由维护者重载插件再试。迁移不会覆盖运行期间并发保存的配置。

配置

打开 设置 → 左侧 Grafana（位于内置插件之后），直接查看已展开的配置面板。如果宿主不支持独立分区，则使用 设置 → 插件（或内置插件）→ Grafana；仅支持旧槽位的宿主使用内嵌 Grafana 助手卡片。

Web 版与桌面版的 Grafana 配置页均默认显示简体中文，不随浏览器或系统语言自动切换。若在 DSH 语言设置中明确选择英文，配置页会使用英文；未选择、语言不支持或偏好读取失败时均使用简体中文。

提示：独立分区优先于插件 tab，插件 tab 优先于旧版内嵌卡片；兼容入口保留原来的默认收起行为。升级后由维护者重载对应 profile 并刷新页面，使新插件代码生效。是否支持开发目录监听/HMR 取决于实际宿主配置，不能仅凭源码已修改判断当前界面已更新。

需要配置：

• Service Account Token：例如 glsa_...。
• Grafana URL：例如 https://grafana.example.com 或 https://example.com/grafana。

Token 使用 DSH 仅允许 loopback same-origin 访问的特权凭证 RPC：仅写不读，保存后的值不会被读取或回显。URL 存储在 grafana settings namespace 的非 secret 字段中，因此可读回明文并在卡片中显示以便核对。界面支持替换和删除。

HTTP 与 HTTPS 开箱即用，内网未配置证书的环境可直接填写 http:// 地址，无需额外设置。注意：HTTP 会明文传输服务账号令牌，不可信网络环境请务必使用 HTTPS。如需强制仅允许 HTTPS，可在插件配置中关闭：

allowInsecureHttp: false

只读模式面向监控排障等不应修改大盘的角色：

readOnly: true

启用后 grafana_push 与 grafana_clone 完全不注册——模型没有可调用的写入工具。设置卡片顶部提供只读模式开关（开 = 只读，关 = 读写），当前模式一目了然；切换只写插件级 readOnly 配置，不影响已配置的源站与默认源站。

切换到只读立即生效：即使写入工具在启动时已注册，审批门也会在运行时拒绝它们。从只读切回读写可能需要重启 DSH（或重新加载插件），取决于插件加载时的模式：以只读模式启动的插件从未注册写入工具，重启或重载之后才会恢复。

settings 中的 baseUrl 为权威来源；早期版本存在 GRAFANA_BASE_URL 凭证中的 URL 会在启动时自动迁移到 settings，之后凭证值仅作兜底。Token 凭证名默认为 GRAFANA_TOKEN，可通过 tokenRef 修改。

多个 Grafana 源站

设置卡片管理的是一个具名 Grafana 源站列表，而不再是单组 URL/令牌。每个源站包含：

• 源站名称（必填、唯一）：中英文皆可。它就是调用工具时传入 source 参数用以指定目标源站的值。
• UID（只读）：自动生成、全球唯一，以淡色小字显示在名称正下方。它是内部稳定主键——改名不会改变 UID，也不会影响已存令牌，且用户无法编辑。
• Grafana URL 与 Service Account Token：每个源站各自独立。令牌以仅写不读的方式存入 DSH 凭证库。新源站使用 GRAFANA_TOKEN_<uid> 引用；轮换已保存的令牌时生成新引用。迁移保留原有引用，包括自定义引用。

点击新增源站创建，移除源站删除，设为默认选择省略 source 时使用哪一台。保存当前源站只保存该卡片，保存全部源站保存所有卡片；写入前校验名称和 URL。移除只删除当前 profile 的源站配置，不自动清除关联凭证。多个 profile 可能共用 DSH 凭证库；当前配置无法证明其他 profile 不再使用某个引用，因此插件暂停自动回收，也不提供删除重试入口。

保存前必须成功读取配置。读取失败或返回畸形数据时，卡片保持只读，并提供重新读取按钮。宿主提供配置版本号时，写入会携带该版本，防止陈旧页面覆盖其它页面的新修改。

令牌变更通过一次配置写入切换到新凭证引用。宿主明确拒绝时，旧配置继续生效；应答丢失时，不推断写入未生效。所有路径均保留已写入或可能写入的凭证，并提示保留原因；成功轮换后旧凭证也保留。成功保存的令牌草稿会清空，其它未保存的编辑予以保留。保留的凭证可能累积，移除源站不等于在 Grafana 撤销令牌；如需撤销访问，应在 Grafana 中撤销相应令牌。

令牌状态区分 configured（已配置）、missing（确认未配置）和 unknown（无法确认）。凭证接口缺失、读取失败或应答畸形时，设置页显示“状态读取失败”，可随时点击重新读取；grafana_sources 输出 token=unknown，不回显凭证值或 provider 错误。已配置只说明凭证存在，不代表 Grafana 鉴权有效。源站草稿是否曾保存由配置基线判断，不依赖令牌状态。

每个工具都接受可选的 source 参数（源站名称），省略则用默认源站。调用 grafana_sources 可列出已配置的名称、UID、URL、令牌是否已配以及哪一台是默认源站。写操作的审批文案首行始终标明目标源站名称与 URL，方便确认改的是哪一台；写入与该源站绑定：等待审批期间默认源站若被改掉，写入会被拒绝，而不是发到执行时随手解析到的那一台。读取—审批—写入整条链路还绑定源站的 URL 与凭证引用，改掉源站地址会使其改前取得的快照失效——id/uid/version 相同并不能证明两次响应来自同一实例。早期版本的单源配置会在启动时迁移为一个名为 default 的源站，并保留其原有的自定义 tokenRef。allowInsecureHttp 仍是全局设置，对所有源站生效。

Grafana 权限

优先使用最小权限 RBAC，只授予目标大盘及文件夹所需范围：

• dashboards:read
• dashboards:write
• 目标文件夹的 folders:read
• grafana_panel_query 需要 datasources:query 以及对所查数据源的访问权限

不支持细粒度 RBAC 时才使用 Editor 角色，避免使用 Admin token。

各工具所需的具体权限：

工具 · Grafana 权限

grafana_get · dashboards:read

grafana_push · dashboards:read + dashboards:write

grafana_clone · dashboards:read + dashboards:write

grafana_panel_query · dashboards:read + datasources:query

grafana_datasources · datasources:read

grafana_metric · datasources:read + datasources:query

grafana_compare · datasources:read + datasources:query（每台源站各自）

grafana_trend · dashboards:read + datasources:query

…(truncated)