@nsyan/db 1.3.0 → 1.3.1

package/index.ts

@@ -50,13 +50,21 @@ function buildDisplayList(configs: ConnConfig[]): { list: string[]; map: Map<str
 // ── 构建「可用数据库」提示（注入系统提示，让 AI 知道有哪些连接） ────
 // 效率项（Spec §6）：每连接只注一行 `名称[家族] + 一行语义`，细节压进系统提示
 
-// 各家族一行语义（KV/搜索/大数据行由后续任务的 dialect.label 接管，此处三库先行）
+// 各家族一行语义：让 AI 一眼知道该类型的 sql 参数填什么（覆盖全部十种类型）
 function familyHint(c: ConnConfig): string {
   switch (c.type) {
     case "postgresql":
     case "mysql":
     case "oracle":
+    case "dm":
       return "关系型，sql 参数填 SQL";
+    case "redis":
+      return "Redis 键值库，sql 参数填单条 Redis 命令（如 GET key / SCAN 0 MATCH user:* COUNT 100；KEYS 已禁用，扫描请用 SCAN）";
+    case "elasticsearch":
+      return "Elasticsearch 搜索库，sql 参数填 DSL JSON（如 {\"query\":{\"match_all\":{}}}；仅支持读端点 _search/_count/_mget）";
+    case "hive":
+    case "spark":
+      return "大数据 SQL 引擎，sql 参数填 SQL（如 SELECT * FROM 库.表 LIMIT 10）";
     case "mongodb":
       return "MongoDB 文档库，sql 参数填 JSON 命令信封（如 {\"find\":\"users\",\"filter\":{}}；读命令 find/count/distinct/aggregate）";
     case "neo4j":
@@ -655,7 +663,7 @@ export default function (pi: ExtensionAPI) {
         const val = await ctx.ui.select(`选择 ${field.label}`, field.options);
         if (!val) continue;
         if (field.valueMap) {
-          (newCfg as any)[field.key] = field.valueMap[val];
+          (newCfg as any)[field.key] = (field.valueMap as Record<string, unknown>)[val];
         } else {
           (newCfg as any)[field.key] = val === "是";
         }
@@ -699,7 +707,11 @@ export default function (pi: ExtensionAPI) {
     };
   });
 
-  // ── 注册 3 个工具（给 LLM 调用） ──────────────────
+  // ── 注册 6 个工具（给 LLM 调用） ──────────────────
+  // 注：pi 的 AgentToolResult.details 为必填字段（registerTool 的 TDetails 默认 unknown）。
+  // 本插件工具没有结构化详情，故在返回对象里统一显式写 details: undefined——与"完全不提供该字段"
+  // 在运行时等价：宿主读取走可选链（result.details?.x）、合并判定用 `!== undefined`，
+  // 且 JSON 序列化会跳过 undefined 值。
 
   // 解析工具 database 参数：缺省走默认连接（Spec §11.1）；无默认则报错指引
   function resolveTargetDb(name: string | undefined): { config?: ConnConfig; error?: string } {
@@ -735,7 +747,7 @@ export default function (pi: ExtensionAPI) {
 
       const target = resolveTargetDb(params.database);
       if (target.error || !target.config) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: target.error ?? "未找到数据库配置" }],
         };
       }
@@ -748,7 +760,7 @@ export default function (pi: ExtensionAPI) {
       // verdict = dialect.isAllowed(sql, readonly) → decide → deny/confirm/run
       const dialect = registry.get(config.type);
       if (!dialect) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `数据库类型 "${config.type}" 暂不支持。` }],
         };
       }
