@nsyan/db 1.0.0 → 1.2.0

package/src/dialects/document-dialect.ts

@@ -0,0 +1,273 @@
+// dialects/document-dialect.ts —— 文档家族基类（JSON 命令信封解析、读写分类、limit 注入、结果拍平）
+// 注：交互语义是"发 JSON 命令文档、拿文档结果"（db.runCommand 形态），与关系型/KV/搜索的
+//     语句·命令·DSL 语义均不同，独立成基类。首个实现为 MongoDB（Spec 共识：Q1 选 JSON 信封）。
+
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
+  QueryResult } from "../core/types.js";
+import type { Dialect, Verdict, Fingerprints } from "./dialect.js";
+
+// ── 信封分类（读写管控核心，Spec 共识 Q3）──────────────
+// 读白名单 + 写需确认 + 管理/DDL/服务端 JS 恒拒 + 未知命令保守按写（ES parseDsl 同款兜底）
+
+/** 读命令白名单（小写；find/count/distinct/aggregate 分类前会先过 JS/写回深扫） */
+const READ_COMMANDS: ReadonlySet<string> = new Set([
+  "find", "count", "distinct", "aggregate",
+  "collstats", "dbstats", "listcollections", "listindexes", "dataSize",
+  "ping", "buildinfo", "hello", "ismaster", "isdbgrid", "serverstatus",
+]);
+
+/** 恒拒命令前缀（小写匹配；与只读开关无关）：DDL/复制集/分片/运维一刀切 */
+const DENY_PREFIXES: readonly string[] = [
+  "drop",       // drop / dropDatabase / dropIndexes / dropUsers ...
+  "create",     // create / createIndexes / createUser / createSearchIndexes ...
+  "replset",    // replSetInitiate / replSetReconfig / replSetStepDown ...
+  "addshard", "removeshard", "balancer",
+  "eval",       // eval / $eval 不走前缀也命中 DENY_COMMANDS，此处兜底变体
+  "shutdown", "kill", "fsync", "repair", "compact", "configurefailpoint",
+];
+
+/** 恒拒命令（精确小写匹配） */
+const DENY_COMMANDS: ReadonlySet<string> = new Set([
+  "collmod", "renamecollection", "converttocapped", "clonecollectionascapped",
+  "reindex", "setparameter", "setfeaturecompatibilityversion", "logrotate",
+  "enablesharding", "shardcollection", "movechunk", "moveprimary", "split",
+  "applyops", "currentop", "clone", "copydb", "clonecollection", "$eval",
+]);
+
+/** 服务端 JS 执行（任意深度出现即恒拒，Q3 共识） */
+const JS_KEYS: ReadonlySet<string> = new Set(["$where", "$function", "$accumulator"]);
+/** aggregate 写回管道阶段（任意深度出现 → 整条按写分类） */
+const AGG_WRITE_KEYS: ReadonlySet<string> = new Set(["$out", "$merge"]);
+
+/** 深度扫描：任意层的对象 key（小写）命中 targets 即 true */
+export function hasAnyKey(node: unknown, targets: ReadonlySet<string>): boolean {
+  if (Array.isArray(node)) return node.some((n) => hasAnyKey(n, targets));
+  if (node !== null && typeof node === "object") {
+    return Object.entries(node as Record<string, unknown>).some(([k, v]) =>
+      targets.has(k.toLowerCase()) || hasAnyKey(v, targets));
+  }
+  return false;
+}
+
+export interface EnvelopeClassified {
+  envelope?: Record<string, unknown>;
+  verdict: Verdict;
+}
+
+/** 解析 + 分类一条命令信封（isAllowed 与 executeOn 共用，保证裁决与执行一致） */
+export function classifyEnvelope(sql: string): EnvelopeClassified {
+  let body: unknown;
+  try {
+    body = JSON.parse(sql.trim());
+  } catch {
+    return {
+      verdict: {
+        ok: false,
+        reason: "MongoDB 命令信封必须是合法 JSON 对象，如 {\"find\":\"users\",\"filter\":{}}（单命令一次执行，不支持多语句）",
+      },
+    };
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return {
+      verdict: { ok: false, reason: "命令信封必须是 JSON 对象（顶层 key 为命令名），如 {\"find\":\"users\"}" },
+    };
+  }
+  const envelope = body as Record<string, unknown>;
+  const cmd = Object.keys(envelope)[0] ?? "";
+  const target = envelope[cmd];
+  const summary = `${cmd}${typeof target === "string" ? " " + target.slice(0, 40) : ""}`;
+
+  // 1) 服务端 JS 恒拒（比命令分类优先：$match 里夹带 $where 也拦）
+  if (hasAnyKey(envelope, JS_KEYS)) {
+    return {
+      envelope,
+      verdict: {
+        ok: false,
+        reason: "禁止服务端 JS 执行（$where / $function / $accumulator），与只读开关无关",
+        isWrite: true,
+        summary: `${summary}（硬限制）`,
+      },
+    };
+  }
+  // 2) 管理/DDL 恒拒（前缀 + 精确名单）
+  const cmdLower = cmd.toLowerCase();
+  if (DENY_PREFIXES.some((p) => cmdLower.startsWith(p)) || DENY_COMMANDS.has(cmdLower)) {
+    return {
+      envelope,
+      verdict: {
+        ok: false,
+        reason: `禁止执行管理/DDL 命令：${cmd}（硬限制）`,
+        isWrite: true,
+        summary: `${summary}（硬限制）`,
+      },
+    };
+  }
+  // 3) aggregate 含 $out/$merge → 整条按写（readonly 由 isAllowed 统一裁决）
+  if (cmdLower === "aggregate" && hasAnyKey(envelope, AGG_WRITE_KEYS)) {
+    return { envelope, verdict: { ok: true, isWrite: true, summary: `${summary}（$out/$merge 写回）` } };
+  }
+  // 4) 读白名单
+  if (READ_COMMANDS.has(cmdLower)) {
+    return { envelope, verdict: { ok: true, isWrite: false, summary } };
+  }
+  // 5) 已知写命令与其余未知命令一律按写（未知写意图不可排除）
+  return { envelope, verdict: { ok: true, isWrite: true, summary } };
+}
+
+// ── limit 注入（Spec 共识 Q8：无界查询自动封顶，bulk 上限 1000）───
+
+/** 单条写命令文档数组上限（防手滑不防恶意；writable 模式另有确认框兜底） */
+export const MAX_BULK_DOCS = 1000;
+
+export function injectLimits(envelope: Record<string, unknown>, maxRows: number): void {
+  const cmd = (Object.keys(envelope)[0] ?? "").toLowerCase();
+  if (cmd === "find") {
+    // Mongo 语义：limit ≤ 0 等价于“不限”，与未提供同等对待，一并收敛到 maxRows
+    const userLimit = typeof envelope.limit === "number" && Number.isFinite(envelope.limit) && envelope.limit > 0
+      ? envelope.limit : undefined;
+    const limit = Math.min(Math.max(1, Math.trunc(userLimit ?? maxRows)), maxRows);
+    envelope.limit = limit;
+    envelope.batchSize = limit; // db.command 走 firstBatch，batchSize 决定单批返回量
+    return;
+  }
+  if (cmd === "aggregate" && Array.isArray(envelope.pipeline)) {
+    // 空 pipeline 同样需要封顶（全集合扫描）
+    const last = envelope.pipeline.length > 0
+      ? envelope.pipeline[envelope.pipeline.length - 1] as Record<string, unknown> | null
+      : null;
+    const hasTailLimit = last !== null && typeof last === "object"
+      && ("$limit" in last || "$count" in last);
+    if (!hasTailLimit) {
+      envelope.pipeline = [...(envelope.pipeline as unknown[]), { $limit: maxRows }];
+    }
+    const cursor = (envelope.cursor !== null && typeof envelope.cursor === "object"
+      ? { ...(envelope.cursor as Record<string, unknown>) }
+      : {}) as Record<string, unknown>;
+    cursor.batchSize = maxRows;
+    envelope.cursor = cursor;
+    return;
+  }
+  // 写命令文档数组封顶（insert/update/delete 的 documents 字段）
+  for (const field of ["documents", "updates", "deletes"]) {
+    const arr = envelope[field];
+    if (Array.isArray(arr) && arr.length > MAX_BULK_DOCS) {
+      envelope[field] = arr.slice(0, MAX_BULK_DOCS);
+    }
+  }
+}
+
+// ── 结果拍平（Spec 共识 Q7：顶层字段并集，上限 50 列）───
+
+export const MAX_QUERY_COLUMNS = 50;
+
+/** BSON 值 → 展示原语：ObjectId 取 hex、其余 BSON 优先 toJSON（Binary/UUID → base64，避免 [object Object]）、Date ISO、对象/数组 JSON */
+function cellOf(v: unknown): unknown {
+  if (v === undefined) return null;
+  if (v === null || typeof v !== "object") return v;
+  const b = v as { toHexString?: () => string; _bsontype?: string; toJSON?: () => unknown };
+  if (typeof b.toHexString === "function") return b.toHexString();
+  if (b._bsontype) {
+    const j = typeof b.toJSON === "function" ? b.toJSON() : undefined;
+    return j !== undefined && j !== null && typeof j !== "object" ? j : JSON.stringify(v);
+  }
+  if (v instanceof Date) return v.toISOString();
+  return JSON.stringify(v);
+}
+
+export function flattenDocs(
+  docs: unknown[],
+  maxRows: number,
+): { columns: string[]; rows: unknown[][]; rowCount: number; truncated?: boolean } {
+  const shown = docs.slice(0, maxRows);
+  // 列 = 顶层字段并集，首现顺序，封顶 MAX_QUERY_COLUMNS
+  // truncated 语义对齐 bigdata 方言：结果数达 maxRows 上限即标截断（无法区分“恰好等于”）
+  const columns: string[] = [];
+  const seen = new Set<string>();
+  for (const d of shown) {
+    if (columns.length >= MAX_QUERY_COLUMNS) break;
+    if (d !== null && typeof d === "object" && !Array.isArray(d)) {
+      for (const k of Object.keys(d as Record<string, unknown>)) {
+        if (!seen.has(k)) {
+          seen.add(k);
+          columns.push(k);
+          if (columns.length >= MAX_QUERY_COLUMNS) break;
+        }
+      }
+    }
+  }
+  const rows = shown.map((d) => {
+    if (d === null || typeof d !== "object" || Array.isArray(d)) return [cellOf(d)];
+    const obj = d as Record<string, unknown>;
+    return columns.map((c) => cellOf(obj[c]));
+  });
+  return { columns, rows, rowCount: rows.length, truncated: docs.length >= maxRows };
+}
+
+// ── 基类 ──────────────────────────────────────────
+
+export abstract class DocumentDialect 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>;
+  /** 执行一条已过白名单的命令信封，返回驱动原始响应 */
+  protected abstract doCommand(client: unknown, config: ConnConfig,
+    envelope: Record<string, unknown>): Promise<unknown>;
+  /** 原始响应 → 文档数组（MongoDB 取 cursor.firstBatch / distinct.values，默认整响应单行） */
+  protected extractDocs(raw: unknown): unknown[] {
+    return [raw];
+  }
+  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 } = classifyEnvelope(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 { envelope, verdict } = classifyEnvelope(sql);
+    if (!envelope || !verdict.ok) {
+      return { success: false, error: verdict.reason ?? "命令被拒绝", duration: `${Date.now() - start}ms` };
+    }
+    injectLimits(envelope, opts.maxRows);
+    try {
+      const raw = await this.withConnection(
+        config,
+        (conn) => this.doCommand(conn.client, config, envelope),
+        opts.timeoutSec * 1000,
+      );
+      const docs = this.extractDocs(raw);
+      const { columns, rows, rowCount, truncated } = flattenDocs(docs, opts.maxRows);
+      return { success: true, columns, rows, rowCount, 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` };
+    }
+  }
+}

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

@@ -8,5 +8,7 @@ export { oracleDialect } from "./oracle.js";
 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";