dsh-db-connector：DeepSeek Harness 的安全數據庫連接器

DeepSeek Harness (DSH) 採用“一切皆插件”的架構。雖然其官方工具集覆蓋了基礎能力，但在數據庫訪問的安全性、只讀限制、寫入審批以及審計追蹤方面，往往需要額外處理。db-connector 插件爲此提供了一套完整的解決方案，支持 SQLite、PostgreSQL 和 MySQL，通過命名連接、架構自省和只讀保護來保障數據安全。

插件名稱爲 johnxu22786/db-connector，由 JohnXu22786 維護。它是一個數據庫連接器包，提供連接管理、架構自省、只讀安全策略、寫入審批門禁以及 SQL 審計日誌功能。

核心功能¶

該插件聚焦於數據庫訪問的四個核心維度：

連接管理：支持 SQLite、PostgreSQL 和 MySQL 的命名連接。連接支持延遲打開和複用，避免頻繁建立連接的開銷。
憑證安全：密碼通過環境變量或 dsh 憑據服務管理。配置項支持 passwordEnv 或 passwordRef，且絕不寫入日誌或審計記錄中。
架構自省：提供表、視圖、列、索引、外鍵信息的查詢。支持基於連接的緩存機制（TTL），並提供 refresh 參數強制刷新緩存，filter 參數用於過濾表名。
訪問控制：
- 只讀保護：db_query 工具僅允許執行 SELECT、EXPLAIN、DESCRIBE、SHOW 語句。任何其他語句（包括 INSERT/UPDATE/DELETE/DDL）在接觸數據庫前會被攔截，並記錄爲 denied 審計條目。
- 寫入審批：INSERT/UPDATE/DELETE/DDL 操作需要顯式的審批確認。支持事務保護和自動提交處理。

安裝與啓用¶

安裝前需確保環境滿足以下要求：
* Node.js 版本 >= 22.16
* 正在運行的 dsh 配置文件
* 可選依賴：PostgreSQL 需要 pg，MySQL 需要 mysql2

通過命令行安裝插件到指定 profile：

dsh plugin --profile <name> add /path/to/dsh-db-connector

安裝後，配置文件中需聲明 dsh.bundle.patch 指向該包的 cordis.patch.yml，或在 profile 的依賴中引入。

配置與使用¶

配置通常寫在插件的 config 塊中，支持 YAML 格式。以下是一個基礎配置示例：

- insert:
    - id: db-connector
      name: 'dsh-db-connector'
      inject: [tools, commands]
      config:
        # 預註冊連接，將在首次使用時延遲打開
        connections:
          appdata:
            driver: sqlite
            database: ./data/app.db
          warehouse:
            driver: postgres
            host: db.internal
            database: warehouse
            user: readonly
            passwordEnv: WAREHOUSE_PG_PASSWORD

        audit:
          enabled: true
          path: .dsh-db/audit.jsonl

        query:
          maxRows: 1000
          timeoutMs: 30000
          maxSqlChars: 512

        schema:
          ttlMs: 60000

        defaultAllowWrite: false

憑證引用¶

密碼通過引用而非明文存儲。passwordEnv 用於讀取環境變量，passwordRef 用於引用 dsh 憑據服務。配置中的字符串支持 ${VAR} 佔位符，系統會在連接時從環境變量展開。

工具使用¶

插件註冊了三個主要工具：

db_connect：管理連接。
- 註冊/重連：{ "action": "connect", "name": "app", "config": { "driver": "sqlite", "database": "./data/app.db" } }
- 列出連接：{ "action": "list" }
- 關閉連接：{ "action": "close", "name": "app" }
db_schema：查詢結構。
- 查詢結構：{ "name": "app", "refresh": false, "filter": "user" }
db_query：執行只讀查詢。
- 執行查詢：{ "sql": "SELECT * FROM users LIMIT 10" }
- 該工具會對 SQL 語句進行注入防護（參數綁定），並對結果行數和查詢字符數進行限制。

注意事項¶

獨立實現：這是一個獨立從零實現的插件，不依賴官方 DSH 工具代碼，其工具名稱和參數格式不綁定官方架構。
運行環境：插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證。
審計記錄：所有數據庫調用（包括成功的查詢、被拒絕的寫入嘗試、執行失敗的語句）均會生成 JSONL 格式的審計日誌，包含時間、連接、語句摘要、耗時、狀態和請求來源。