dsh-limix-data 0.0.0-stage → 0.3.11

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "LimiX Data Sources",
+    "description": "Configures database connections, inspects table schemas, runs read-only queries, and exports CSV files for LimiX prediction and analysis."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "LimiX 数据源",
+    "description": "配置数据库连接，查看库表结构，执行只读查询并导出 CSV，供 LimiX 预测分析使用。"
+  }
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "dsh-limix-data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.11",
+  "type": "module",
+  "description": "配置数据库连接，查看库表结构，执行只读查询并导出 CSV，供 LimiX 预测分析使用。",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./assets/icon.png"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "assets/icon.png",
+    "src",
+    "tsdown.config.ts",
+    "LICENSE",
+    "LICENSING.md",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dependencies": {
+    "mysql2": "^3.23.2",
+    "pg": "^8.22.0"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "tsdown": "^0.15.7",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Limitless2023/limix-dsh.git",
+    "directory": "packages/data"
+  },
+  "homepage": "https://github.com/Limitless2023/limix-dsh#readme",
+  "bugs": {
+    "url": "https://github.com/Limitless2023/limix-dsh/issues"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0"
+}

package/src/CLAUDE.md

@@ -0,0 +1,10 @@
+# packages/data/src/
+
+> L2 | 父级: ../CLAUDE.md
+
+index.ts - 全局设置路由与 limixDatasource 工厂；工具注册使用调用方上下文。
+host/ - 把参数字段表转换成宿主接受的 JSON Schema。
+core/ - 配置存储、SQL 只读校验、数据库驱动与 CSV 导出。
+client/ - 注册数据源设置页，通过同源路由保存连接和演示标识。
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

package/src/client/CLAUDE.md

@@ -0,0 +1,8 @@
+# packages/data/src/client/
+
+> L2 | 父级: ../CLAUDE.md
+
+index.tsx - 全局设置入口，只挂载数据源设置页。
+DatasourceSettings.tsx - 数据库连接表单、演示标识和连接测试；经同源路由保存，不注册对话工具。
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

package/src/client/DatasourceSettings.tsx

