dsh-de-workbench

Data Engineer 数据分析工作台 · 在 DSH（DeepSeek Harness）上用自然语言直接问数据

   

连接数据源 → 自然语言提问 → 自动生成并执行 SQL → 得到结论、结果表与可交付成果

功能特性 · 快速开始 · 使用场景 · 界面速览 · 数据源支持 · 安全与隐私 · 常见问题 · 开发 · 开源协议

---

功能特性

数据分析通常卡在"问人要 SQL、手动拼 Excel、换个工具调图表"——dsh-de-workbench 让分析回归提问本身：

• 💬 零门槛对话即分析：直接用大白话提问（如"近 30 天各渠道收入对比"），AI 自动探查库表结构、编写并执行 SQL、输出结论。全程不需要手写 SQL。
• 🗂️ 多数据源直连：duckdb / SQLite / PostgreSQL / MySQL，以及 CSV / Excel / Parquet / JSON 文件型数据源——建好连接即可开问。
• 📚 业务口径内置（知识库注入）：语义模型（表/字段业务含义 + 指标口径公式）+ 参考 SQL 主题树随会话注入，AI 优先按你确认过的口径作答，不凭常识瞎猜。
• 🎯 分析质量三重保障：SQL 错误结构化诊断与自纠错 → 结果形态校验（空结果/截断/缺 LIMIT 的精确 warning）→ LLM 答案校验兜底；结论卡片带「⚠ 警示 / ✓ 已校验」可信度徽标，可疑之处可一键追问修正。
• 🧩 技能方法论包：预置 metric-first（口径优先）/ sql-quality（SQL 规范）/ clarify-first（澄清规范）/ values-probe（值域探查）/ time-axis（时间口径）五个分析技能，按需启停，AI 遵循方法论作答。
• 📊 成果自动落盘与交付：每回合结论（问题 + SQL + 结果表）自动保存为 Markdown 报告；支持 CSV / Excel 导出、离线 HTML 报告（含自绘 SVG 图表），可直接分享给不使用 DSH 的同事。
• 🔍 本地语义检索：schema 向量索引（LanceDB 内嵌）+ 本地语义模型（bge-small-zh-v1.5 自动下载），中文问题 × 英文表名跨语言检索。
• 🛠️ 提示词透明可调：影响 NL2SQL 的全部内置提示词（工具描述 / 注入引言 / 校验指令）数据化，在面板中直接查看与优化，保存即热生效。

快速开始

环境要求

• DeepSeek Harness（DSH）已安装（pnpm dsh web 可启动，浏览器打开 http://127.0.0.1:3080）
• 一个可访问的数据源（本地 duckdb / SQLite 文件即可起步）

安装插件

任选一种方式（构建产物均已打包/入库，无需本地构建）。推荐方式一：从 GitHub Releases 安装，版本锁定、升级明确。

# 方式一：从 GitHub Releases 安装（推荐，版本锁定）
#   最新版链接见 https://github.com/WaySeeSee/dsh-de-workbench/releases
pnpm dsh plugin --profile web add "https://github.com/WaySeeSee/dsh-de-workbench/releases/download/v1.0.0/dsh-de-workbench-1.0.0.tgz"

# 方式二：从 GitHub 仓库直接安装（跟随仓库最新提交）
pnpm dsh plugin --profile web add "github:WaySeeSee/dsh-de-workbench"

# 方式三：从本地打包文件安装（离线 / 内网分发）
pnpm dsh plugin --profile web add "/路径/dsh-de-workbench-1.0.0.tgz"

# 方式四：克隆到本地后以 link 方式安装（适合二次开发）
git clone https://github.com/WaySeeSee/dsh-de-workbench.git
pnpm dsh plugin --profile web add "link:/绝对路径/dsh-de-workbench"

⚠ 首次安装（任选方式）会编译原生模块（duckdb / onnxruntime 等）。若 pnpm 提示 ERR_PNPM_IGNORED_BUILDS，在 profile 的 pnpm-workspace.yaml 中把对应依赖的 allowBuilds 设为 true 后重新执行安装命令。

⚠ 开发建议：将插件安装到独立的 dev profile（--profile web-dev 配合独立 DSH_HOME），避免影响日常使用的实例。

升级插件

所有安装方式均为显式升级（不会自动更新）：

• 方式一（Release）：发布新版本后，把安装命令中的 v1.0.0 换成新版本号（如 v1.1.0）重新执行即可；旧版本用户不受影响。
• 方式二（git 直装）：重新执行安装命令即跟随仓库最新提交（安装时会锁定当时 commit，可用 pnpm update dsh-de-workbench 在 profile 目录内更新）。
• 查看已安装版本：pnpm dsh plugin --profile web list（或查看 profile 的 node_modules/dsh-de-workbench/package.json 的 version）。

开始分析

1. 重启 DSH、刷新浏览器，侧边栏出现**「数据工作台」**分区；
2. 点 ⚙ 数据源管理 → 新建连接（duckdb / SQLite 选本地文件，PostgreSQL / MySQL 填连接参数，支持测试连接）；
3. 点 [+ 创建数据工作台] 建一个工作台，绑定数据源；
4. 在工作台里 [新建分析]，DSH 会话打开「数据」标签页（数据面板）；
5. 直接在对话中提问，例如："共有多少张表？每张表多少行？" —— 数据面板会展示 SQL、结果表与结论，可继续追问或一键修正。

