Skip to content
Back to search

dsh-connect

DeepSeek Harness 数据源连接插件,支持数据库元数据发现、AI 语义建模、只读 SQL 查询和固定 HTTP API 调用

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/niuhuoshan--dsh-connect/badge.svg)](/listings/niuhuoshan--dsh-connect)

HTML

<a href="/listings/niuhuoshan--dsh-connect"><img src="/api/listings/niuhuoshan--dsh-connect/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

从 DSH 插件源安装

在 DSH Web profile 中执行:

dsh plugin --profile web add @niuhuoshan/dsh-connect

安装后重启 DSH,在 **设置 -> DSH连接器** 中可以看到插件入口。入口图标使用连接图标,页面包含 **数据库** 和 **HTTP API** 两个 tab。

本地开发安装

项目需要 Node.js 22+ 和 pnpm:

pnpm install
pnpm run check
pnpm pack --pack-destination dist

开发时也可以直接安装目录:

dsh plugin --profile web add /path/to/dsh-connect

如果使用本地 DSH runtime 的 profile 包管理器,可安装打包文件:

cd /path/to/dsh-runtime
./node_modules/.bin/pnpm \
  --dir /path/to/dsh-home/profiles/web \
  add -w file:/path/to/dsh-connect/dist/dsh-connect-0.1.0.tgz

