@nsyan/db 1.3.3 → 1.3.5

package/README.md

@@ -68,7 +68,7 @@ pi install ./packages/db     # 本仓库开发者
 | 机制 | 行为 |
 |------|------|
 | AI 只读模式 | **默认开**；关闭后允许写 |
-| 写确认 | 写操作弹框展示：理由 + 命令摘要 + SQL |
+| 写确认 | 写操作弹框展示：理由 + 命令摘要 + SQL（自动格式化 + 按方言语法高亮） |
 | 写执行理由 | AI 必须附 `reason`（动机+影响范围），缺失直接拒绝 |
 | 连接级强制只读 | 标记的连接（如生产库）无视全局开关，永远只读 |
 | 家族白名单 | Redis/ES/Mongo 只读白名单；`DROP`、管理 DDL、服务端 JS、`CALL dbms.*` 恒拒 |

package/docs/USAGE.md

@@ -161,6 +161,7 @@ SHOW INDEXES
 
 - AI 发起写操作必须附 `reason` 参数（动机 + 影响范围，如 *"将 status=2 的历史订单归档，预计影响 1.2 万行"*）
 - 确认框**首行展示理由**，执行结果末尾回显；缺失时拒绝并引导补充（与确认策略无关）
+- 弹窗里的 SQL 自动**格式化**（子句换行、逗号拆列、`AND`/`OR` 缩进、`CREATE TABLE` 长列定义块状展开）并按方言**语法高亮**（关系型/大数据/图 → SQL，MongoDB/Elasticsearch → JSON，Redis → 纯色代码块）；理由/摘要/库名用 **Markdown 排版**（引用块 + 加粗标签 + 行内代码 + emoji 图标）。TUI 走自定义弹窗（Enter 执行 / Esc 取消）；**pi web 走同一份 Markdown**（react-markdown + Prism 渲染，同样高亮，代码块带行号与复制按钮，正文可滚动）。弹窗尺寸由 pi-web 写死（560×760），内容过长靠正文滚动。美化只作用于展示，**实际执行的永远是原始语句**
 - 开启审计（`/db config → 审计日志`）后，写成功追加 `~/.pi/agent/db-audit/<YYYY-MM-DD>.jsonl`：
   - 一天一个文件；字段含时间/项目路径/连接/摘要/理由/**完整 SQL 不截断**
   - 文件 `0600`；审计失败静默降级，不阻断主流程

package/index.ts

@@ -16,6 +16,7 @@ import {
   recordLastUsed, recordTestResult, connSummaryLine, envTagLabel, formatRelativeTime,
 } from "./src/config.js";
 import type { PluginConfig } from "./src/config.js";
+import { confirmSqlExecution } from "./src/ui/sql-confirm.js";
 
 // ── URL 解析：遍历 registry 各方言 parseUrl，首个非 null 胜出 ────
 // 关系型 JDBC + 原生 URI 双形态由各方言 parseUrl 兼收（Spec §7）
@@ -530,10 +531,11 @@ export default function (pi: ExtensionAPI) {
         continue;
       }
       if (action === "confirm") {
-        const ok = await ctx.ui.confirm(
-          "SQL 执行确认",
-          `${verdict.summary ?? ""}\n\nSQL:\n${sql}`
-        );
+        const ok = await confirmSqlExecution(ctx, {
+          summary: verdict.summary,
+          sql,
+          type: config.type,
+        });
         if (!ok) continue;
       }
       ctx.ui.notify("正在执行查询...", "info");
@@ -800,10 +802,13 @@ export default function (pi: ExtensionAPI) {
             content: [{ type: "text" as const, text: "当前环境无法弹出确认对话框，已取消 SQL 执行。请在有界面的环境中操作。" }],
           };
         }
-        const ok = await ctx.ui.confirm(
-          "SQL 执行确认",
-          `理由: ${params.reason}\n\n${verdict.summary ?? ""}\n\n数据库: ${config.name}\n\nSQL:\n${params.sql}`,
-        );
+        const ok = await confirmSqlExecution(ctx, {
+          reason: params.reason,
+          summary: verdict.summary,
+          database: config.name,
+          sql: params.sql,
+          type: config.type,
+        });
         if (!ok) {
           return { details: undefined,
             content: [{ type: "text" as const, text: "用户取消了 SQL 执行。" }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsyan/db",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "AI 数据库接入扩展 for pi coding agent：PostgreSQL/MySQL/Oracle/达梦DM/Redis/Elasticsearch/MongoDB/Neo4j/Hive/Spark 十种数据库，查询/表结构/扫描建连/安全管控 | Database tools for the pi agent: query, schema, scan-and-connect for 10 databases",
   "keywords": [
     "pi-extension",
@@ -45,6 +45,7 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "files": [
@@ -69,10 +70,12 @@
     "mysql2": "^3.23.1",
     "neo4j-driver": "^5.28.3",
     "oracledb": "^7.0.1",
-    "pg": "^8.22.0"
+    "pg": "^8.22.0",
+    "ws": "^8.22.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
     "@types/node": "^22.20.2",
     "@types/pg": "^8.20.0",
     "tsx": "^4.23.13",

package/src/core/index.ts

@@ -3,5 +3,7 @@ export type { DbTypeId, DbFamily, ConnConfig, ParsedTarget, DbConnection, ExecOp
   CandidateStatus, Candidate, CandidateInput, TableInfo, ColumnInfo, QueryResult, ListTablesResult,
   DescribeTableResult, TestConnectionResult } from "./types.js";
 export { stripComments, splitStatements, isWriteStatement, isDropStatement } from "./sql-text.js";
+export { formatSql, formatSqlForDisplay, displayLangFor } from "./sql-format.js";
+export type { DisplayLang } from "./sql-format.js";
 export { decide } from "./policy.js";
 export type { ConfirmMode } from "./policy.js";

package/src/core/sql-format.ts

@@ -0,0 +1,294 @@
+// core/sql-format.ts —— 确认框「展示用」SQL 美化 + 高亮语言映射。
+//
+// 设计红线：本模块只决定「弹窗里看到什么」，绝不参与执行。
+// 实际执行永远走原始 params.sql（见 index.ts query_database），
+// 因此这里即使美化得再激进也不会改变语义；反过来也要求尽量保留
+// 字符串字面量、注释与标识符原貌，避免「看到的 SQL ≠ 执行的 SQL」。
+import type { DbTypeId } from "./types.js";
+
+/** 弹窗代码块高亮语言；undefined = 无对应语法，走 pi 的代码块配色 */
+export type DisplayLang = "sql" | "json" | undefined;
+
+/** 方言 → 高亮语言：关系型/大数据/图用 sql，文档/搜索用 json，Redis 命令无同类语法 */
+export function displayLangFor(type: DbTypeId): DisplayLang {
+  switch (type) {
+    case "postgresql":
+    case "mysql":
+    case "oracle":
+    case "dm":
+    case "hive":
+    case "spark":
+    case "neo4j":
+      return "sql";
+    case "elasticsearch":
+    case "mongodb":
+      return "json";
+    case "redis":
+      return undefined;
+  }
+}
+
+interface Tok {
+  k: "w" | "s" | "n" | "p" | "c"; // word / string / number / punctuation / comment
+  t: string;
+  sp: boolean; // 原串中该 token 前是否有空白（用于保留 `COUNT(*)` 与 `IN (` 的差异）
+}
+
+const MULTI_OP = ["->>", "->", "::", "<=", ">=", "<>", "!=", "||", ":=", "|>"];
+const JOIN_PREFIX = new Set(["LEFT", "RIGHT", "INNER", "OUTER", "FULL", "CROSS", "NATURAL"]);
+
+// 触发换行的「子句关键字」（含多词形式，合并后匹配）
+const CLAUSE = new Set([
+  "SELECT", "FROM", "WHERE", "GROUP BY", "HAVING", "ORDER BY", "LIMIT", "OFFSET",
+  "FETCH", "RETURNING", "WINDOW", "QUALIFY",
+  "INSERT INTO", "VALUES", "SET", "UPDATE", "DELETE FROM", "WITH",
+  "UNION", "UNION ALL", "EXCEPT", "INTERSECT",
+  "JOIN", "LEFT JOIN", "RIGHT JOIN", "INNER JOIN", "OUTER JOIN", "FULL JOIN",
+  "CROSS JOIN", "NATURAL JOIN", "MERGE", "MATCH", "UNWIND", "RETURN", "REMOVE",
+  "CREATE", "ALTER", "DROP", "TRUNCATE", "CALL", "EXPLAIN",
+]);
+// 这些子句里的逗号按列/赋值拆行（更接近主流 SQL 格式化器）
+const COMMA_CLAUSES = new Set(["SELECT", "SET", "VALUES", "RETURNING", "GROUP BY", "ORDER BY"]);
+const COND = new Set(["AND", "OR", "ON", "WHEN"]);
+// 不换行但统一大写的常见保留字/属性词（保持与子句关键字一致的观感）
+const KEYWORD = new Set([
+  "AS", "ASC", "DESC", "DISTINCT", "ALL", "IN", "NOT", "NULL", "IS", "LIKE", "ILIKE",
+  "BETWEEN", "EXISTS", "CASE", "THEN", "ELSE", "END", "TRUE", "FALSE", "DEFAULT", "USING",
+  "RECURSIVE", "OVER", "PARTITION", "UNBOUNDED", "PRECEDING", "FOLLOWING", "CURRENT", "ROW",
+  "ROWS", "RANGE", "CAST", "INTERVAL", "PRIMARY", "FOREIGN", "KEY", "REFERENCES", "UNIQUE",
+  "INDEX", "CONSTRAINT", "CHECK", "CASCADE", "RESTRICT", "IF", "REPLACE", "IGNORE",
+  "DUPLICATE", "INTO", "TOP", "NULLS", "FIRST", "LAST", "OPTION", "LOCK", "FOR",
+]);
+
+const INDENT = "  ";
+// 括号组内容超过这个「显示宽度」就当成块状列表拆行：
+// 覆盖 CREATE TABLE(...) 长列定义、IN(...) 长列表等子句关键字覆盖不到的列表。
+// 约等于 pi web 弹窗代码区（~560px / 等宽 ~7.5px）的可见列数。
+const BLOCK_WIDTH = 64;
+const WIDE = /[\u1100-\u115f\u2329\u232a\u2e80-\u4dcf\u4e00-\u9fff\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe6f\uff00-\uff60\uffe0-\uffe6\u20000-\u3fffd]/u;
+
+/** 终端显示宽度：CJK/全角按 2 列（与 pi-tui/可见宽度一致，避免中文注释撑爆行宽判断） */
+function displayWidth(s: string): number {
+  let w = 0;
+  for (const ch of s) w += WIDE.test(ch) ? 2 : 1;
+  return w;
+}
+
+function tokenize(sql: string): Tok[] {
+  const toks: Tok[] = [];
+  const n = sql.length;
+  let i = 0;
+  let sp = false;
+  const rest = (from: number) => sql.slice(from);
+
+  while (i < n) {
+    const ch = sql[i];
+    if (ch === " " || ch === "\t" || ch === "\r" || ch === "\n") { sp = true; i++; continue; }
+
+    // 行注释 -- ...
+    if (ch === "-" && sql[i + 1] === "-") {
+      let j = i;
+      while (j < n && sql[j] !== "\n") j++;
+      toks.push({ k: "c", t: sql.slice(i, j).trimEnd(), sp });
+      i = j; sp = true; continue;
+    }
+    // 块注释 /* ... */
+    if (ch === "/" && sql[i + 1] === "*") {
+      let j = i + 2;
+      while (j < n && !(sql[j] === "*" && sql[j + 1] === "/")) j++;
+      j = Math.min(n, j + 2);
+      toks.push({ k: "c", t: sql.slice(i, j), sp });
+      i = j; sp = true; continue;
+    }
+    // 字符串 / 引号标识符（'' 与反斜杠转义都按原样保留）
+    if (ch === "'" || ch === '"' || ch === "`") {
+      let j = i + 1;
+      while (j < n) {
+        if (sql[j] === "\\") { j += 2; continue; }
+        if (sql[j] === ch) {
+          if (sql[j + 1] === ch) { j += 2; continue; }
+          j++; break;
+        }
+        j++;
+      }
+      toks.push({ k: "s", t: sql.slice(i, j), sp });
+      i = j; sp = false; continue;
+    }
+    // 数字
+    const num = /^(?:0[xX][0-9a-fA-F]+|[0-9]+(?:\.[0-9]*)?(?:[eE][+-]?[0-9]+)?|\.[0-9]+(?:[eE][+-]?[0-9]+)?)/.exec(rest(i));
+    if (num) { toks.push({ k: "n", t: num[0], sp }); i += num[0].length; sp = false; continue; }
+    // 单词 / 标识符（保留原始大小写，仅子句关键字后续统一大写）
+    const word = /^[A-Za-z_@#$][A-Za-z0-9_@#$]*/.exec(rest(i));
+    if (word) { toks.push({ k: "w", t: word[0], sp }); i += word[0].length; sp = false; continue; }
+    // 多字符运算符
+    const op = MULTI_OP.find((o) => rest(i).startsWith(o));
+    if (op) { toks.push({ k: "p", t: op, sp }); i += op.length; sp = false; continue; }
+    // 单字符标点
+    toks.push({ k: "p", t: ch, sp });
+    i++; sp = false;
+  }
+  return toks;
+}
+
+/** 宽松的 SQL 美化：按子句换行、逗号拆列、AND/OR 缩进、长括号组拆块；不改变 token 内容 */
+export function formatSql(sql: string): string {
+  const toks = tokenize(sql);
+  if (toks.length === 0) return sql.trim();
+
+  // 预计算括号配对，用于判断某个 (...) 是否足够长、该拆成块状列表
+  const matchIdx = new Map<number, number>();
+  {
+    const stack: number[] = [];
+    for (let idx = 0; idx < toks.length; idx++) {
+      const t = toks[idx];
+      if (t.k !== "p") continue;
+      if (t.t === "(") stack.push(idx);
+      else if (t.t === ")") {
+        const open = stack.pop();
+        if (open !== undefined) matchIdx.set(open, idx);
+      }
+    }
+  }
+  const innerWidth = (open: number): number => {
+    const close = matchIdx.get(open);
+    if (close === undefined) return 0;
+    let w = 0;
+    for (let k = open + 1; k < close; k++) w += displayWidth(toks[k].t) + 1;
+    return w;
+  };
+
+  let out = "";
+  let pending = false; // 下一个 token 前补一个空格
+  let depth = 0;       // 括号深度
+  let breakCommas = false;
+  let prevWord = ""; // 上一个单词（大写），用于识别 `FOR UPDATE` / `ON DUPLICATE KEY UPDATE` 等非语句头场景
+  // 每层括号：block = 长列表按块拆行；clause = 内含子句（子查询），收尾 ) 单独成行
+  const parenStack: { block: boolean; clause: boolean }[] = [];
+
+  const atLineStart = () => out === "" || out.endsWith("\n");
+  const newline = (indent: number) => {
+    out = out.replace(/[ \t]+$/, "");
+    if (!out.endsWith("\n")) out += "\n";
+    out += INDENT.repeat(Math.max(0, indent));
+    pending = false;
+  };
+  const write = (s: string, noSpace = false) => {
+    if (!atLineStart() && pending && !noSpace) out += " ";
+    out += s;
+    pending = false;
+  };
+
+  for (let i = 0; i < toks.length; i++) {
+    const tok = toks[i];
+
+    if (tok.k === "c") {
+      write(tok.t);
+      if (tok.t.startsWith("--")) newline(depth); else pending = true;
+      prevWord = "";
+      continue;
+    }
+
+    if (tok.k === "s" || tok.k === "n") { write(tok.t); pending = true; prevWord = ""; continue; }
+
+    if (tok.k === "p") {
+      prevWord = "";
+      const t = tok.t;
+      if (t === ",") {
+        write(",", true);
+        const inBlock = parenStack.length > 0 && parenStack[parenStack.length - 1].block;
+        if (breakCommas && depth === 0) newline(1);
+        else if (inBlock) newline(depth);
+        else pending = true;
+      } else if (t === "(") {
+        const block = innerWidth(i) > BLOCK_WIDTH;
+        parenStack.push({ block, clause: false });
+        write("(", !tok.sp);
+        depth++;
+        if (block) newline(depth); // 长列表：首项另起一行
+      } else if (t === ")") {
+        const top = parenStack.pop();
+        if (top?.clause === true || top?.block === true) newline(depth - 1); // 子查询/块列表收尾对齐
+        write(")", true);
+        depth = Math.max(0, depth - 1);
+        pending = true;
+      } else if (t === ".") {
+        write(".", true);
+      } else if (t === ";") {
+        write(";", true);
+        out = out.replace(/[ \t]+$/, "") + "\n\n";
+        pending = false;
+        breakCommas = false;
+      } else if (t === "*" && (out.endsWith("(") || out.endsWith(",") || atLineStart())) {
+        write("*", true); // COUNT(*) / SELECT * 的星号
+        pending = true;
+      } else {
+        write(t); // 二元运算符两侧留空格
+        pending = true;
+      }
+      continue;
+    }
+
+    // word：先尝试合并多词子句
+    const upper = tok.t.toUpperCase();
+    const nextW = toks[i + 1]?.k === "w" ? toks[i + 1].t.toUpperCase() : "";
+    let kw = upper;
+    if ((upper === "GROUP" || upper === "ORDER" || upper === "PARTITION") && nextW === "BY") { kw = upper + " BY"; i++; }
+    else if (upper === "UNION" && nextW === "ALL") { kw = "UNION ALL"; i++; }
+    else if (upper === "INSERT" && nextW === "INTO") { kw = "INSERT INTO"; i++; }
+    else if (upper === "DELETE" && nextW === "FROM") { kw = "DELETE FROM"; i++; }
+    else if (JOIN_PREFIX.has(upper) && nextW === "JOIN") { kw = upper + " JOIN"; i++; }
+
+    // 这些 UPDATE/VALUES 不是语句头/子句头，不能换行——否则确认框会
+    // 把一条 INSERT 的尾部渲染成看似两条语句，误导安全判断。
+    const nextTok = toks[i + 1];
+    const nextIsFnParen = nextTok?.k === "p" && nextTok.t === "(" && nextTok.sp === false;
+    const inlineUpdate = kw === "UPDATE" && (prevWord === "FOR" || prevWord === "DO" || prevWord === "KEY" || prevWord === "DUPLICATE");
+    const inlineValuesFn = kw === "VALUES" && nextIsFnParen; // MySQL VALUES(col) 函数
+
+    if (CLAUSE.has(kw) && !inlineUpdate && !inlineValuesFn) {
+      if (parenStack.length > 0) parenStack[parenStack.length - 1].clause = true;
+      newline(depth);
+      breakCommas = COMMA_CLAUSES.has(kw);
+      write(kw);
+      pending = true;
+    } else if (COND.has(kw)) {
+      newline(depth + 1);
+      write(kw);
+      pending = true;
+    } else if (KEYWORD.has(upper) || inlineUpdate || inlineValuesFn) {
+      write(upper);
+      pending = true;
+    } else {
+      write(tok.t); // 非关键字保留原始大小写
+      pending = true;
+    }
+    prevWord = kw.slice(kw.lastIndexOf(" ") + 1);
+  }
+
+  return out
+    .replace(/[ \t]+$/gm, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/**
+ * 展示用 SQL：关系型/大数据/图走 SQL 美化；MongoDB / Elasticsearch 的 JSON 信封走 2 空格缩进。
+ * 解析/美化失败时原样返回（弹窗宁可不好看，也不能显示错）。
+ */
+export function formatSqlForDisplay(sql: string, type: DbTypeId): string {
+  const raw = sql.trim();
+  if (!raw) return raw;
+  if (type === "mongodb" || type === "elasticsearch") {
+    try {
+      return JSON.stringify(JSON.parse(raw), null, 2);
+    } catch {
+      return raw;
+    }
+  }
+  try {
+    const formatted = formatSql(raw).trim();
+    return formatted || raw;
+  } catch {
+    return raw;
+  }
+}

package/src/ui/sql-confirm.ts

@@ -0,0 +1,124 @@
+// src/ui/sql-confirm.ts —— SQL 执行确认弹窗（展示层）。
+//
+// 目标：把「弹窗里那段密不透风的 SQL」变成可读的格式化 + 语法高亮 + 有层次的排版。
+//
+// 能力边界（已核对 pi / pi-web 源码）：
+// - ctx.ui.confirm 底层是 SelectList，标题/正文按纯文本渲染，无法高亮；
+// - ctx.ui.custom 可挂任意 TUI 组件，且 pi-tui 的 Markdown 代码块会调用
+//   theme.highlightCode（cli-highlight），这就是 TUI 的 SQL 语法高亮入口；
+// - RPC（pi-web）下 custom() 返回 undefined，但 pi-web 0.9.x 的确认弹窗正文
+//   用 react-markdown 渲染，代码围栏走 Prism（已注册 sql/json），因此**发 Markdown
+//   就能在 pi web 里高亮**（还会自带语言标签/行号/复制按钮 + 正文原生滚动）。
+//   注意：Markdown 会把单个换行折叠成空格，所以标签之间必须用空行/列表分隔。
+// - RPC 的 confirm 请求只有 title/message/timeout，弹窗尺寸由 pi-web 写死
+//   （560×760），插件层改不了。
+import type { DbTypeId } from "../core/types.js";
+import { displayLangFor, formatSqlForDisplay } from "../core/sql-format.js";
+
+export interface SqlConfirmInfo {
+  /** 写操作执行理由（菜单「执行查询」路径没有 reason） */
+  reason?: string;
+  /** 策略层摘要，如「CREATE IF（共 1 条语句）」 */
+  summary?: string;
+  database?: string;
+  sql: string;
+  type: DbTypeId;
+}
+
+/** 压缩换行/多余空白：Markdown 单换行会折叠，多行理由先并成一行避免结构被破坏 */
+function oneLine(s: string): string {
+  return s.replace(/\s*\n+\s*/g, " ").replace(/\s{2,}/g, " ").trim();
+}
+
+/** 转义会破坏行内代码/引用的反引号（其余 Markdown 符号在中文语境下误伤概率低，不激进转义） */
+function escInline(s: string): string {
+  return s.replace(/`/g, "\\`");
+}
+
+/** 围栏长度 = SQL 里最长反引号串 + 1（至少 3），避免语句内含 ``` 时把围栏撑破 */
+function fenceFor(sql: string): string {
+  const runs = sql.match(/`+/g) ?? [];
+  const longest = runs.reduce((max, r) => Math.max(max, r.length), 0);
+  return "`".repeat(Math.max(3, longest + 1));
+}
+
+/**
+ * 构造确认弹窗的 Markdown 正文（TUI 与 pi web 共用同一份文案）。
+ * 结构：引用块(执行理由) + 列表(影响摘要/数据库) + 代码块(SQL，带方言语言标记)。
+ * 颜色由主题对 引用/加粗/行内代码/代码块 的默认着色决定（Markdown 无法任意指定颜色）。
+ */
+export function buildSqlConfirmMarkdown(info: SqlConfirmInfo): string {
+  const sql = formatSqlForDisplay(info.sql, info.type);
+  const lang = displayLangFor(info.type) ?? "";
+  const fence = fenceFor(sql);
+  const lines: string[] = [];
+
+  const reason = info.reason ? oneLine(info.reason) : "";
+  if (reason) {
+    lines.push(`> **📝 执行理由**：${escInline(reason)}`);
+    lines.push("");
+  }
+
+  const meta: string[] = [];
+  const summary = info.summary ? oneLine(info.summary) : "";
+  const database = info.database ? oneLine(info.database) : "";
+  if (summary) meta.push(`- **📋 影响摘要**：\`${escInline(summary)}\``);
+  if (database) meta.push(`- **🗄️ 数据库**：\`${escInline(database)}\``);
+  if (meta.length > 0) {
+    lines.push(...meta);
+    lines.push("");
+  }
+
+  lines.push(`${fence}${lang}`);
+  lines.push(sql);
+  lines.push(fence);
+  return lines.join("\n");
+}
+
+/** TUI 自定义弹窗：标题 + Markdown 正文（引用/列表/高亮 SQL 代码块）+ 操作提示 */
+async function showTuiConfirm(ctx: any, markdown: string): Promise<boolean> {
+  const [{ DynamicBorder, getMarkdownTheme }, { Container, Markdown, matchesKey, Text }] = await Promise.all([
+    import("@earendil-works/pi-coding-agent"),
+    import("@earendil-works/pi-tui"),
+  ]);
+
+  const result = await ctx.ui.custom((_tui: any, theme: any, _kb: any, done: (v: boolean) => void) => {
+    const container = new Container();
+    const border = new DynamicBorder((s: string) => theme.fg("accent", s));
+
+    container.addChild(border);
+    container.addChild(new Text(theme.fg("accent", theme.bold("SQL 执行确认")), 1, 0));
+    // 与 pi web 同一份 Markdown：Markdown 代码块 → highlightCode(code, lang) → 语法高亮
+    container.addChild(new Markdown(markdown, 1, 1, getMarkdownTheme()));
+    container.addChild(new Text(theme.fg("dim", "Enter 执行  ·  Esc 取消"), 1, 1));
+    container.addChild(border);
+
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (matchesKey(data, "enter")) { done(true); return; }
+        if (matchesKey(data, "escape")) { done(false); return; }
+      },
+    };
+  });
+
+  return result === true;
+}
+
+/**
+ * 统一的 SQL 执行确认入口。返回 true 表示用户确认执行。
+ * 任何 UI 异常都回退到 ctx.ui.confirm（同一份 Markdown）——确认环节绝不因渲染故障被静默跳过。
+ */
+export async function confirmSqlExecution(ctx: any, info: SqlConfirmInfo): Promise<boolean> {
+  const markdown = buildSqlConfirmMarkdown(info);
+  if (ctx?.mode === "tui" && typeof ctx?.ui?.custom === "function") {
+    try {
+      return await showTuiConfirm(ctx, markdown);
+    } catch {
+      // 自定义组件不可用/异常 → 落到下方 confirm
+    }
+  }
+  const ok = await ctx.ui.confirm("SQL 执行确认", markdown);
+  return ok === true;
+}