dsh-data-agent

101Star7Fork5Issue0Watching

为 DeepSeek Harness 接入 MySQL/PostgreSQL/SQLite/ClickHouse 等 9 种数据库,提供数据模式预设与 SQL 工具,让对话式完成数据分析与可视化报告。

机审证据安装命令仓库已核验dsh-plugin Topic许可证READMEAI 百科
语言
JavaScript
License
MIT
分支
main
data-agentdeepseek-harnessdshdsh-plugin

安装

$ dsh plugin --profile web add github:omdsh-dev/dsh-data-agent

在终端中运行以上命令,通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh?看这篇新手教程

对话式安装

帮我安装 DeepSeek Harness 插件 omdsh-dev/dsh-data-agent:先查看仓库 https://github.com/omdsh-dev/dsh-data-agent.git 确认安全性,然后执行安装命令并验证插件加载成功。

把这段指令粘贴给 DSH Web GUI 里的助手,由它代你完成安装与验证。

一句话定位

让 DeepSeek Harness 直接连接常见数据库,用自然语言提问即可完成 SQL 编写、执行、结果分析与可视化报告,并同时支持 Web UI 与 dsh-tui 终端两种入口。

核心能力

  • 通过对话完成数据分析:用自然语言提问,工具会查看表结构、生成并执行 SQL、根据真实结果继续追问
  • 自动生成可视化报告:单次工具调用产出 1-6 个只读数据集与 1-8 个图表视图(指标/折线/柱状/饼/散点/表格),并保存为离线 HTML
  • 共享连接服务:Web 工作台、dsh-tui 表单、agent 工具共用同一连接存储,会话间连接互不影响
  • 9 种主流数据库:MySQL、PostgreSQL、SQLite、Oracle、Hive、Impala、ClickHouse、Apache Doris、SQL Server
  • 安全凭证处理:TUI 密码始终隐藏、临时密码不进 argv 与日志、SQL Server 输入拒绝 GO 与变量替换
  • 三类 SQL 工具:sql-query 结构化只读、sql-write 单条写/管理、sql-cmd 原始客户端输出

技术实现

  • 语言: TypeScript + React(客户端 UI)
  • 关键依赖: @clickhouse/client、@deepseek-ai/cordis、@deepseek-ai/dsh-tools、schemastery
  • 架构模式: Cordis 双行插件(data-agent + data-agent-routes)通过 cordis.patch.yml 注入宿主;浏览器端由 lib/client.js 注册到 conversation.input.right 等 DSH 客户端槽位
  • 入口文件: src/index.ts(服务器端)、src/routes.ts(Web 路由)、src/client/index.ts(浏览器)

适用场景

业务/数据分析师需要在不写代码的前提下查询 MySQL、PostgreSQL、ClickHouse 等业务库,让 AI 自动完成从取数、聚合到生成可视化报告的完整链路。研发同学也能用它在 dsh-tui 中做临时数据探查、生成可分享的离线分析报告。生产数据库建议搭配只读账号使用,避免误改数据。

前置依赖与兼容性

依赖最低版本说明
DSH0.1.0-rc.7+由 peerDependencies 中 @deepseek-ai/dsh-* ^0.1.0-rc.7 决定
平台macOS / Windows / Linuxsrc/client-discovery.ts 支持 darwin、linux、win32 平台下的客户端自动发现
Node.js未声明package.json 未声明 engines
原生模块仅依赖 @clickhouse/client 1.23.x HTTP 客户端,其他数据库通过命令行子进程调用

安装方式

dsh plugin --profile web add github:omdsh-dev/dsh-data-agent

配置项

配置类型说明默认值
presetId字符串安装到 DSH_HOME/.agent-presets/ 的预设目录名data-agent
installPreset布尔启动时是否自安装"数据模式"预设true
connectTimeoutMs数字(≥1000)单次 /connect 连接测试的超时时间(毫秒)10000
introspectMaxTables数字(≥1)/connect 与 /status 返回的表数量上限500
queryTimeoutMs数字(≥1000)单条数据库工具查询的超时时间(毫秒)30000
maxResultChars数字(≥1024)单次查询 stdout/stderr 捕获上限(字符)20000
maxRows数字(≥1)sql-query 等读取工具返回的最大行数100
maxQueryChars数字(≥1024)单条 SQL 文本的最大长度65536
readonly布尔默认是否启用只读模式(拒绝写/管理语句)false
persistConnections布尔是否将非敏感连接信息持久化到 DSH 存储域true
clients对象按数据库类型覆盖 CLI 客户端路径与额外参数(searchPaths/command/args)平台默认
connections对象按会话 ID 预置默认连接(key '*' 作为通配默认),不允许包含密码空对象