安装或更新后需要重启 DSH,使 Host 端和浏览器端插件重新加载。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 380 lines
  1. # dsh-connect
  2. `dsh-connect` 是 DeepSeek Harness(DSH)的连接器插件,围绕两类能力工作:
  3. 1. 连接数据库,发现物理结构,并生成可供 Agent 检索的语义元数据。
  4. 2. 配置固定的第三方 HTTP API,将每个已启用的 API 注册为一个受约束的 Agent 工具。
  5. 它适合把企业数据库和已有业务 API 安全地接入 DSH 对话。用户不需要在聊天中输入数据库密码或 API 密钥,也不需要记住工具名;工具描述会注册到 DSH Agent,由 Agent 根据对话和元数据决定是否调用。
  6. ## 功能边界
  7. | 范围 | dsh-connect 提供 | 明确不提供 |
  8. | --- | --- | --- |
  9. | 数据库 | MySQL、PostgreSQL、ClickHouse over HTTP(S) 的连接、扫描、元数据管理和受限查询 | 写库、DDL、多语句 SQL |
  10. | 元数据 | 表、视图、字段、主外键、DDL、注释、语义识别、YAML 导出 | 把样例数据暴露给 Agent 或模型 |
  11. | HTTP API | 用户预先配置的固定方法、域名、路径、参数和认证方式 | 模型任意决定 URL、跨域跳转或任意 HTTP 请求 |
  12. | 对话 | Agent 自动使用已注册的元数据工具和 API 工具 | 完整 ChatBI 编排、无限制 NL2SQL |
  13. | 关系 | 保留数据库实际发现的外键引用 | 关系推荐、关系分析和关系建模功能 |
  14. ## 安装
  15. ### 从 DSH 插件源安装
  16. 在 DSH Web profile 中执行:
  17. ```bash
  18. dsh plugin --profile web add @niuhuoshan/dsh-connect
  19. ```
  20. 安装后重启 DSH,在 **设置 -> DSH连接器** 中可以看到插件入口。入口图标使用连接图标,页面包含 **数据库** 和 **HTTP API** 两个 tab。
  21. ### 本地开发安装
  22. 项目需要 Node.js 22+ 和 pnpm:
  23. ```bash
  24. pnpm install
  25. pnpm run check
  26. pnpm pack --pack-destination dist
  27. ```
  28. 开发时也可以直接安装目录:
  29. ```bash
  30. dsh plugin --profile web add /path/to/dsh-connect
  31. ```
  32. 如果使用本地 DSH runtime 的 profile 包管理器,可安装打包文件:
  33. ```bash
  34. cd /path/to/dsh-runtime
  35. ./node_modules/.bin/pnpm \
  36. --dir /path/to/dsh-home/profiles/web \
  37. add -w file:/path/to/dsh-connect/dist/dsh-connect-0.1.0.tgz
  38. ```
  39. 安装或更新后需要重启 DSH,使 Host 端和浏览器端插件重新加载。
  40. ## 快速上手
  41. 1. 打开 **设置 -> DSH连接器 -> 数据库**,点击 **添加数据库**。
  42. 2. 填写连接信息,点击 **测试连接**,确认数据库凭据可用。
  43. 3. 点击 **扫描**,完成物理元数据发现;需要语义识别时,先勾选 **AI 语义增强(DSH 默认模型)**,再点击 **AI 建模**。
  44. 4. 点击数据库卡片上的 **元数据**,检查和编辑表、字段的业务描述。
  45. 5. 在聊天中直接描述需求,例如“查一下销售库最近 7 天每天的订单量”。Agent 会先检索元数据,再在允许的范围内调用查询工具。
  46. 6. 在 **HTTP API** tab 中添加固定 API,测试成功并启用后,在聊天中用自然语言描述业务需求即可触发对应 API。
  47. 插件没有额外的斜杠命令。是否调用某个工具由 DSH Agent 根据工具描述、已启用状态和当前对话判断;显式说出工具名可以帮助排查,但不是正常使用的必要条件。
  48. ## 典型使用案例
  49. ### 数据库问答
  50. 销售团队接入一个只读的 MySQL 数据源,扫描并完成 AI 语义识别后,用户可以直接提问:
  51. ```text
  52. 华东区域本月每天的订单量和销售金额是多少?
  53. ```
  54. Agent 会先从表名、字段业务名称和描述中找到相关 profile,再调用只读查询工具。数据库账号本身仍应只授予业务需要的读取权限,插件不会绕过数据库权限。
  55. ### 固定业务 API
  56. 管理员配置一个天气、物流或内部工单 API,声明固定的 URL、路径参数和认证方式后,用户可以说:
  57. ```text
  58. 查询上海的物流轨迹,单号是 SF123456。
  59. ```
  60. Agent 只能调用已经注册的 API 工具和已声明的参数,响应可通过 JSON Pointer 裁剪为业务需要的字段。
  61. ### 数据库结构变化
  62. 源库新增字段、删除表或修改字段注释后,再次执行默认的增量扫描。dsh-connect 会比较 fingerprint,只重建变化对象;扫描成功后清理已经不存在的旧对象,未变化的语义描述和人工编辑内容继续保留。若扫描中途停止,已完成对象保留,旧对象不会被提前删除。
  63. ## 数据库接入
  64. 支持的数据库及默认端口:
  65. | 类型 | 连接方式 | 默认端口 |
  66. | --- | --- | ---: |
  67. | MySQL | MySQL 协议 | 3306 |
  68. | PostgreSQL | PostgreSQL 协议 | 5432 |
  69. | ClickHouse | HTTP(S) | 8123 |
  70. 数据库卡片可配置:
  71. - 名称、数据库类型、主机、端口、数据库名、用户名和密码。
  72. - `Schema 白名单`:逗号分隔;留空表示扫描当前账号可见的全部 schema。
  73. - TLS 开关。
  74. - 样例行数:0 到 3 行,默认不采样。
  75. - AI 语义增强开关和数据源启用开关。
  76. 密码不会写入普通业务表,也不会在列表接口返回,而是通过 DSH credential service 保存。编辑已有数据源时密码留空表示保留旧凭据。
  77. ## 元数据发现与同步
  78. 一次扫描会读取以下信息:
  79. - schema、表、视图和表注释;
  80. - 字段名、数据库类型、可空性、默认值和字段注释;
  81. - 主键、外键及其引用的 schema、对象和字段;
  82. - 数据库原生 DDL,或驱动生成的 DDL;
  83. - 可选的最多 3 行样例数据。
  84. 样例数据只用于本地 profile,不会通过 Agent 元数据工具返回,也不会发送给 AI 模型。样例中的密码、token、API key、邮箱、手机号、身份证等敏感字段会脱敏。
  85. ### 扫描模式
  86. | 模式 | 用途 |
  87. | --- | --- |
  88. | `incremental` | 默认模式。每次发现全部对象,但只对物理 fingerprint 或语义 fingerprint 发生变化的对象重新处理。 |
  89. | `rebuild-ai` | 在已开启 AI 语义增强时,强制重建 AI 语义结果;适合切换 DSH 默认模型或 prompt 版本后重新识别。 |
  90. | `full` | 完整重建 profile,适合需要彻底刷新本地元数据的场景。 |
  91. 物理 fingerprint 会覆盖表结构变化,因此增删字段、字段类型变化、注释或 DDL 变化会在下一次扫描时重新入库。扫描成功结束后,数据库中已经不存在的对象会从 profile 中清理;如果中途停止,则不会执行这一步,以免误删尚未扫描到的对象。
  92. 当前同步由用户在设置页手动触发,没有内置的定时扫描任务;需要自动化时可由 DSH 或外部调度器调用 `sources/scan`。
  93. 扫描状态包括等待、扫描中、完成和失败。点击 **停止** 会中止当前任务并立即移除未完成的任务记录,已经逐表写入的 profile 会保留,尚未处理的对象不会写入。用户界面不会把停止后的数据源永久显示为“已取消”。
  94. ## AI 元数据识别
  95. AI 识别使用 DSH 当前的默认模型路由,不在 dsh-connect 中单独配置模型。任务启动时会记录 provider、model、reasoning effort 和分析时间,并在 profile 中保留模型状态和 prompt 版本。
  96. 识别结果包括:
  97. - 表业务名称、表描述、标签、同义词和临时对象判断;
  98. - 字段业务名称、字段描述、同义词、枚举值和字段角色;
  99. - 0 到 100 的置信度及置信度原因。
  100. 模型输出会经过严格 JSON/schema 校验。普通数字置信度会自动识别为 0~1 概率或 0~100 分数,然后四舍五入并限制在 0~100;模型结果格式错误会单独标记。AI 服务不可用或返回无效结果时,插件保留启发式识别结果并将 `modelStatus` 标记为 `failed`。
  101. 字段角色的含义是元数据语义,不是数据库权限:
  102. - `标识/关联字段`:主键、外键以及 `*_id`、`*_code`、`*_uuid`、`*_no` 等标识字段;
  103. - `描述/分类字段`:名称、状态、类型、地区、分类等属性;
  104. - `数值字段`:金额、数量、计数、比率和评分;
  105. - `时间字段`:日期、时间戳等;
  106. - `暂不确定`:无法可靠判断的字段。
  107. 存在主键、显式外键或明显标识命名时,Host 会进行保护性纠正,避免把关联标识误判为普通维度字段。AI 结果不是业务事实,仍应在元数据页面人工复核。
  108. ## 元数据页面
  109. 从数据库卡片进入 **元数据** 后:
  110. - 左侧展示所有表名、schema 和表描述,并支持搜索;
  111. - 右侧分为 **表元数据** 和 **字段元数据** 两个 tab;
  112. - 表元数据可编辑业务名称、描述、标签、同义词以及是否从 Agent 检索中忽略;
  113. - 字段元数据可编辑业务名称、字段用途、同义词、枚举值和描述;
  114. - 另有只读的元数据浏览入口,可查看 DDL、字段类型、主键和实际外键引用。
  115. ### 指标
  116. 插件提供指标推荐和持久化 RPC,可生成记录数以及数值字段的求和、平均值等候选指标,并支持 `count`、`sum`、`avg`、`min`、`max`、`formula` 聚合方式和批量保存。
  117. 指标是业务定义,不是仅凭字段名就能确定的事实。推荐结果只能作为候选,业务人员需要确认名称、口径、表达式、单位和启用状态。dsh-connect 不会自动建立关系,也不会把指标推荐当作关系建模。
  118. ## 只读 SQL
  119. 在数据库卡片的 **元数据 -> 只读 SQL** tab 中可以执行查询,Agent 也可以调用同一能力。
  120. 约束如下:
  121. - 只允许一条 `SELECT` 或 `WITH` 语句;
  122. - SQL 最长 20,000 个字符;
  123. - 禁止分号、SQL 注释、多语句以及 `INSERT`、`UPDATE`、`DELETE`、`DROP`、`ALTER`、`CREATE`、`TRUNCATE`、`GRANT`、`REVOKE`、`SET`、`USE`、`CALL`、`INTO`、`OUTFILE`、`DUMPFILE` 等操作;
  124. - 默认最多返回 100 行,调用接口可请求 1 到 1,000 行;
  125. - 返回列名、行数据、行数、是否截断和耗时;敏感列会脱敏;
  126. - MySQL 和 PostgreSQL 使用只读事务,ClickHouse 使用 readonly 设置和 30 秒执行限制。
  127. 查询失败时,错误会显示在当前页面底部,不会强制跳转到其他页面。
  128. 示例:
  129. ```text
  130. 请从“销售库”查询最近 7 天每天的订单量,只返回日期和数量,不要修改数据。
  131. ```
  132. Agent 通常会先调用元数据搜索和单表详情工具,再生成符合上述约束的查询。这个流程不等同于一个可以执行任意 SQL 的完整 ChatBI 系统。
  133. ## Agent 工具
  134. 插件启动时注册以下固定工具:
  135. | 工具 | 用途 |
  136. | --- | --- |
  137. | `dsh_connect_list_data_sources` | 列出已启用数据源、类型、数据库名、对象数和扫描状态;不返回主机和凭据。 |
  138. | `dsh_connect_search_metadata` | 搜索表、视图、字段、业务名称、描述、标签和同义词。 |
  139. | `dsh_connect_get_table_metadata` | 根据 profile id 读取单表的 DDL、字段、主外键和语义信息;不返回样例行。 |
  140. | `dsh_connect_query_data_source` | 执行受限只读 SQL。 |
  141. | `dsh_connect_export_metadata_yaml` | 导出当前数据源的元数据和指标 YAML。 |
  142. | `dsh_connect_create_http_api` | 根据自然语言生成 HTTP API 的非敏感配置,并进入 DSH 审批流程。 |
  143. 每个已启用的 HTTP API 还会动态注册为:
  144. ```text
  145. dsh_connect_api_<slug>
  146. ```
  147. `slug` 只能使用小写字母、数字和下划线,并以小写字母开头。停用或删除 API 后,动态工具会同步移除。
  148. ## HTTP API 接入
  149. ### 在设置页面配置
  150. 进入 **设置 -> DSH连接器 -> HTTP API -> 添加 API**,填写:
  151. - 名称、工具标识(slug)和用途描述;
  152. - HTTP 方法:`GET`、`POST`、`PUT`、`PATCH` 或 `DELETE`;
  153. - 基础 URL 和路径模板;路径参数使用 `{name}`;
  154. - 参数位置:`path`、`query`、`header`、`body`;
  155. - 参数类型:`string`、`number`、`integer`、`boolean`、`json`;
  156. - 认证方式:无认证、Bearer Token、API Key 或 Basic Auth;
  157. - 超时(1,000~120,000 毫秒)、最大响应大小(1 KiB~2 MiB)和可选 JSON Pointer;
  158. - 是否允许访问私有网络、是否启用为 Agent 工具。
  159. 基础 URL 不应包含 query string;query 参数应声明在参数列表中。响应为 JSON 时,可使用 RFC 6901 JSON Pointer(例如 `/data/items`)只提取需要的部分。设置页提供 **测试请求**,测试错误会留在当前弹窗中。
  160. ### 配置示例
  161. 下面的定义会注册 `dsh_connect_api_weather`:
  162. ```text
  163. 名称:上海天气
  164. 工具标识:weather
  165. 描述:查询指定城市当前天气,返回温度和天气状况
  166. 方法:GET
  167. 基础 URL:https://api.example.com
  168. 路径模板:/v1/weather/{city}
  169. 参数:city / path / string / 必填
  170. 参数:units / query / string / 可选
  171. JSON Pointer:/data
  172. 认证:无
  173. ```
  174. 配置完成并启用后,在聊天中可以直接说:
  175. ```text
  176. 查一下上海今天的天气。
  177. ```
  178. Agent 会根据 API 描述填充 `city=上海` 并调用固定工具。模型不能临时修改基础域名、HTTP 方法、路径模板或声明之外的参数。
  179. ### 通过对话添加 API
  180. 固定工具 `dsh_connect_create_http_api` 支持用自然语言创建配置,但创建不是无确认写入,流程为:
  181. 1. 用户描述公开的 API 信息;
  182. 2. Agent 生成结构化的非敏感配置;
  183. 3. DSH 展示审批预览;
  184. 4. 用户批准后保存并注册工具。
  185. 示例:
  186. ```text
  187. 添加一个上海天气 API:
  188. GET https://api.example.com/v1/weather/{city}
  189. 参数 city 是路径参数,返回 JSON 的 /data,暂时不需要认证。
  190. ```
  191. 对话创建不会接受 token、密码、API key 值、Authorization 值或私网访问开关。需要认证时,只能在对话中声明认证类型和公开参数名;创建后 API 默认禁用,下一步到 **设置 -> DSH连接器 -> HTTP API** 填写凭据并启用。
  192. ## HTTP 安全边界
  193. - 只允许 `http` 和 `https`,URL 不得内嵌用户名、密码,也不得包含 fragment;
  194. - 基础 URL 和路径必须保持同一 origin,禁止重定向;
  195. - 默认拒绝私网、回环、链路本地和保留地址;私网访问只能由设置页面对固定 API 显式开启;
  196. - `Authorization`、`Host`、`Cookie`、`Content-Length`、`Connection` 等受控请求头不能由模型覆盖;
  197. - 动态调用只能传入配置中声明的参数,未知参数会被拒绝;
  198. - 请求超时和响应大小均受配置上限约束,响应超限会截断;
  199. - Bearer token、API key、Basic password 和数据库密码只保存在 DSH credential service 中,不会出现在设置列表或 Agent 返回值中。
  200. ## 变更记录与 YAML
  201. 元数据页面的 **变更记录** 使用分页摘要,只显示变更时间、动作和摘要,不加载整份 `before/after` YAML,避免大数据量导致页面卡顿。记录类型包括元数据创建、更新、扫描和 AI 建模。
  202. 点击 **导出 YAML**,或调用 `dsh_connect_export_metadata_yaml`,可以得到当前数据源的可审阅文本,内容包括:
  203. - 表和视图的业务名称、描述、标签、同义词和忽略状态;
  204. - 字段类型、可空性、主键标识和语义描述;
  205. - 已保存的指标定义。
  206. 导出的 YAML 适合代码审查、版本管理或在其他流程中二次处理;它不是回灌数据库的迁移脚本。
  207. ## RPC 开发者参考
  208. Host 端 RPC 前缀为 `/dsh-connect`:
  209. | 能力 | endpoint |
  210. | --- | --- |
  211. | 数据源 | `sources/list`、`sources/save`、`sources/delete`、`sources/test`、`sources/scan`、`sources/cancel`、`sources/query` |
  212. | 任务 | `jobs/list` |
  213. | 元数据 | `metadata/list`、`metadata/get`、`metadata/update`、`metadata/yaml`、`metadata/changes` |
  214. | 指标 | `metrics/list`、`metrics/recommend`、`metrics/save`、`metrics/save-batch`、`metrics/delete` |
  215. | HTTP API | `apis/list`、`apis/save`、`apis/delete`、`apis/test` |
  216. 所有写入 payload 都会经过 schema 校验。校验失败统一返回 `Invalid dsh-connect request`,具体字段错误在 RPC error details 中;业务执行错误会返回受限的安全错误信息。
  217. ## 目录结构
  218. ```text
  219. src/
  220. index.ts Host 插件入口
  221. domain.ts 持久化表定义
  222. types.ts 领域模型和校验 schema
  223. host/rpc.ts 设置页 RPC 和业务操作
  224. host/store.ts 存储访问及安全视图
  225. host/datasource/ MySQL、PostgreSQL、ClickHouse 接入
  226. host/metadata/ 元数据发现、AI 识别、指标和 YAML
  227. host/http/ HTTP 安全、执行器、动态工具、对话创建
  228. client/ DSH 设置界面
  229. tests/ 单元测试
  230. scripts/build.mjs Host 和 Browser 构建脚本
  231. ```
  232. ## 开发命令
  233. ```bash
  234. pnpm install # 安装依赖
  235. pnpm run typecheck # TypeScript 类型检查
  236. pnpm run test # 运行 Vitest
  237. pnpm run build # 构建 Host、Browser 和声明文件
  238. pnpm run check # 类型检查 + 测试 + 构建
  239. pnpm pack --pack-destination dist
  240. ```
  241. 构建产物为:
  242. - `lib/index.js`:Host ESM 插件入口;
  243. - `lib/client.js`:浏览器端设置页 loader bundle;
  244. - `lib/types/`:TypeScript 声明文件;
  245. - `dist/dsh-connect-0.1.0.tgz`:可安装的插件包。
  246. ## 常见问题
  247. ### AI 建模按钮不可用
  248. 请确认该数据库已勾选 **AI 语义增强(DSH 默认模型)**,并且 DSH 的默认模型服务已加载。dsh-connect 不提供单独的模型配置入口。
  249. ### 扫描很慢
  250. 扫描需要读取数据库对象;开启 AI 后还会逐个对象调用模型。日常同步使用默认的 `incremental`,只有需要重建语义结果时才使用 `rebuild-ai` 或 `full`。
  251. ### 停止扫描后为什么仍有部分元数据
  252. 扫描按对象逐个提交,停止前已经完成的对象会保留;未完成对象不会写入。只有扫描成功结束后,才会清理数据库中已经删除的旧对象。
  253. ### HTTP API 无法调用
  254. 检查 API 是否启用、凭据是否已在设置页配置,以及目标地址是否触发私网或 origin 安全策略。认证 API 通过对话创建后默认是禁用状态,必须先补充凭据再启用。
  255. ### 只读 SQL 报错
  256. 确认只提交一条 `SELECT` 或 `WITH`,不要带分号、注释或写入/DDL 关键字。页面会在当前只读 SQL tab 底部显示错误详情。
  257. ## License
  258. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.