@nsyan/db 1.0.0 → 1.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nsyan/db",
-  "version": "1.0.0",
-  "description": "AI 接入数据库扩展 —— 四大家族方言架构，支持 PostgreSQL/MySQL/Oracle/达梦/Redis/Elasticsearch/Hive/Spark，提供查询/表结构/扫描建连工具给 LLM",
+  "version": "1.1.0",
+  "description": "AI 接入数据库扩展 —— 五大家族方言架构，支持 PostgreSQL/MySQL/Oracle/达梦/Redis/Elasticsearch/MongoDB/Hive/Spark 九种数据库，提供查询/表结构/扫描建连/连接清单工具给 LLM",
   "keywords": [
     "pi-extension",
     "pi-package",
@@ -13,6 +13,8 @@
     "dm",
     "redis",
     "elasticsearch",
+    "mongodb",
+    "mongo",
     "hive",
     "spark"
   ],
@@ -43,6 +45,7 @@
     "es7": "npm:@elastic/elasticsearch@7",
     "hive-driver": "^1.0.1",
     "ioredis": "^6.0.0",
+    "mongodb": "^6.21.0",
     "mysql2": "^3.23.1",
     "oracledb": "^7.0.1",
     "pg": "^8.22.0"

package/src/config.ts

@@ -1,10 +1,10 @@
 // config.ts —— 连接配置与插件配置读写（含旧文件名兼容 + mtime 内存缓存）
 // 注：本模块只做 JSON 文件 IO，不依赖任何 pi 运行时模块
-import { existsSync, readFileSync, writeFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync, readFileSync, writeFileSync, statSync, chmodSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { registry } from "./dialects/index.js";
-import type { ConnConfig, DbTypeId } from "./core/types.js";
+import type { ConnConfig, DbTypeId, TestConnectionResult } from "./core/types.js";
 
 // ── 路径 ──────────────────────────────────────────
 
@@ -23,6 +23,8 @@ export interface PluginConfig {
   max_rows: number;
   /** 单条 SQL 超时秒数 */
   query_timeout: number;
+  /** 写操作审计日志（v1.1 UX 共识 Q4 修订：默认关闭，/db config 开启；reason 强校验不受此开关影响） */
+  audit_enabled: boolean;
 }
 
 export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
@@ -30,6 +32,7 @@ export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
   confirm_before_exec: "write",
   max_rows: 100,
   query_timeout: 30,
+  audit_enabled: false,
 };
 
 // ── mtime 内存缓存 ────────────────────────────────
@@ -78,6 +81,8 @@ export function loadConfigs(): ConnConfig[] {
 
 export function saveConfigs(configs: ConnConfig[]): void {
   writeFileSync(CONFIG_FILE, JSON.stringify(configs, null, 2));
+  // 降险（v1.1 UX 共识 Q4）：配置含明文密码，限制为仅当前用户可读写
+  try { chmodSync(CONFIG_FILE, 0o600); } catch { /* 只读文件系统等场景容错 */ }
   invalidateConfigCache(CONFIG_FILE);
 }
 
@@ -119,6 +124,7 @@ export function getConfigSummary(cfg: PluginConfig): string {
     `执行确认: ${confirmLabel}`,
     `最大行数: ${cfg.max_rows}`,
     `查询超时: ${cfg.query_timeout}s`,
+    `审计日志: ${cfg.audit_enabled ? "开" : "关"}`,
   ].join("\n");
 }
 
@@ -140,6 +146,8 @@ export interface ParsedConnectionString {
   password?: string;
   database?: string;
   dbIndex?: number;
+  /** URI 查询参数（MongoDB: authSource/replicaSet/tls...） */
+  options?: Record<string, string>;
 }
 
 export function parseConnectionString(input: string): ParsedConnectionString | null {
@@ -154,11 +162,70 @@ export function parseConnectionString(input: string): ParsedConnectionString | n
     if (p.password !== undefined) out.password = p.password;
     if (p.database !== undefined) out.database = p.database;
     if (p.dbIndex !== undefined) out.dbIndex = p.dbIndex;
+    if (p.options !== undefined) out.options = p.options;
     return out;
   }
   return null;
 }
 
