前言¶
DeepSeek Harness（DSH）通過插件機制擴展能力，其中 dsh-mysql 插件提供了基礎的 MySQL 連接管理與查詢工具。在此基礎上，dsh-plugin-nlbi 插件增加了自然語言查詢（Text2SQL）與商業智能（BI）報表功能。該插件旨在降低 SQL 編寫門檻，讓開發者或業務人員能通過自然語言與數據庫交互，並直接生成可視化圖表。
該插件由 1byteone 維護，基於 dsh-mysql（v0.1.4）的連接底座進行二次開發，保留了原有的連接管理能力，同時新增了智能查詢、圖表生成與報表收藏等特性。
核心功能¶
插件提供了以下主要能力：
- 自然語言查詢 (
nl_query)：基於 Text2SQL 技術，將自然語言轉換爲 SQL 語句。生成過程包含 AST 語法樹校驗與正則校驗，確保安全性。 - BI 圖表生成 (
sql_to_chart)：根據查詢結果自動生成圖表規格，支持多種圖表類型。 - 報表收藏與管理：提供
save_report、list_reports、delete_report和rerun_report等接口，用於管理生成的報表。 - 數據瀏覽器：包含 SchemaTree（表結構導航樹）與 GridPanel（數據網格），支持在右側欄進行表結構瀏覽、數據預覽、分頁、排序及 WHERE 過濾。
- 智能查詢與側欄工作臺：提供右側欄工作臺，集成智能查詢、數據瀏覽與報表功能。
- 繼承的連接管理工具：繼承了
dsh-mysql的工具，包括mysql_query（只讀查詢）、mysql_tables（查看錶結構）和mysql_execute（寫操作）。
安裝與啓用¶
安裝前請確保已安裝 Node.js >= 18。
# 安裝最新穩定版插件
dsh plugin --profile web add dsh-plugin-nlbi@latest
安裝完成後，需要重啓 DeepSeek Harness Web 進程：
dsh web
如果啓動時提示端口占用（如 EADDRINUSE: address already in use 127.0.0.1:3080），說明服務已在運行，直接訪問 http://127.0.0.1:3080 即可，無需重複執行安裝命令。
典型用法¶
1. 對話中自然語言查庫¶
在 DSH 的對話輸入框中輸入自然語言，系統將調用 nl_query 工具。生成的 SQL 以草稿形式展示，需用戶顯式點擊“運行”按鈕執行。
- 示例：
用戶：上個月每天的訂單量是多少？
系統調用：nl_query
結果：返回表格數據及對應的 BI 圖表
2. 右側欄全能工作臺¶
右側欄功能依賴 betterSidebar 或 dsh-web-ui-all 插件。若未安裝前置插件，系統會自動降級處理，核心功能仍可通過設置頁使用。
打開右側欄，進入 Nlbi 數據庫 tab，包含三個子區：
- 智能查詢：輸入自然語言，即時返回表格和圖表，支持一鍵“發到對話”。
- 數據瀏覽：通過左側 SchemaTree 選擇表，右側 GridPanel 展示數據。
- 報表：自然語言生成圖表，支持收藏、重跑與導出。
注意事項¶
- LLM 依賴：
nl_query的 Text2SQL 功能依賴於 LLM 服務（如 DeepSeek 或 OpenAI）。 - 僅支持 MySQL：插件繼承自
dsh-mysql，目前僅支持 MySQL 數據庫。 - 安全性：
nl_query強制執行只讀操作，即使數據庫連接開啓了寫權限。SQL 生成經過雙層校驗（AST + 正則），防止寫操作泄露。 - 圖表導出：圖表導出當前僅支持導出 SQL（Markdown 格式）。
- 側欄依賴：右側欄的智能查詢、數據瀏覽和報表功能需要
betterSidebar或dsh-web-ui-all插件支持，但已做降級處理，無側欄時功能仍可使用。
