- Language
- JavaScript
- License
- MIT
- Branch
- main
data-agentdeepseek-harnessdshdsh-plugin
为 DeepSeek Harness 接入 MySQL/PostgreSQL/SQLite/ClickHouse 等 9 种数据库，提供数据模式预设与 SQL 工具，让对话式完成数据分析与可视化报告。
$ dsh plugin --profile web add github:omdsh-dev/dsh-data-agentRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
让 DeepSeek Harness 直接连接常见数据库，用自然语言提问即可完成 SQL 编写、执行、结果分析与可视化报告，并同时支持 Web UI 与 dsh-tui 终端两种入口。
业务/数据分析师需要在不写代码的前提下查询 MySQL、PostgreSQL、ClickHouse 等业务库，让 AI 自动完成从取数、聚合到生成可视化报告的完整链路。研发同学也能用它在 dsh-tui 中做临时数据探查、生成可分享的离线分析报告。生产数据库建议搭配只读账号使用，避免误改数据。
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.1.0-rc.7+ | 由 peerDependencies 中 @deepseek-ai/dsh-* ^0.1.0-rc.7 决定 |
| 平台 | macOS / Windows / Linux | src/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 与只读账号最佳实践即可放心使用。