前言¶
DSH 的插件體系可以把外部能力掛到 agent 側。數據庫這類能力很常見，但直接讓模型執行任意 SQL 風險較高：讀庫需要穩定，寫庫需要審批，連接配置也需要集中管理。
dsh-sql 提供一套 SQL 工具，定位是工程師級數據庫插件，覆蓋連接管理、只讀查詢、寫操作與結構探查，支持 SQLite / MySQL / PostgreSQL 三引擎。
這是什麼¶
dsh-sql 是 DSH 插件，圍繞數據庫訪問提供四個工具：
sql_list：列出連接並做連通性測試。sql_query：執行只讀查詢。sql_exec：執行寫操作或 DDL。sql_schema：查看錶清單和表結構。
它強調只讀白名單、寫審批門、流式行數鉗制和多連接配置。許可證爲 MIT，運行要求 Node >=22.13。
核心功能¶
工具邊界¶
sql_list：用於確認當前配置了哪些連接，以及連接是否可用。sql_query：用於只讀查詢，支持SELECT、PRAGMA、EXPLAIN、SHOW、DESCRIBE、WITH；按關鍵字白名單校驗，並拒絕多語句。sql_exec：用於寫操作/DDL，可執行多語句腳本；受readOnly禁用與審批門控制。sql_schema：用於查看錶清單和表結構，並做標識符白名單校驗。
連接與限制¶
- 支持 SQLite / MySQL / PostgreSQL 三引擎。
- 支持多連接配置。
- 查詢返回行數上限
maxRows範圍爲1-10000。 queryTimeoutMs默認60秒，範圍5秒到10分鐘。execTimeoutMs默認120秒，範圍5秒到10分鐘。- 密碼支持環境變量
DSH_SQL_PASSWORD_<連接名>，例如連接名爲prod時使用DSH_SQL_PASSWORD_PROD。
安裝與啓用¶
在 Web profile 下安裝：
dsh plugin --profile web add dsh-sql
安裝後，sql_list、sql_query、sql_exec、sql_schema 可在 DSH 插件側使用。該插件已在 @deepseek-ai/dsh@0.1.2-alpha.4 源碼模式下驗證，驗證日期爲 2026-09-02。
典型用法¶
下面示例來自已覈實用法：
sql_list {}
sql_schema {}
sql_schema { table: users }
sql_query { sql: SELECT * FROM orders WHERE status = 'pending' LIMIT 50 }
sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
sql_list 用於先看有哪些連接是否可用；sql_schema 用於看錶結構；sql_query 用於只讀查詢；sql_exec 用於寫操作，默認會觸發審批。headless 環境無審批通道時，sql_exec 會拒絕執行。readOnly 爲 true 時，sql_exec 被禁用。
適用場景與注意¶
適合需要在 DSH 中接入數據庫、同時限制模型只讀或審批寫庫的場景。若連接生產庫，建議把寫操作放在受審批的環境中，並考慮使用 readOnly: true。密碼優先使用 DSH_SQL_PASSWORD_<連接名> 環境變量，不要寫入可公開配置。
使用前應將 dsh-sql 視爲以當前 dsh 進程權限運行：它能訪問的數據庫取決於該進程的連接與權限。安裝前建議先檢查源碼與許可證。卸載後需重啓 Web 服務；如需徹底清理，可手動刪除自己 profile cordis.patch.yml 中覆蓋的插件行。
結尾¶
dsh-sql 的價值在於把數據庫訪問拆成四個邊界更清晰的工具：列連接、讀查詢、受控寫、結構探查。這樣既能讓 agent 查庫，也能把寫操作限制在審批和只讀策略內。