@@ -758,19 +770,19 @@ export default function (pi: ExtensionAPI) {
         const note = !cfg.ai_readonly && config.forceReadonly === true
           ? `（连接 ${config.name} 已设置强制只读）`
           : "";
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: (verdict.reason ?? "该操作不被允许。如需修改，请执行 /db config 更改配置。") + note }],
         };
       }
       // 写操作强制附执行理由（v1.1 UX 共识 Q1/Q3：与确认策略解耦；缺 reason 拒绝并引导 AI 补充）
       if (writeRequiresReason(verdict, params.reason)) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: "写操作必须附执行理由：请在 reason 参数中说明动机与影响范围（如\"将status=2的历史订单归档，预计影响1.2万行\"），补充后重试。" }],
         };
       }
       if (action === "confirm") {
         if (!ctx?.hasUI) {
-          return {
+          return { details: undefined,
             content: [{ type: "text" as const, text: "当前环境无法弹出确认对话框，已取消 SQL 执行。请在有界面的环境中操作。" }],
           };
         }
@@ -779,7 +791,7 @@ export default function (pi: ExtensionAPI) {
           `理由: ${params.reason}\n\n${verdict.summary ?? ""}\n\n数据库: ${config.name}\n\nSQL:\n${params.sql}`,
         );
         if (!ok) {
-          return {
+          return { details: undefined,
             content: [{ type: "text" as const, text: "用户取消了 SQL 执行。" }],
           };
         }
@@ -793,7 +805,7 @@ export default function (pi: ExtensionAPI) {
       );
 
       if (!result.success) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `查询失败: ${result.error}` }],
         };
       }
@@ -841,7 +853,7 @@ export default function (pi: ExtensionAPI) {
         text += `\n执行理由: ${params.reason}`;
       }
 
-      return { content: [{ type: "text" as const, text }] };
+      return { details: undefined, content: [{ type: "text" as const, text }] };
     },
   });
 
@@ -858,7 +870,7 @@ export default function (pi: ExtensionAPI) {
     async execute(_toolCallId: string, params: { database?: string; pattern?: string }, _signal: any) {
       const target = resolveTargetDb(params.database);
       if (target.error || !target.config) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: target.error ?? "未找到数据库配置" }],
         };
       }
@@ -866,14 +878,14 @@ export default function (pi: ExtensionAPI) {
 
       const dialect = registry.get(config.type);
       if (!dialect) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `数据库类型 "${config.type}" 暂不支持。` }],
         };
       }
       const result = await dialect.listTables(toRuntimeConfig(config, dialect.defaultPort), params.pattern);
 
       if (!result.success || !result.tables) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `获取表列表失败: ${result.error}` }],
         };
       }
@@ -885,7 +897,7 @@ export default function (pi: ExtensionAPI) {
         return `${schema}${t.name} (${t.type})${desc}`;
       });
 
-      return {
+      return { details: undefined,
         content: [{ type: "text" as const, text: `数据库 "${config.name}"${params.pattern ? `（pattern: ${params.pattern}）` : ""} 共 ${result.count} 张表:\n${lines.join("\n")}` }],
       };
     },
@@ -904,7 +916,7 @@ export default function (pi: ExtensionAPI) {
     async execute(_toolCallId: string, params: { database?: string; table: string }, _signal: any) {
       const target = resolveTargetDb(params.database);
       if (target.error || !target.config) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: target.error ?? "未找到数据库配置" }],
         };
       }
@@ -912,14 +924,14 @@ export default function (pi: ExtensionAPI) {
 
       const dialect = registry.get(config.type);
       if (!dialect) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `数据库类型 "${config.type}" 暂不支持。` }],
         };
       }
       const result = await dialect.describeTable(toRuntimeConfig(config, dialect.defaultPort), params.table);
 
       if (!result.success || !result.columns) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `获取表结构失败: ${result.error}` }],
         };
       }
@@ -935,7 +947,7 @@ export default function (pi: ExtensionAPI) {
         );
       }
 
-      return {
+      return { details: undefined,
         content: [{ type: "text" as const, text: lines.join("\n") }],
       };
     },
@@ -966,9 +978,9 @@ export default function (pi: ExtensionAPI) {
           "4. 调用 db_scan_save 提交候选数组。带 url 的候选必须能被对应方言解析，编造的 url 会被拒绝；",
           "5. 工具会弹确认框让用户逐个确认并补录密码，把工具返回的保存结果汇报给用户。",
         ].join("\n");
-        return { content: [{ type: "text" as const, text }] };
+        return { details: undefined, content: [{ type: "text" as const, text }] };
       } catch (err) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: `扫描失败: ${err instanceof Error ? err.message : String(err)}` }],
         };
       }
