# grafana-bridge-cli

**Repository Path**: gfs_5/grafana-bridge-cli

## Basic Information

- **Project Name**: grafana-bridge-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Grafana-bridge-cli

`gfb` 是参照 `grafana-bridge` 里的查询桥接实现改出来的一套命令行工具。它复用了同样的 Grafana 配置和桥接思路，只是把服务调用方式改成了本地 CLI 子命令，适合在终端里直接查库、看表结构、跑只读 SQL。

## 工具作用

- 支持 MySQL / PostgreSQL 两种 Grafana 数据源桥接
- 支持多环境 `.env` 配置切换
- 默认按命名规则加载环境相关的业务提示词
- 覆盖原桥接能力的主要命令：
  - `init`
  - `list-databases`
  - `list-schemas`（仅 PostgreSQL）
  - `list-tables`
  - `describe-table`
  - `query-sql`
  - `health`
  - `get-environment`
  - `get-current-time`
  - `list-tools`
- 输出支持 `table` / `json` / `text`

## 安装

推荐直接从 Gitee 安装：

```bash
uv tool install git+https://gitee.com/gfs_5/grafana-bridge-cli.git
```

如果已经安装过，需要强制覆盖安装（更新到最新版本）：

```bash
uv tool install --force git+https://gitee.com/gfs_5/grafana-bridge-cli.git
```

安装后可直接执行：

```bash
gfb --help
```

卸载：

```bash
uv tool uninstall grafana-bridge-cli
```

当前会同时安装 `gfb` 和兼容别名 `grafana-bridge-cli`，后续建议统一使用 `gfb`。

### 安装 AI Skill

如果你会在 AI 工具里使用 `gfb`，建议在安装 CLI 后紧接着安装 skill。

- `npx skill(s) add` 要求目标 Git 仓库根目录存在 `skills/` 目录。
- 本仓库已提供可安装技能：
  - `skills/gfb-cli/SKILL.md`
  - `skills/gfb-evolution-summary/SKILL.md`

```bash
# 使用 HTTPS 地址安装（默认安装到所有支持的 AI 工具）
npx skills add https://gitee.com/gfs_5/grafana-bridge-cli.git -y

# 或使用 SSH 地址安装
npx skills add git@gitee.com:gfs_5/grafana-bridge-cli.git -y
```

如果需要指定安装到特定的 AI 工具，可以使用 `--agent` 参数：

```bash
# 仅安装到 Kiro (Claude Code)
npx skills add https://gitee.com/gfs_5/grafana-bridge-cli.git --agent claude-code -y

# 仅安装到 Cursor
npx skills add https://gitee.com/gfs_5/grafana-bridge-cli.git --agent cursor -y

# 仅安装到 Windsurf
npx skills add https://gitee.com/gfs_5/grafana-bridge-cli.git --agent windsurf -y

# 安装到多个工具（用空格分隔）
npx skills add https://gitee.com/gfs_5/grafana-bridge-cli.git --agent claude-code cursor windsurf -y

# 安装到所有支持的工具
npx skills add https://gitee.com/gfs_5/grafana-bridge-cli.git --agent '*' -y
# 或使用 --all 快捷方式
npx skills add https://gitee.com/gfs_5/grafana-bridge-cli.git --all
```

支持的 AI 工具 agent 名称：
- `claude-code` - Kiro (Claude Code)
- `cursor` - Cursor
- `windsurf` - Windsurf
- `cline` - Cline
- `codebuddy` - CodeBuddy
- `qoder` - Qoder
- `trae` - Trae
- `trae-cn` - Trae CN (中文版)
- `openclaw` - OpenClaw

查看已安装的 skills：

```bash
# 查看项目级 skills
npx skills list

# 查看全局 skills
npx skills list -g

# 查看特定 agent 的 skills
npx skills list -a claude-code

# 以 JSON 格式查看
npx skills list -g --json
```

如果需要从源码开发安装：

```bash
cd grafana-bridge-cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## 快速使用

```bash
uv tool install git+https://gitee.com/gfs_5/grafana-bridge-cli.git
```

1. 初始化一个环境配置。

```bash
gfb init prod
```

这会生成：

```text
.gfb/
├── hooks.json
└── envs/
    └── prod/
        ├── .env
        ├── hint.md
        ├── ontology.ttl
        ├── query-patterns.md
        ├── schema-knowledge.md
        └── optimization-tips.md
```

2. 编辑 `.gfb/envs/prod/.env`，填入真实 Grafana 连接信息。

3. 验证配置是否可用。

```bash
gfb --env prod health
gfb --env prod get-environment --format json
```

## 配置

默认只读取当前目录 `.gfb/` 下的环境文件：

- `.gfb/envs/prod/.env`
- `.gfb/envs/<环境名>/.env`

如果配置文件不在 `.gfb/` 下，请通过 `--env-file` 直接指定路径。

可通过 `gfb init <env>` 生成示例配置模板，实际项目建议放在当前目录 `.gfb/envs/<环境名>/.env`。

最小配置示例：

```env
ENVIRONMENT_DESCRIPTION="示例环境"
SERVICE_TYPE=mysql
GRAFANA_URL=http://grafana.example.com
GRAFANA_API_KEY=your-api-key
GRAFANA_DATASOURCE_UID=your-datasource-uid
```

常见初始化命令：

```bash
# 生成 prod 环境
gfb init prod

