# dsh-data-agent

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

## Metadata

- Author: [@omdsh-dev](https://github.com/omdsh-dev)
- Repo: <https://github.com/omdsh-dev/dsh-data-agent.git>
- GitHub: [omdsh-dev/dsh-data-agent](https://github.com/omdsh-dev/dsh-data-agent)
- Stars: 101
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `data-agent`, `deepseek-harness`, `dsh`, `dsh-plugin`
- Forks: 7
- Open Issues: 5
- Last push: 2026-08-20T06:20:04.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
让 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 中做临时数据探查、生成可分享的离线分析报告。生产数据库建议搭配只读账号使用，避免误改数据。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| 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 客户端，其他数据库通过命令行子进程调用 |

## 安装方式

```bash
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 隔离

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-data-agent](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-data-agent)
Wiki generated by AI (model: `MiniMax-M3`)