@@ -996,7 +1008,7 @@ export default function (pi: ExtensionAPI) {
     }),
     async execute(_toolCallId: string, params: { candidates: unknown[] }, _signal: any, _onUpdate?: any, ctx?: any) {
       if (!ctx?.ui) {
-        return { content: [{ type: "text" as const, text: "db_scan_save 需要交互式会话（ctx.ui 不可用）。请引导用户在终端执行 /db add 手动添加。" }] };
+        return { details: undefined, content: [{ type: "text" as const, text: "db_scan_save 需要交互式会话（ctx.ui 不可用）。请引导用户在终端执行 /db add 手动添加。" }] };
       }
       const { candidates, rejected } = validateCandidates(params.candidates, new Set(loadConfigs().map((c) => c.name)));
       const lines: string[] = [];
@@ -1006,7 +1018,7 @@ export default function (pi: ExtensionAPI) {
       if (candidates.length === 0) {
         lines.push(rejected.length > 0 ? "没有可保存的候选。" : "未收到有效候选（candidates 需为数组，每项含 dialectId+host）。",
           "提示：从配置文件原文提取后重试；确认方言取值在支持列表内。");
-        return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+        return { details: undefined, content: [{ type: "text" as const, text: lines.join("\n") }] };
       }
       lines.push(`收到 ${candidates.length} 个连接候选，逐个确认：`, ...candidates.map(candidateLine), "");
       const results: string[] = [];
@@ -1019,7 +1031,7 @@ export default function (pi: ExtensionAPI) {
         }
       }
       lines.push("", "保存结果：", ...results.map((r) => "  - " + r));
-      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+      return { details: undefined, content: [{ type: "text" as const, text: lines.join("\n") }] };
     },
   });
 
@@ -1033,7 +1045,7 @@ export default function (pi: ExtensionAPI) {
     async execute() {
       const configs = loadConfigs();
       if (configs.length === 0) {
-        return {
+        return { details: undefined,
           content: [{ type: "text" as const, text: "尚无数据库连接。请引导用户在终端执行 /db add 或 /db scan 建连。" }],
         };
       }
@@ -1046,7 +1058,7 @@ export default function (pi: ExtensionAPI) {
         const url = registry.get(c.type)?.displayUrl(c) ?? "";
         return `- ${c.name} [${shortTypeLabel(c.type)}]${marks ? " " + marks : ""} - ${fullTypeLabel(c.type)}${c.database ? " · 库: " + c.database : ""} · ${url} · ${test}${used ? " · " + used : ""}${c.description ? " · " + c.description : ""}`;
       });
-      return {
+      return { details: undefined,
         content: [{ type: "text" as const, text: `共 ${configs.length} 个连接：\n${lines.join("\n")}\n\n标注 [prod·强制只读] 的连接永远只读（即使全局允许写操作）。` }],
       };
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsyan/db",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "AI 数据库接入扩展 for pi —— 达梦(DM)/PostgreSQL/MySQL/Oracle/Redis/Elasticsearch/MongoDB/Neo4j/Hive/Spark 十种数据库，六大家族方言，提供查询/表结构/扫描建连/连接清单 LLM 工具 | Database access extension for the pi coding agent: query, schema browsing, connection scanning and audit tools for PostgreSQL, MySQL, Oracle, DM (Dameng 达梦), Redis, Elasticsearch, MongoDB, Neo4j, Hive and Spark",
   "keywords": [
     "pi-extension",
@@ -60,14 +60,17 @@
     "mysql2": "^3.23.1",
     "neo4j-driver": "^5.28.3",
     "oracledb": "^7.0.1",
-    "neo4j-driver": "^5.28.3",
     "pg": "^8.22.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@types/node": "^22.20.2",
     "@types/pg": "^8.20.0",
-    "tsx": "^4.23.13"
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
   },
   "scripts": {
-    "test": "tsx --test \"test/**/*.test.ts\""
+    "test": "tsx --test \"test/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
   }
 }

package/src/config.ts

@@ -274,11 +274,26 @@ export function toRuntimeConfig(c: ConnConfig, defaultPort: number): ConnConfig
   };
 }
 
