前言¶
在 DeepSeek Harness（DSH）里做智能体开发，数据分析往往是绕不开的一环：业务同学想直接问「最近一个月哪个地区销售额下滑最多」，工程师却要反复切到 BI 工具、手写 SQL、再把结果贴回对话里。DSH 的核心理念是「一切皆插件」——社区里已经有人把「连库查数」这件事做成了独立插件。
今天要介绍的是 dsh-data-agent（仓库 omdsh-dev/dsh-data-agent）。它在 GitHub 上已有 164 个 star、12 个 fork，在 SkillHub 插件库 中归类为「联网工具」。插件由社区组织 omdsh-dev 维护，采用 MIT 许可证；需要说明的是，SkillHub 与 dshfind 等目录均为社区运营的 DSH 插件索引，并非 DeepSeek 或幻方官方应用商店。
这是什么¶
一句话概括：dsh-data-agent 是 DSH 的数据分析插件，把数据库连接、SQL 执行与结果解读串进同一次对话流程。
连接数据库后，你可以直接用自然语言描述业务问题。DSH 会查看库表结构、编写并执行 SQL，再根据真实返回结果继续调整查询或深入分析，最终给出可读的数据结论与商业洞察。插件同时支持 Web UI 与 dsh-tui，无需修改 DSH 源码；npm 包名为 @yejiming/dsh-data-agent。
核心功能与亮点¶
根据 GitHub README 与仓库说明，已核实的主要能力如下：
- 对话式数据分析：用自然语言提问，DSH 会拆解分析步骤、查询真实数据并整理结论；支持在同一上下文中连续追问，逐步缩小范围或比较维度。
- 自动 SQL 闭环：不是只生成一段未经验证的 SQL，而是根据表结构写查询、执行、结合报错或结果继续迭代，直到拿到可用答案。
- AI 驱动的数据治理（Catalog）：可用当前会话配置的模型扫描数据库，为表和字段生成业务含义候选；所有 AI 建议需人工确认，也可手工补充术语与指标定义。后续分析会通过
catalog-search、catalog-get、metric-get等工具读取已确认的口径。 - HTML 分析报告（render-analysis）：Agent 在判断需要可视化时，可一次调用生成含 metric、折线、柱状、饼图、散点、表格等视图的综合报告，并保存到工作目录
analysis-reports/下的离线 HTML 文件；Web UI 支持内联预览与「查看分析」弹窗。 - 多界面共享同一套工具协议：Web UI（推荐配合 dsh-web-ui）与 dsh-tui（推荐配合 dsh-TUI）共用数据库服务与八工具协议；数据模式会保留
sql-query、sql-write、sql-cmd、render-analysis及 Catalog 相关工具，而不会混入describe_image、ssh_*等无关能力。 - 常见业务数据库支持：MySQL、PostgreSQL、SQLite、Oracle、Hive、Impala、ClickHouse、Apache Doris、SQL Server 等，覆盖业务库、分析库、本地文件与数仓场景。
- 只读保护与密码处理：支持只读模式与数据库只读账号；TUI 中临时密码会被隐藏，且不会作为表单草稿恢复。
Web UI 还提供「数据库工作台」：在输入框右上角的数据库按钮中，可在同一弹窗里完成连接配置、浏览库表、数据治理与临时 SQL 执行。
安装与启用¶
以下命令来自仓库 README，安装到 Web profile（推荐 npm 方式）：
dsh plugin --profile web add @yejiming/dsh-data-agent
也可从 GitHub 直接安装：
dsh plugin --profile web add github:omdsh-dev/dsh-data-agent
若主要在终端使用 dsh-tui，可安装到对应 profile：
dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent
插件会自动安装「数据模式」预设，并在 profile 启动时预加载相关数据库工具。仓库中 lib/ 已提交，通过 npm 或 GitHub 安装时无需本地构建。
典型用法示例¶
在 Web UI 中使用¶
启动 Web UI：
dsh --profile web
操作步骤：
- 新建会话并选择「数据模式」。
- 点击输入框右上角的数据库按钮，在工作台中填写连接信息。
- 连接成功后，直接在对话框中提出分析问题。
- 根据第一轮结果继续追问，让 DSH 缩小范围、比较维度或总结结论。
例如可以输入：
分析最近30天订单变化，找出销售额下降最明显的地区和商品，并解释主要原因
DSH 会自行查看相关表、生成并执行查询，再根据真实结果完成分析。
在 dsh-tui 中使用¶
启动终端界面后，切换到数据模式并连接数据库：
/preset data-agent
/database connect
连接成功后直接提问。常用数据库命令还包括：
/database status 查看当前连接
/database test 测试当前连接
/database disconnect 断开当前连接
/catalog scan 启动 Catalog 扫描
/catalog status 查看扫描结果
为获得更有价值的分析，建议在问题中补充业务目标、时间范围和关注维度，例如：
分析2026年第二季度各地区的销售额和毛利率变化，找出表现异常的地区，
继续拆解到品类和核心客户，并给出三条可执行的业务建议。
使用前准备¶
DSH 执行查询时，需要本机能够访问目标数据库，并安装相应的命令行客户端（如 MySQL 的 mysql、PostgreSQL 的 psql 等）。ClickHouse 使用插件内置的 HTTP 适配器，无需单独安装 clickhouse-client。建议先准备一个只读数据库账号，在不修改业务数据的前提下完成探索。
适用场景与注意事项¶
适合谁用：
- 需要在 DSH 对话中直接查库、看数、做临时分析的数据分析师或工程师；
- 希望用自然语言降低 SQL 门槛、又希望结果基于真实查询数据的业务同学；
- 已在用 DSH Web UI 或 dsh-tui，想为智能体补上「数据模式」工作流的开发者。
务必注意：
- 插件及其适配器运行在 DSH 进程内，以当前 dsh 进程的权限访问数据库与文件系统，并非操作系统级沙箱。安装前应自行审阅源码与 MIT 许可证，确认符合你的安全策略。
- 推荐使用数据库只读账号，并在连接表单中开启只读模式。未开启只读时，Agent 可按你的要求执行更新或管理语句；连接生产库前请确认账号权限与备份策略。
- 不同会话的数据库连接相互隔离，便于分别处理不同项目或客户环境。
- Catalog 仅持久化脱敏后的元数据与人工确认的口径，不保存密码、查询结果或样例行；AI 候选的确认与删除在 Web「数据治理」页完成。
- 若出现
failed to mount或找不到@yejiming/dsh-data-agent，通常是当前 profile 尚未安装插件或仍在使用旧版预设，需执行对应安装命令后完全退出并重启 DSH。
结尾¶
如果你希望把 DSH 从「写代码的智能体」扩展到「能连库、能查数、能出报告的数据助手」，dsh-data-agent 是目前社区里较完整的一条路径：对话提问、自动 SQL、数据治理、HTML 报告与只读保护都集成在「数据模式」预设里，Web 与 TUI 也能共用同一套能力。
