# @liziy/db-plugin

> 版本 2.2.1 — AI 接入数据库，原生 Node.js 实现

安装后，AI 助手可以直接查询你的数据库——无需手动切换工具、复制粘贴连接信息。

## 它做了什么

- 管理数据库连接（PostgreSQL / MySQL / Oracle）
- 给 LLM 注册了 3 个工具：`query_database`、`list_tables`、`describe_table`
- 系统提示自动注入「可用数据库」列表和当前执行策略，AI 每轮都能看到现有连接及读写权限，不用再猜连接名称
- 当 AI 需要查数据时，会自动使用这些工具，你只需告知它用哪个数据库
- 原生 Node.js 实现（`pg` / `mysql2` / `oracledb`），无需 Python

## 命令

| 命令 | 说明 |
|------|------|
| `/db` | 管理菜单：打开连接 / 编辑连接 / 新增连接 / 删除连接 / 设置 |
| `/db add` | 快速新增 |
| `/db edit` | 快速编辑 |
| `/db rm` | 快速删除 |
| `/db ls` | 列出所有连接 |
| `/db config` | 查看/修改全局设置 |

新增时只需提供 JDBC URL（如 `jdbc:postgresql://host:5432/db`），系统会自动解析类型和地址，并测试连接是否可达。

`/db` → `打开连接` 后进入循环操作菜单（执行查询 / 列出表 / 查看详情 / 编辑 / 删除），执行后留在当前菜单可连续操作，`← 返回` 退出。

## 设置

通过 `/db config` 修改全局设置。设置会在每轮对话注入系统提示，模型可以看到当前的只读和执行确认策略：

| 设置项 | 默认值 | 说明 |
|--------|--------|------|
| AI 只读模式 | 是 | 开启时 AI 只能执行 SELECT 查询；关闭时允许执行写操作 |
| 执行确认 | 写操作确认 | 不确认 / 写操作确认 / 每次都确认；当前策略会同步告知模型 |
| 最大行数 | 100 | 查询返回的最大行数 |
| 查询超时 | 30s | 单条 SQL 超时秒数 |

## 安全控制

- **执行策略同步**：系统提示会动态注入当前 AI 只读模式和执行确认设置，工具描述不会再固定声明只能查询
- **硬限制 DROP TABLE**：即使关闭只读模式，AI 也无法执行 DROP TABLE
- **只读模式**：开启时 AI 只能执行 SELECT，禁止 INSERT/UPDATE/DELETE；关闭时允许写操作
- **确认策略**：根据设置决定不确认、仅写操作确认或每条 SQL 确认
- **手工查询一致**：`/db` 菜单手工执行查询与 AI 工具使用相同的只读配置

## 安装

```bash
pi install npm:@liziy/db-plugin
```

> 依赖 `pg` / `mysql2` / `oracledb` / `typebox` npm 包，`pi install` 会自动安装。

## 版本历史

### 2.2.2

- “查看连接”更名“打开连接”；连接操作菜单改为循环，执行后留在当前菜单可连续操作，`← 返回` 退出

### 2.2.1

- 修复 AI 只读设置关闭后，工具描述仍让模型误认为只能执行 SELECT 的问题
- 在每轮系统提示中注入当前只读模式、执行确认策略和 `DROP TABLE` 硬限制
- 修复 `/db` 手工查询路径始终写死为只读的问题

### 2.2.0

- 系统提示注入「可用数据库」列表，AI 不再猜连接名称
- `/db` 菜单新增「编辑连接」，删除连接增加二次确认
- 「配置」改名「设置」，`database` 参数忽略大小写匹配
- 依赖改用 `typebox`（原 `@sinclair/typebox` 未声明且无法解析）

### 2.1.0

- 确认策略改为交互式确认框：AI 执行写操作时直接弹出确认框，用户可原地确认或取消
- 移除对 `/db` 命令的依赖，体验更流畅

### 2.0.0

- 从 Python 子进程迁移到原生 Node.js（`pg` / `mysql2` / `oracledb`）
- 移除 Python 依赖，不再需要手动 `pip install`
- 跨平台超时支持（`statement_timeout` / `max_execution_time`）
- 删除 `scripts/` 目录

### 1.0.0

- 初始发布：Python 子进程实现，支持 PostgreSQL / MySQL / Oracle

## 许可

MIT