它做什么
dsh-data-agent 把 Harness 会话连到一个数据库上，让模型去做分析，而不是让你去写查询。你用日常业务语言提一个问题；插件的 agent 预设让模型自己探查库表结构、写 SQL、执行，并带着结果继续往下推演——最后画出来。
README 把目标用户定位为不写 SQL 的分析师，并把它要消除的工作描述成那个熟悉的循环：反复提需求写查询、导出表格、再在图表工具里重新调格式。
| 界面 | 提供什么 |
|---|---|
| 对话 | 自然语言提问；模型探查库表、编写并执行 SQL，并在追问中连续推演 |
| 工作台 | 连接配置、库表浏览、数据治理与 SQL 执行，合在一个 web 面板里 |
| 数据治理 | 模型扫描库表结构，为表和字段生成通俗的业务释义；你逐项确认、修改或补充指标定义 |
| 报告 | 自动生成图表与多维看板，导出为独立的离线 HTML，落在 analysis-reports/ |
图表来自 echarts（^6.1.0），打包用 fflate，schema 校验用 schemastery 与 zod——都是声明在 dependencies 里的运行时依赖，也就是说工作台是这个包的一部分，而不是一个外部服务。
它是怎么接上去的
package.json 声明 dsh.engines.dsh 为 >=0.1.2-alpha.2，本条目按原文逐字记录为 dshTarget。正是这条声明把等级定在 L3 而不是 L2：仓库可解析、README 存在、清单可解析、安装命令能对已发布包解析，且作者声明了 Harness 目标版本。
清单同时带有插件的两半：
dsh.bundle.patch→cordis.patch.yml，宿主侧。dsh.client，platform: "web"，注入八个宿主 UI 包，包括dsh-client-ui-agent-preset、-conversation、-renderer、-session、-tool与-workspace。注入 agent-preset 这件事，正是「数据模式」能成为新会话里一个可选模式、而不需要你传参数的原因。
发布的 files 为 lib/**、cordis.patch.yml、preset/**、dsh-plugin.json 与 conformance/dsh-ecosystem/**——最后一项不常见，值得点出：项目自己随包发布了它的合规性证据。
peer 依赖是 ^0.1.2-alpha.2 的 DSH 宿主包，外加 react ^18.2.0 || ^19.0.0。这个 peer 集合很宽，同时也是一句关于「它期望哪一代宿主」的精确陈述。
要求与安装
-
一个不低于声明下限
>=0.1.2-alpha.2的 DSH 环境。 -
宿主到目标数据库的网络可达。 README 覆盖了本地 SQLite 文件、局域网数据库与云端数据库。
-
装进你真正会用的 profile。 README 给了两条命令，因为这个插件支持两种界面：
# web profile（推荐） dsh plugin --profile web add @yejiming/dsh-data-agent # 终端 profile dsh plugin --profile dsh-tui add @yejiming/dsh-data-agent -
无安装期生命周期脚本。 声明的脚本是
bundle、watch、build、typecheck、test、conformance、conformance:artifact——没有preinstall/install/postinstall/prepare。 -
存在一次首次启动的预设迁移，且有文档。 升级后首次启动时，插件会重写原版
data-agent预设，使其满足新版 DSH 要求的persona.config.prefix字段，同时保留旧版使用的text字段。用户自定义过的预设不会被覆盖。若启动报$.prefix missing required value，README 的处置办法是：备份$DSH_HOME/.agent-presets/data-agent/agent.cordis.yml（默认位于~/.dsh），让 persona 的prefix与原text使用相同提示词，再重启。 -
怎么用——web profile 下新建会话、选 「数据模式」，通过它的连接配置（带测试连接）或输入框右上角的数据库图标填写连接信息，然后直接提问。终端 profile 下用
/preset data-agent切模式、/database connect连接。
网络与数据
查询在哪里跑。 README 把分析与报告生成描述为本地行为：插件从你的宿主机连出去，连到你指定的数据库。报告写在工作目录的 analysis-reports/ 下，是自包含的 HTML——README 的要点是这个文件自带样式与数据，同事无需安装任何东西就能离线打开。
只读是推荐姿势，不是默认继承的属性。 README 建议使用只读数据库账号，并且在连接配置里打开只读模式；它声明在该模式下写入、修改、删除语句——UPDATE、DELETE、DROP 之类——会被拒绝。这是两道独立的控制，而如果插件层的检查被绕过，兜底的仍然是数据库账号那道。
凭据。 README 描述连接密码仅在当前会话运行时使用、不写入明文历史，也绝不向远程服务器上报。请把这理解为「文档所述的设计」，而不是经过审计的性质——本条目为 security: unverified，没有第三方扫描记录。
模型会看到你的库表结构。 数据治理之所以存在，正是因为模型要读表名、字段名与注释来生成业务释义。不该让模型看到的内容，就不该出现在你用于连接的账号可访问范围内。
未记录遥测——README 与发布清单都没有描述外发分析。
已知限制
- 只捆绑了一个数据库驱动。
@clickhouse/client是dependencies里唯一的数据库客户端。README 那张更宽的表（MySQL、PostgreSQL、SQLite、Oracle、SQL Server、Doris、Hive、Impala）因此依赖宿主环境提供到这些引擎的可用通路——那张表是产品面，每个引擎都值得你自己先做一次连接测试再依赖它。 - 只读保护是「一个设置 + 一次授权」。 两者互不替代，而且当你以高权限账号连接、又没做账号侧那一半时，数据库本身并不会替你拦住。
- 治理产出由模型生成，需要你复核。 插件自己的工作流就要求你确认释义、补充「净成交额 = 订单金额 − 退款金额」这类指标公式，这本身就是承认第一遍可能理解错你的业务。
- 预设迁移是一次真实的升级步骤。 自定义过的
data-agent预设被刻意保留，这也意味着它可能正是让新版宿主启动失败的原因——所以才有了文档里那段prefix修法。 - 声明的目标版本是下限，不是上限。
>=0.1.2-alpha.2逐字记录作者声明，并不代表后续每个版本都测过。 - Star（194）代表关注度，不代表审查。 本站没有任何条目声称 L4/L5，本条目也不表示已对真实数据库做过冒烟安装。
何时用 / 何时不用
适合你和数据之间的瓶颈是 SQL 而不是权限的情况：这里的价值是一个会探查库表、写出查询、解释结果、并在你追问时继续下去的模型——外加一份可以交给不用 DSH 的人的报告。可浏览的目录与指标定义层，是让重复分析保持一致而不是每次即兴的原因。
不要把它当作数据库客户端、BI 替代品，或者让 Agent 写生产库的通道。如果你已经有顺手的查询工具和图表库，这个插件的贡献在于语言层，而不在连接层。如果你的数据根本不允许被描述给托管模型，那么治理不是缓解措施——它恰恰就是把库表结构送出去的那个机制。
FAQ
我不会写 SQL，能用它做分析吗？
可以。这个插件的目标就是不做 SQL 的人：你描述问题，模型探查库表、写查询并执行。工作台里的 SQL 执行模块是给想自己写的人准备的。
它会不会修改或删除我的数据？
按 README 的建议配置就不会——只读数据库账号，加上连接配置里的只读模式。README 声明只读模式下写入与删除语句会被拒绝。两道都要上；数据库真正强制执行的是账号授权那道。
支持哪些数据库？
README 列出 MySQL、PostgreSQL、SQLite、Oracle、SQL Server、ClickHouse、Doris、Hive、Impala，以及本地 SQLite 文件。包内只捆绑了 @clickhouse/client，其余依赖你的宿主能否连通那些引擎——请用一次连接测试确认你的引擎，而不是假定那张表都成立。
怎么把分析结果分享给不用 DSH 的同事？
每张生成的图表或看板都会在 analysis-reports/ 下存成一个独立的 .html 文件。它自带样式与数据，用任意浏览器离线打开即可，也可以通过邮件或聊天工具发送。
得到第一个答案之后还能继续问吗？
能，这正是它的设计循环——README 举的例子包括按省份拆解、把柱状图换成饼图、追问某个月环比为何下降。每次追问都在同一会话里基于上一步结果继续。