验证安装

curl http://127.0.0.1:3080/api/dsh-de-workbench/health
# → {"plugin":"dsh-de-workbench","ok":true}

使用场景

场景	提问示例
📈 业务指标速查	"这个月各渠道的收入分别是多少？和上月比变化多少？"
🕒 时间趋势分析	"过去 90 天每日订单量趋势，周末是否有明显波动？"
🏆 排行与 Top-N	"销量最高的 10 个商品是什么？各占总额多少比例？"
🔍 异常排查	"哪些订单状态异常（如退款后仍标记完成）？各多少笔？"
🧮 口径核对	"按我们的指标口径，Q2 净收入是多少？"（口径来自语义模型）
📁 文件数据探索	"把这份 CSV 导进来，看看各列的分布和空值情况。"

界面速览

工作台围绕 DSH 原生会话展开，插件提供四块界面：

① 数据源管理（全局连接注册表）——新建/编辑/删除连接、连接测试、向量模式设置。

② 数据工作台主页——数据源绑定、会话入口、提示词与技能、知识库管理、成果汇总。

③ 数据面板（官方会话「数据」标签页）——上方数据源列表与预览，下方回合结论（SQL + 结果表 + 可信度徽标），支持修正追问、存为参考 SQL、一键复制。

④ 知识库管理（工作台主页）——参考 SQL 主题树、语义模型（支持结构化 metrics: 指标公式，注入"指标口径速查"）。

⑤ 离线 HTML 报告——回合成果一键生成自包含 HTML（内联 CSS + 静态 SVG 图表），双击即用、可离线分享。

📷 截图未就绪：以上为占位位置，将同名截图放入 assets/screenshots/（见 assets/screenshots/README.md）后即自动展示。

数据源支持

• 🦆 duckdb：本地 .duckdb / .db 文件，即开即用（可作无服务起步首选）
• 🗃️ SQLite：本地 .sqlite / .db 文件
• 🐘 PostgreSQL / 🐬 MySQL：网络数据库，引擎级只读保护
• 📁 文件型数据源：CSV / Excel（.xlsx）/ Parquet / JSON——自动物化为 duckdb 可查形态（零额外依赖，xlsx 走内置 exceljs）

安全与隐私

• 🛡️ 严格只读：SQL 执行默认只读；全局只读开关开启后，全部写路径（db mutate / 界面 CRUD / 直连确认）在服务端统一拒绝。
• 🔑 凭据加密落盘：连接密码以 enc:v1: 密文存储（AES-256-GCM），内存明文、落盘密文；密钥丢失时明确提示重新配置，不静默回退。
• 🧱 来源校验围栏：写凭据/配置的请求校验本机来源，防跨站注入与 DNS rebinding。
• 💻 纯本地执行：查询与报告生成全部在本地 DSH 实例内运行，数据不出本机；向量检索本地模型可选，无需外部服务。

常见问题

Q: 我不会写 SQL，能用来做数据分析吗？ 可以。直接用自己的话描述问题即可，AI 负责探查表结构、生成 SQL、执行并解释结果。遇到歧义（如指标口径不清）它会先澄清或查你配置的知识库，而不是瞎猜。 Q: 连接生产库会不会误删误改数据？ 不会。插件 SQL 执行默认为只读（SELECT 等），写操作需要显式确认；你还可以在数据源管理顶部打开「全局只读」，此后所有写路径都被服务端拒绝。更稳妥的做法是连接只读账号。 Q: 表和字段是英文缩写，AI 能看懂业务含义吗？ 可以。在知识库中维护语义模型：让 AI 生成中文业务含义候选（或手动填写），把字段/指标口径（如"净成交额 = 订单金额 − 退款金额"）固化下来；此后分析会优先采用这些口径。 Q: 分析结果怎么分享给不用 DSH 的同事？ 每回合结论可一键导出：CSV / Excel 用于数据，离线 HTML 报告（自带图表）用于汇报——单文件自包含，双击即用，微信/邮件直接发。 Q: 提问的库表很多，AI 怎么找到相关的那几张？ 连接可构建 schema 向量索引：AI 先按问题语义检索相关表/列（支持中文问 × 英文 schema 的本地语义模式），再针对命中表探查结构，不会大海捞针逐个猜。

开发

npm install          # 安装 esbuild / typescript / 驱动依赖
node build.mjs       # 产出 lib/index.js + lib/client.js + lib/duckdb-worker.js
npm test             # 测试套件（node:test 162 断言）+ 纯模块 tsc 类型门禁
npm pack             # 产出可分发的安装包 dsh-de-workbench-<version>.tgz（可挂 GitHub Releases）

• 宿主半区：src/（Node ESM，路由/服务/工具注册）；浏览器半区：src/client/（React UI，经 DSH slot 注入）。
• 数据库能力：src/database/providers/（duckdb / sqlite / postgres / mysql / file）+ duckdb worker 子进程隔离。
• 知识库 / 技能 / 提示词：src/knowledge.ts、src/skillTemplates.ts、src/prompts.ts。
• 数据存储：连接 / 工作台 / 会话注册表写入 DSH 插件数据目录（$DSH_HOME/plugins/dsh-de-workbench/）。

开源协议

MIT License