-// 供 UI 层展示类型短标签（原 index.ts 内 5 处重复映射的收敛点之一）
+// 供 UI 层展示类型标签（原 index.ts 内 5 处重复映射的收敛点之一）
+// 单一数据源：短标签与全称同表维护。键类型用 Record<DbTypeId, ...> 而非 Record<string, ...>，
+// 新增方言而漏补标签时会在类型检查阶段报错，不再静默 fallback 成原始 id。
+const TYPE_LABELS: Record<DbTypeId, { short: string; full: string }> = {
+  postgresql: { short: "PG", full: "PostgreSQL" },
+  mysql: { short: "MySQL", full: "MySQL" },
+  oracle: { short: "Oracle", full: "Oracle" },
+  dm: { short: "DM", full: "达梦" },
+  redis: { short: "Redis", full: "Redis" },
+  elasticsearch: { short: "ES", full: "Elasticsearch" },
+  mongodb: { short: "MongoDB", full: "MongoDB" },
+  neo4j: { short: "Neo4j", full: "Neo4j" },
+  hive: { short: "Hive", full: "Hive" },
+  spark: { short: "Spark", full: "Spark" },
+};
+
 export function shortTypeLabel(type: DbTypeId): string {
-  return ({ postgresql: "PG", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB", neo4j: "Neo4j" } as Record<string, string>)[type] ?? type;
+  return TYPE_LABELS[type]?.short ?? type;
 }
 
 export function fullTypeLabel(type: DbTypeId): string {
-  return ({ postgresql: "PostgreSQL", mysql: "MySQL", oracle: "Oracle", mongodb: "MongoDB", neo4j: "Neo4j" } as Record<string, string>)[type] ?? type;
+  return TYPE_LABELS[type]?.full ?? type;
 }

package/src/core/scan/validate.ts

@@ -6,7 +6,7 @@
 
 import { basename } from "node:path";
 import { registry } from "../../dialects/index.js";
-import type { Candidate, CandidateInput, CandidateStatus, DbTypeId } from "../types.js";
+import type { Candidate, CandidateInput, CandidateStatus, ConnConfig, DbTypeId } from "../types.js";
 
 /** 各类型建连必需字段（空串同样视为缺失）——家族语义，非正则，保留 */
 const REQUIRED: Record<DbTypeId, string[]> = {
@@ -54,7 +54,9 @@ export function validateCandidates(raw: unknown, existingNames: Set<string>): Va
 
     // ② 带 url 时：方言 parseUrl 必须能解析（防幻觉——claim 与 url 矛盾整条拒）
     //    解析成功时以解析结果为准（host/port/database/username/password 由 URL 补全）
-    let bag: Partial<CandidateInput> = {
+    // 归一化后 port/dbIndex 恒为 number（下行 parseInt 收敛）。此处用 Partial<ConnConfig> 而非
+    // Partial<CandidateInput>——后者的 port 是 number|string，会让下方端口范围校验退化为字符串比较。
+    let bag: Partial<ConnConfig> = {
       host: typeof c.host === "string" ? c.host.trim() : undefined,
       port: typeof c.port === "number" ? c.port : parseInt(String(c.port ?? ""), 10) || undefined,
       username: nonEmpty(c.username) ? String(c.username) : undefined,
@@ -90,7 +92,7 @@ export function validateCandidates(raw: unknown, existingNames: Set<string>): Va
     }
 
     // ④ 缺字段判定
-    const missing = (REQUIRED[dialect.id] ?? []).filter((f) => !nonEmpty(bag[f as keyof CandidateInput]));
+    const missing = (REQUIRED[dialect.id] ?? []).filter((f) => !nonEmpty(bag[f as keyof ConnConfig]));
 
     // ⑤ 命名：显式 name > 默认；同名（含与本批前序候选撞名）→ exists 状态
     let name = nonEmpty(c.name) ? String(c.name).trim()

package/src/dialects/dm.ts

@@ -80,10 +80,12 @@ class DmDialect extends RelationalDialect {
   protected async doExecute(client: unknown, stmt: string, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }> {
     const dmConn = client as dmdb.Connection;
     const maxRows = opts.maxRows;
+    // 上游 dmdb 的 ExecuteOptions 未声明 maxRows/fetchArraySize（运行时可接受或被忽略）；
+    // 结果另有下方 .slice(0, maxRows) 兜底，故此处仅放宽类型断言，不改运行时行为。
     const res = await dmConn.execute(stmt, [], {
       maxRows,
       fetchArraySize: maxRows,
-    });
+    } as dmdb.ExecuteOptions);
     if (res.metaData && res.metaData.length > 0) {
       const columns = res.metaData.map((m: any) => m.name);
       const rows = (res.rows ?? []).slice(0, maxRows).map((r: any) => [...r]);
@@ -95,7 +97,8 @@ class DmDialect extends RelationalDialect {
   async versionQuery(conn: DbConnection): Promise<string> {
     const dmConn = conn.client as dmdb.Connection;
     const res = await dmConn.execute("SELECT * FROM V$VERSION");
-    return (res.rows ?? [])[0]?.[0] as string ?? "unknown";
+    const rows = (res.rows as unknown[][] | undefined) ?? [];
+    return (rows[0]?.[0] as string | undefined) ?? "unknown";
   }
 
   async listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult> {

package/src/dialects/elasticsearch.ts

@@ -163,7 +163,9 @@ class ElasticsearchDialect extends SearchDialect {
         return { columns: ["count"], rows: [[count]], rowCount: count };
       }
       if (kind.endpoint === "_mget") {
-        const res = await es.mget({ index, body: { docs: [] } });
+        // 注：_mget 需兼容 v7 客户端的 body 形态（本文件为 v7/v8/v9 三客户端分发），
+        // 而 v8/v9 的类型已把请求体改为顶层 docs，故按运行时通用形态传参并放宽参数类型。
+        const res = await es.mget({ index, body: { docs: [] } } as unknown as Parameters<ClientV8["mget"]>[0]);
         return docsToRows(unwrap(res));
       }
       // _search：DSL 整体即 body

package/src/dialects/hive.ts

@@ -61,7 +61,9 @@ class HiveDialect extends BigDataDialect {
   }
 
   protected async doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection> {
-    const client = new hive.HiveClient(TCLIService, TCLIService_types);
+    // 上游 hive-driver 的 TCLIServiceTypes 声明不完整（缺 25 个请求类型），与其运行时实际
+    // 使用的 thrift 定义不一致；仅放宽类型断言，运行时对象未做任何改动。
+    const client = new hive.HiveClient(TCLIService, TCLIService_types as any);
     await client.connect(
       { host: config.host ?? "localhost", port: config.port ?? DEFAULT_PORT },
       new hive.connections.TcpConnection(),

package/src/dialects/mysql.ts

@@ -109,9 +109,11 @@ class MysqlDialect extends RelationalDialect {
     try {
       const tables = await this.withConnection(config, async (conn) => {
         const mysqlConn = conn.client as mysql.Connection;
+        // config.database 为可选（ConnConfig），而 mysql2 的 ExecuteValues 不接受 undefined 元素；
+        // 此处仅放宽类型断言，运行时参数与既有行为完全一致。
         const [rows] = await mysqlConn.execute(
           "SELECT TABLE_NAME, TABLE_TYPE, TABLE_COMMENT FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? ORDER BY TABLE_NAME",
-          [config.database],
+          [config.database] as any[],
         );
         const all = (rows as any[]).map((r: any) => ({
           schema: "",
@@ -149,7 +151,7 @@ class MysqlDialect extends RelationalDialect {
         try {
           const [commentRows] = await mysqlConn.execute(
             "SELECT COLUMN_NAME, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?",
-            [config.database, table],
+            [config.database, table] as any[],
           );
           const commentMap = new Map((commentRows as any[]).map((r: any) => [r.COLUMN_NAME, r.COLUMN_COMMENT]));
           for (const col of cols) {

package/src/dialects/neo4j.ts

@@ -270,7 +270,7 @@ class Neo4jDialect extends GraphDialect {
             const f = r._fields ?? [];
             const types = f[3] as string[] | null;
             if (!Array.isArray(types) || !types.includes(graphName)) continue;
-            indexLines.push(`${f[0]}(${f[1]}, ${f[5] ?? "online"}) ON ${isRel ? "rel" : "node"}(${types.join(":")}).(${(f[4] ?? []).join(",")})`);
+            indexLines.push(`${f[0]}(${f[1]}, ${f[5] ?? "online"}) ON ${isRel ? "rel" : "node"}(${types.join(":")}).(${((f[4] ?? []) as string[]).join(",")})`);
           }
         } catch { /* SHOW 失败降级 */ }
         try {
@@ -281,7 +281,7 @@ class Neo4jDialect extends GraphDialect {
             const types = f[3] as string[] | null;
             if (!Array.isArray(types) || !types.includes(graphName)) continue;
             for (const p of (f[4] ?? []) as string[]) if (String(f[1]).toUpperCase().includes("UNIQUE")) uniqueProps.add(p);
-            indexLines.push(`${f[0]}(${f[1]}) ON ${types.join(":")}.(${(f[4] ?? []).join(",")})`);
+            indexLines.push(`${f[0]}(${f[1]}) ON ${types.join(":")}.(${((f[4] ?? []) as string[]).join(",")})`);
           }
         } catch { /* 降级 */ }
 

package/src/dialects/oracle.ts

@@ -1,7 +1,7 @@
 // src/dialects/oracle.ts
 import oracledb from "oracledb";
 import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
-  ListTablesResult, DescribeTableResult, ColumnInfo, TestConnectionResult } from "../core/types.js";
+  ListTablesResult, DescribeTableResult, TableInfo, ColumnInfo, TestConnectionResult } from "../core/types.js";
 import { RelationalDialect } from "./relational-dialect.js";
 import { register, filterTables, type Fingerprints } from "./dialect.js";
 
@@ -107,7 +107,9 @@ class OracleDialect extends RelationalDialect {
            WHERE T.OWNER NOT IN ('SYS', 'SYSTEM', 'DBSNMP', 'XDB')
            ORDER BY T.OWNER, T.TABLE_NAME`,
         );
-        const all = (res.rows ?? []).map((r: any) => ({
+        // 显式标注 TableInfo[]：oracledb 无类型声明，res.rows 退化为 any，若不标注则
+        // filterTables 的泛型会回退到约束 { name; schema? }，丢失 type/description 两个字段。
+        const all: TableInfo[] = (res.rows ?? []).map((r: any) => ({
           schema: r[1],
           name: r[0],
           type: "TABLE",

package/src/dialects/redis.ts

@@ -93,9 +93,13 @@ class RedisDialect extends KvDialect {
         let sampled = 0;
         let cursor = "0";
         // LIKE（%/_）→ SCAN 通配（*/?），全局替换（String.replace 单次替换是 bug）
-        const matchArgs = pattern ? ["MATCH", pattern.split("").map((ch) => ch === "%" ? "*" : ch === "_" ? "?" : ch).join("")] : [];
+        const scanPattern = pattern ? pattern.split("").map((ch) => ch === "%" ? "*" : ch === "_" ? "?" : ch).join("") : null;
         do {
-          const [next, keys] = await redis.scan(cursor, "COUNT", 100, ...matchArgs);
+          // ioredis 的 scan 重载要求 MATCH/COUNT 固定次序，不能靠 spread 拼参；
+          // Redis 的 SCAN 命令本身不区分参数顺序，故两个分支与原来的命令语义完全一致。
+          const [next, keys] = scanPattern
+            ? await redis.scan(cursor, "MATCH", scanPattern, "COUNT", 100)
+            : await redis.scan(cursor, "COUNT", 100);
           cursor = next;
           for (const key of keys) {
             if (sampled >= 200) break;
@@ -166,7 +170,8 @@ class RedisDialect extends KvDialect {
           } else if (type === "set") {
             preview = JSON.stringify(await redis.smembers(key)).slice(0, 200);
           } else if (type === "zset") {
-            preview = JSON.stringify(await redis.zrange(key, 0, 9, "WITHSCORES")).slice(0, 200);
+            // ioredis 6 的 zrange 重载把 stop 声明为 string|Buffer（漏了 number）；索引 "9" 与数字 9 等价。
+            preview = JSON.stringify(await redis.zrange(key, 0, "9", "WITHSCORES")).slice(0, 200);
           }
         } catch { /* ignore */ }
         return [

package/src/dialects/spark.ts

@@ -58,7 +58,8 @@ class SparkDialect extends BigDataDialect {
   }
 
   protected async doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection> {
-    const client = new hive.HiveClient(TCLIService, TCLIService_types);
+    // 同 hive.ts：上游 hive-driver 的 TCLIServiceTypes 声明不完整，仅放宽类型断言，不动运行时。
+    const client = new hive.HiveClient(TCLIService, TCLIService_types as any);
     await client.connect(
       { host: config.host ?? "localhost", port: config.port ?? DEFAULT_PORT },
       new hive.connections.TcpConnection(),