dsh-plugin-nlbi

Natural-language data queries + BI reports for DeepSeek Harness.

在 DeepSeek Harness 对话里，用自然语言问数据库；答案不只是文字，而是「可编辑的 SQL + 可交互的数据表格 + 可复用的 BI 图表/报表」。

基于 dsh-mysql (v0.1.4) 连接底座二次开发，保留全部既有功能的同时，新增 Text2SQL、BI 图表、报表收藏、侧栏数据面板（借鉴 IDEA Database 工具窗）。

Features

继承上游（dsh-mysql v0.1.4）

• 设置页连接管理：多套 MySQL 连接 CRUD（表白名单/写权限/测试连通性）
• 会话级连接选择：输入栏 🐬 按钮一键切换当前会话连接
• 3 个全局 Agent 工具：

新增能力（本插件）

安全模型

• nl_query 强制只读（即使连接开了写权限）
• 双层 SQL 校验：AST 级（node-sql-parser）+ 正则级（上游 shared.js），100% 防写操作泄露
• 表白名单、单语句、MAX_EXECUTION_TIME(15000)、2000 行截断
• 生成 SQL 以草稿展示，运行需显式点击（防模型幻觉）

Quick Start

前置条件

• Node.js >= 18
• pnpm（推荐）或 npm
• DeepSeek Harness 已安装并配置好 web profile

安装

# 从 npm 安装最新稳定版（推荐）
dsh plugin --profile web add dsh-plugin-nlbi@latest

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

# 重启 DSH（仅当当前没有实例运行时）
dsh web

npm package: https://www.npmjs.com/package/dsh-plugin-nlbi

如果启动时提示 EADDRINUSE: address already in use 127.0.0.1:3080，说明 DSH Web 已经运行，直接打开 http://127.0.0.1:3080，不要重复执行 dsh web。

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

pnpm pack
dsh plugin --profile web add ./dsh-plugin-nlbi-0.2.1.tgz

前置插件（可选，推荐）

要使用右侧栏全能工作台，建议安装侧栏支持插件：

# 安装 dsh-better-sidebar（推荐，轻量）
dsh plugin --profile web add dsh-better-sidebar

# 或安装 @linxin666/dsh-web-ui-all（功能更全）
dsh plugin --profile web add @linxin666/dsh-web-ui-all

# 重启 DSH
dsh --profile web

不安装前置插件也能使用本插件的核心功能：🐬 输入栏连接选择、💬 对话中 nl_query / mysql_query 工具、设置页连接管理。

配置数据库连接

1. 打开浏览器 → http://127.0.0.1:3080
2. 进入 设置 → Nlbi 数据库（唯一新增的 tab）
3. 点击「+ 添加连接」，填写数据库信息
4. 点击「测试连接」确认连通，点击「保存」

使用方式

方式 A：对话中自然语言查库

用户：上个月每天的订单量是多少？
Agent：调用 nl_query → 生成 SQL → 返回表格 + 图表

方式 B：右侧栏全能工作台 打开右侧栏 → 🛢 Nlbi 数据库 tab，内含 3 个子区：

Screenshots

右侧栏工作台（智能查询 / 数据浏览 / 报表 三合一）
┌─────────────────────────────────────────────┐
│ 🔌 dsh-test · dsh_test          ▼           │
│ [🔍 智能查询] [🗂 数据浏览] [📊 报表]      │
├─────────────────────────────────────────────┤
│ 💬 查询所有用户                              │
│ [🔍 查询]  [💬 发到对话]                     │
│ 💡 查询所有用户  💡 统计各分类商品数量        │
│ 💡 上个月每天的订单量  💡 订单最多的前5个用户  │
│ ┌─ 生成 SQL（只读）──────────────────────┐  │
│ │ SELECT * FROM users LIMIT 2000          │  │
│ │ [复制 SQL] [💾 收藏为报表]              │  │
│ └────────────────────────────────────────┘  │
│ ┌─ [表格 (50)] [图表] ────────────────────┐ │
│ │ id │ name │ email │ status │ created_at  │ │
│ │ 1  │ 张三  │ ...   │ active │ 2026-...   │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Architecture

┌───────────────────────────── DSH Web 浏览器 ─────────────────────────────┐
│                                                                           │
│  lib/client.js（单文件 bundle，React 无 JSX）                             │
│    ├─ 🐬 输入栏连接选择器（会话级）                                        │
│    ├─ ⚙️ 设置页「Nlbi 数据库」连接管理                                     │
│    ├─ 📊 BI 结果渲染（对话输出渲染表格/图表）                                │
│    └─ 🛢 右侧栏全能工作台（智能查询/数据浏览/报表）                          │
└───────────────┬────────────────────────────────────────────┬──────────────┘
                │                                            │
┌───────────────▼──────────────── DSH Host (Node) ──────────▼──────────────┐
│  lib/index.js（连接管理 + 5 工具 + 14 RPC 服务）                          │
│                                                                           │
│  新增模块：                                                                │
│  ├─ sqlsafe.js    AST 级 SQL 安全校验（分类/白名单/LIMIT 改写/一站式）      │
│  ├─ text2sql.js   Text2SQL 编排（Schema 注入/LLM 调用/JSON 解析/护栏执行）  │
│  └─ chart.js      BI 图表规格生成（5 类场景启发式）                         │
│                                                                           │
│  工具：mysql_query / mysql_tables / mysql_execute / nl_query / sql_to_chart │
└────────────────────────────────────────────────────────────────────────────┘

技术栈

Test

cd dsh-plugin-nlbi

# 语法检查
node --check lib/index.js lib/shared.js lib/sqlsafe.js lib/text2sql.js \
  lib/chart.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

当前测试覆盖：69 组断言，全部通过 ✅

Development

# 克隆
git clone https://github.com/1byteone/dsh-plugin-nlbi.git
cd dsh-plugin-nlbi

# 安装依赖
pnpm install

# 本地打包安装
pnpm pack
dsh plugin --profile web add dsh-plugin-nlbi-*.tgz

# 重启 DSH
dsh --profile web

Limitations

Changelog

0.1.1 (2026-08-23)

• 新增：前置插件检测与安装提示（无 betterSidebar 时显示引导卡片）
• 优化：降低 betterSidebar 依赖，无侧栏时自动降级为设置页连接管理
• 发布：npm + GitHub + awesome-dsh-plugin 三路分发

0.1.0 (2026-08-23)

• 首个稳定版本发布
• Text2SQL、BI 图表、报表收藏、侧栏数据面板
• 独立 Git 仓库 + GitHub Release + npm 发布

License

MIT

Acknowledgements

Forked from dsh-mysql (v0.1.4, MIT) by 1321928757.

Links

• GitHub
• npm
• DSH Plugin 开发教程
• DeepSeek Harness