dsh-plugin-nlbi

dsh plugin --profile web add dsh-plugin-nlbi

dsh-plugin-nlbi

DeepSeek Harness 的自然语言查询 + 商业智能报表插件。在 dsh-mysql 连接底座之上，提供 Text2SQL、15+ 图表类型、Dashboard 仪表盘、指标/维度管理、多维分析、自助分析、报表导出、审计日志与数据权限。

[English](./README.md)

功能总览

🔌 数据接入

• MySQL 多连接管理（设置页增删改+测试）
• 连接池自动管理（配置变更自动重建）
• 表白名单 + 写权限开关

📐 数据建模与指标管理

• 指标定义：GMV、订单数、客单价等业务指标，支持表达式/聚合类型/格式
• 维度定义：地区、时间、商品类别等分析维度，支持层级定义（省→市→区）
• 数据集：关联表+Join+指标+维度，形成可复用分析模型
• 智能推荐：根据表结构自动推荐指标候选

📊 可视化引擎（15+ 图表类型）

类型 · 用途 · 说明

📊 统计卡 · 单一数值展示 · SUM/AVG/MAX/MIN

📈 折线图 · 趋势分析 · 时间序列数据

📊 柱状图 · 分类对比 · 各类别数值比较

🥧 饼图 · 占比分布 · 低基数类目占比

📊 面积图 · 趋势+规模 · 折线 + 面积填充

🔽 漏斗图 · 转化分析 · 各阶段转化率

🔵 散点图 · 相关性 · 双变量关系

🔥 热力图 · 密度分布 · 时段×维度热力

🕸 雷达图 · 多维对比 · 多维度评分

🔀 桑基图 · 流向分析 · 数据流向

🎯 仪表盘 · 目标完成度 · 单一指标仪表

🗂 矩形树图 · 层级占比 · 树形占比展示

📊 堆叠柱状图 · 堆叠对比 · 多维度堆叠

🌊 瀑布图 · 累计增减 · 逐步增减展示

📏 进度条 · 进度展示 · 完成百分比

📐 Dashboard 仪表盘

• 12 列网格布局，自由拖拽调整组件位置/大小
• 多组件类型：KPI 卡片、图表、表格、文本
• 全局筛选器：下拉选择、日期范围、文本搜索
• 自动刷新（60 秒）
• 复制/编辑/删除 Dashboard
• 多 Dashboard 管理

🔍 智能查询（Text2SQL）

• 自然语言 → SQL 自动生成
• 双层安全护栏（AST + 正则）
• 自动注入表白名单和行级权限
• 自动推荐图表类型
• 分析类型识别（趋势/对比/排名/占比/漏斗/相关）

🔧 自助分析

• 可见字段列表（按类型着色）
• 拖拽式维度/指标选择
• 聚合方式选择（SUM/AVG/COUNT/MIN/MAX）
• 排序 + Top N
• 图表类型选择
• 自动生成 SQL 预览

📋 报表管理

• 收藏查询结果为报表
• 重跑报表（最新数据+图表）
• 导出为 Markdown/CSV/TSV/Excel
• 删除报表

📥 数据导出

• CSV 导出（防注入）
• TSV 导出（适合粘贴到 Excel）
• Markdown 表格复制
• Excel（HTML 格式，兼容 WPS/Office）
• 图表 PNG 导出（前端 ECharts getDataURL）

🔒 数据权限

• 行级权限：按列值过滤（= / IN / LIKE）
• 列级黑名单：禁止查看敏感列
• 查询超时和行数上限
• 权限自动注入到 Text2SQL prompt

📋 审计日志

• 记录所有查询操作（类型/时间/耗时/成功/失败）
• 环形缓冲（最多 1000 条）
• 侧栏面板查看

📐 多维分析

• 同比增长率计算
• 环比增长率计算
• 累计值计算
• 移动平均（窗口可调）
• Top N 排名
• 排名计算
• 增长率计算

安装

从 npm 安装（推荐）

# 安装最新稳定版
 dsh plugin --profile web add dsh-plugin-nlbi@latest

# 或固定安装当前版本
 dsh plugin --profile web add dsh-plugin-nlbi@0.2.1