# 生成 PostgreSQL 环境并覆盖已有文件
gfb init dev --service-type postgres --force
```

## Hints 使用

`gfb` 默认会按环境名读取 `.gfb/envs/<env>/hint.md`，用于向调用方暴露环境说明和业务上下文。

默认命名规则：

```text
.gfb/envs/prod/.env  ->  .gfb/envs/prod/hint.md
.gfb/envs/225/.env   ->  .gfb/envs/225/hint.md
```

如果需要沉淀业务知识，建议通过 `skills/gfb-cli/SKILL.md` 和 `skills/gfb-evolution-summary/SKILL.md` 中约定的流程维护对应 hints 与进化记录。

- CLI 默认读取 `.gfb/envs/<env>/hint.md` 作为基础环境提示词。
- 如果确实需要覆盖默认规则，仍然可以显式配置 `CLIENT_HINT=file:...`。
- `.gfb/envs/<env>/query-patterns.md`、`.gfb/envs/<env>/schema-knowledge.md`、`.gfb/envs/<env>/optimization-tips.md` 这类业务 hints 由使用 `gfb` skill 的 AI 在会话中按规则读取和维护。
- `.gfb/envs/<env>/ontology.ttl` 用于沉淀结构化本体信息（表、关系、查询引用）。

推荐流程：

1. 进入某个环境后，先执行 `gfb --env <env> get-environment --format json`，让调用方先看到当前环境说明和基础 hints。
2. 在查询过程中，先探查结构，再执行只读 SQL。
3. 会话结束前，由使用 `gfb` skill 的 AI 根据本次查询结果总结稳定、可复用、可验证的业务知识。
4. 将总结后的内容写入对应 hints 文件，而不是写原始日志或一次性结果。

建议按内容类型维护 hints：

- `query-patterns.md`：可复用 SQL 模板、过滤口径、统计方式。
- `schema-knowledge.md`：表用途、关键字段、字段语义、关联关系。
- `optimization-tips.md`：查询顺序、性能经验、稳定排错方法。

## 自进化机制

`gfb` 的自进化分成两层：`Skill` 进化负责工具使用经验，`Hints` 进化负责业务知识沉淀。

默认通过项目级 hook 配置 `.gfb/hooks.json` 的 `after_round` 事件自动触发。普通查询命令会在执行后自动记录会话并尝试运行 hooks（`auto_execute_hooks=true`）。

如需手动补跑某轮会话，也可以显式调用：

```bash
gfb --env <env> --session-id <session-id> --actor-id <actor-id> run-hooks --event after_round
```

### Hook 使用说明（推荐）

#### 1) 初始化

首次在项目中执行以下命令（`gfb init` 已默认创建 `hooks.json`，这里给出显式方式）：

```bash
gfb init prod
# 或者单独初始化/重置 hook 配置
gfb init-hooks
```

#### 2) 先获取环境与渐进上下文（推荐）

在每轮查询前，建议先读取环境上下文。默认 `smart` 模式会返回：

- 基础环境提示（`hint.md`）
- 索引信息（hints + evolution）
- 与任务关键词相关的少量片段（减少一次性加载过多提示词）
- 当任务中出现表名（如 `users`、`t_order`）时，会优先召回 `ontology.ttl` 中对应表与关系片段

```bash
gfb --env prod get-environment --context-mode smart --task "查询 dcp_case 案例数量"
```

可选模式：

- `base`: 仅基础提示
- `index`: 仅索引
- `smart`: 索引 + 相关片段（默认）
- `full`: 更大范围上下文

#### 3) 执行查询时携带会话 ID（可选）

在同一轮会话里，所有 `gfb` 命令都建议带同一个 `--session-id`，用于聚合本轮轨迹。若不传，CLI 会按环境自动生成并复用会话 ID：

```bash
gfb --env prod --session-id round-20260419-01 list-databases
gfb --env prod --session-id round-20260419-01 list-tables --database your_db
gfb --env prod --session-id round-20260419-01 query-sql "SELECT id FROM your_db.your_table LIMIT 10"
```

也可以通过环境变量统一注入：

```bash
export GFB_SESSION_ID=round-20260419-01
export GFB_ACTOR_ID=alice__alice@example.com
```

#### 4) 会话收尾触发 after_round

```bash
gfb --env prod --session-id round-20260419-01 --actor-id alice__alice@example.com run-hooks --event after_round
```

仅检查本轮会执行哪些 hook（不执行）：

```bash
gfb check-hooks --event after_round
gfb --env prod --session-id round-20260419-01 run-hooks --event after_round --dry-run
```

#### 5) 产物位置

- 运行轨迹：`.gfb/runtime/events/<session-id>.jsonl`
- Skill 进化：
  - `.gfb/evolution-by-user/<actor-id>/skill-evolution.md`
  - `.gfb/evolution-by-user/<actor-id>/skill-exceptions.md`
  - `.gfb/evolution-by-user/<actor-id>/skill-best-practices.md`
- Hints 进化：
  - `.gfb/envs/<env>/ontology.ttl`
  - `.gfb/envs/<env>/query-patterns.md`
  - `.gfb/envs/<env>/schema-knowledge.md`
  - `.gfb/envs/<env>/optimization-tips.md`

#### 6) 常见问题

- 没有产生任何进化内容：先确认 `.gfb/hooks.json` 中 `auto_execute_hooks` 是否为 `true`，再检查本轮是否有实际查询命令执行。
- `run-hooks` 报 session 为空：补充 `--session-id`，或先执行至少一条普通命令让 CLI 自动创建会话。
- actor 目录不符合预期：显式传 `--actor-id`，否则默认 `machine-unknown`（或读取 `GFB_ACTOR_ID`）。

### Skill 进化

- 目标：沉淀 `gfb` 本身怎么用得更稳、更快、更少出错。
- 内容：命令顺序、参数约束、错误处理、权限边界、排错路径、最佳实践。
- 存储位置：`.gfb/evolution-by-user/<actor_id>/`
- 典型文件：
  - `skill-evolution.md`
  - `skill-exceptions.md`
  - `skill-best-practices.md`
- 统一协议：`gfb-evolution-summary/v1`（手动与自动进化共用）
- 触发方式：由 `after_round` hook 检查本轮 session 事件后自动写入；也可由 AI 手动补充。
- 写入原则：append-only，记录的是工具经验，不写业务表结构或业务结论。

### Hints 进化

- 目标：沉淀当前项目、当前环境下可复用的业务知识。
- 内容：环境说明、查询模板、字段语义、关联关系、查询优化建议。
- 存储位置：
  - `.gfb/envs/<env>/hint.md`
  - `.gfb/envs/<env>/ontology.ttl`
  - `.gfb/envs/<env>/query-patterns.md`
  - `.gfb/envs/<env>/schema-knowledge.md`
  - `.gfb/envs/<env>/optimization-tips.md`
- 触发方式：由 `after_round` hook 根据本轮查询轨迹自动沉淀（SQL 模式/表线索/优化建议），也可由 AI 手动补充高质量业务结论。
- 写入原则：写稳定、可复用、可验证的结论，不写原始日志或一次性结果。

### 边界说明

- `Skill` 进化只写工具经验，不写业务知识。
- `Hints` 进化只写业务知识，不写纯工具使用心得。
- 若未传 `--session-id`（且未设置 `GFB_SESSION_ID`），CLI 会自动按环境创建并复用会话 ID。

## 详细命令

### 常用场景

```bash
# 默认读取 .gfb/envs/prod/.env
gfb list-databases

