@nsyan/db 1.1.0 → 1.2.0

package/README.md

@@ -4,171 +4,100 @@
 
 **AI 接入数据库插件 —— 方言化架构，原生 Node.js 实现**
 
-支持关系型 / KV / 搜索 / 文档 / 大数据五大家族，共 9 种数据库的查询、表结构浏览与项目配置扫描建连。
-
-![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)
+[![npm](https://img.shields.io/npm/v/@nsyan/db?color=blue)](https://www.npmjs.com/package/@nsyan/db)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
 
 </div>
 
+为 [pi](https://github.com/earendilofficial/pi) 提供 10 种数据库的查询、表结构浏览、扫描建连与安全管控：AI 通过 5 个工具读写数据库，用户通过 `/db` 菜单管理连接。
+
 ## ✨ 特性
 
-- **方言化架构**：`core/` + `dialects/` 零 pi 运行时依赖，为 MCP server 复用铺路
-- **9 种数据库**：PostgreSQL · MySQL · Oracle · 达梦 DM8 · Redis · Elasticsearch · MongoDB · Hive · Spark（Thrift Server）
-- **五大家族**：关系型 / KV / 搜索 / 文档 / 大数据，各有一套共享基类
-- **安全强化**：
-  - 多语句**逐条**检查，`SELECT 1; DROP TABLE x` 无法绕过
-  - 注释剥离后再匹配，`/* c */ DELETE` 无法绕过
-  - CTE-DML / `FOR UPDATE` 识别为写操作
-  - Redis 命令白名单（只读模式放行读命令，`FLUSHALL/CONFIG/SHUTDOWN` 恒拒）
-  - ES 端点白名单（只读模式放行读端点，`DELETE index` 恒拒）
-  - MongoDB JSON 命令信封白名单（读命令白名单，`drop*`/`create*`/管理命令/服务端 JS `$where/$function/$accumulator` 恒拒，aggregate 含 `$out/$merge` 按写分类）
-- **代码扫描建连** `/db scan`：从 Spring 配置 / docker-compose / .env 自动抽取连接候选
-- **P0 体验**：一键连接串（自动识别家族）、默认连接（`database` 参数可选）、`list_tables` pattern 过滤、超 50 行结果自动导出 CSV/JSON
+- **10 种数据库 · 6 家族**：PostgreSQL · MySQL · Oracle · 达梦 · Redis · Elasticsearch · MongoDB · Neo4j · Hive · Spark
+- **AI 工具**：查询 / 表结构 / 连接清单 / 扫描建连，读多写少场景的 token 友好输出
+- **扫描建连**：从 Spring / docker-compose / .env 自动抽取连接候选，终端确认后写入
+- **安全模型**：只读模式、写确认 + 执行理由、连接级强制只读、家族白名单、管理命令恒拒
+- **审计**（可选）：写操作按天落盘，含理由与完整 SQL
+- **零构建**：TypeScript 由 pi/tsx 直接加载，core/dialects 零 pi 运行时依赖
 
 ## 📦 安装
 
-**npm 安装（推荐，任意机器可用）：**
-
-```bash
-pi install npm:@nsyan/db
-```
-
-**本地源码安装（本仓库开发者）：**
-
 ```bash
-# 在本仓库根目录执行
-pi install ./packages/db
+pi install npm:@nsyan/db     # npm 安装（推荐）
+pi install ./packages/db     # 本仓库开发者
 ```
 
-> 依赖 `pg` / `mysql2` / `oracledb` / `dmdb` / `ioredis` / `@elastic/elasticsearch` / `es7` / `mongodb` / `hive-driver` / `typebox`，`pi install` 自动安装。
-
 ## 🚀 快速开始
 
-```bash
-/db add          # 新增连接（一键粘贴连接串，或按家族逐步填写）
-/db ls           # 列出所有连接
-/db scan         # 扫描项目源码自动建连
-/db config       # 查看/修改全局设置
-```
-
-AI 侧接入后，直接用 `query_database` / `list_tables` / `describe_table` / `scan_project_configs` / `db_connections` 五个工具即可。
-
-## 🗂️ 连接管理
-
-- **状态摘要列表**：连接选择器展示 `名称 [类型] ⭐默认 [prod·强制只读] · 上次使用 2 天前 · 测试 ✓45ms`，打开/编辑/删除/切默认共用
-- **⚡ 切换默认**：一级菜单直达（选中即切），无需进入连接动作菜单
-- **🧪 测试连接**：连接动作菜单内独立入口；**编辑保存后自动回测**，结果回显
-- **📋 从现有复制**：新增连接第三条路径，复制类型/账号/环境标签等全部设置，仅需改名
-- **环境标签 + 强制只读**：连接可标 `dev/test/prod`；`prod` 建连时主动建议开启**强制只读**——开启后该连接无视全局只读开关，永远只接受查询（AI 侧写入会被拒并提示原因）
-- **db_connections 工具**：AI 可自查连接清单与环境标签，说“在生产库查一下”时先识别哪条是 prod
-- 最近使用时间与测试结果自动回写，无需手工维护
+1. `/db add` 粘贴连接串一键建连（支持 `postgresql://` · `jdbc:*` · `redis://` · `mongodb+srv://` · `bolt://`/`neo4j://` · `http://host:9200`）
+2. 直接让 AI 查询：*「查一下订单表最近 10 条」*
+3. `/db scan` 从项目源码自动发现数据库连接（密码只在终端补录，不进模型上下文）
 
 ## 🗄️ 支持的数据库
 
-| 数据库 | 家族 | 驱动 | 支持版本 | 备注 |
-|--------|------|------|---------|------|
-| PostgreSQL | 关系型 | `pg` | 9.6 ~ 17 全系 | `statement_timeout` 全版本可用 |
-| MySQL | 关系型 | `mysql2` v3 | 5.7 / 8.0 / 8.4 | `max_execution_time` 需 ≥5.7.8，低版本自动忽略（客户端超时仍生效） |
-| Oracle | 关系型 | `oracledb`（Thin，零依赖） | ≥12.1 | Thin 模式硬性要求 DB ≥12.1，11g 及以下不支持（会给出版本原因指引）；Thick 模式列入后续迭代 |
-| 达梦 DM | 关系型 | `dmdb` | DM8 全系；DM9 未验证 | 纯 JS 依赖，macOS/Linux/Windows 可用 |
-| Redis | KV | `ioredis` | 2.8 ~ 8.x | `SCAN` 需 ≥2.8；`MEMORY USAGE` 需 ≥4.0，低版本自动跳过；生产库一律 SCAN，禁 `KEYS` |
-| Elasticsearch | 搜索 | `@elastic/elasticsearch` v8 + v7（npm 别名 `es7`） | 7.x / 8.x / 更新大版本 | 连接时探测大版本分发对应客户端；未知大版本用最新客户端尝试并给出版本警告 |
-| MongoDB | 文档 | `mongodb`（官方驱动，纯 JS） | **已验证主流区 6.0 / 7.0 / 8.0**；4.2~5.x 可用未验证（4.x 已 EOL） | `query_database` 的 sql 参数填 JSON 命令信封；`mongodb://` 与 Atlas `mongodb+srv://` 双形态；`describe_table` 优先读 `$jsonSchema` validator，缺失时采样 ≤100 文档推断字段（非权威）；无 limit 自动补 maxRows |
-| Hive | 大数据 | `hive-driver` | 目标 2.x；4.x 未实测 | HS2 Thrift 协议；无 4.x 环境前声明仅支持 2/3 |
-| Spark（Thrift Server） | 大数据 | `hive-driver`（复用） | 2.x ~ 4.x | 与 Hive 同协议栈；Spark Connect（DataFrame/gRPC）不支持 |
-
-> 版本兼容采用**端点抽测**：每个支持项只实测「最老支持版 + 最新版」两个端点，中间版本声明兼容不实测。
-
-## ⚙️ 新增连接
-
-`/db add` 首问选择「粘贴连接串（一键）」或「逐步填写」。连接串自动识别家族：
-
-```
-postgresql://user:pass@host:5432/db     → PostgreSQL
-jdbc:mysql://host:3306/db               → MySQL
-jdbc:oracle:thin:@//host:1521/svc       → Oracle（也支持 SID 形式）
-jdbc:dm://host:5236/schema              → 达梦
-redis://:pass@host:6379/0               → Redis（含 rediss:// TLS）
-mongodb://user:pass@host:27017/db       → MongoDB（含 +srv Atlas 形态，authSource/replicaSet 进 options）
-http://host:9200                        → Elasticsearch
-jdbc:hive2://host:10000/db              → Hive / Spark
-```
-
-逐步填写按家族分支：Redis 无账号要求、需库号（dbIndex）；MongoDB 账号可空（本地无认证常见）；ES/其余 URL + 账号 + 密码。
+| 数据库 | 家族 | 支持版本 |
+|--------|------|---------|
+| PostgreSQL | 关系型 | 9.6 ~ 17 |
+| MySQL | 关系型 | 5.7 / 8.0 / 8.4 |
+| Oracle | 关系型 | ≥12.1（Thin 零依赖） |
+| 达梦 DM | 关系型 | DM8 全系；DM9 未验证 |
+| Redis | KV | 2.8 ~ 8.x |
+| Elasticsearch | 搜索 | 7.x / 8.x+（自动探测大版本） |
+| MongoDB | 文档 | 已验证 6.0 / 7.0 / 8.0；4.2+ 可用 |
+| Neo4j | 图 | 官方兼容矩阵 4.4 ~ 2025.x；已验证 4.4.29 community |
+| Hive | 大数据 | 2.x / 3.x；4.x 未实测 |
+| Spark（Thrift Server） | 大数据 | 2.x ~ 4.x |
+
+> 版本采用**端点抽测**：只实测「最老支持版 + 最新版」，中间版本声明兼容。
+
+## 🧾 sql 参数形态
+
+`query_database` 的 `sql` 参数按家族填对应形态：
+
+| 家族 | 形态 | 示例 |
+|------|------|------|
+| KV · Redis | 空格分隔命令 | `GET key` / `SCAN 0 MATCH user:*` |
+| 搜索 · ES | JSON DSL | `{"query": {"match_all": {}}}` |
+| 文档 · MongoDB | JSON 命令信封 | `{"find": "users", "filter": {}}` |
+| 图 · Neo4j | Cypher | `MATCH (n:Person) RETURN n LIMIT 10` |
+
+关系型直接填 SQL。各家族示例与实现要点 → [docs/USAGE.md](./docs/USAGE.md)。
+
+## 🔐 安全模型
+
+| 机制 | 行为 |
+|------|------|
+| AI 只读模式 | **默认开**；关闭后允许写 |
+| 写确认 | 写操作弹框展示：理由 + 命令摘要 + SQL |
+| 写执行理由 | AI 必须附 `reason`（动机+影响范围），缺失直接拒绝 |
+| 连接级强制只读 | 标记的连接（如生产库）无视全局开关，永远只读 |
+| 家族白名单 | Redis/ES/Mongo 只读白名单；`DROP`、管理 DDL、服务端 JS、`CALL dbms.*` 恒拒 |
+| 审计日志 | 默认关；`/db config` 开启后写操作按天落盘（完整 SQL，0600） |
+| 凭据 | 配置文件 `0600`；扫描场景密码掩码，不进模型上下文 |
 
-## 🍃 MongoDB 命令信封
-
-MongoDB 走 `query_database`，`sql` 参数填 JSON 命令信封（`db.runCommand` 文档形态，单命令一次执行）：
-
-```json
-{"find": "users", "filter": {"age": {"$gt": 18}}, "sort": {"created_at": -1}}
-{"count": "users"}
-{"aggregate": "orders", "pipeline": [{"$group": {"_id": "$status", "n": {"$sum": 1}}}]}
-{"insert": "users", "documents": [{"name": "x"}]}
-```
-
-- 未写 limit 的读命令自动补 `maxRows`，结果超限自动标 `truncated`
-- 返回文档拍平为列（顶层字段并集，封顶 50 列，嵌套转 JSON 字符串）
-- `list_tables` → `listCollections`；`describe_table` → `collStats` + 索引 + validator/采样字段推断
-- 硬限制：`drop*`/`create*` 等管理 DDL 与服务端 JS（`$where`/`$function`/`$accumulator`）恒拒；aggregate 含 `$out`/`$merge` 按写操作处理
-
-## 🔎 代码扫描建连 `/db scan`
-
-从项目源码自动抽取连接信息（Spring `application*.yml/properties`、`docker-compose.yml`、`.env`、通用 URL 正则）：
-
-```bash
-/db scan            # 扫描当前工作目录
-/db scan ./backend  # 扫描指定子目录（越界拒绝）
-```
-
-扫描结果按状态分组：✅ 可直接建 / ✏️ 待补字段 / 🔒 jasypt 加密（只标注不建）/ ⏭️ 同名已存在。逐个确认后才写入配置——**绝不静默建连、绝不静默覆盖**。占位符 `${KEY:default}` 取 default，`${KEY}` 依次查同目录 `.env` → 进程环境变量，缺省在终端追问。
-
-AI 侧说「连一下这个项目的数据库」等，会调用 `scan_project_configs` 展示**掩码后**的候选（不写盘），建连仍需你在终端确认，密码不进模型上下文。
-
-## ⭐ 默认连接
-
-`/db` → 打开连接 → `⭐ 设为默认`。AI 调用工具时 `database` 参数可省略，缺省走默认连接；未设默认时给出指引。
-
-## 💾 查询结果导出
-
-查询结果超过 50 行时，完整结果自动导出到 `/tmp`（CSV + JSON 双格式），只返回文件路径。结果达到 `max_rows` 上限截断时有明确标注。
-
-## 🔐 安全控制
+## ⚙️ 设置
 
-- **执行策略同步**：系统提示动态注入当前 AI 只读模式与执行确认设置
-- **逐语句检查**：多语句 SQL 逐条检查，注释剥离后再匹配
-- **硬限制**：DROP TABLE/DATABASE（关系型/大数据）、`FLUSHALL/FLUSHDB/CONFIG/SHUTDOWN`（Redis）、`DELETE <index>`（ES）、`drop*`/`create*`/管理命令/服务端 JS（MongoDB）
-- **只读白名单**：Redis 读命令白名单、ES 读端点白名单、MongoDB 读命令白名单（JS 执行恒拒）
-- **连接级强制只读**：标了 `forceReadonly` 的连接（如生产库）无视全局开关，永远只读
-- **写操作执行理由**：AI 发起写操作必须附 `reason`（动机+影响范围），确认框首行展示、随结果回显；缺失时直接拒绝并引导补充，与确认策略无关
-- **本地审计（默认关闭）**：`/db config → 审计日志` 开启后，写成功追加 `~/.pi/agent/db-audit/<YYYY-MM-DD>.jsonl`（按天分文件，含项目路径/连接/理由/**完整 SQL 不截断**，0600）；审计失败不阻断主流程。清理示例：`find ~/.pi/agent/db-audit -name "*.jsonl" -mtime +90 -delete`。理由强校验不受此开关影响
-- **凭据降险**：连接配置含明文密码，保存时自动 `chmod 0600`（仅当前用户可读写）；系统钥匙串（keychain）列入远期规划
-- **确认策略**：不确认 / 写操作确认 / 每次确认；无 UI 环境自动取消
-- **手工查询一致**：`/db` 菜单手工执行与 AI 工具使用相同的策略裁决
+`/db config` 修改，每轮注入系统提示：
 
-## ⚙️ 设置
+| 设置项 | 默认值 |
+|--------|--------|
+| AI 只读模式 | 是 |
+| 执行确认 | 写操作确认 |
+| 最大行数 | 100 |
+| 查询超时 | 30s |
+| 审计日志 | 关 |
 
-通过 `/db config` 修改，每轮注入系统提示：
+## 📚 详细文档
 
-| 设置项 | 默认值 | 说明 |
-|--------|--------|------|
-| AI 只读模式 | 是 | 开启时 AI 只能执行查询；关闭时允许写操作 |
-| 执行确认 | 写操作确认 | 不确认 / 写操作确认 / 每次都确认 |
-| 最大行数 | 100 | 查询返回的最大行数 |
-| 查询超时 | 30s | 单条语句超时（服务端设置失败时客户端兜底） |
+连接管理（三种建连路径 / 环境标签 / 自动回测）、扫描建连、各家族 sql 详解、审计配置 → **[docs/USAGE.md](./docs/USAGE.md)**
+更新记录 → [CHANGELOG](../../CHANGELOG.md)
 
 ## 📁 开发
 
 ```bash
-pnpm install
-cd packages/db
-NODE_ENV=development pnpm test   # 运行全部单测（tsx + node:test）
+pnpm install && cd packages/db && pnpm test   # tsx + node:test，无构建产物
 ```
 
-## 📜 更新记录
-
-见仓库根目录 [CHANGELOG.md](../../CHANGELOG.md)。当前版本 **1.1.0**（2026-09-10）：新增 MongoDB 支持（document 家族）；连接管理体验升级（状态摘要/切换默认/从现有复制/环境标签+强制只读/db_connections 工具）。
-
 ## 📄 许可
 
 [MIT](./LICENSE)

package/docs/USAGE.md

@@ -0,0 +1,138 @@
+# db 使用手册
+
+主 README 是能力速览；本页承接全部使用细节。遇到本文未覆盖的行为，以 `src/` 代码与测试为准。
+
+## 🔗 连接管理
+
+### 新增连接（/db add）
+
+首问三选一：
+
+1. **⚡ 粘贴连接串（一键）**——自动识别家族：
+
+   ```
+   postgresql://user:pass@host:5432/db     → PostgreSQL
+   jdbc:mysql://host:3306/db               → MySQL
+   jdbc:oracle:thin:@//host:1521/svc       → Oracle（也支持 SID 形式）
+   jdbc:dm://host:5236/schema              → 达梦
+   redis://:pass@host:6379/0               → Redis（含 rediss:// TLS）
+   mongodb://user:pass@host:27017/db       → MongoDB（含 +srv Atlas 形态）
+   bolt://user:pass@host:7687/db           → Neo4j（也认 neo4j://、bolt+s(ssc)://、neo4j+s(ssc)://）
+   http://host:9200                        → Elasticsearch
+   jdbc:hive2://host:10000/db              → Hive / Spark
+   ```
+
+2. **📝 逐步填写**——按家族分支：Redis 无账号要求、需库号（dbIndex）；MongoDB 账号可空（本地无认证常见）；ES/其余 URL + 账号 + 密码。
+
+3. **📋 从现有复制**——复制现有连接的全部设置（类型/账号/options/环境标签），仅需改名，可选立即编辑。
+
+所有路径在测试连接通过后，会追问「环境标签」（dev/test/prod，可跳过）；选 prod 时主动建议开启**强制只读**。
+
+### 编辑与测试
+
+- `/db edit` 编辑器支持修改名称/URL/账号/密码/环境标签/强制只读/说明
+- **保存后自动回测**连接，结果即时回显并记录
+- 连接动作菜单含独立「🧪 测试连接」，结果（版本/延迟）写入连接摘要
+
+### 状态摘要与默认连接
+
+- 所有连接选择器展示：`名称 [类型] ⭐默认 [prod·强制只读] · 上次使用 2 天前 · 测试 ✓45ms`
+- 最近使用时间与测试结果自动回写，无需手工维护
+- 一级菜单「⚡ 切换默认」选中即切；AI 调用工具时 `database` 参数可省略，缺省走默认连接
+
+### 环境标签与强制只读
+
+- 连接可标 `dev / test / prod`，列表与 AI 系统提示均可见
+- `强制只读` 的连接**无视全局只读开关**，永远只接受查询；AI 侧写入会被拒并提示原因
+- 典型用法：全局允许写（开发库随便改），生产库连接强制只读
+
+## 🔎 扫描建连（/db scan）
+
+从项目源码自动抽取连接信息（Spring `application*.yml/properties`、`docker-compose.yml`、`.env`、通用 URL 正则）：
+
+```bash
+/db scan            # 扫描当前工作目录
+/db scan ./backend  # 扫描指定子目录（越界拒绝）
+```
+
+- 结果状态：✅ 可直接建 / ✏️ 待补字段 / 🔒 jasypt 加密（只标注不建）/ ⏭️ 同名已存在
+- **绝不静默建连、绝不静默覆盖**：逐个确认后才写入；占位符 `${KEY:default}` 取 default，`${KEY}` 依次查同目录 `.env` → 进程环境变量
+- AI 侧说「连一下这个项目的数据库」会调用 `scan_project_configs` 展示**掩码后**候选，建连仍需终端确认
+
+## 🧾 各家族 sql 形态详解
+
+### Redis（KV）
+
+`sql` 填空格分隔的命令，整体视为一条：
+
+```
+GET mykey
+SCAN 0 MATCH user:* COUNT 100      # 生产库一律 SCAN，禁 KEYS
+HGETALL myhash
+```
+
+只读白名单：GET/HGETALL/LRANGE/ZRANGE/SCAN/INFO 等；`FLUSHALL/FLUSHDB/CONFIG/SHUTDOWN` 恒拒。`describe_table` 对 key 返回类型/长度/TTL/内存/编码/值预览。
+
+### Elasticsearch（搜索）
+
+`sql` 填 JSON DSL（端点信封）：
+
+```json
+{"query": {"match_all": {}}}
+{"count": {"query": {"match": {"status": "paid"}}}}
+```
+
+顶层 key 决定端点：`query/count/mget` → 读；`bulk/delete/update` → 写；未知 key 保守按写。`DELETE <index>` 字符串恒拒。
+
+### MongoDB（文档）
+
+`sql` 填 JSON 命令信封（`db.runCommand` 文档形态，单命令一次执行）：
+
+```json
+{"find": "users", "filter": {"age": {"$gt": 18}}, "sort": {"created_at": -1}}
+{"count": "users"}
+{"aggregate": "orders", "pipeline": [{"$group": {"_id": "$status", "n": {"$sum": 1}}}]}
+{"insert": "users", "documents": [{"name": "x"}]}
+```
+
+实现要点：
+
+- **limit 注入**：未写 limit 的读命令自动补 `maxRows`（aggregate 自动追加 `$limit` 阶段），超限标 `truncated`
+- **结果拍平**：返回文档拍平为列——顶层字段并集，封顶 50 列，嵌套转 JSON 字符串；`_id` 取 hex
+- **list_tables** → `listCollections`；**describe_table** → `collStats` + 索引 + `$jsonSchema` validator（缺失时采样 ≤100 文档推断字段，非权威 schema）
+- **硬限制**：`drop*`/`create*` 等管理 DDL、服务端 JS（`$where`/`$function`/`$accumulator`）恒拒；aggregate 含 `$out`/`$merge` 按写分类；未知命令保守按写
+- 连接串：`mongodb://` 与 `mongodb+srv://`（SRV 默认 TLS）；`authSource` 缺省 `admin`，`replicaSet`/`authMechanism` 等经 options 贯通
+
+### Neo4j（图）
+
+`sql` 填 Cypher 原文，支持分号分隔多语句（逐条执行，返回最后一条结果）：
+
+```cypher
+MATCH (n:Person) RETURN n LIMIT 10
+MATCH (n:Person)-[r:KNOWS]->(m) WHERE n.age > 18 RETURN n, r, m
+CALL db.labels() YIELD label RETURN label
+SHOW INDEXES
+```
+
+实现要点：
+
+- **图结构即表**：`list_tables` 返回 node label（NODE LABEL）与关系类型（RELATIONSHIP，`rel:` 前缀）；`describe_table` 目标填 label 名或 `rel:类型`
+- **describe_table**：实体计数 + `SHOW INDEXES/CONSTRAINTS`（过滤目标）+ 采样 ≤100 推断属性键与类型分布（非权威 schema）；唯一约束属性标主键；只依赖核心过程，**不依赖 APOC**
+- **读写管控**：CREATE/MERGE/DELETE/DETACH/SET/REMOVE/DROP/FOREACH/LOAD CSV 任意深度出现即按写（`MATCH (n) DETACH DELETE n` 这类读外壳夹写拦得住）；字符串字面量与注释内的写词不误判；`CALL dbms.*` 管理过程**恒拒**；未知 CALL 过程（含 apoc.*）保守按写
+- **结果拍平**：Node 渲染为 `:Label {属性}`，Relationship 为 `-(TYPE)-> {属性}`，Path 为 `<path:n>`；无返回记录的写语句回显变更计数（创建节点 n，设置属性 m）
+- **limit 封顶**：客户端截断对齐关系型方言（不做 Cypher LIMIT 注入，任意语句尾部加 LIMIT 不总合法）
+- **连接串**：`bolt://`/`neo4j://`/`bolt+s://`/`neo4j+s://` 等；建连统一走 Bolt 直连（`bolt://`/`bolt+s://`）——单机社区版无路由服务，`neo4j://` 路由 scheme 会报 No routing servers available；URL 路径段 = 图数据库名（缺省 `neo4j`）
+- **扫描建连**：Spring `spring.neo4j.uri`（Boot 3）/ `spring.data.neo4j.uri`（Boot 2）+ authentication 账号密码键、`.env` `NEO4J_URI`/`NEO4J_URL`/`BOLT_URL`、docker-compose `neo4j` 镜像（`NEO4J_AUTH`/`NEO4J_PASSWORD`）、通用 URL 正则
+
+## ✍️ 写操作：理由与审计
+
+- AI 发起写操作必须附 `reason` 参数（动机 + 影响范围，如 *"将 status=2 的历史订单归档，预计影响 1.2 万行"*）
+- 确认框**首行展示理由**，执行结果末尾回显；缺失时拒绝并引导补充（与确认策略无关）
+- 开启审计（`/db config → 审计日志`）后，写成功追加 `~/.pi/agent/db-audit/<YYYY-MM-DD>.jsonl`：
+  - 一天一个文件；字段含时间/项目路径/连接/摘要/理由/**完整 SQL 不截断**
+  - 文件 `0600`；审计失败静默降级，不阻断主流程
+  - 清理示例：`find ~/.pi/agent/db-audit -name "*.jsonl" -mtime +90 -delete`
+
+## 💾 查询结果导出
+
+结果超过 50 行时自动导出 `/tmp`（CSV + JSON 双格式），只回文件路径；达到 `max_rows` 截断时有明确标注。

package/index.ts

@@ -58,6 +58,8 @@ function familyHint(c: ConnConfig): string {
       return "关系型，sql 参数填 SQL";
     case "mongodb":
       return "MongoDB 文档库，sql 参数填 JSON 命令信封（如 {\"find\":\"users\",\"filter\":{}}；读命令 find/count/distinct/aggregate）";
+    case "neo4j":
+      return "Neo4j 图数据库，sql 参数填 Cypher（如 MATCH (n:Person) RETURN n LIMIT 10；list_tables 列出 label 与关系类型，describe_table 目标填 label 名或 rel:类型）";
     default:
       return `${fullTypeLabel(c.type)}，sql 参数填查询或命令`;
   }
@@ -264,11 +266,11 @@ export default function (pi: ExtensionAPI) {
     let dbIndex: number | undefined;
 
     if (mode === "⚡ 粘贴连接串（一键）") {
-      const url = (await ctx.ui.input("连接串", "postgresql://user:pass@host:5432/db 或 jdbc:mysql://... 或 redis://:pass@host:6379/0 或 mongodb://user:pass@host:27017/db"))?.trim();
+      const url = (await ctx.ui.input("连接串", "postgresql://user:pass@host:5432/db 或 jdbc:mysql://... 或 redis://:pass@host:6379/0 或 mongodb://user:pass@host:27017/db 或 neo4j://user:pass@host:7687"))?.trim();
       if (!url) { ctx.ui.notify("连接串不能为空", "error"); return; }
       const pcs = parseConnectionString(url);
       if (!pcs) {
-        ctx.ui.notify("连接串无法识别。支持: postgresql/mysql/oracle/dm/hive JDBC、redis(s)://、mongodb(srv)://、http(s)://host:9200", "error");
+        ctx.ui.notify("连接串无法识别。支持: postgresql/mysql/oracle/dm/hive JDBC、redis(s)://、mongodb(srv)://、neo4j/bolt(s)://、http(s)://host:9200", "error");
         return;
       }
       parsed = { dialectId: pcs.dialectId, host: pcs.host, port: pcs.port, database: pcs.database, options: pcs.options };
@@ -285,6 +287,7 @@ export default function (pi: ExtensionAPI) {
           "  Oracle:     jdbc:oracle:thin:@//host:port/service 或 @host:port:SID\n" +
           "  Redis:      redis://[:password@]host:port[/db]\n" +
           "  MongoDB:    mongodb://user:pass@host:27017/db 或 mongodb+srv://...\n" +
+          "  Neo4j:      neo4j://user:pass@host:7687/db 或 bolt://host:7687（路径段为图数据库名）\n" +
           "  ES:         http://host:9200", "error");
         return;
       }
@@ -299,6 +302,11 @@ export default function (pi: ExtensionAPI) {
       } else if (parsed.dialectId === "mongodb") {
         username = (await ctx.ui.input("账号（可空，本地无认证留空）", ""))?.trim() ?? "";
         password = (await ctx.ui.input("密码（可空）", ""))?.trim() ?? "";
+      } else if (parsed.dialectId === "neo4j") {
+        username = (await ctx.ui.input("账号", "neo4j"))?.trim() || "neo4j";
+        password = (await ctx.ui.input("密码", ""))?.trim() ?? "";
+        const dbInput = (await ctx.ui.input("图数据库名（缺省 neo4j）", parsed.database ?? "neo4j"))?.trim();
+        parsed.database = dbInput || parsed.database || "neo4j";
       } else {
         username = (await ctx.ui.input("账号", "root"))?.trim() || "root";
         password = (await ctx.ui.input("密码", ""))?.trim() ?? "";
@@ -742,11 +750,11 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "query_database",
     label: "数据库查询",
-    description: "执行 SQL 语句，支持关系型（PostgreSQL/MySQL/Oracle/达梦）/ Redis / Elasticsearch / MongoDB / Hive / Spark 九种数据库，返回执行结果。支持读和写，写操作受确认策略约束且必须附 reason 执行理由（动机+影响范围），用户确认框将展示该理由；是否允许写以及是否需确认，以系统提示中的当前数据库工具执行策略为准。DROP TABLE 始终禁止。MongoDB 的 sql 参数填 JSON 命令信封（db.runCommand 形态，如 {\"find\":\"users\",\"filter\":{}}）。",
+    description: "执行语句，支持关系型（PostgreSQL/MySQL/Oracle/达梦）/ Redis / Elasticsearch / MongoDB / Neo4j / Hive / Spark 十种数据库，返回执行结果。支持读和写，写操作受确认策略约束且必须附 reason 执行理由（动机+影响范围），用户确认框将展示该理由；是否允许写以及是否需确认，以系统提示中的当前数据库工具执行策略为准。DROP TABLE 始终禁止。MongoDB 的 sql 参数填 JSON 命令信封（db.runCommand 形态，如 {\"find\":\"users\",\"filter\":{}}）；Neo4j 填 Cypher（如 MATCH (n:Person) RETURN n LIMIT 10）。",
     promptSnippet: "执行 SQL 语句。先根据系统提示中的当前数据库工具执行策略判断是否允许写操作；写操作必须在 reason 参数说明动机与影响范围（如\"将status=2的历史订单归档，预计影响1.2万行\"），否则会被拒绝。database 参数取系统提示「可用数据库」列表中的名称（缺省走默认连接）。使用 list_tables 查看表结构后再编写 SQL。",
     parameters: Type.Object({
       database: Type.Optional(Type.String({ description: "数据库连接名称（取系统提示「可用数据库」列表中的名称；缺省走默认连接）" })),
-      sql: Type.String({ description: "SQL 语句；MongoDB 填 JSON 命令信封，Redis 填命令，ES 填 DSL" }),
+      sql: Type.String({ description: "语句；关系型填 SQL，MongoDB 填 JSON 命令信封，Redis 填命令，ES 填 DSL，Neo4j 填 Cypher" }),,
       reason: Type.Optional(Type.String({ description: "执行理由，写操作必填：动机+影响范围（如\"将status=2的历史订单归档，预计影响1.2万行\"）。读操作无需填写" })),
     }),
     async execute(_toolCallId: string, params: { database?: string; sql: string; reason?: string }, _signal: any, _onUpdate?: any, ctx?: any) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nsyan/db",
-  "version": "1.1.0",
-  "description": "AI 接入数据库扩展 —— 五大家族方言架构，支持 PostgreSQL/MySQL/Oracle/达梦/Redis/Elasticsearch/MongoDB/Hive/Spark 九种数据库，提供查询/表结构/扫描建连/连接清单工具给 LLM",
+  "version": "1.2.0",
+  "description": "AI 接入数据库扩展 —— 六大家族方言架构，支持 PostgreSQL/MySQL/Oracle/达梦/Redis/Elasticsearch/MongoDB/Neo4j/Hive/Spark 十种数据库，提供查询/表结构/扫描建连/连接清单工具给 LLM",
   "keywords": [
     "pi-extension",
     "pi-package",
@@ -15,6 +15,9 @@
     "elasticsearch",
     "mongodb",
     "mongo",
+    "neo4j",
+    "graph",
+    "cypher",
     "hive",
     "spark"
   ],
@@ -32,6 +35,7 @@
   "files": [
     "index.ts",
     "src/",
+    "docs/",
     "README.md"
   ],
   "exports": {
@@ -47,7 +51,9 @@
     "ioredis": "^6.0.0",
     "mongodb": "^6.21.0",
     "mysql2": "^3.23.1",
+    "neo4j-driver": "^5.28.3",
     "oracledb": "^7.0.1",
+    "neo4j-driver": "^5.28.3",
     "pg": "^8.22.0"
   },
   "devDependencies": {

package/src/config.ts

@@ -276,9 +276,9 @@ export function toRuntimeConfig(c: ConnConfig, defaultPort: number): ConnConfig
 
 // 供 UI 层展示类型短标签（原 index.ts 内 5 处重复映射的收敛点之一）
 export function shortTypeLabel(type: DbTypeId): string {
-  return ({ postgresql: "PG", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB" } as Record<string, string>)[type] ?? type;
+  return ({ postgresql: "PG", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB", neo4j: "Neo4j" } as Record<string, string>)[type] ?? type;
 }
 
 export function fullTypeLabel(type: DbTypeId): string {
-  return ({ postgresql: "PostgreSQL", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB" } as Record<string, string>)[type] ?? type;
+  return ({ postgresql: "PostgreSQL", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB", neo4j: "Neo4j" } as Record<string, string>)[type] ?? type;
 }

package/src/core/scan/candidates.ts

@@ -42,6 +42,7 @@ const REQUIRED: Record<DbTypeId, string[]> = {
   spark: ["host", "port", "database", "username"],
   redis: ["host", "port", "password"],
   elasticsearch: ["host", "port"],
+  neo4j: ["host", "port", "username", "password"], // 工作库可选（缺省 neo4j；社区版默认开认证）
   mongodb: ["host", "port"], // 账号/工作库可选（本地无认证常见）
 };
 
@@ -82,6 +83,7 @@ function dialectFromImage(image: string): DbTypeId | null {
   if (/(^|\/)(mysql|mariadb)/.test(i)) return "mysql";
   if (/(^|\/)mongo/.test(i)) return "mongodb"; // mongo / mongodb 镜像（mongo-express 误报可忍变）
   if (/redis/.test(i)) return "redis";
+  if (/neo4j/.test(i)) return "neo4j";
   if (/elasticsearch/.test(i)) return "elasticsearch";
   if (/dm8|dameng/.test(i)) return "dm";
   if (/hive/.test(i)) return "hive";
@@ -166,7 +168,7 @@ export async function scanProject(
     if (base === ".env" || base.startsWith(".env.")) {
       const env = parseEnv(text);
       for (const [k, v] of Object.entries(env)) {
-        if (/(^|_)(DATABASE_URL|DATASOURCE_URL|REDIS_URL|ELASTICSEARCH_URL|MONGODB_URI|MONGO_URL|DB_URL|JDBC_URL)$|_URL$/i.test(k)) {
+        if (/(^|_)(DATABASE_URL|DATASOURCE_URL|REDIS_URL|ELASTICSEARCH_URL|MONGODB_URI|MONGO_URL|NEO4J_URI|NEO4J_URL|BOLT_URL|DB_URL|JDBC_URL)$|_URL$/i.test(k)) {
           pushUrl(v, file, profile, weight);
         }
       }
@@ -181,8 +183,8 @@ export async function scanProject(
           const bag: FieldBag = {
             host: svc.name, // compose 网络内服务名即主机名
             port: hostPortOf(svc.ports),
-            username: svc.env["POSTGRES_USER"] ?? svc.env["MYSQL_USER"] ?? svc.env["ES_USERNAME"] ?? svc.env["MONGO_INITDB_ROOT_USERNAME"],
-            password: svc.env["POSTGRES_PASSWORD"] ?? svc.env["MYSQL_ROOT_PASSWORD"] ?? svc.env["MYSQL_PASSWORD"] ?? svc.env["REDIS_PASSWORD"] ?? svc.env["ELASTIC_PASSWORD"] ?? svc.env["MONGO_INITDB_ROOT_PASSWORD"],
+            username: svc.env["POSTGRES_USER"] ?? svc.env["MYSQL_USER"] ?? svc.env["ES_USERNAME"] ?? svc.env["MONGO_INITDB_ROOT_USERNAME"] ?? svc.env["NEO4J_AUTH"]?.split("/")[0],
+            password: svc.env["POSTGRES_PASSWORD"] ?? svc.env["MYSQL_ROOT_PASSWORD"] ?? svc.env["MYSQL_PASSWORD"] ?? svc.env["REDIS_PASSWORD"] ?? svc.env["ELASTIC_PASSWORD"] ?? svc.env["MONGO_INITDB_ROOT_PASSWORD"] ?? svc.env["NEO4J_PASSWORD"],
             database: svc.env["POSTGRES_DB"] ?? svc.env["MYSQL_DATABASE"] ?? svc.env["MONGO_INITDB_DATABASE"],
           };
           raws.push({ dialectId, bag, file, profile, confidence: weight });

package/src/core/scan/parsers.ts

@@ -138,7 +138,7 @@ export function parseCompose(text: string): ComposeService[] {
 
 // ── 通用 URL 正则（全文件扫描兜底）──────────────────
 
-const URL_RE = /(?:jdbc:(?:postgresql|mysql|oracle|dm|hive2)|rediss?|mongodb\+srv|mongodb|postgresql|mysql):\/\/[^\s"'<>`]+|https?:\/\/[^\s"'<>`]*:9200[^\s"'<>`]*/g;
+const URL_RE = /(?:jdbc:(?:postgresql|mysql|oracle|dm|hive2)|rediss?|mongodb\+srv|mongodb|neo4j\+s(sc)?|neo4j|bolt\+s(sc)?|bolt|postgresql|mysql):\/\/[^\s"'<>`]+|https?:\/\/[^\s"'<>`]*:9200[^\s"'<>`]*/g;
 
 export function extractUrls(text: string): string[] {
   const out = new Set<string>();

package/src/core/scan/spring.ts

@@ -1,7 +1,7 @@
 // scan/spring.ts —— Spring 专属：datasource / data.redis / elasticsearch / data.mongodb 键映射 + profile 分组
 import type { DbTypeId } from "../types.js";
 
-export type SpringGroup = "datasource" | "redis" | "es" | "mongo";
+export type SpringGroup = "datasource" | "redis" | "es" | "mongo" | "neo4j";
 
 export interface RawDbConfig {
   group: SpringGroup;
@@ -47,12 +47,19 @@ const SPRING_KEYS: Array<[string, Field]> = [
   ["spring.data.elasticsearch.password", "password"],
   ["spring.data.mongodb.uri", "url"],       // Spring Boot 2.x+（含 3.x）
   ["spring.mongodb.uri", "url"],            // Spring Boot 1.x 旧前缀
+  ["spring.neo4j.uri", "url"],              // Spring Boot 3.x
+  ["spring.data.neo4j.uri", "url"],         // Spring Boot 2.x 旧前缀
+  ["spring.neo4j.authentication.username", "username"],
+  ["spring.neo4j.authentication.password", "password"],
+  ["spring.data.neo4j.username", "username"],
+  ["spring.data.neo4j.password", "password"],
 ];
 
 function groupOf(key: string): SpringGroup {
   if (key.includes("redis")) return "redis";
   if (key.includes("elasticsearch")) return "es";
   if (key.includes("mongodb")) return "mongo"; // 独立分组：避免与 datasource 的 url 字段互相覆盖
+  if (key.includes("neo4j")) return "neo4j";
   return "datasource";
 }
 
@@ -67,7 +74,23 @@ export function springKeysToRaw(dotted: Record<string, string>, file: string, we
     (raw as Record<string, unknown>)[field] = v;
     groups.set(g, raw);
   }
-  return [...groups.values()];
+  // baomidou dynamic-datasource（多数据源）：spring.datasource.dynamic.datasource.<name>.<field>
+  // 每个 <name> 独立成候选（与 Spec 单组 datasource 键互不覆盖）
+  const dynamic = new Map<string, RawDbConfig>();
+  const DYNAMIC_PREFIX = "spring.datasource.dynamic.datasource.";
+  for (const [key, value] of Object.entries(dotted)) {
+    if (!key.startsWith(DYNAMIC_PREFIX) || value === "") continue;
+    const rest = key.slice(DYNAMIC_PREFIX.length); // "<name>.<field>"
+    const dot = rest.indexOf(".");
+    if (dot <= 0) continue;
+    const name = rest.slice(0, dot);
+    const field = rest.slice(dot + 1);
+    if (field !== "url" && field !== "jdbc-url" && field !== "username" && field !== "password") continue;
+    const raw = dynamic.get(name) ?? { group: "datasource" as const, profile: profileOf(basename(file)), file, weight };
+    (raw as Record<string, unknown>)[field === "jdbc-url" ? "url" : field] = value;
+    dynamic.set(name, raw);
+  }
+  return [...groups.values(), ...dynamic.values()];
 }
 
 function basename(p: string): string {