前言¶

DeepSeek Harness（dsh）里，若要让 agent 查库、改数据或做维护，常见做法是临时写脚本或把连接串塞进对话上下文。Firebird 又往往跑在 Windows 服务器上，路径、认证插件和 wire 加密和默认 Node 驱动行为不一致，一旦把 SQL 和凭据交给模型自由拼接，风险和误连都很大。

下面介绍社区维护的 bundle 插件 dsh-firebird-connector（npm 包名 dsh-firebird-connector，维护者 long18229425025）。它在 dsh 里提供命名连接、只读/读写/管理三种访问模式、强制参数绑定、对象白名单、写操作与危险操作的确认门，以及 JSONL 审计；驱动在独立子进程执行，超时回收 worker，避免拖死整个 dsh 进程。

这是什么¶

dsh-firebird-connector 是面向 DeepSeek Harness 的 Firebird 2.5 / 3.0 / 4.0 / 5.0 数据库连接器 bundle。Agent 通过一组 firebird_* 工具在配置好的连接上工作，而不是直接持有 DSN 或明文密码。

插件按 profile 安装：Web（dsh web）与 Desktop 各自使用 ~/.dsh/profiles/web 与 ~/.dsh/profiles/desktop，配置与依赖互不影响。社区目录页：https://www.skillhub.cn/plugins/long18229425025/dsh-firebird-connector；源码与文档：https://github.com/long18229425025/dsh-firebird-connector。

核心约束与能力¶

资料中强调的设计边界如下，也是和「裸连数据库」的主要差别：

1. 凭据只来自环境变量（userEnv / passwordEnv）或 dsh 凭据引用（userRef / passwordRef）；配置里禁止 user、username、password 等明文字段，审计与工具结果也不写入密码。
2. SQL 必须通过 ? / :name 参数绑定；插件不接受把用户输入拼进 SQL 字符串。
3. 每个连接必须声明 accessMode：readonly、readwrite 或 admin，并可叠加 allowedObjects 白名单（空数组表示不限制对象名）。
4. 每次工具调用写入 JSONL 审计（含拒绝与失败）；日志里 SQL 只保留前 200 字符，并附完整 SQL 的 SHA-256。
5. 写操作默认需要显式确认；危险操作需二次确认；GRANT / REVOKE 使用两阶段一次性确认令牌。
6. node-firebird@^2.18.2 由 profile 单独安装，本包不 bundled 驱动，避免双份依赖。

环境要求：Node.js >= 20.19（dsh 自带运行时即可）、支持 bundle 的 dsh 版本、目标 Firebird 实例，以及 profile 内已安装的 node-firebird@^2.18.2。

安装与启用¶

dsh 插件没有全局目录；Web 端用 CLI 管理，Desktop 端 CLI 会拒绝 --profile desktop 的插件管理，需在桌面应用内操作。

Web profile¶

先安装驱动，再安装连接器；本地开发也可指向插件目录（README 中有示例路径）：

dsh plugin --profile web add "node-firebird@^2.18.2"
dsh plugin --profile web add "dsh-firebird-connector"

编辑 ~/.dsh/profiles/web/cordis.patch.yml 追加 firebird-connector 配置（见下一节），然后重启 dsh web。

Desktop profile¶

1. 打开左侧栏 插件（不是「设置 → 内置插件」）。
2. 添加插件，输入 dsh-firebird-connector；同样方式添加 node-firebird@^2.18.2。
3. 在 ~/.dsh/profiles/desktop/cordis.patch.yml 追加 firebird-connector 配置，勿覆盖已有 UI 配置行。
4. 完全退出并重启 Desktop；在「已安装插件」中确认条目。插件只注册 agent 工具，无独立菜单页；对话中调用 firebird_list_connections 验证。

只安装插件、不配置 connections 时，启动校验会失败，桌面端也看不到可用连接。

配置示例¶

每个 profile 单独配置。最小结构参考 README 与仓库内 config.example.yml：

- id: firebird-connector
  config:
    logLevel: info
    audit:
      file: ~/.dsh/firebird/audit.jsonl

    connections:
      app_ro:
        dsn: firebird://127.0.0.1:3050//data/app.fdb
        accessMode: readonly
        userEnv: FB_APP_RO_USER
        passwordEnv: FB_APP_RO_PASSWORD

      app_rw:
        host: 127.0.0.1
        port: 3050
        database: '/data/app.fdb'
        accessMode: readwrite
        allowedObjects: [CUSTOMERS, ORDERS, V_ORDERS]
        userRef: firebird/app-rw-user
        passwordRef: firebird/app-rw-password
        role: APP_WRITER
        allowRoleSwitch: true

凭据环境变量必须对 运行 dsh 的进程可见：Web 在启动 dsh web 的终端里设置；Desktop 若从开始菜单启动，通常要在系统用户环境变量中设置后重启应用。userEnv 与 userRef 二选一，同时配置会报错。

连接可用 dsn 或 host / port / database；DSN 支持 firebird://、jdbc:firebirdsql:// 等，且禁止在 DSN 里带账号或查询参数。插件默认 authPlugin: auto（先 Srp，必要时回退 Legacy_Auth）和 wireCrypt: false，以适配未强制 wire 加密的 Firebird 3.x；Windows 上数据库路径建议用 host + database，避免 /D://... 这类写法。

根配置仅允许 logLevel、audit.file 和 connections；未知字段会导致加载失败。

Agent 工具概览¶

工具均通过 defineTool 注册，返回 JSON 文本。下表摘自 README，便于对照 accessMode 选连接：

readwrite 仅覆盖表、视图、索引级 DDL；存储过程、触发器、角色等需 admin。CREATE DATABASE 与配置 SQL 里的 USER 语法会被拒绝，用户管理走 firebird_manage_user。

典型验证步骤：配置好只读连接后，在对话中让 agent 调用 firebird_list_connections，再对 app_ro 使用 firebird_query，传入绑定参数而非字面拼接条件。

适用场景与注意¶

适合：已在用 dsh 做运维或业务辅助，需要 agent 在 Firebird 上读数、受控写入或元数据探查，且希望凭据与 SQL 有统一护栏和审计的团队。

务必注意：

• 插件以 当前 dsh 进程的权限与环境变量运行；安装前应阅读源码与许可证（MIT，见 GitHub 与 npm 包 0.1.1）。
• 元数据工具不受 allowedObjects 限制；若对象名本身敏感，不要对不可信调用方开放相关工具。
• SkillHub 等社区目录与 DeepSeek / 幻方无官方从属关系，插件为社区贡献，非官方应用商店条目。

结尾¶

dsh-firebird-connector 把 Firebird 访问收进命名连接、参数化 SQL、模式分级和 JSONL 审计里，让 dsh agent 在可预期的边界内工作。安装时记得 profile 内同时提供 node-firebird@^2.18.2 与 cordis.patch.yml 中的 connections。

• 目录页：https://www.skillhub.cn/plugins/long18229425025/dsh-firebird-connector
• GitHub：https://github.com/long18229425025/dsh-firebird-connector