npm 包地址：<https://www.npmjs.com/package/dsh-plugin-nlbi>

从本地源码/压缩包安装（开发测试）

pnpm pack
dsh plugin --profile web add C:\path\to\dsh-plugin-nlbi-0.2.1.tgz

安装后，如果当前没有运行中的 DSH Web 实例，再启动：

dsh web

如果提示 EADDRINUSE: 127.0.0.1:3080，说明 DSH Web 已经运行，直接打开 <http://127.0.0.1:3080>，不要重复启动。安装后打开 设置 → Nlbi 数据库，添加连接并点「测试连接」。

快速上手

1. 添加连接：打开 设置 → Nlbi 数据库 → + 添加连接，填写主机/端口/账号/密码/默认库

2. 选择连接：在会话输入栏左侧点击 🐬 按钮，选择刚添加的连接

3. 自然语言查库：在输入框输入"上个月每天的订单量"或"各分类商品数量"

4. 创建 Dashboard：在右侧栏 📐 仪表盘 标签页，点击「+ 新建」

5. 定义指标：在右侧栏 📐 指标 标签页，定义 GMV、订单数等业务指标

6. 自助分析：在右侧栏 🔧 自助分析 标签页，拖拽字段生成分析

架构

                    BI 平台
                       │
       ┌───────────────┼───────────────┐
       ↓               ↓               ↓
   数据接入          数据建模         权限管理
       │               │               │
       ↓               ↓               ↓
 MySQL/Excel/API    Dataset/指标    RBAC/行级权限
       │               │
       └───────→ 指标层 ←──────────────┘
                    │
                    ↓
              可视化分析引擎
                    │
       ┌────────────┼────────────┐
       ↓            ↓            ↓
    Dashboard     自助分析      报表
       │            │            │
       └────────────┼────────────┘
                    ↓
              多维分析引擎
                    │
          ┌─────────┼─────────┐
          ↓         ↓         ↓
        下钻       联动       筛选
                    │
               发布/分享
                    │
          ┌─────────┼─────────┐
          ↓         ↓         ↓
        Excel      PDF       大屏

安全模型

• 双层 SQL 安全：AST 级校验（node-sql-parser）+ 正则级校验（shared.js）
• 强制只读：nl_query/mysql_query 仅接受 SELECT/SHOW/DESCRIBE/EXPLAIN
• 表白名单：超出白名单的表引用直接拒绝
• 行级权限：自动注入 WHERE 条件
• 列级黑名单：禁止查看敏感列
• LIMIT 注入：自动补 LIMIT 2000，拒绝无限制查询
• 超时保护：MAX_EXECUTION_TIME(15000ms) 优化器提示

开发

node --check lib\index.js lib\shared.js lib\sqlsafe.js lib\text2sql.js lib\chart.js lib\metrics.js lib\dashboard.js lib\export.js lib\typert.host.js lib\client.js
node test\shared.test.mjs
node test\sqlsafe.test.mjs
node test\text2sql.test.mjs
node test\chart.test.mjs
node test\chart-v2.test.mjs
node test\metrics.test.mjs
node test\dashboard.test.mjs
node test\export.test.mjs

版本历史

v0.2.0（2026-08-23）

• 🎉 全面升级为企业级 BI 报表系统
• 📐 新增指标/维度/数据集管理
• 📊 扩展 15+ 图表类型（漏斗/散点/热力/雷达/桑基/仪表盘/树图/面积/堆叠/瀑布/进度条）
• 📐 新增 Dashboard 仪表盘（网格布局/多组件/全局筛选器/自动刷新）
• 🔍 增强 Text2SQL prompt（指标感知/分析类型/chartType 输出）
• 🔧 新增自助分析面板（拖拽字段→生成 SQL）
• 📥 新增数据导出（CSV/TSV/Markdown/Excel）
• 📋 新增审计日志
• 🔒 新增行级权限和列级黑名单
• 📐 新增多维分析函数（同比/环比/累计/移动平均/TopN/排名）

v0.1.1

• 基础 Text2SQL 自然语言查库
• 4 种图表类型（bar/line/pie/stat）
• 报表收藏
• 侧栏数据面板（SchemaTree + GridPanel）