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 格式的审计日志，包含时间、连接、语句摘要、耗时、状态和请求来源。