WorkBuddy Grafana 连接器

一个 WorkBuddy 连接器，用于 Grafana：通过自然语言读取实时观测数据并安全编辑大盘。

English

核心能力

• 通过浏览器 URL 或 UID 获取大盘完整 JSON 或结构化摘要。
• 查询面板背后的实时数据（PromQL、LogQL、adhoc 过滤、模板变量）。
• 无需大盘直接运行裸 PromQL/LogQL 查询。
• 检查当前正在告警的条目和规则定义。
• 按标题和标签搜索大盘。
• 用 grafana_clone 复制大盘。
• 用 grafana_push 更新大盘——每次写入都需要用户明确审批。
• 多个具名 Grafana 源站，每个源站独立凭证。
• Service Account Token 仅存储在本机，绝不暴露给模型。

环境要求

| 组件 | 要求 | | --- | --- | | WorkBuddy | 5.0.0 或更高 | | Node.js | 20.3 或更高（WorkBuddy 会托管运行时）| | Grafana | Grafana 10/11（传统 Dashboard HTTP API） |

安装

通过 WorkBuddy 连接器市场安装，或本地加载用于开发。

Token 配置

连接后需要配置：

1. Grafana 地址 — 你的 Grafana 实例地址（如 https://grafana.example.com）
2. Service Account Token — 在 Grafana → Administration → Service Accounts 中创建

管理多个 Grafana 源站

连接器支持多个具名 Grafana 源站。第一个源站用上面两个必填字段配置。要添加、编辑或删除更多源站，需要开启可选的本地管理界面：

1. 在连接表单里填写可选的「本地管理界面端口」——填 1 自动分配空闲端口，或直接填端口号如 18999。
2. 在 WorkBuddy 中重新连接，让新设置生效。
3. 在浏览器中打开 http://127.0.0.1:<端口>。完整地址会在启动时输出到 stderr。
4. 使用 Web 界面添加源站、设为默认、轮换 Token 和删除源站。
5. Token 值加密存储，不会回显。配置变更跨重启持久保存。
   • macOS 生产入口把加密主密钥保存在登录钥匙串中；旧版 .key 会在迁移验证成功后移除。
   • 凭证清理失败会显示为持久待办，可在页面中重试；重试前会确认没有源站仍引用该凭证。
6. 要关闭管理界面，清空该字段并重新连接。

管理界面只监听 127.0.0.1，外部网络无法访问。该字段留空（默认）即完全不启动。

测试或临时联调可用 WORKBUDDY_GRAFANA_DATA_DIR 指定隔离数据目录。WORKBUDDY_GRAFANA_KEY_BACKEND=file 仅用于隔离测试或尚未验证系统凭证库的平台，不建议在 macOS 生产配置中使用。

Grafana 权限

| 工具 | 权限 | | --- | --- | | grafana_get / grafana_search / grafana_status | dashboards:read | | grafana_push / grafana_clone | dashboards:read + dashboards:write | | grafana_panel_query / grafana_trend | dashboards:read + datasources:query | | grafana_datasources | datasources:read | | grafana_metric | datasources:read + datasources:query | | grafana_alerts | alert.instances:read（definitions: true 另需 alert.provisioning:read） | | grafana_sources | 无（只读本机配置） |

工具

11 个有效工具 + 2 个旧名别名：

| 工具 | 行为 | | --- | --- | | grafana_get | 获取完整大盘 JSON（记录写快照）或结构化摘要（只读）。 | | grafana_push | 在审批、版本检查和目录保持后写回大盘。 | | grafana_clone | 把大盘复制为全新大盘。需要审批。 | | grafana_panel_query | 执行面板查询，返回有界统计数据摘要。 | | grafana_datasources | 列出数据源（类型、名称、默认、URL）。 | | grafana_metric | 对指定数据源运行裸 PromQL/LogQL 查询。 | | grafana_trend | 回答"在涨还是在跌？"，含桶化趋势与火花线。 | | grafana_alerts | 列出活跃告警，可选附加规则定义。 | | grafana_search | 按标题和标签搜索大盘（最多 50 条）。 | | grafana_status | 检查 Grafana 连通性与凭证有效性。 | | grafana_sources | 列出已配置源站。绝不返回令牌值。 |

写入安全

• 每次写入（grafana_push、grafana_clone）都需要通过 MCP elicitation 获得用户明确审批。
• 审批绑定到特定源站、大盘身份和版本——审批后换源会被拒绝。
• POST 前检测版本冲突。
• POST 不自动重试。
• 写入结果经校验（status、uid、version 必须齐全）。
• 写入默认禁用。要启用，请在连接表单里把可选的「启用大盘写入」填为 true 并重新连接——且需先确认当前 WorkBuddy 客户端的逐次 MCP elicitation 确实可用。
• 开关只接通审批协调器，不会跳过可信快照、版本、目录、源站或凭证代次检查。

开发

npm install
npm run verify

许可证

MIT。详见 LICENSE。

本项目为个人作品，不隶属于 Grafana Labs 或 WorkBuddy，也未获其认可。