@nsyan/db 1.1.0 → 1.2.0

package/src/core/scan/walker.ts

@@ -1,6 +1,6 @@
 // scan/walker.ts —— 目录漫步：默认忽略常见无关目录；resolveRoot 越界拒绝（Spec §8.5 红线）
 import { readdirSync, statSync, type Dirent } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { extname, isAbsolute, join, relative, resolve } from "node:path";
 
 const IGNORED_DIRS = new Set([
   "node_modules", ".git", "target", "dist", "venv", "logs", "docs",
@@ -10,6 +10,13 @@ const IGNORED_DIRS = new Set([
 const MAX_FILES = 2000;
 const MAX_DEPTH = 8;
 
+/** 扫描目标配置文件：不受普通文件配额挤占（大型 Java 工程源码文件可轻易冲爆 MAX_FILES） */
+const CONFIG_EXTS = new Set([".yml", ".yaml", ".properties"]);
+function isConfigFile(name: string): boolean {
+  const base = name.toLowerCase();
+  return base === ".env" || base.startsWith(".env.") || CONFIG_EXTS.has(extname(base));
+}
+
 /**
  * 把输入路径解析为绝对路径；越界（cwd 子树之外、`..` 上跳、cwd 本身除外）
  * 直接抛 "scan path out of scope"——与「密码不进上下文」同级别的红线。
@@ -24,11 +31,13 @@ export function resolveRoot(input: string): string {
   return abs;
 }
 
-/** 递归收集文本候选文件（忽略无关目录与隐藏目录，上限 MAX_FILES）。 */
+/** 递归收集文本候选文件（忽略无关目录与隐藏目录，上限 MAX_FILES）；配置类文件单独收集不被挤占 */
 export function walk(root: string): string[] {
   const out: string[] = [];
+  const configs: string[] = [];
   const visit = (dir: string, depth: number): void => {
-    if (depth > MAX_DEPTH || out.length >= MAX_FILES) return;
+    // 不因 out 满而提前返回：必须走完整棵树，否则后遍历到的目录里的配置文件永远收不到
+    if (depth > MAX_DEPTH) return;
     let entries: Dirent[];
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
     for (const e of entries) {
@@ -37,11 +46,18 @@ export function walk(root: string): string[] {
       const p = join(dir, e.name);
       if (e.isDirectory()) visit(p, depth + 1);
       else if (e.isFile()) {
-        try { if (statSync(p).isFile()) out.push(p); } catch { /* ignore */ }
-        if (out.length >= MAX_FILES) return;
+        try {
+          if (statSync(p).isFile()) {
+            if (isConfigFile(e.name)) {
+              if (configs.length < MAX_FILES) configs.push(p);
+            } else if (out.length < MAX_FILES) {
+              out.push(p);
+            }
+          }
+        } catch { /* ignore */ }
       }
     }
   };
   visit(root, 0);
-  return out;
+  return [...configs, ...out];
 }

package/src/core/types.ts

@@ -1,14 +1,14 @@
 // core/types.ts
 export type DbTypeId = "postgresql" | "mysql" | "oracle" | "dm"
-  | "redis" | "elasticsearch" | "mongodb" | "hive" | "spark";
-export type DbFamily = "relational" | "kv" | "search" | "document" | "bigdata";
+  | "redis" | "elasticsearch" | "mongodb" | "hive" | "spark" | "neo4j";
+export type DbFamily = "relational" | "kv" | "search" | "document" | "bigdata" | "graph";
 
 export interface ConnConfig {
   id: string; name: string; type: DbTypeId;
   description?: string; host?: string; port?: number;
   username?: string; password?: string;
   /** 家族语义：关系型=库名 / DM=schema / Redis=不用（用 dbIndex）/
-      ES=默认 index / Hive-Spark=database 名 */
+      ES=默认 index / Hive-Spark=database 名 / Neo4j=图数据库名（缺省 neo4j） */
   database?: string;
   dbIndex?: number;                 // Redis 库号
   apiKey?: string;                  // ES 预留（二期）

package/src/dialects/dm.ts

@@ -8,18 +8,24 @@ import { register, filterTables, type Fingerprints } from "./dialect.js";
 // ── URL 解析（JDBC 主形态 + 原生 URI 双形态，Spec §7）───
 
 const DM_DEFAULT_PORT = 5236;
-const JDBC_RE = /^jdbc:dm:\/\/([^:/?#]+)(?::(\d+))?\/([^?#]+)$/;
-const NATIVE_RE = /^dm:\/\/([^:/?#@]+)(?::(\d+))?\/([^?#]+)$/;
+const JDBC_RE = /^jdbc:dm:\/\/([^:/?#]+)(?::(\d+))?(?:\/([^?#]*))?$/;
+const NATIVE_RE = /^dm:\/\/([^:/?#@]+)(?::(\d+))?(?:\/([^?#]*))?$/;
 
 function parseDmUrl(url: string): ParsedTarget | null {
-  const clean = url.split("?")[0];
+  const qIdx = url.indexOf("?");
+  const clean = qIdx >= 0 ? url.slice(0, qIdx) : url;
   const m = clean.match(JDBC_RE) ?? clean.match(NATIVE_RE);
   if (!m) return null;
   const host = m[1];
   const port = m[2] ? parseInt(m[2], 10) : DM_DEFAULT_PORT;
-  const database = m[3];
-  if (!host || !database) return null;
-  return { host, port, database };
+  // 库名 = URL 路径段；缺失时回退 query 的 schema= 参数（jdbc:dm://host:port?schema=x 常见形态）
+  let database = m[3] || undefined;
+  if (!database && qIdx >= 0) {
+    const schema = new URLSearchParams(url.slice(qIdx + 1)).get("schema");
+    if (schema) database = schema;
+  }
+  if (!host) return null;
+  return database !== undefined ? { host, port, database } : { host, port };
 }
 
 // ── DM（达梦）方言 ─────────────────────────────────
@@ -41,16 +47,29 @@ class DmDialect extends RelationalDialect {
   }
 
   displayUrl(config: ConnConfig): string {
-    return `jdbc:dm://${config.host}:${config.port}/${config.database}`;
+    return `jdbc:dm://${config.host}:${config.port}${config.database ? "/" + config.database : ""}`;
   }
 
   protected async doConnect(config: ConnConfig, _timeoutMs: number): Promise<DbConnection> {
-    const conn = await dmdb.getConnection({
-      user: config.username,
-      password: config.password,
-      connectString: `${config.host}:${config.port}`,
-      schema: config.database,
-    });
+    let conn: dmdb.Connection;
+    try {
+      // loginEncrypt=false：跳过握手消息加密。dmdb 默认走 MD5/RSA 遗留算法，
+      // Node≥17（OpenSSL 3）报 digital envelope routines::unsupported；
+      // 若服务端强制加密，请以 NODE_OPTIONS=--openssl-legacy-provider 启动宿主
+      conn = await dmdb.getConnection({
+        user: config.username,
+        password: config.password,
+        connectString: `${config.host}:${config.port}`,
+        schema: config.database,
+        loginEncrypt: false,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/digital envelope routines|ERR_OSSL/i.test(msg)) {
+        throw new Error(`${msg}（DM 登录加密与 Node≥17 OpenSSL 3 不兼容；请以 NODE_OPTIONS=--openssl-legacy-provider 启动 pi）`);
+      }
+      throw err;
+    }
     return {
       type: "dm",
       client: conn,
@@ -84,7 +103,8 @@ class DmDialect extends RelationalDialect {
       const tables = await this.withConnection(config, async (conn) => {
         const dmConn = conn.client as dmdb.Connection;
         const res = await dmConn.execute(
-          `SELECT TABLE_NAME, OWNER, COMMENTS FROM ALL_TABLES T
+          // 列名全部加表前缀：DM 对 JOIN 中的裸列名报 -2112 有歧义
+          `SELECT T.TABLE_NAME, T.OWNER, C.COMMENTS FROM ALL_TABLES T
            LEFT JOIN ALL_TAB_COMMENTS C ON T.TABLE_NAME = C.TABLE_NAME AND T.OWNER = C.OWNER
            WHERE T.OWNER NOT IN ('SYS', 'SYSDBA', 'SYSSSO', 'CTISYS')
            ORDER BY T.OWNER, T.TABLE_NAME`,
@@ -110,18 +130,25 @@ class DmDialect extends RelationalDialect {
     try {
       const columns: ColumnInfo[] = await this.withConnection(config, async (conn) => {
         const dmConn = conn.client as dmdb.Connection;
+        // schema 限定："schema.table" 显式指定，否则用连接 schema（config.database，大小写保持原样，
+        // DM 建库时可能带引号存为小写）；都无时不限定，保持旧兼容。避免同名表跨 schema 列重复
+        const dotIdx = table.indexOf(".");
+        const owner = (dotIdx > 0 ? table.slice(0, dotIdx) : config.database) || undefined;
+        const tableName = (dotIdx > 0 ? table.slice(dotIdx + 1) : table).toUpperCase();
+        const ownerFilter = owner ? " AND C.OWNER = :2" : "";
+        const binds = owner ? [tableName, owner] : [tableName];
         const res = await dmConn.execute(
           `SELECT
-            COLUMN_NAME,
-            DATA_TYPE || CASE WHEN DATA_PRECISION IS NOT NULL THEN '(' || DATA_PRECISION || ',' || DATA_SCALE || ')' WHEN DATA_LENGTH IS NOT NULL AND DATA_TYPE LIKE '%CHAR%' THEN '(' || DATA_LENGTH || ')' ELSE '' END,
-            NULLABLE,
-            DATA_DEFAULT,
-            COMMENTS
+            C.COLUMN_NAME,
+            C.DATA_TYPE || CASE WHEN C.DATA_PRECISION IS NOT NULL THEN '(' || C.DATA_PRECISION || ',' || C.DATA_SCALE || ')' WHEN C.DATA_LENGTH IS NOT NULL AND C.DATA_TYPE LIKE '%CHAR%' THEN '(' || C.DATA_LENGTH || ')' ELSE '' END,
+            C.NULLABLE,
+            C.DATA_DEFAULT,
+            COM.COMMENTS
           FROM ALL_TAB_COLUMNS C
           LEFT JOIN ALL_COL_COMMENTS COM ON C.TABLE_NAME = COM.TABLE_NAME AND C.COLUMN_NAME = COM.COLUMN_NAME AND C.OWNER = COM.OWNER
-          WHERE C.TABLE_NAME = :1 AND C.OWNER NOT IN ('SYS', 'SYSDBA', 'SYSSSO', 'CTISYS')
+          WHERE C.TABLE_NAME = :1${ownerFilter} AND C.OWNER NOT IN ('SYS', 'SYSDBA', 'SYSSSO', 'CTISYS')
           ORDER BY C.COLUMN_ID`,
-          [table.toUpperCase()],
+          binds,
         );
         const cols: ColumnInfo[] = (res.rows ?? []).map((r: any) => ({
           name: r[0],
@@ -132,14 +159,16 @@ class DmDialect extends RelationalDialect {
           comment: r[4] || "",
         }));
 
-        // 查主键
+        // 查主键（与列查询同 schema 限定）
         try {
+          const ownerFilterPk = owner ? " AND c.OWNER = :2" : "";
+          const bindsPk = owner ? [tableName, owner] : [tableName];
           const pkRes = await dmConn.execute(
             `SELECT cc.COLUMN_NAME
              FROM ALL_CONS_COLUMNS cc
              JOIN ALL_CONSTRAINTS c ON cc.CONSTRAINT_NAME = c.CONSTRAINT_NAME AND cc.OWNER = c.OWNER
-             WHERE c.CONSTRAINT_TYPE = 'P' AND c.TABLE_NAME = :1`,
-            [table.toUpperCase()],
+             WHERE c.CONSTRAINT_TYPE = 'P' AND c.TABLE_NAME = :1${ownerFilterPk}`,
+            bindsPk,
           );
           const pkSet = new Set((pkRes.rows ?? []).map((r: any) => r[0]));
           for (const col of cols) {

package/src/dialects/elasticsearch.ts

@@ -40,6 +40,26 @@ function makeClient(config: ConnConfig, ClientClass: new (opts: Record<string, u
   return new ClientClass(opts);
 }
 
+/** v7 客户端响应包 { body, statusCode, headers }，v8+ 直接返回体——统一解包 */
+function unwrap<T>(res: T | { body: T }): T {
+  const r = res as { body?: unknown } | null;
+  return r !== null && typeof r === "object" && "body" in r && (r as { body?: unknown }).body !== undefined
+    ? (r as { body: T }).body
+    : (res as T);
+}
+
+/** v7 客户端探测版本（v8/v9 产品校验拒收的低版本 ES 用） */
+async function probeVersionViaV7(config: ConnConfig): Promise<string> {
+  const v7 = makeClient(config, ClientV7 as unknown as new (opts: Record<string, unknown>) => AnyClient);
+  try {
+    const info = await (v7 as ClientV7).info();
+    const body = unwrap(info) as { version?: { number?: string } };
+    return body.version?.number ?? "";
+  } finally {
+    try { await v7.close(); } catch { /* ignore */ }
+  }
+}
+
 class ElasticsearchDialect extends SearchDialect {
   id = "elasticsearch" as const;
   label = "Elasticsearch";
@@ -60,33 +80,35 @@ class ElasticsearchDialect extends SearchDialect {
   }
 
   protected async doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection> {
-    // 先用"最新客户端"做无版本探测 GET /（testConnection 与 withConnection 共用）；
-    // GET / 返回 version.number 后按大版本分发（详见 testConnection）
+    // v8/v9 客户端强制产品校验（响应须带 X-elastic-product 头，ES 7.14+ 才有），
+    // 对 7.0~7.13 直接抛 "unknown product"。探测失败回退 v7 客户端再探——双探都失败才认定不可达。
     const probe = makeClient(config, ClientV8 as unknown as new (opts: Record<string, unknown>) => AnyClient);
+    let versionNumber = "";
+    let useV7 = false;
     try {
       const info = await (probe as ClientV8).info();
-      const versionNumber = (info as unknown as { version?: { number?: string } }).version?.number ?? "";
-      const major = pickMajor(versionNumber);
-      if (major === 7) {
-        const v7 = makeClient(config, ClientV7 as unknown as new (opts: Record<string, unknown>) => AnyClient);
-        return { type: "elasticsearch", client: v7, async close() { await v7.close(); } };
-      }
-      // 8 及未知更高大版本：一律用最新客户端尝试（未知版本不硬拒，warning 由 testConnection 给出）
-      return { type: "elasticsearch", client: probe, async close() { await probe.close(); } };
-    } catch (err: unknown) {
+      versionNumber = (info as unknown as { version?: { number?: string } }).version?.number ?? "";
+    } catch {
+      try { await probe.close(); } catch { /* ignore */ }
+      useV7 = true;
+      versionNumber = await probeVersionViaV7(config);
+    }
+    if (useV7 || pickMajor(versionNumber) === 7) {
       try { await probe.close(); } catch { /* ignore */ }
-      throw err;
+      const v7 = makeClient(config, ClientV7 as unknown as new (opts: Record<string, unknown>) => AnyClient);
+      return { type: "elasticsearch", client: v7, async close() { await v7.close(); } };
     }
+    // 8 及未知更高大版本：一律用最新客户端尝试（未知版本不硬拒，warning 由 testConnection 给出）
+    return { type: "elasticsearch", client: probe, async close() { await probe.close(); } };
   }
 
   async versionQuery(conn: DbConnection): Promise<string> {
     // 连接建立时已做版本探测，这里复用一次 GET / 取完整版本号
     const client = conn.client as ClientV8;
-    const info = await client.info();
-    return (info as unknown as { version?: { number?: string } }).version?.number ?? "unknown";
+    const info = unwrap(await client.info()) as { version?: { number?: string } };
+    return info.version?.number ?? "unknown";
   }
 
-  // testConnection 复写基类：同时返回服务端版本号 + 未知大版本的 warning（Spec §12）
   async testConnection(config: ConnConfig): Promise<TestConnectionResult> {
     const start = Date.now();
     try {
@@ -95,6 +117,9 @@ class ElasticsearchDialect extends SearchDialect {
       try {
         const info = await (probe as ClientV8).info();
         versionNumber = (info as unknown as { version?: { number?: string } }).version?.number ?? "";
+      } catch {
+        // v8/v9 产品校验拒收低版本 ES（<7.14 无产品头）→ v7 客户端探测
+        versionNumber = await probeVersionViaV7(config);
       } finally {
         try { await probe.close(); } catch { /* ignore */ }
       }
@@ -121,21 +146,21 @@ class ElasticsearchDialect extends SearchDialect {
       : undefined;
     if (kind.type === "query_string") {
       const res = await es.search({ index, size: opts.maxRows, q: kind.text });
-      return hitsToRows(res);
+      return hitsToRows(unwrap(res));
     }
     if (kind.type === "read") {
       if (kind.endpoint === "_count") {
         const res = await es.count({ index });
-        const count = (res as unknown as { count?: number }).count ?? 0;
+        const count = (unwrap(res) as unknown as { count?: number }).count ?? 0;
         return { columns: ["count"], rows: [[count]], rowCount: count };
       }
       if (kind.endpoint === "_mget") {
         const res = await es.mget({ index, body: { docs: [] } });
-        return docsToRows(res);
+        return docsToRows(unwrap(res));
       }
       // _search：DSL 整体即 body
       const res = await es.search({ index, body, size: opts.maxRows });
-      return hitsToRows(res);
+      return hitsToRows(unwrap(res));
     }
     throw new Error(`ES 写端点 ${kind.endpoint} 需走非只读确认流程执行，本方言 executeOn 仅执行读查询`);
   }
@@ -146,7 +171,7 @@ class ElasticsearchDialect extends SearchDialect {
       const tables: TableInfo[] = await this.withConnection(config, async (conn) => {
         const es = conn.client as ClientV8;
         const res = await es.cat.indices({ format: "json", h: "index,health,docs.count,store.size", s: "index" });
-        const rows = (res as unknown as Array<Record<string, string>>).slice(0, 500);
+        const rows = (unwrap(res) as unknown as Array<Record<string, string>>).slice(0, 500);
         return filterTables(rows.map((r) => ({
           schema: "",
           name: r["index"] ?? "",
@@ -170,9 +195,9 @@ class ElasticsearchDialect extends SearchDialect {
         const es = conn.client as ClientV8;
         const mappingRes = await es.indices.getMapping({ index: target });
         const settingsRes = await es.indices.getSettings({ index: target });
-        const mapping = mappingRes as unknown as Record<string, { mappings?: { properties?: Record<string, { type?: string; index?: boolean; analyzer?: string }> } }>;
+        const mapping = unwrap(mappingRes) as unknown as Record<string, { mappings?: { properties?: Record<string, { type?: string; index?: boolean; analyzer?: string }> } }>;
         const props = mapping[target]?.mappings?.properties ?? {};
-        const settings = settingsRes as unknown as Record<string, { settings?: { index?: Record<string, string> } }>;
+        const settings = unwrap(settingsRes) as unknown as Record<string, { settings?: { index?: Record<string, string> } }>;
         const idxSettings = settings[target]?.settings?.index ?? {};
         const cols: ColumnInfo[] = Object.entries(props).map(([name, def]) => ({
           name,

package/src/dialects/graph-dialect.ts

@@ -0,0 +1,234 @@
+// dialects/graph-dialect.ts —— 图家族基类（Cypher 语句切分、读写分类、结果拍平）
+// 交互形态：query_database 的 sql 参数填 Cypher 原文（与关系型"逐条执行取最后一条结果"一致，
+//     支持分号分隔多语句；注释与字符串字面量内的分号不切分）。
+// 首个实现为 Neo4j（bolt 协议官方驱动）。与 Mongo JSON 信封语义不同，独立成基类。
+
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
+  QueryResult } from "../core/types.js";
+import type { Dialect, Verdict, Fingerprints } from "./dialect.js";
+import { stripComments, splitStatements } from "../core/sql-text.js";
+
+// ── Cypher 读写分类（本家族管控核心，Spec 共识：关键字白名单 + 保守兜底）──────
+// 读 = MATCH/OPTIONAL MATCH/RETURN/WITH/UNWIND/SHOW（白名单类目）/CALL 只读过程白名单；
+// 写 = CREATE/MERGE/DELETE/DETACH/SET/REMOVE/DROP/FOREACH/LOAD CSV/TERMINATE 任意出现；
+// 恒拒 = CALL dbms.*（管理过程，与只读开关无关）；未知语句保守按写。
+
+/** 只读 CALL 过程白名单（小写精确前缀匹配；schema/元数据核心过程，不依赖 APOC） */
+const READ_PROCEDURES: ReadonlySet<string> = new Set([
+  "db.labels", "db.relationshipTypes", "db.propertyKeys",
+  "db.indexes", "db.constraints",
+  "db.schema.visualization", "db.schema.nodeTypeProperties", "db.schema.relTypeProperties",
+]);
+
+/** SHOW 允许的类目（其后第一个词）；TRANSACTIONS 需进一步排除 TERMINATE */
+const SHOW_CATEGORIES = /^(INDEX(?:ES)?|CONSTRAINT(?:S)?|PROCEDURES?|FUNCTIONS?|SETTINGS|DATABASES?|TRANSACTIONS?)\b/i;
+
+/** 写关键字（任意深度出现即整条按写）；字面量已剥离，不受字符串内容误伤 */
+// 注：(?<![\w.$`]) 防止 n.create / `Remove` 这类属性名·反引号标识符误命中；
+//     CALL {} 子查询本身不算写——子查询内的写关键字会被扫到，纯读子查询放行 */
+const WRITE_KEYWORD_RE =
+  /(?<![\w.$`])(?:CREATE|MERGE|DELETE|DETACH|SET|REMOVE|DROP|FOREACH|TERMINATE)(?![\w$`])|LOAD\s+CSV/i;
+
+/** 剥离字符串字面量（' "）与反引号标识符内容，防止值内写词误判 */
+function stripLiterals(text: string): string {
+  let out = "";
+  let q: string | null = null;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (q) {
+      if (ch === q) q = null; // 字面量内容整体丢弃（Cypher '' 双写转义已随内容消失）
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") { q = ch; out += " "; continue; }
+    out += ch;
+  }
+  return out;
+}
+
+/** 单条 Cypher 语句分类（isAllowed 与 executeOn 共用，保证裁决与执行一致） */
+export function classifyStatement(stmt: string): Verdict {
+  const clean = stripComments(stmt);
+  const head = clean.trim().slice(0, 80);
+  const text = stripLiterals(clean);
+  const summary = head.replace(/\s+/g, " ");
+
+  // 1) CALL dbms.* 管理过程恒拒（版本查询走 versionQuery 直连，不经此裁决）
+  if (/\bCALL\s+dbms\./i.test(text)) {
+    return { ok: false, reason: `禁止执行管理过程：CALL dbms.*（硬限制）`, isWrite: true, summary: `${summary}（硬限制）` };
+  }
+  // 2) SHOW 类目白名单；TERMINATE 已被写关键字拦截（TRANSACTION ... TERMINATE）
+  const showM = /^\s*SHOW\s+(\w+)/i.exec(text);
+  if (showM) {
+    if (!SHOW_CATEGORIES.test(showM[1])) {
+      return { ok: false, reason: `未知 SHOW 类目：${showM[1]}（按拒绝处理）`, isWrite: true, summary };
+    }
+    return { ok: true, isWrite: WRITE_KEYWORD_RE.test(text), summary };
+  }
+  // 3) 任意深度写关键字 → 按写（含 MATCH ... DELETE、FOREACH 内写、CALL {} 子查询写）
+  const isWrite = WRITE_KEYWORD_RE.test(text);
+  if (isWrite) return { ok: true, isWrite: true, summary };
+  // 4) CALL 过程：扫描全部过程名，任一不在白名单 → 保守按写
+  //    （apoc.* 无法安全区分读写，统一走写确认；dbms.* 已在步骤 1 恒拒）
+  const procs = [...text.matchAll(/\bCALL\s+([\w.]+)/gi)].map((m) => m[1].toLowerCase());
+  if (procs.length > 0) {
+    if (procs.every((p) => READ_PROCEDURES.has(p))) return { ok: true, isWrite: false, summary };
+    return { ok: true, isWrite: true, summary: `${summary}（未知过程，按写）` };
+  }
+  // 5) 已知读开头（MATCH/OPTIONAL/RETURN/WITH/UNWIND）→ 读；其余未知保守按写
+  if (/^\s*(MATCH|OPTIONAL|RETURN|WITH|UNWIND)\b/i.test(text)) {
+    return { ok: true, isWrite: false, summary };
+  }
+  return { ok: true, isWrite: true, summary: `${summary}（未知语句，按写）` };
+}
+
+/** 多语句分类：任一写 → 整体按写；任一恒拒 → 整体拒绝 */
+export function classifyCypher(sql: string): Verdict {
+  const stmts = splitStatements(sql);
+  if (stmts.length === 0) {
+    return { ok: false, reason: "Cypher 语句不能为空，如 MATCH (n:Person) RETURN n LIMIT 10" };
+  }
+  let anyWrite = false;
+  const parts: string[] = [];
+  for (const s of stmts) {
+    const v = classifyStatement(s);
+    if (!v.ok) return v;
+    if (v.isWrite) anyWrite = true;
+    if (v.summary) parts.push(v.summary);
+  }
+  return { ok: true, isWrite: anyWrite, summary: stmts.length > 1 ? `${stmts.length} 条语句` : parts[0] ?? "" };
+}
+
+// ── 结果拍平（Record → 行；Node/Relationship/Path 等 graph 类型转展示原语）───
+
+/** 驱动值 → 展示原语：Node/Relationship 摘要、Integer 取数值、时间类型 ISO、其余 JSON */
+export function cellOf(v: unknown): unknown {
+  if (v === undefined || v === null) return null;
+  const t = v as { __isInteger__?: boolean; toString?: () => string;
+    labels?: string[]; properties?: Record<string, unknown>;
+    type?: string; startNodeElementId?: string; endNodeElementId?: string;
+    elementId?: string; segments?: unknown[];
+    toISOString?: () => string };
+  // neo4j Integer（驱动返回自定义类型，防超长精度丢失）
+  if (typeof v === "object" && t.__isInteger__ && typeof t.toString === "function") {
+    const n = Number(t.toString());
+    return Number.isSafeInteger(n) ? n : t.toString();
+  }
+  // Node：label(:a:b) + 属性 JSON
+  if (Array.isArray(t.labels)) {
+    return (t.labels.map((l) => `:${l}`).join("") || ":?")
+      + " " + JSON.stringify(t.properties ?? {});
+  }
+  // Relationship：-[TYPE]-> + 属性 JSON
+  if (typeof t.type === "string" && t.startNodeElementId !== undefined) {
+    return `-(${t.type})-> ${JSON.stringify(t.properties ?? {})}`;
+  }
+  // Path：段数摘要（节点/关系全展开过于冗长）
+  if (Array.isArray(t.segments)) return `<path:${t.segments.length}>`;
+  // 时间类型：统一 ISO 字符串
+  if (typeof t.toISOString === "function") return t.toISOString();
+  if (typeof v === "object") return JSON.stringify(v);
+  return v;
+}
+
+export function flattenRecords(
+  records: unknown[],
+  maxRows: number,
+): { columns: string[]; rows: unknown[][]; rowCount: number; truncated?: boolean } {
+  const shown = records.slice(0, maxRows);
+  const columns: string[] = [];
+  const rows: unknown[][] = [];
+  for (const r of shown) {
+    const keys = (r as { keys?: string[] }).keys ?? [];
+    const values = (r as { _fields?: unknown[] })._fields ?? [];
+    for (const k of keys) if (!columns.includes(k)) columns.push(k);
+    rows.push(keys.map((_, i) => cellOf(values[i])));
+  }
+  return { columns, rows, rowCount: rows.length, truncated: records.length >= maxRows };
+}
+
+// ── 基类 ──────────────────────────────────────────
+
+export abstract class GraphDialect implements Dialect {
+  abstract id: Dialect["id"];
+  abstract label: string;
+  abstract family: Dialect["family"];
+  abstract defaultPort: number;
+  abstract fingerprints: Fingerprints;
+  abstract parseUrl(url: string): ParsedTarget | null;
+  abstract displayUrl(config: ConnConfig): string;
+  abstract versionQuery(conn: DbConnection): Promise<string>;
+  protected abstract doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection>;
+  /** 在图数据库上执行一条 Cypher 语句，返回驱动 Record 数组（database 缺省由方言决定） */
+  protected abstract runCypher(conn: DbConnection, config: ConnConfig,
+    cypher: string): Promise<{ records: unknown[]; summary: unknown }>;
+  abstract listTables(config: ConnConfig, pattern?: string): Promise<import("../core/types.js").ListTablesResult>;
+  abstract describeTable(config: ConnConfig, target: string): Promise<import("../core/types.js").DescribeTableResult>;
+
+  isAllowed(sql: string, readonly: boolean): Verdict {
+    const verdict = classifyCypher(sql);
+    if (!verdict.ok) return verdict;
+    if (verdict.isWrite && readonly) {
+      return { ...verdict, ok: false, reason: `只读模式下不允许执行写语句：${verdict.summary}` };
+    }
+    return verdict;
+  }
+
+  async executeOn(config: ConnConfig, sql: string, opts: ExecOpts): Promise<QueryResult> {
+    const start = Date.now();
+    const verdict = classifyCypher(sql);
+    if (!verdict.ok) {
+      return { success: false, error: verdict.reason ?? "语句被拒绝", duration: `${Date.now() - start}ms` };
+    }
+    try {
+      const stmts = splitStatements(sql);
+      const result = await this.withConnection(config, async (conn) => {
+        let last: { records: unknown[]; summary: unknown } = { records: [], summary: null };
+        for (const s of stmts) last = await this.runCypher(conn, config, s);
+        return last;
+      }, opts.timeoutSec * 1000);
+      const { columns, rows, rowCount, truncated } = flattenRecords(result.records, opts.maxRows);
+      const counters = summarizeCounters(result.summary);
+      // 写语句无返回记录时，用单列结果行回显变更统计（否则 rowCount=0 无反馈）
+      const outColumns = counters && columns.length === 0 ? ["result"] : columns;
+      const outRows = counters && columns.length === 0 ? [[counters]] : rows;
+      return {
+        success: true, columns: outColumns, rows: outRows, rowCount: outRows.length,
+        truncated, duration: `${Date.now() - start}ms`,
+      };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err), duration: `${Date.now() - start}ms` };
+    }
+  }
+
+  async withConnection<T>(config: ConnConfig, fn: (conn: DbConnection) => Promise<T>, timeoutMs = 10_000): Promise<T> {
+    const conn = await this.doConnect(config, timeoutMs);
+    try { return await fn(conn); }
+    finally { await conn.close(); }
+  }
+
+  async testConnection(config: ConnConfig): Promise<import("../core/types.js").TestConnectionResult> {
+    const start = Date.now();
+    try {
+      const version = await this.withConnection(config, (conn) => this.versionQuery(conn));
+      return { success: true, version, latency: `${Date.now() - start}ms` };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err), latency: `${Date.now() - start}ms` };
+    }
+  }
+}
+
+/** 写语句统计摘要（driver summary.counters → "created 2 nodes, set 3 props"） */
+function summarizeCounters(summary: unknown): string | undefined {
+  const c = (summary as { counters?: { _stats?: Record<string, number> } })?.counters?._stats;
+  if (!c) return undefined;
+  const LABELS: Record<string, string> = {
+    nodesCreated: "创建节点", nodesDeleted: "删除节点", relationshipsCreated: "创建关系",
+    relationshipsDeleted: "删除关系", propertiesSet: "设置属性", labelsAdded: "添加标签",
+    labelsRemoved: "移除标签", indexesAdded: "创建索引", indexesRemoved: "删除索引",
+    constraintsAdded: "创建约束", constraintsRemoved: "删除约束",
+  };
+  const parts = Object.entries(c)
+    .filter(([k, v]) => v > 0 && LABELS[k])
+    .map(([k, v]) => `${LABELS[k]} ${v}`);
+  return parts.length > 0 ? parts.join("，") : undefined;
+}

package/src/dialects/index.ts

@@ -9,5 +9,6 @@ export { dmDialect } from "./dm.js";
 export { redisDialect } from "./redis.js";
 export { esDialect } from "./elasticsearch.js";
 export { mongoDialect } from "./mongodb.js";
+export { neo4jDialect } from "./neo4j.js";
 export { hiveDialect } from "./hive.js";
 export { sparkDialect } from "./spark.js";

package/src/dialects/kv-dialect.ts

@@ -37,6 +37,7 @@ const READ_CMDS = [
   "LRANGE", "LLEN", "LINDEX", "SMEMBERS", "SCARD", "SISMEMBER",
   "ZRANGE", "ZSCORE", "ZCARD", "SCAN", "TYPE", "TTL", "PTTL", "EXISTS",
   "STRLEN", "GETRANGE", "INFO", "DBSIZE", "RANDOMKEY", "OBJECT", "MEMORY",
+  "PING", "TIME", "ECHO", "LOLWUT", "LASTSAVE",
 ];
 
 // ── 恒拒命令（与只读开关无关；CONFIG 一刀切含 CONFIG GET，有意从紧）───
@@ -109,7 +110,19 @@ export abstract class KvDialect implements Dialect {
 }
 
 // ── 命令结果转行（展示层统一转字符串，保持原类型）───
+// ioredis sendCommand 对字符串响应可能返回 Buffer，先递归解码为 UTF-8
+// （否则 INFO/SCAN/GET 等会按字节逐行渲染成乱码数字）
+function decodeValue(v: unknown): unknown {
+  if (Buffer.isBuffer(v)) return v.toString("utf8");
+  if (Array.isArray(v)) return v.map(decodeValue);
+  if (v !== null && typeof v === "object") {
+    return Object.fromEntries(Object.entries(v as Record<string, unknown>).map(([k, x]) => [k, decodeValue(x)]));
+  }
+  return v;
+}
+
 function toRows(cmd: string, raw: unknown): unknown[][] {
+  raw = decodeValue(raw);
   if (raw === null || raw === undefined) return [];
   if (Array.isArray(raw)) {
     // 偶数长度数组（HGETALL 等）按 k/v 配对展示

package/src/dialects/mongodb.ts

@@ -224,6 +224,13 @@ class MongoDialect extends DocumentDialect {
     const r = raw as RawCommandResult;
     if (r?.cursor?.firstBatch !== undefined) return r.cursor.firstBatch;
     if (Array.isArray(r?.values)) return r.values.map((v) => ({ value: v })); // distinct
+    // 单文档响应（count/insert 等）：剥掉协议噪声字段 ok:1，避免多一列无信息量输出
+    // （仅剩 ok 一键时保留，避免空列）
+    if (r !== null && typeof r === "object" && "ok" in r && Object.keys(r).length > 1) {
+      const clone = { ...(r as Record<string, unknown>) };
+      delete clone.ok;
+      return [clone];
+    }
     return [raw]; // count/collStats/写结果等单文档响应
   }
 

package/src/dialects/mysql.ts

@@ -78,7 +78,18 @@ class MysqlDialect extends RelationalDialect {
     try {
       await mysqlConn.execute(`SET max_execution_time = ${timeoutMs}`);
     } catch { /* ignore: server too old for max_execution_time */ }
-    const [rows, fields] = await mysqlConn.execute(stmt);
+    // 事务控制等语句（START TRANSACTION/BEGIN/COMMIT/ROLLBACK…）不支持 prepared 协议，
+    // mysql2 抛 ER_UNSUPPORTED_PS；此类语句降级 query()（插件从不绑定参数，语义等价）
+    let result: [unknown, unknown];
+    try {
+      result = await mysqlConn.execute(stmt);
+    } catch (err) {
+      const code = (err as { code?: string } | null)?.code ?? "";
+      const msg = err instanceof Error ? err.message : String(err);
+      if (code !== "ER_UNSUPPORTED_PS" && !/prepared statement protocol/i.test(msg)) throw err;
+      result = await mysqlConn.query(stmt);
+    }
+    const [rows, fields] = result as [{ affectedRows?: number; length?: number }, Array<{ name: string }>];
     if (Array.isArray(fields) && fields.length > 0) {
       const columns = fields.map((f: any) => f.name);
       const data = (rows as any[]).slice(0, maxRows).map((r: any) => columns.map((col: string) => r[col]));