前言¶
在 DeepSeek Harness（dsh）里做数据分析或排查问题时，模型往往需要连库、看表结构、跑查询。若每次都在对话里手写连接串，或把密码写进聊天记录，既难复用也不安全。社区插件 dsh-data-agent（npm 包 @tomowang/dsh-data-agent）把数据源注册、连通性检查、Schema 浏览与注释、只读 SQL 执行和图表渲染收进同一套能力：既可通过聊天工具调用，也可在 Web UI 的 Settings 里维护。下面介绍它的定位、能力与安装方式。
这是什么¶
dsh-data-agent 是 maintainer tomowang 发布的 dsh 客户端插件（GitHub：tomowang/dsh-data-agent）。官方简介：在对话或 Settings UI 中管理数据库连接、浏览/标注 Schema，并执行 SQL。
支持的数据库类型包括 MySQL、PostgreSQL、SQLite、ClickHouse。密码不写入插件配置：连接项引用环境变量名 passwordEnv，在连接时通过 harness 的 ctx.credentials（若已挂载）或 process.env 解析；变量名必须以 DSH_DA_ 开头（例如 DSH_DA_PROD_DB_PASSWORD），避免误读主机上无关密钥。
插件目录页：https://www.skillhub.cn/plugins/tomowang/dsh-data-agent。
核心功能¶
数据源管理¶
- 注册、编辑、删除、列出数据源：聊天工具
da_add_data_source/da_edit_data_source/da_remove_data_source/da_list_data_sources，或在 Settings → Data Sources 中操作。 - 凭证（含
passwordEnv）只能在 Settings 里绑定；聊天工具不能设置passwordEnv，对已绑定密码的数据源也不能从聊天修改host、port、user、ssl等，降低提示注入把密码指到别的主机的风险。
连通性与 Schema¶
da_test_connection检查连接。da_get_schema返回库级概览或单表列级详情；在聊天里以 Markdown 表格展示，在聊天卡片与 Settings 的 Schema 查看器里为可展开的富 UI。
表/列注释¶
- 聊天：
da_set_comment。 - Settings Schema 查看器：点击内联编辑。
- 两处写入同一存储。
SQL 执行与只读¶
da_run_sql执行 SQL；对标记为只读的数据源，通过 AST 校验（非简单字符串匹配）拒绝写语句，并始终拒绝语句堆叠（statement-stacking）。- 聊天可用
da_set_read_only把数据源设为只读；取消只读仅能在 Settings 勾选，避免被注入的模型先关只读再写入。 - 只读模式下还会在数据库侧只读运行，并拒绝一批已知可绕过只读的函数（如
pg_read_file、LOAD_FILE、ClickHousefile()、dblink_exec、pg_advisory_lock、GET_LOCK等）；文档仍建议用权限最小的数据库用户连接。 - SQLite：
da_run_sql拒绝所有数据源上的ATTACH与VACUUM INTO。从聊天添加 SQLite 时，文件路径须在插件配置的sqliteChatDirs目录内（解析符号链接与..后校验）；默认列表为空，一般需在 Settings 添加，或在配置中显式放行目录：
config:
sqliteChatDirs:
- /home/me/data
图表¶
da_render_chart用 chart.js 渲染柱状/堆叠柱/折线/饼图；数据可来自内联data，或引用此前da_run_sql结果的resultId（同会话内存缓存约 30 分钟）。- 除 Web UI 交互图外，服务端用 skia-canvas 栅格化 PNG 并返回 URL，便于模型在回复里用 Markdown 图片嵌入。
安装与启用¶
要求 dsh 0.2.1-rc.2 或更高，且 web profile 至少启动过一次（dsh --profile web）。当前插件版本在 npm 上为 0.5.1（以 package 发布为准）；peerDependencies 要求 @deepseek-ai/dsh >= 0.2.1-rc.2。
命令行安装（摘自 README，勿自行拼接 github:owner/repo）：
# 1. 安装 dsh 启动器
npm install -g @deepseek-ai/dsh
# 2. 将插件装入 web profile
dsh plugin --profile web add @tomowang/dsh-data-agent
# 3. 批准 skia-canvas 原生构建脚本（da_render_chart 的 PNG 输出需要）
dsh plugin --profile web approve-builds
安装后重启 web profile 进程以加载插件。也可在 Web UI 的 dsh-market 搜索 tomowang/dsh-data-agent 并点击 Install。
Node 引擎要求（package.json）：^22.19.0 || >=24.0.0。许可证：MIT。
典型用法（聊天工具）¶
在已配置数据源与密码环境变量的前提下，常见流程可以是：
da_list_data_sources查看已注册连接。da_test_connection确认可达。da_get_schema浏览库或单表结构；需要时用da_set_comment或 Settings 补注释。- 只读探查：
da_set_read_only（若尚未只读）后da_run_sql查询；需要可视化时用da_render_chart引用resultId或内联数据。 - 写操作仅在非只读数据源、且数据库用户具备相应权限时通过
da_run_sql执行；敏感变更仍建议在 Settings 控制只读与凭证。
README 提供 Demo 视频与 Settings → Data Agent 面板截图，可作为 UI 操作参考。
适用场景与注意¶
适合：已在 dsh web 环境跑智能体、需要可重复的数据源配置、在对话里查数/看图、又希望密码与主机绑定与只读策略与聊天隔离的团队或个人。
注意：
- 插件以 当前 dsh 进程权限 运行；安装前请阅读源码与 MIT 许可证，自行评估风险。
- 只读模式不是完整权限体系；应对每个数据源使用最小权限的数据库账号。
- Settings → Data Sources 使用 dsh 已认证 API，浏览器需已登录 dsh；若提示未登录，请用启动时打印的 URL 重新打开。
- 从 0.4 升级到 0.5 需先升级 dsh 到 0.2.1-rc.2；从 0.3 到 0.4 涉及
DSH_DA_前缀、sqliteChatDirs、只读仅 Settings 可解除等迁移说明，见 GitHub README 的 Upgrading 章节。
DeepSeek Harness 生态强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-data-agent 把多引擎连接、Schema 浏览与注释、AST 约束下的 SQL 与只读策略、以及 chart.js 图表与 PNG 导出，统一进 dsh 的对话工具与 Settings。若你在 harness 里做数据问答或运维查数，可按上文命令安装并在 Settings 先配好 DSH_DA_* 环境变量与数据源。