@@ -0,0 +1,175 @@
+/**
+ * [INPUT]: 依赖 react（宿主 external）；数据面走同源路由 GET/POST /limix-datasource/config、POST /test
+ * [OUTPUT]: 对外提供 DatasourceSettings：连接清单、演示标识、增删改表单、测试连接、保存
+ * [POS]: limix-datasource 的设置 UI（对位 Next.js 版 /datasources 管理页的 DSH 形态）；
+ *        样式对齐宿主 token（主色 rgb(65,118,230)、胶囊、幽灵钮、13px）
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+import { useEffect, useState } from "react";
+
+const ACCENT = "rgb(65, 118, 230)";
+
+interface Source {
+  id?: string;
+  name: string;
+  kind: "postgres" | "mysql";
+  host: string;
+  port: number;
+  database: string;
+  schema?: string | null;
+  username: string;
+  password: string;
+  isDemo?: boolean;
+}
+
+const EMPTY: Source = {
+  name: "", kind: "postgres", host: "localhost", port: 5432,
+  database: "", schema: "", username: "", password: "",
+};
+
+const ui = {
+  wrap: { padding: "8px 4px", fontSize: 13, maxWidth: 760 },
+  h: { fontSize: 15, fontWeight: 700, margin: "0 0 4px" },
+  sub: { opacity: 0.55, marginBottom: 14, lineHeight: 1.6 },
+  card: {
+    border: "1px solid rgba(0,0,0,.09)", borderRadius: 12, padding: 14, marginBottom: 12,
+  },
+  row: { display: "flex", gap: 8, flexWrap: "wrap" as const, marginBottom: 8 },
+  field: { display: "flex", flexDirection: "column" as const, gap: 3 },
+  label: { fontSize: 11, opacity: 0.55 },
+  input: {
+    padding: "5px 9px", borderRadius: 8, border: "1px solid rgba(0,0,0,.15)",
+    fontSize: 13, background: "Canvas", color: "CanvasText", minWidth: 0,
+  },
+  btn: (primary: boolean) => ({
+    fontSize: 12.5, cursor: "pointer", padding: "5px 14px", borderRadius: 999,
+    border: primary ? "none" : "1px solid rgba(0,0,0,.15)",
+    background: primary ? ACCENT : "transparent",
+    color: primary ? "#fff" : "inherit",
+  }),
+  tag: (ok: boolean) => ({
+    fontSize: 12, marginLeft: 8, color: ok ? "#16a34a" : "#dc2626",
+  }),
+};
+
+export function DatasourceSettings(): JSX.Element {
+  const [sources, setSources] = useState<Source[]>([]);
+  const [loaded, setLoaded] = useState(false);
+  const [dirty, setDirty] = useState(false);
+  const [msg, setMsg] = useState<{ ok: boolean; text: string } | null>(null);
+  const [testing, setTesting] = useState<number | null>(null);
+  const [testResult, setTestResult] = useState<Record<number, { ok: boolean; text: string }>>({});
+
+  useEffect(() => {
+    fetch("/limix-datasource/config")
+      .then((r) => r.json())
+      .then((d) => { setSources(d.sources ?? []); setLoaded(true); })
+      .catch(() => { setMsg({ ok: false, text: "读取配置失败（Node 半路由不可达）" }); setLoaded(true); });
+  }, []);
+
+  function patch(i: number, k: keyof Source, v: unknown) {
+    setSources((ss) => ss.map((s, j) => (j === i ? { ...s, [k]: v } : s)));
+    setDirty(true);
+    setMsg(null);
+  }
+
+  async function test(i: number) {
+    setTesting(i);
+    try {
+      const r = await fetch("/limix-datasource/test", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ source: sources[i] }),
+      }).then((x) => x.json());
+      setTestResult((m) => ({ ...m, [i]: r.ok ? { ok: true, text: `连接成功 ${r.version ?? ""}` } : { ok: false, text: r.error ?? "失败" } }));
+    } catch (e) {
+      setTestResult((m) => ({ ...m, [i]: { ok: false, text: String(e) } }));
+    } finally {
+      setTesting(null);
+    }
+  }
+
+  async function save() {
+    try {
+      const r = await fetch("/limix-datasource/config", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ sources }),
+      }).then((x) => x.json());
+      if (r.ok) { setSources(r.sources); setDirty(false); setMsg({ ok: true, text: "已保存，agent 侧即时生效" }); }
+      else setMsg({ ok: false, text: r.error ?? "保存失败" });
+    } catch (e) {
+      setMsg({ ok: false, text: String(e) });
+    }
+  }
+
+  const F = (i: number, k: keyof Source, label: string, width: number, type = "text") => (
+    <span style={ui.field}>
+      <span style={ui.label}>{label}</span>
+      <input style={{ ...ui.input, width }} type={type} value={String(sources[i][k] ?? "")}
+        onChange={(e) => patch(i, k, k === "port" ? Number(e.target.value) : e.target.value)} />
+    </span>
+  );
+
+  return (
+    <div style={ui.wrap}>
+      <h3 style={ui.h}>数据源</h3>
+      <div style={ui.sub}>
+        配置客户数据库连接（postgres / mysql），LimiX 分析师即可对话取数：看表结构 → 生成 SQL（先展示确认）→
+        预览 → 物化成 CSV 进文件区 → 预测。全链路只读三闸防护；<b>建议使用只读账号</b>。
+        凭据以 0600 权限明文存于 DSH_HOME/limix-datasource.json（本地单用户环境取舍）。
+      </div>
+
+      {!loaded && <div style={{ opacity: 0.5 }}>加载中…</div>}
+      {loaded && sources.length === 0 && <div style={{ opacity: 0.6, marginBottom: 12 }}>还没有数据源，点下方"新增"。</div>}
+
+      {sources.map((s, i) => (
+        <div key={s.id ?? `new-${i}`} style={ui.card}>
+          <div style={ui.row}>
+            {F(i, "name", "名称", 170)}
+            <span style={ui.field}>
+              <span style={ui.label}>类型</span>
+              <select style={{ ...ui.input, width: 110 }} value={s.kind}
+                onChange={(e) => patch(i, "kind", e.target.value)}>
+                <option value="postgres">postgres</option>
+                <option value="mysql">mysql</option>
+              </select>
+            </span>
+            {F(i, "host", "主机", 150)}
+            {F(i, "port", "端口", 70)}
+          </div>
+          <div style={ui.row}>
+            {F(i, "database", "数据库", 130)}
+            {F(i, "schema", "schema(PG 可选)", 130)}
+            {F(i, "username", "用户名", 120)}
+            {F(i, "password", "密码", 140, "password")}
+          </div>
+          <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+            <label style={{ display: "flex", alignItems: "center", gap: 5, marginRight: "auto", fontSize: 12 }}>
+              <input type="checkbox" checked={!!s.isDemo} onChange={(e) => patch(i, "isDemo", e.target.checked)} />
+              演示数据（模拟数据源）
+            </label>
+            <span role="button" style={ui.btn(false)} onClick={() => void test(i)}>
+              {testing === i ? "测试中…" : "测试连接"}
+            </span>
+            <span role="button" style={{ ...ui.btn(false), color: "#dc2626" }}
+              onClick={() => { setSources((ss) => ss.filter((_, j) => j !== i)); setDirty(true); }}>
+              删除
+            </span>
+            {testResult[i] && <span style={ui.tag(testResult[i].ok)}>{testResult[i].text}</span>}
+          </div>
+        </div>
+      ))}
+
+      <div style={{ display: "flex", gap: 10, alignItems: "center", marginTop: 4 }}>
+        <span role="button" style={ui.btn(false)}
+          onClick={() => { setSources((ss) => [...ss, { ...EMPTY }]); setDirty(true); }}>
+          ＋ 新增数据源
+        </span>
+        <span role="button" style={{ ...ui.btn(true), opacity: dirty ? 1 : 0.5 }}
+          onClick={() => { if (dirty) void save(); }}>
+          保存
+        </span>
+        {msg && <span style={ui.tag(msg.ok)}>{msg.text}</span>}
+      </div>
+    </div>
+  );
+}

package/src/client/index.tsx

@@ -0,0 +1,18 @@
+/**
+ * [INPUT]: 依赖宿主 slots 服务；组件见 ./DatasourceSettings
+ * [OUTPUT]: 浏览器半 Cordis 插件：settings.section 挂"数据源"整页（官方 ui-settings-models 同款注册法）
+ * [POS]: limix-datasource 的设置入口；数据经同源路由 /limix-datasource/* 与 Node 半交互
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+import { DatasourceSettings } from "./DatasourceSettings.tsx";
+
+export const inject = ["slots"];
+
+export function apply(ctx: any): void {
+  ctx.slots.inject("settings.section", () =>
+    ctx.slots.register(
+      { name: "settings.section", id: "limix-datasource", order: 30, label: () => "数据源" },
+      DatasourceSettings,
+    ),
+  );
+}

package/src/core/CLAUDE.md

@@ -0,0 +1,13 @@
+# packages/data/src/core/
+
+> L2 | 父级: ../CLAUDE.md
+
+drivers.ts - PostgreSQL/MySQL 只读短连接；MySQL DATE 原样保留日历日期。
+types.ts - 数据源、表结构、查询结果与驱动接口。
+store.ts - 本地配置读写与连接转换；凭据文件权限 0600。
+guard.ts - 只读 SQL 校验与行数限制。
+materialize.ts - 预览与 CSV 物化；调用驱动和 SQL 校验。
+cells.ts - 列名去重与单元格序列化。
+csv.ts - CSV 引号、逗号与换行转义。
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

package/src/core/cells.ts

@@ -0,0 +1,67 @@
+/**
+ * [INPUT]: 无运行时依赖(纯函数, client/server/test 均可 import — 刻意不带 server-only)
+ * [OUTPUT]: 对外提供 sanitizeColumns(列名清洗)/cellToText(单元格→CSV 值)
+ * [POS]: lib/datasource 的物化纯逻辑层, 被 materialize.ts 消费并再导出;
+ *        与 guard.ts 同属"可单测的纯函数"一档 —— 三处审查修复(时区/撞名/公式注入)的行为契约锁在 cells.test.ts
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+/** 列名清洗: 去首尾空白、内部空白/特殊字符换下划线 — LimiX/CSV 下游友好 */
+export function sanitizeColumns(columns: string[]): string[] {
+  const seen = new Set<string>();
+  return columns.map((c, i) => {
+    let name = (c || `col_${i + 1}`).trim().replace(/[\s,;"'`]+/g, "_");
+    if (!name) name = `col_${i + 1}`;
+    // 撞名逐级避让并登记生成名本身, 防 ["x","x","x_2"] 撞出两个 x_2(审查发现 F4)
+    if (seen.has(name)) {
+      let k = 2;
+      while (seen.has(`${name}_${k}`)) k++;
+      name = `${name}_${k}`;
+    }
+    seen.add(name);
+    return name;
+  });
+}
+
+/** 两位补零 */
+function p2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+/** 合法数字字面量(含负号/正号/小数/科学计数) — 这类必须原样, 否则毁掉下游数值解析 */
+const NUMERIC_LITERAL = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+
+/**
+ * CSV 公式注入中和(审查发现 F6): Excel/WPS 打开 CSV 时会把 = + - @ 开头(及前导 Tab/CR)的单元格当公式执行。
+ * 数据来自客户库、理论上可被上游污染 → 加前导单引号让表格软件当纯文本。
+ * ⚠️ 关键例外: **负数必须放行** —— PG 的 numeric/decimal 经驱动返回的是字符串(保精度),
+ * 若把 "-5.5" 变成 "'-5.5", LimiX 侧数值解析直接崩(与时区 bug 同类的静默数据污染)。
+ */
+function neutralizeFormula(s: string): string {
+  if (!/^[=+\-@\t\r]/.test(s)) return s;
+  if (NUMERIC_LITERAL.test(s)) return s;
+  return `'${s}`;
+}
+
+/**
+ * 单元格 → CSV 值。
+ * 时间戳按**本地字段**拼串: 驱动把 DB 的 timestamp/DATETIME(无时区语义)按进程本地时区解析成 Date,
+ * 若再 toISOString() 转 UTC 会平移时区差(实测东八区平移 8 小时, 时序预测的时间轴整体错位)。
+ * 取本地字段即把驱动的解析原样还原成 DB 里的墙钟时间(审查发现 P0)。
+ */
+export function cellToText(v: unknown): string | number {
+  if (v === null || v === undefined) return "";
+  if (typeof v === "number") return v;
+  if (typeof v === "bigint") return v.toString();
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (v instanceof Date) {
+    if (Number.isNaN(v.getTime())) return "";
+    const d = `${v.getFullYear()}-${p2(v.getMonth() + 1)}-${p2(v.getDate())}`;
+    const t = `${p2(v.getHours())}:${p2(v.getMinutes())}:${p2(v.getSeconds())}`;
+    return `${d} ${t}`;
+  }
+  // 二进制列(MySQL BLOB / PG bytea)转 hex, 免 JSON.stringify 出 {"type":"Buffer",...} 垃圾(审查发现 F5)
+  if (v instanceof Uint8Array) return `0x${Buffer.from(v).toString("hex")}`;
+  if (typeof v === "object") return neutralizeFormula(JSON.stringify(v));
+  return neutralizeFormula(String(v));
+}

package/src/core/csv.ts

@@ -0,0 +1,13 @@
+/**
+ * [INPUT]: 无依赖（自 Next.js 版 lib/limix/csv.ts 摘取 toCsv 一个函数）
+ * [OUTPUT]: 对外提供 toCsv（含引号/逗号/换行转义）
+ * [POS]: core 的 CSV 序列化原子，materialize 消费
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+export function toCsv(columns: string[], rows: (string | number)[][]): string {
+  const esc = (v: string | number) => {
+    const s = v == null ? "" : String(v);
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+  };
+  return [columns.map(esc).join(","), ...rows.map((r) => r.map(esc).join(","))].join("\n");
+}

package/src/core/drivers.ts

@@ -0,0 +1,250 @@
+
+/**
+ * [INPUT]: 依赖 pg(Pool)/mysql2(纯JS, 懒加载) 驱动、./types 的统一接口
+ * [OUTPUT]: 对外提供 getDriver(kind)；MySQL DATE 保留日历字符串，不经过时区换算。
+ * [POS]: lib/datasource 的驱动适配层 — 每次调用建短连接即用即弃(serverless 友好, 不留池);
+ *        只读三闸之二: 会话级 read-only + 语句超时(第一闸 guard 在上游, 第三闸=客户只读账号)
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+import type { ColumnInfo, DataSourceConn, DatasourceDriver, QueryResult, TableInfo } from "./types";
+
+const CONNECT_TIMEOUT_MS = 8_000;
+
+// ============================================================
+// PostgreSQL(兼容人大金仓) — 走 pg, 短连接 Client
+// ============================================================
+const postgresDriver: DatasourceDriver = {
+  async testConnection(conn) {
+    try {
+      const version = await withPgClient(conn, 5_000, async (c) => {
+        const r = await c.query("SELECT version() AS v");
+        return String(r.rows[0]?.v || "");
+      });
+      return { ok: true, version };
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+  },
+
+  async listTables(conn) {
+    return withPgClient(conn, 15_000, async (c) => {
+      const schema = conn.schema || "public";
+      const r = await c.query(
+        `SELECT t.table_name AS name, obj_description(pc.oid) AS comment
+           FROM information_schema.tables t
+           JOIN pg_class pc ON pc.relname = t.table_name
+           JOIN pg_namespace pn ON pn.oid = pc.relnamespace AND pn.nspname = t.table_schema
+          WHERE t.table_schema = $1 AND t.table_type = 'BASE TABLE'
+          ORDER BY t.table_name`,
+        [schema],
+      );
+      return r.rows.map((row) => ({ name: String(row.name), comment: row.comment ? String(row.comment) : null }));
+    });
+  },
+
+  async describeTable(conn, table, sampleN = 5) {
+    assertIdent(table);
+    return withPgClient(conn, 20_000, async (c) => {
+      const schema = conn.schema || "public";
+      const qualified = `${qIdent(schema)}.${qIdent(table)}`;
+      const n = Math.min(sampleN, 20);
+      // 列结构 / 表注释 / 采样行**一次往返取回** —— 三条分开发就是三个 RTT(跨区往返约 100ms/次,
+      // 点一次表要等 300ms 纯属白等)。子查询各自 json 聚合, 结果一行三列。
+      const r = await c.query(
+        `SELECT
+           (SELECT json_agg(x ORDER BY x.attnum) FROM (
+              SELECT a.attnum,
+                     a.attname AS name,
+                     format_type(a.atttypid, a.atttypmod) AS "dataType",
+                     col_description(a.attrelid, a.attnum) AS comment
+                FROM pg_attribute a
+               WHERE a.attrelid = $1::regclass AND a.attnum > 0 AND NOT a.attisdropped
+            ) x) AS columns,
+           obj_description($1::regclass) AS comment,
+           (SELECT json_agg(s) FROM (SELECT * FROM ${qualified} LIMIT ${n}) s) AS sample`,
+        [qualified],
+      );
+      const row = r.rows[0] || {};
+      const columns: ColumnInfo[] = ((row.columns as { name: string; dataType: string; comment: string | null }[] | null) ?? []).map(
+        (x) => ({ name: String(x.name), dataType: String(x.dataType), comment: x.comment ? String(x.comment) : null }),
+      );
+      return {
+        name: table,
+        comment: row.comment ? String(row.comment) : null,
+        columns,
+        sampleRows: ((row.sample as Record<string, unknown>[] | null) ?? []) as Record<string, unknown>[],
+      } satisfies TableInfo;
+    });
+  },
+
+  async runQuery(conn, sql, opts) {
+    return withPgClient(conn, opts.timeoutMs, async (c) => {
+      const r = await c.query({ text: sql, rowMode: "array" });
+      const columns = (r.fields || []).map((f) => f.name);
+      const rows = (r.rows || []) as unknown[][];
+      const truncated = rows.length >= opts.maxRows;
+      return { columns, rows: rows.slice(0, opts.maxRows), rowCount: Math.min(rows.length, opts.maxRows), truncated } satisfies QueryResult;
+    });
+  },
+};
+
+async function withPgClient<T>(conn: DataSourceConn, timeoutMs: number, fn: (c: import("pg").Client) => Promise<T>): Promise<T> {
+  const { Client } = await import("pg");
+  // schema 限定的源: search_path 走**启动参数**(零往返) —— 否则 listTables 列得出表、
+  // 裸 SQL `FROM 该表` 却报"不存在"(演示源就在 demo_source schema 里, agent 按表清单写的 SQL 必踩)。
+  // schema 名已过 assertIdent 白名单, 拼进 options 安全。
+  const startupOptions = conn.schema ? `-c search_path=${assertIdentAndReturn(conn.schema)},public` : undefined;
+  const client = new Client({
+    host: conn.host,
+    port: conn.port,
+    database: conn.database,
+    user: conn.username,
+    password: conn.password,
+    connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
+    options: startupOptions,
+    // 本地容器无 TLS, 云库(Supabase 等)要 TLS — prefer 语义: 先试 TLS 失败落明文由服务端决定;
+    // pg 无内置 prefer, 用宽松校验 + 允许降级: 云端主机名默认开 TLS, localhost/127 不开
+    ssl: isLocalHost(conn.host) ? undefined : { rejectUnauthorized: false },
+  });
+  await client.connect();
+  try {
+    // 三闸之二: 会话级只读 + 语句超时(guard 之外的纵深)。
+    // ⚠️ 只读**必须走显式 SET**, 不可挪进上面的启动参数 —— 实测 Supabase 连接池会过滤部分
+    // 启动参数(search_path 生效、default_transaction_read_only 被丢弃, SHOW 出来是 off),
+    // 而只读是最后防线, 静默失效等于裸奔。两条合并成一次往返(无参数走 simple protocol, 可多语句)。
+    await client.query(
+      `SET default_transaction_read_only = on; SET statement_timeout = ${Math.max(1_000, Math.floor(timeoutMs))}`,
+    );
+    return await fn(client);
+  } finally {
+    void client.end().catch(() => {});
+  }
+}
+
+// ============================================================
+// MySQL — 走 mysql2/promise, 短连接
+// ============================================================
+const mysqlDriver: DatasourceDriver = {
+  async testConnection(conn) {
+    try {
+      const version = await withMysql(conn, 5_000, async (c) => {
+        const [rows] = await c.query("SELECT VERSION() AS v");
+        return String((rows as { v?: unknown }[])[0]?.v || "");
+      });
+      return { ok: true, version };
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+  },
+
+  async listTables(conn) {
+    return withMysql(conn, 15_000, async (c) => {
+      const [rows] = await c.query(
+        `SELECT TABLE_NAME AS name, TABLE_COMMENT AS comment
+           FROM information_schema.TABLES
+          WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE'
+          ORDER BY TABLE_NAME`,
+        [conn.database],
+      );
+      return (rows as { name: unknown; comment: unknown }[]).map((r) => ({
+        name: String(r.name),
+        comment: r.comment ? String(r.comment) : null,
+      }));
+    });
+  },
+
+  async describeTable(conn, table, sampleN = 5) {
+    assertIdent(table);
+    return withMysql(conn, 20_000, async (c) => {
+      const [cols] = await c.query(
+        `SELECT COLUMN_NAME AS name, COLUMN_TYPE AS data_type, COLUMN_COMMENT AS comment
+           FROM information_schema.COLUMNS
+          WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
+          ORDER BY ORDINAL_POSITION`,
+        [conn.database, table],
+      );
+      const columns: ColumnInfo[] = (cols as { name: unknown; data_type: unknown; comment: unknown }[]).map((r) => ({
+        name: String(r.name),
+        dataType: String(r.data_type),
+        comment: r.comment ? String(r.comment) : null,
+      }));
+      // 表级注释也带上 — 它是 agent NL2SQL 视野的一部分(审查发现 P3)
+      const [tc] = await c.query(
+        `SELECT TABLE_COMMENT AS comment FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?`,
+        [conn.database, table],
+      );
+      const tcRow = (tc as { comment?: unknown }[])[0];
+      const [sample] = await c.query(`SELECT * FROM \`${table}\` LIMIT ${Math.min(sampleN, 20)}`);
+      return {
+        name: table,
+        comment: tcRow?.comment ? String(tcRow.comment) : null,
+        columns,
+        sampleRows: sample as Record<string, unknown>[],
+      } satisfies TableInfo;
+    });
+  },
+
+  async runQuery(conn, sql, opts) {
+    return withMysql(conn, opts.timeoutMs, async (c) => {
+      const [rows, fields] = await c.query({ sql, rowsAsArray: true, timeout: opts.timeoutMs });
+      const columns = (fields || []).map((f) => f.name);
+      const arr = rows as unknown[][];
+      const truncated = arr.length >= opts.maxRows;
+      return { columns, rows: arr.slice(0, opts.maxRows), rowCount: Math.min(arr.length, opts.maxRows), truncated } satisfies QueryResult;
+    });
+  },
+};
+
+async function withMysql<T>(
+  conn: DataSourceConn,
+  timeoutMs: number,
+  fn: (c: import("mysql2/promise").Connection) => Promise<T>,
+): Promise<T> {
+  const mysql = await import("mysql2/promise");
+  const c = await mysql.createConnection({
+    host: conn.host,
+    port: conn.port,
+    database: conn.database,
+    user: conn.username,
+    password: conn.password,
+    connectTimeout: CONNECT_TIMEOUT_MS,
+    dateStrings: ['DATE'], // 营业日期不代表某个时刻，不能转 UTC 后改变日期。
+    ssl: isLocalHost(conn.host) ? undefined : { rejectUnauthorized: false },
+  });
+  try {
+    await c.query("SET SESSION TRANSACTION READ ONLY");
+    await c.query(`SET SESSION MAX_EXECUTION_TIME = ${Math.max(1_000, Math.floor(timeoutMs))}`); // 毫秒, 仅 SELECT 生效
+    return await fn(c);
+  } finally {
+    void c.end().catch(() => {});
+  }
+}
+
+// ============================================================
+// 公共小件
+// ============================================================
+function isLocalHost(host: string): boolean {
+  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "host.docker.internal";
+}
+
+/** 标识符白名单(表名/schema名): 字母数字下划线中文, 防注入拼接 */
+function assertIdent(name: string): void {
+  if (!/^[\w一-龥]+$/.test(name)) throw new Error(`非法标识符: ${name}`);
+}
+
+/** 同上, 校验通过即回传 —— 供拼接处一行完成"校验+使用", 免漏校验 */
+function assertIdentAndReturn(name: string): string {
+  assertIdent(name);
+  return name;
+}
+
+function qIdent(name: string): string {
+  assertIdent(name);
+  return `"${name}"`;
+}
+
+export function getDriver(kind: DataSourceConn["kind"]): DatasourceDriver {
+  if (kind === "postgres") return postgresDriver;
+  if (kind === "mysql") return mysqlDriver;
+  throw new Error(`不支持的数据源类型: ${kind}`);
+}