前言¶
在 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、架構與驗證文檔）及 目錄頁。