常见问题

Q: 哪些数据库可以连接?

A: 支持 MySQL、PostgreSQL、SQLite、Oracle、Hive、Impala、ClickHouse、Apache Doris、SQL Server 共 9 种,覆盖业务库、数仓、本地 SQLite 文件等场景。

Q: 数据库密码如何处理?

A: Web 临时密码只存在进程内存;TUI 表单输入时仅显示 *,重新打开表单不会恢复。持久化采用 DSH credential reference 引用,MySQL/Doris 通过 MYSQL_PWD 环境变量传,SQL Server 用 SQLCMDPASSWORD,ClickHouse 通过官方 HTTP 客户端的认证字段。

Q: 是否需要安装数据库 CLI 客户端?

A: 是。除 ClickHouse(用包内置的官方 HTTP 客户端)和 SQLite(系统通常自带)外,其他数据库需要命令行客户端,未在 PATH 时可通过 profile 的 clients.searchPaths 或 command 指定绝对路径。MySQL/Doris 自动加 --default-character-set=utf8mb4 避免 Windows 代码页导致中文乱码。

Q: 安装失败或出现 failed to mount 怎么办?

A: 通常是当前 profile 还没装插件或仍在用旧版 preset。先确认目标 profile 已执行 install 命令并完全重启 DSH;未改动的旧 preset 会被自动迁移,手工编辑过的需要删除其中指向 @yejiming/dsh-data-agent/tool 与 /command 的两行配置块。

Q: 分析报告 HTML 存放在哪里?

A: 每次成功的 render-analysis 调用都会在会话工作目录的 analysis-reports/{title}.html 生成一份离线 Dashboard,文件内联数据与 SVG 渲染代码,断网也能直接打开。Web 同时给出内联预览和"查看分析"按钮;dsh-tui 只返回文件绝对路径,由你在本机浏览器打开。

Q: 只读模式是绝对安全吗?

A: 不是。插件运行在 DSH 进程内(trusted in-process),不提供 OS、进程或 realm 沙箱。推荐组合是数据库只读账号 + 连接表单只读模式,但账号权限才是最终边界。

Q: Doris 和 SQL Server 当前支持有什么限制?

A: Doris 当前只浏览当前/internal catalog,不会臆造外部 catalog 层级;SQL Server 只支持 SQL Login,不支持集成/Windows/Entra 认证、DSN 或命名实例,且需要 Microsoft ODBC sqlcmd 18.x。

Q: 卸载插件会删除连接信息吗?

A: 默认卸载只移除当前 profile 的运行时 effect,不会主动删除已保存的非敏感连接信息和数据模式 preset。如需彻底清理,请先备份,再手动删除 DSH_HOME/.agent-presets/data-agent 并通过目标 profile 的存储管理删除 data_agent_connections@1 记录。

上手难度

入门 — 无需写代码即可在 Web 或 dsh-tui 中连接数据库并完成分析;掌握 SQL 与只读账号最佳实践即可放心使用。

已知问题与限制

  • 生态适配器(@dsh-std/adapter-dsh)只发布声明降级快照,不会重复注册命令、工具或 UI handler,原生 Cordis 路径仍是唯一功能实现
  • Apache Doris 首版只浏览当前/internal catalog,不支持外部 catalog 层级
  • SQL Server 首版只支持 SQL Login,不支持集成/Windows/Entra 认证、DSN 与命名实例
  • ClickHouse 实际 Server/Cloud + TLS 组合需在部署侧冒烟验证,README 不对所有 Cloud/TLS 配置做兼容性承诺
  • render-analysis 报告 JSON 上限 512 KiB(src/analysis.ts:33),超过会要求聚合或拆分报告,不静默删减数据
  • 工作台导出硬上限 50000 行(src/defaults.ts:27),超出部分不会被导出
  • 插件仍以 trusted in-process 方式运行,不提供 OS、进程或 realm 隔离

收录徽章

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-data-agent)

把这段 markdown 粘贴到你的 GitHub README,链接回本插件详情页。徽章只声明已被本站收录,不代表安全认证。

返回插件目录