+// ── 使用/测试记录（v1.1 UX 共识 Q1：连接列表摘要的数据源）───
+
+/** 回写最近使用时间（查询/列表/表结构成功后调用；找不到连接时静默跳过） */
+export function recordLastUsed(configName: string): void {
+  const all = loadConfigs();
+  const c = all.find((x) => x.name === configName);
+  if (!c) return;
+  c.lastUsedAt = new Date().toISOString();
+  saveConfigs(all);
+}
+
+/** 回写最近一次测试连接结果（测试连接/编辑后自动测试/向导建连成功时调用） */
+export function recordTestResult(configName: string, r: TestConnectionResult): void {
+  const all = loadConfigs();
+  const c = all.find((x) => x.name === configName);
+  if (!c) return;
+  c.lastTest = { ok: r.success, latency: r.latency, version: r.version, at: new Date().toISOString() };
+  saveConfigs(all);
+}
+
+/** 相对时间文案：刚刚 / N 分钟前 / N 小时前 / N 天前 / YYYY-MM-DD */
+export function formatRelativeTime(iso: string): string {
+  const t = new Date(iso).getTime();
+  if (!Number.isFinite(t)) return "";
+  const diff = Date.now() - t;
+  const min = Math.floor(diff / 60_000);
+  if (min < 1) return "刚刚";
+  if (min < 60) return `${min} 分钟前`;
+  const hour = Math.floor(min / 60);
+  if (hour < 24) return `${hour} 小时前`;
+  const day = Math.floor(hour / 24);
+  if (day < 30) return `${day} 天前`;
+  return iso.slice(0, 10);
+}
+
+/** 环境标签片段：[prod·强制只读] / [dev]；无标签返回空串 */
+export function envTagLabel(c: Pick<ConnConfig, "envTag" | "forceReadonly">): string {
+  if (!c.envTag) return "";
+  return `[${c.envTag}${c.forceReadonly ? "·强制只读" : ""}]`;
+}
+
+/** 连接摘要行（选择列表/查看列表共用）：名称 [类型] ⭐默认 [prod·强制只读] · 上次使用 … · 测试 … */
+export function connSummaryLine(c: ConnConfig): string {
+  const parts = [`${c.name} [${shortTypeLabel(c.type)}]`];
+  if (c.isDefault) parts.push("⭐默认");
+  const tag = envTagLabel(c);
+  if (tag) parts.push(tag);
+  if (c.lastUsedAt) {
+    const rel = formatRelativeTime(c.lastUsedAt);
+    if (rel) parts.push(`上次使用 ${rel}`);
+  }
+  if (c.lastTest) {
+    parts.push(`测试 ${c.lastTest.ok ? "✓" : "✗"}${c.lastTest.latency ?? ""}`);
+  }
+  const desc = c.description ? ` - ${c.description}` : "";
+  return parts.join(" · ") + desc;
+}
+
 // ── 默认连接（Spec §11.1 P0：database 参数可选，缺省走 isDefault 标记的连接）───
 
 export function getDefaultConfig(configs: ConnConfig[]): ConnConfig | undefined {
@@ -171,9 +238,6 @@ export function setDefaultConfig(configs: ConnConfig[], id: string): ConnConfig[
 
 // ── 查询结果导出（Spec §11.1 P0：长结果落盘不糊上下文）───
 
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
 import { toCsv } from "./core/export.js";
 
 export interface QueryExport {
@@ -212,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" } as Record<string, string>)[type] ?? type;
+  return ({ postgresql: "PG", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB" } as Record<string, string>)[type] ?? type;
 }
 
 export function fullTypeLabel(type: DbTypeId): string {
-  return ({ postgresql: "PostgreSQL", mysql: "MySQL", oracle: "Oracle" } as Record<string, string>)[type] ?? type;
+  return ({ postgresql: "PostgreSQL", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB" } as Record<string, string>)[type] ?? type;
 }

package/src/core/audit.ts

@@ -0,0 +1,67 @@
+// core/audit.ts —— 写操作审计日志（v1.1 UX 共识 Q4 + 轮转共识：按本地日期一天一个 .jsonl，SQL 存完整原文不截断）
+// 注：本模块只做文件 IO，不依赖任何 pi 运行时模块；审计失败静默降级，绝不阻断查询主流程
+
+import { appendFileSync, chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { DbTypeId } from "./types.js";
+
+/** 审计目录：~/.pi/agent/db-audit/，按天一个 <YYYY-MM-DD>.jsonl */
+export const AUDIT_DIR = join(homedir(), ".pi", "agent", "db-audit");
+
+export interface AuditEntry {
+  /** ISO 时间 */
+  time: string;
+  /** 执行时的项目路径（process.cwd()），跨项目区分用 */
+  project: string;
+  /** 连接名 */
+  connection: string;
+  /** 数据库类型 */
+  type: DbTypeId;
+  /** verdict.summary（如 "UPDATE orders（共 1 条语句）"） */
+  summary: string;
+  /** AI 提供的执行理由（全文） */
+  reason: string;
+  /** 完整 SQL（共识：不截断） */
+  sql: string;
+  /** 执行时的生效只读标记（写成功恒为 false，保留字段以备语义扩展） */
+  readonly: boolean;
+}
+
+/** 本地日期 → YYYY-MM-DD（审计文件按本地天轮转） */
+export function localDateStr(d: Date): string {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+/** 审计文件路径：<dir>/<YYYY-MM-DD>.jsonl（按 time 的本地日期取天） */
+export function auditFilePath(time: Date, dir: string = AUDIT_DIR): string {
+  return join(dir, `${localDateStr(time)}.jsonl`);
+}
+
+// 目录 mkdir / 文件 chmod 仅进程生命周期内首次执行（后续每次追加只剩 1 次 appendFileSync syscall）
+const ensuredDirs = new Set<string>();
+const chmoddedFiles = new Set<string>();
+
+/**
+ * 追加一条审计记录到按天轮转的 JSONL 文件（一行一条）。
+ * 同步写入保证返回结果前已落盘（单次开销亚毫秒级）；失败静默降级不阻断主流程。
+ * @param entry 审计条目
+ * @param dir 审计目录，默认 AUDIT_DIR（测试可注入临时目录）
+ */
+export function appendAuditLog(entry: AuditEntry, dir: string = AUDIT_DIR): void {
+  try {
+    if (!ensuredDirs.has(dir)) {
+      mkdirSync(dir, { recursive: true });
+      ensuredDirs.add(dir);
+    }
+    const file = auditFilePath(new Date(entry.time), dir);
+    appendFileSync(file, JSON.stringify(entry) + "\n", "utf-8");
+    if (!chmoddedFiles.has(file)) {
+      try { chmodSync(file, 0o600); } catch { /* 平台不支持等场景容错 */ }
+      chmoddedFiles.add(file);
+    }
+  } catch { /* 审计失败不影响主流程 */ }
+}

package/src/core/policy.ts

@@ -9,3 +9,16 @@ export function decide(verdict: Verdict, _readonly: boolean, confirm: ConfirmMod
   if (confirm === "write" && verdict.isWrite) return "confirm";
   return "run";
 }
+
+/** 生效只读 = 全局只读 ∨ 连接级强制只读（v1.1 UX 共识 Q3；isAllowed/ExecOpts 均用此值） */
+export function effectiveReadonly(aiReadonly: boolean, config: { forceReadonly?: boolean }): boolean {
+  return aiReadonly || config.forceReadonly === true;
+}
+
+/**
+ * 写操作是否缺失执行理由（v1.1 UX 共识 Q1/Q3：与确认策略解耦，isWrite 即要求）。
+ * 命中时工具层应拒绝执行并引导 AI 补充 reason（动机+影响范围）。
+ */
+export function writeRequiresReason(verdict: Verdict, reason?: string): boolean {
+  return verdict.ok === true && verdict.isWrite === true && !(typeof reason === "string" && reason.trim() !== "");
+}

package/src/core/scan/candidates.ts

@@ -20,6 +20,7 @@ interface FieldBag {
   username?: string; password?: string;
   database?: string; dbIndex?: number;
   ssl?: boolean;
+  options?: Record<string, string>;
   url?: string;
 }
 
@@ -41,6 +42,7 @@ const REQUIRED: Record<DbTypeId, string[]> = {
   spark: ["host", "port", "database", "username"],
   redis: ["host", "port", "password"],
   elasticsearch: ["host", "port"],
+  mongodb: ["host", "port"], // 账号/工作库可选（本地无认证常见）
 };
 
 // ── 工具函数 ──────────────────────────────────────
@@ -78,6 +80,7 @@ function dialectFromImage(image: string): DbTypeId | null {
   const i = image.toLowerCase();
   if (/postgres/.test(i)) return "postgresql";
   if (/(^|\/)(mysql|mariadb)/.test(i)) return "mysql";
+  if (/(^|\/)mongo/.test(i)) return "mongodb"; // mongo / mongodb 镜像（mongo-express 误报可忍变）
   if (/redis/.test(i)) return "redis";
   if (/elasticsearch/.test(i)) return "elasticsearch";
   if (/dm8|dameng/.test(i)) return "dm";
@@ -109,7 +112,9 @@ export async function scanProject(
   const dirEnvCache = new Map<string, Record<string, string> | undefined>();
 
   const pushUrl = (url: string, file: string, profile: string, confidence: number, keyFields?: Partial<RawDbConfig>): void => {
-    const parsed = parseUrlViaRegistry(stripQuery(url));
+    // 先用完整 URL 路由（MongoDB 的 authSource/replicaSet 等在 query 里，不能剥）；
+    // 失败再回退剥离 query 的旧路径（兼容 JDBC 带查询参数时各 parseUrl 的锚点匹配）
+    const parsed = parseUrlViaRegistry(url) ?? parseUrlViaRegistry(stripQuery(url));
     if (!parsed) return;
     raws.push({
       dialectId: parsed.dialectId,
@@ -123,6 +128,7 @@ export async function scanProject(
         database: parsed.database,
         dbIndex: parsed.dbIndex,
         ssl: parsed.ssl,
+        options: parsed.options,
       },
       file, profile, confidence,
     });
@@ -160,7 +166,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|DB_URL|JDBC_URL)$|_URL$/i.test(k)) {
+        if (/(^|_)(DATABASE_URL|DATASOURCE_URL|REDIS_URL|ELASTICSEARCH_URL|MONGODB_URI|MONGO_URL|DB_URL|JDBC_URL)$|_URL$/i.test(k)) {
           pushUrl(v, file, profile, weight);
         }
       }
@@ -175,9 +181,9 @@ 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"],
-            password: svc.env["POSTGRES_PASSWORD"] ?? svc.env["MYSQL_ROOT_PASSWORD"] ?? svc.env["MYSQL_PASSWORD"] ?? svc.env["REDIS_PASSWORD"] ?? svc.env["ELASTIC_PASSWORD"],
-            database: svc.env["POSTGRES_DB"] ?? svc.env["MYSQL_DATABASE"],
+            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"],
+            database: svc.env["POSTGRES_DB"] ?? svc.env["MYSQL_DATABASE"] ?? svc.env["MONGO_INITDB_DATABASE"],
           };
           raws.push({ dialectId, bag, file, profile, confidence: weight });
           // compose 里也可能带完整 Spring URL

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?|postgresql|mysql):\/\/[^\s"'<>`]+|https?:\/\/[^\s"'<>`]*:9200[^\s"'<>`]*/g;
+const URL_RE = /(?:jdbc:(?:postgresql|mysql|oracle|dm|hive2)|rediss?|mongodb\+srv|mongodb|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 键映射 + profile 分组
+// scan/spring.ts —— Spring 专属：datasource / data.redis / elasticsearch / data.mongodb 键映射 + profile 分组
 import type { DbTypeId } from "../types.js";
 
-export type SpringGroup = "datasource" | "redis" | "es";
+export type SpringGroup = "datasource" | "redis" | "es" | "mongo";
 
 export interface RawDbConfig {
   group: SpringGroup;
@@ -45,11 +45,14 @@ const SPRING_KEYS: Array<[string, Field]> = [
   ["spring.data.elasticsearch.uris", "url"],
   ["spring.data.elasticsearch.username", "username"],
   ["spring.data.elasticsearch.password", "password"],
+  ["spring.data.mongodb.uri", "url"],       // Spring Boot 2.x+（含 3.x）
+  ["spring.mongodb.uri", "url"],            // Spring Boot 1.x 旧前缀
 ];
 
 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 字段互相覆盖
   return "datasource";
 }
 

package/src/core/types.ts

@@ -1,7 +1,7 @@
 // core/types.ts
 export type DbTypeId = "postgresql" | "mysql" | "oracle" | "dm"
-  | "redis" | "elasticsearch" | "hive" | "spark";
-export type DbFamily = "relational" | "kv" | "search" | "bigdata";
+  | "redis" | "elasticsearch" | "mongodb" | "hive" | "spark";
+export type DbFamily = "relational" | "kv" | "search" | "document" | "bigdata";
 
 export interface ConnConfig {
   id: string; name: string; type: DbTypeId;
@@ -13,7 +13,16 @@ export interface ConnConfig {
   dbIndex?: number;                 // Redis 库号
   apiKey?: string;                  // ES 预留（二期）
   options?: Record<string, string>; // Hive/Spark 会话变量等（旧文件 extraParams 读取时并入此字段）
+  // MongoDB: authSource/replicaSet/tls/authMechanism 等（options.srv=true 标记 SRV 连接）
   isDefault?: boolean;              // 默认连接标记（§11.1，G 阶段接线）
+  /** 环境标签（v1.1 UX 共识 Q3）：dev/test/prod；prod 建议配 forceReadonly */
+  envTag?: "dev" | "test" | "prod";
+  /** 连接级强制只读：无视全局 ai_readonly，该连接永远只接受查询 */
+  forceReadonly?: boolean;
+  /** 最近一次成功使用时间（ISO）；工具/菜单查询成功后回写 */
+  lastUsedAt?: string;
+  /** 最近一次测试连接结果（菜单/向导/编辑后自动测试时回写） */
+  lastTest?: { ok: boolean; latency?: string; version?: string; at: string };
   createdAt: string;
 }
 
@@ -21,6 +30,8 @@ export interface ParsedTarget {
   host: string; port: number;
   username?: string; password?: string;
   database?: string; dbIndex?: number; ssl?: boolean;
+  /** URI 查询参数（MongoDB: authSource/replicaSet/tls...），由 parseUrl 解出、建连时回填 */
+  options?: Record<string, string>;
 }
 
 export interface DbConnection { type: DbTypeId; client: unknown; close(): Promise<void>; }

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` };
+    }
+  }
+}