前言¶
在 DSH 里让助手理解内网数据库结构，常见做法是外挂 SQL 客户端、手工导出 DDL，或依赖与业务系统绑定的工具链。这些路径往往带来凭证散落、驱动环境不一致，或把未脱敏的连接信息写进模型上下文等问题。下面介绍 stitchmaps 维护的独立插件 dsh-db-connect：在 DSH 客户端内完成连接配置、驱动诊断、连通性测试，以及分页浏览 schema → 表 → 列；它不依赖 HZsql、SQLBot、hz-workbench、traffic-domain 资产或其凭证体系。
这是什么¶
dsh-db-connect（GitHub：stitchmaps/dsh-db-connect）是面向 DeepSeek Harness 的客户端插件，当前版本 0.2.0。定位是内网数据库连接与元数据浏览：Oracle（含 11.2 Thick）、PostgreSQL、MySQL、MariaDB、SQL Server、SQLite。README 明确：不执行任意 SQL、不读应用行数据、不写库、不提供语义层；Redis、MongoDB、达梦等未实现。
核心功能¶
连接与驱动¶
- 多引擎连接配置；Oracle 支持 Thick/Thin、Service Name/SID，可指定 Oracle Client 目录。
- Windows 下凭据静态存储使用 CurrentUser DPAPI；公开 API 不返回密码，模型工具参数/结果中也不 echo 命令行密钥。
- Databases → Runtime 中配置独立 Python 解释器绝对路径并运行诊断；留空时 Host 依次尝试
DSH_DB_PYTHON与 PATH 上的 Python，不依赖 DSH 私有 bundled runtime 布局。 - 每条连接默认不对助手开放元数据；需显式启用。
元数据浏览¶
- 分页查看列详情（数据类型、可空、默认值、注释）及键/结构视图（主键、唯一与其他索引、外键）。
- 中英文 UI，使用 DSH theme tokens。
Host 与模型工具¶
- 共享 Host 应用服务承载 UI 与模型工具；子进程有界，支持取消与 deadline。
db_connections：仅返回已显式启用的连接 ID、标签、类型与 revision。db_inspect：动作包括test、schemas、tables、columns、indexes；分页默认 100 行、最大 200，通过hasMore与offset翻页。columns返回类型与注释等；indexes返回单表主键、索引与外键结构。- 工具不能创建连接、改密钥、自授权或改 Python 设置；元数据视为不可信数据而非指令。
驱动矩阵（摘要）¶
| 数据库 | 要点 |
|---|---|
| Oracle 11.2 | oracledb==3.4.2，Thick；推荐 Client 19c Basic，与 Python 架构一致 |
| Oracle 12.1+ | 同上驱动，Thin 或 Thick；Thin 无法连 11g |
| PostgreSQL | psycopg[binary] 3.x；默认 TLS verify-full |
| MySQL / MariaDB | PyMySQL[rsa] 1.x；默认校验证书 |
| SQL Server | pyodbc 5.x；需单独安装 ODBC Driver 18 |
| SQLite | 标准库 sqlite3；绝对路径，URI mode=ro 与 query_only |
其他驱动依赖见仓库 python/requirements.txt。插件启动时不下载包、不访问公网服务；@deepseek-ai/dsh-tools 由 DSH 提供 peer 包。
安装与启用¶
API 基线为 DSH 0.2.1-rc.3；manifest 声明 >=0.2.1-rc.3 <0.3.0。旧版 DSH 0.1.6 桌面不兼容。Node 要求 >=22.19.0（见 package.json）。
官方步骤如下（安装命令以 README 为准，勿手动追加 insert 条目）：
- 从 GitHub Releases 下载
dsh-db-connect-0.2.0.tgz，或通过仓库目录，使用当前 DSH 插件管理器的本地包安装能力，传入绝对路径安装。 - 准备独立 Python 环境（README 推荐 Windows x64 Python 3.12）。SQLite 仅用标准库；其余驱动按
python/requirements.txt安装。 - 打开 Databases → Runtime，设置解释器绝对路径并运行诊断。
- 添加并保存连接，再测试并浏览结构（仅保存不会连库）。
- 若需助手使用，再显式启用该连接的 assistant access。
注意：修改 Python 路径会清空已有密码与 assistant 授权；修改端点、用户名、库名、Oracle 模式/Client 目录或 TLS 配置需重新输入密码。应先配置解释器，再添加连接。
内网离线部署可参考 README 中的 PowerShell 脚本（prepare-offline.ps1 / setup-runtime.ps1），在匹配 OS、架构与 Python 主次版本的前提下准备 wheelhouse 并在目标机 --no-index 安装。
典型用法¶
客户端工作流¶
- 安装插件并配置 Runtime Python，直至诊断通过。
- 新建连接（按引擎填写主机、库/SID、TLS 等），保存后点测试。
- 在 UI 中分页浏览 schema、表、列与索引结构。
- 对允许助手访问的连接勾选启用；模型侧即可调用
db_connections与db_inspect拉取元数据（仍不执行任意 SQL）。
模型工具分页示例（概念）¶
对某已启用连接调用 db_inspect，例如 action: "tables"、schema: "<name>"，默认页大小 100；若响应 hasMore: true，下次传入更大 offset 继续读取，单页不超过 200。
适用场景与注意¶
适合：需要在 DSH 内统一管理内网库连接、做驱动自检、让助手在受控策略下查看表结构（而非跑 ad-hoc 查询或读业务数据）的团队。
务必知晓：
- 插件以当前 DSH 进程所在用户权限运行；DPAPI 无法隔离同 Windows 用户下任意代码；与 DSH 终端/文件工具共享同一身份。应对库账号最小权限，并按内网策略决定是否启用 assistant access。
- 配置持久化在
<DSH_HOME>/dsh-db-connect/connections.json（默认~/.dsh/）。损坏的配置fail closed，不会静默覆盖；跨机器或 Windows 账户需重录密码。 - 安装前请阅读源码与 MIT 许可证；社区目录 skillhub.cn 插件页 与 GitHub 为独立信息源，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-db-connect 把内网多引擎连接、驱动诊断与分页元数据浏览收进 DSH 客户端，并与 HZsql 等生态解耦；0.2.0 范围止于连接与元数据，不替代 SQL 客户端或数据访问层。进一步了解可查看 GitHub 仓库（含中文 README.zh.md、架构与验证文档）及 目录页。