# 指定环境后缀
gfb --env 236 list-databases

# 指定输出格式
gfb --env 236 --format json get-environment

# MySQL
gfb --env 225 list-tables --database dcp_614
gfb --env 225 describe-table --database dcp_614 --table dcp_resource
gfb --env 225 query-sql "SELECT * FROM dcp_614.dcp_resource LIMIT 10"

# PostgreSQL
gfb --env pg list-schemas
gfb --env pg list-tables --schema public
gfb --env pg describe-table --schema public --table users
```

### 命令语法

```bash
gfb [--env ENV] [--env-file PATH] [--format table|json|text] [--session-id ID] [--actor-id ID] [--verbose] <command>
```

### 子命令

- `init`
- `init [env_name] [--env-name <name>] --service-type mysql|postgres [--force]`
- `list-databases`
- `list-schemas`
- `list-tables --database <name>` 或 `--schema <name>`
- `describe-table --database <name> --table <name>`
- `describe-table --schema <name> --table <name>`
- `query-sql "<sql>"`
- `query-sql --file query.sql`
- `init-hooks [--force]`
- `check-hooks --event <event>`
- `run-hooks --event <event> [--dry-run]`
- `health`
- `get-environment`
- `get-current-time`
- `list-tools`

## 约束

- MySQL 默认禁止 `DELETE` / `DROP` / `TRUNCATE` / `UPDATE` / `REPLACE`
- PostgreSQL 默认禁止 `DELETE` / `DROP` / `TRUNCATE` / `UPDATE` / `REPLACE` / `ALTER` / `CREATE`
- 建议查询时自行加 `LIMIT`

## 兼容性说明

这套 CLI 保留了 `grafana-bridge` 的核心配置字段：

- `ENVIRONMENT_DESCRIPTION`
- `SERVICE_TYPE`
- `GRAFANA_URL`
- `GRAFANA_API_KEY`
- `GRAFANA_USERNAME`
- `GRAFANA_PASSWORD`
- `GRAFANA_DATASOURCE_UID`
- `HTTP_PROXY`
- `HTTPS_PROXY`
- `CLIENT_HINT`

这样你可以直接把原来的 `.env` 文件迁过来用；如果不配置 `CLIENT_HINT`，会自动按环境名加载 `.gfb/envs/<env>/hint.md`。