dsh-limix-data 0.0.0-stage → 0.3.11

package/src/core/guard.ts

@@ -0,0 +1,138 @@
+/**
+ * [INPUT]: 无运行时依赖(纯函数, client/server/test 均可 import)
+ * [OUTPUT]: 对外提供 guardSql(SQL 安全阀: 校验+注入 LIMIT) + GuardResult + PREVIEW_MAX_ROWS/MATERIALIZE_MAX_ROWS
+ * [POS]: lib/datasource 的防御第一闸(第二闸=驱动会话级 read-only[最后防线], 第三闸=客户只读账号) —
+ *        仅放行单条 SELECT/WITH, 拦截写操作/多语句/注释走私/方言歧义转义; 所有查询入口(工具/API)必须先过此阀
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+export const PREVIEW_MAX_ROWS = 100;
+export const MATERIALIZE_MAX_ROWS = 500_000;
+
+export type GuardResult =
+  | { ok: true; sql: string }
+  | { ok: false; reason: string };
+
+// 词首关键字白名单 — 只允许查询形态
+const ALLOWED_STARTS = /^(select|with)\b/i;
+
+// 危险关键字黑名单(词边界) — 出现在任何位置一律拒绝。
+// 宁可误杀也不放行; 但"仅语句起手位才危险、SELECT 里是常用函数/列名"的词不在此列:
+//   replace(字符串函数, REPLACE INTO 起手已被白名单拦)、comment(常见列名, COMMENT ON 起手已被拦)
+const FORBIDDEN =
+  /\b(insert|update|delete|drop|create|alter|truncate|grant|revoke|merge|call|execute|exec|copy|vacuum|analyze|lock|rename|set|use|do|load|handler|import|install|reset|purge|kill|shutdown|prepare|deallocate|declare|fetch|listen|notify|refresh|reindex|cluster|checkpoint|discard|security|into\s+outfile|into\s+dumpfile)\b/i;
+
+// 敏感对象/函数 — information_schema 对 NL2SQL 有用不拦, 但拒绝系统管控函数与凭据表
+const FORBIDDEN_OBJECTS = /\b(pg_terminate_backend|pg_cancel_backend|pg_reload_conf|pg_sleep|mysql\.user|benchmark\s*\()/i;
+
+type ScanOut = {
+  /** 字面量→''占位、注释→单个空格: 用于关键字/分号判定(防注释粘连骗过词边界) */
+  stripped: string;
+  /** 字面量原样保留、注释→单个空格: 用于 LIMIT 定位与最终下发(注释移除后语义不变) */
+  cleaned: string;
+  /** 引号区域内出现反斜杠 — PG(standard_conforming_strings)与 MySQL 转义语义相反, 存在解析歧义 */
+  backslashInLiteral: boolean;
+};
+
+/**
+ * 单趟扫描出两个视图。字符串按"非转义方言"(PG 默认)解析: 反斜杠是普通字符、'' 是转义引号;
+ * 一旦引号区内出现反斜杠即打歧义标记, 由调用方整句拒绝 — 因为同一 payload 在 MySQL(反斜杠转义)
+ * 与 PG 下会解析出不同的语句边界, 任何单一解析都可能被另一方言走私多语句(审查发现 F2)。
+ */
+function scanSql(sql: string): ScanOut {
+  let stripped = "";
+  let cleaned = "";
+  let backslashInLiteral = false;
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const ch = sql[i];
+    const two = sql.slice(i, i + 2);
+    if (two === "--" || ch === "#") {
+      // 行注释(-- 标准, # MySQL) → 换成单个空格保词边界(审查发现 F1: 换空串会让 DELETE/**/FROM 粘成 DELETEFROM 逃过 \b 判定)
+      while (i < n && sql[i] !== "\n") i++;
+      stripped += " ";
+      cleaned += " ";
+      continue;
+    }
+    if (two === "/*") {
+      const end = sql.indexOf("*/", i + 2);
+      i = end === -1 ? n : end + 2;
+      stripped += " ";
+      cleaned += " ";
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      const quote = ch;
+      let literal = quote;
+      i++;
+      while (i < n) {
+        if (sql[i] === "\\") backslashInLiteral = true; // 不当转义处理, 只标记歧义
+        if (sql[i] === quote) {
+          if (sql[i + 1] === quote) {
+            // '' 双写转义(SQL 标准) — 属于字面量内部
+            literal += quote + quote;
+            i += 2;
+            continue;
+          }
+          literal += quote;
+          i++;
+          break;
+        }
+        literal += sql[i];
+        i++;
+      }
+      stripped += quote + quote; // 判定视图: 字面量清空只留引号壳, 保词边界
+      cleaned += literal;        // 下发视图: 字面量原样
+      continue;
+    }
+    stripped += ch;
+    cleaned += ch;
+    i++;
+  }
+  return { stripped, cleaned, backslashInLiteral };
+}
+
+/**
+ * SQL 安全阀。
+ * @param sql 原始 SQL(单条查询)
+ * @param maxRows 行数上限 — 语句无 LIMIT 时自动追加; 有 LIMIT 但超上限时收紧
+ */
+export function guardSql(sql: string, maxRows: number): GuardResult {
+  const raw = (sql || "").trim().replace(/;+\s*$/, ""); // 去尾部分号
+  if (!raw) return { ok: false, reason: "SQL 为空" };
+  if (raw.length > 20_000) return { ok: false, reason: "SQL 过长(>20000 字符)" };
+
+  const { stripped, cleaned, backslashInLiteral } = scanSql(raw);
+
+  if (backslashInLiteral) {
+    return { ok: false, reason: "字符串字面量里含反斜杠, PG/MySQL 转义语义有歧义, 请改写(如改用 || 拼接或去掉反斜杠)" };
+  }
+
+  // 多语句: 剥掉字面量/注释后仍出现分号 = 拒绝
+  if (stripped.includes(";")) return { ok: false, reason: "只允许单条语句(检测到分号)" };
+
+  if (!ALLOWED_STARTS.test(stripped.trim())) {
+    return { ok: false, reason: "只允许 SELECT / WITH 查询语句" };
+  }
+  const forbidden = stripped.match(FORBIDDEN);
+  if (forbidden) return { ok: false, reason: `检测到禁用关键字: ${forbidden[1] || forbidden[0]}` };
+  const forbiddenObj = stripped.match(FORBIDDEN_OBJECTS);
+  if (forbiddenObj) return { ok: false, reason: `检测到禁用对象/函数: ${forbiddenObj[0]}` };
+
+  // LIMIT 处理 — 一律在 cleaned(注释已除, 字面量完整, 可直接执行)上定位与改写,
+  // 避免"stripped 里匹配到、raw 里因注释匹配不到"的假失败(审查发现 P2)
+  const base = cleaned.trim();
+  const cap = Math.max(1, Math.floor(maxRows));
+  const tail = /\blimit\s+(\d+)((\s+offset\s+\d+)?\s*)$/i.exec(base);
+  if (tail) {
+    const nLimit = parseInt(tail[1], 10);
+    if (nLimit > cap) {
+      const sqlOut = base.slice(0, tail.index) + `LIMIT ${cap}` + (tail[2] || "");
+      return { ok: true, sql: sqlOut };
+    }
+    return { ok: true, sql: base };
+  }
+  // 子查询内可能有 LIMIT 但外层没有 → 统一包一层再截断, 语义安全
+  return { ok: true, sql: `SELECT * FROM (${base}) AS _guarded LIMIT ${cap}` };
+}

package/src/core/materialize.ts

@@ -0,0 +1,46 @@
+
+/**
+ * [INPUT]: 依赖 ./drivers 的 getDriver、./guard 的 guardSql、./store 的 toConn、lib/limix/csv 的 toCsv
+ * [OUTPUT]: 对外提供 previewQuery(≤100行 JSON) + materializeQuery(全量→CSV 文本, 列名已清洗)
+ * [POS]: lib/datasource 的取数出口 — DB 数据进入文件区(窄腰)前的最后一站;
+ *        落文件动作留给调用方(agent 工具走 saveAgentFile, API 走 saveSessionFile), 本层不碰存储
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+import { toCsv } from "./csv";
+import { cellToText, sanitizeColumns } from "./cells";
+import { getDriver } from "./drivers";
+import { guardSql, MATERIALIZE_MAX_ROWS, PREVIEW_MAX_ROWS } from "./guard";
+import { toConn, type StoredSource } from "./store";
+import type { QueryResult } from "./types";
+
+// 纯逻辑在 ./cells(无 server-only, 可单测); 此处再导出保持既有引用路径不变
+export { cellToText, sanitizeColumns } from "./cells";
+
+const PREVIEW_TIMEOUT_MS = 20_000;
+const MATERIALIZE_TIMEOUT_MS = 50_000; // 贴 serverless maxDuration 之下
+
+export async function previewQuery(source: StoredSource, sql: string): Promise<QueryResult> {
+  const g = guardSql(sql, PREVIEW_MAX_ROWS);
+  if (!g.ok) throw new Error(`SQL 未通过安全阀: ${g.reason}`);
+  const driver = getDriver(source.kind);
+  const res = await driver.runQuery(toConn(source), g.sql, { maxRows: PREVIEW_MAX_ROWS, timeoutMs: PREVIEW_TIMEOUT_MS });
+  // 单元格与 materialize 走同一套转换 —— 否则 Date 被 JSON 序列化成 UTC(16:00Z),
+  // 与物化 CSV 里的墙钟时间(00:00)对不上, agent 拿预览核对时会误判需要"时区纠偏"
+  return { ...res, columns: sanitizeColumns(res.columns), rows: res.rows.map((r) => r.map(cellToText)) };
+}
+
+export async function materializeQuery(
+  source: StoredSource,
+  sql: string,
+): Promise<{ csv: string; columns: string[]; rowCount: number; truncated: boolean }> {
+  const g = guardSql(sql, MATERIALIZE_MAX_ROWS);
+  if (!g.ok) throw new Error(`SQL 未通过安全阀: ${g.reason}`);
+  const driver = getDriver(source.kind);
+  const res = await driver.runQuery(toConn(source), g.sql, {
+    maxRows: MATERIALIZE_MAX_ROWS,
+    timeoutMs: MATERIALIZE_TIMEOUT_MS,
+  });
+  const columns = sanitizeColumns(res.columns);
+  const rows = res.rows.map((r) => r.map(cellToText));
+  return { csv: toCsv(columns, rows), columns, rowCount: res.rowCount, truncated: res.truncated };
+}

package/src/core/store.ts

@@ -0,0 +1,97 @@
+/**
+ * [INPUT]: 依赖 node:fs/path/crypto 与 DSH_HOME 环境变量；类型对齐 ./types
+ * [OUTPUT]: 对外提供 readConfig/writeConfig/listSources/getSource/toConn —— JSON 配置文件版数据源清单
+ * [POS]: core 的存储层（DSH 形态重写：原版是 Postgres 表 + AES-GCM 密文，此处为
+ *        $DSH_HOME/limix-datasource.json 明文配置 + 0600 权限——本地单用户演示环境的诚实取舍，
+ *        对外网生产库应配只读账号（三闸模型第三闸）。保持 toConn 出参形状不变，drivers/materialize 零改动）
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import type { DataSourceConn, DataSourceKind } from "./types";
+
+/** 配置文件里的一条数据源（密码明文；文件 0600） */
+export type StoredSource = {
+  id: string;
+  name: string;
+  kind: DataSourceKind;
+  host: string;
+  port: number;
+  database: string;
+  schema?: string | null;
+  username: string;
+  password: string;
+  isDemo?: boolean;
+};
+
+export type DatasourceConfig = { sources: StoredSource[] };
+
+export function configPath(): string {
+  const home = process.env.DSH_HOME || join(process.env.HOME || "~", ".dsh");
+  return join(home, "limix-datasource.json");
+}
+
+export function readConfig(): DatasourceConfig {
+  try {
+    const raw = readFileSync(configPath(), "utf8");
+    const v = JSON.parse(raw);
+    return { sources: Array.isArray(v?.sources) ? v.sources : [] };
+  } catch {
+    return { sources: [] };
+  }
+}
+
+/** 原子写（tmp+rename）+ 0600 */
+export function writeConfig(cfg: DatasourceConfig): void {
+  const p = configPath();
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = p + ".tmp";
+  writeFileSync(tmp, JSON.stringify(cfg, null, 2), "utf8");
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, p);
+}
+
+export function listSources(): StoredSource[] {
+  return readConfig().sources;
+}
+
+export function getSource(id: string): StoredSource | null {
+  return readConfig().sources.find((s) => s.id === id) ?? null;
+}
+
+export function upsertSource(s: Omit<StoredSource, "id"> & { id?: string }): StoredSource {
+  const cfg = readConfig();
+  const row: StoredSource = { ...s, id: s.id || randomUUID() };
+  const i = cfg.sources.findIndex((x) => x.id === row.id);
+  if (i >= 0) cfg.sources[i] = row;
+  else cfg.sources.push(row);
+  writeConfig(cfg);
+  return row;
+}
+
+export function deleteSource(id: string): boolean {
+  const cfg = readConfig();
+  const n = cfg.sources.length;
+  cfg.sources = cfg.sources.filter((x) => x.id !== id);
+  if (cfg.sources.length === n) return false;
+  writeConfig(cfg);
+  return true;
+}
+
+/** 行 → 驱动连接参数（形状与原版一致，drivers/materialize 零改动消费） */
+export function toConn(row: StoredSource): DataSourceConn {
+  return {
+    kind: row.kind,
+    host: row.host,
+    port: row.port,
+    database: row.database,
+    schema: row.schema ?? null,
+    username: row.username,
+    password: row.password,
+  };
+}
+
+export function ensureConfigFile(): void {
+  if (!existsSync(configPath())) writeConfig({ sources: [] });
+}

package/src/core/types.ts

@@ -0,0 +1,68 @@
+/**
+ * [INPUT]: 无运行时依赖(纯类型)
+ * [OUTPUT]: 对外提供 DataSourceKind/DataSourceRow/DataSourceConn/TableInfo/ColumnInfo/QueryResult/DatasourceDriver 类型
+ * [POS]: lib/datasource 的类型真相源, 被 crypto/guard/drivers/store/materialize 与 mastra 工具消费
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+/** P0 支持 postgres(兼容金仓)/mysql; P1 追加 dm/oracle/mssql — 枚举先留位 */
+export type DataSourceKind = "postgres" | "mysql";
+
+export const DATA_SOURCE_KINDS: DataSourceKind[] = ["postgres", "mysql"];
+
+/** data_sources 表一行(凭据只存密文, 明文永不出 lib/datasource) */
+export type DataSourceRow = {
+  id: string;
+  ownerId: string | null;
+  name: string;
+  kind: DataSourceKind;
+  host: string;
+  port: number;
+  database: string;
+  /** postgres 专用: 限定 schema(演示库用 demo_source), 空=默认 public */
+  schema: string | null;
+  username: string;
+  secretEncrypted: string;
+  isDemo: boolean;
+  createdAt: string;
+};
+
+/** 驱动层连接参数(解密后, 仅存在于单次调用栈上) */
+export type DataSourceConn = {
+  kind: DataSourceKind;
+  host: string;
+  port: number;
+  database: string;
+  schema?: string | null;
+  username: string;
+  password: string;
+};
+
+export type ColumnInfo = {
+  name: string;
+  dataType: string;
+  comment: string | null;
+};
+
+export type TableInfo = {
+  name: string;
+  comment: string | null;
+  columns: ColumnInfo[];
+  sampleRows: Record<string, unknown>[];
+};
+
+export type QueryResult = {
+  columns: string[];
+  rows: unknown[][];
+  rowCount: number;
+  /** 行数是否被 maxRows 截断 */
+  truncated: boolean;
+};
+
+/** 统一驱动接口 — 每种数据库实现一份; 全部只读语义(会话级 read-only + guard 双闸) */
+export type DatasourceDriver = {
+  testConnection(conn: DataSourceConn): Promise<{ ok: boolean; version?: string; error?: string }>;
+  listTables(conn: DataSourceConn): Promise<{ name: string; comment: string | null }[]>;
+  describeTable(conn: DataSourceConn, table: string, sampleN?: number): Promise<TableInfo>;
+  runQuery(conn: DataSourceConn, sql: string, opts: { maxRows: number; timeoutMs: number }): Promise<QueryResult>;
+};

package/src/host/CLAUDE.md

@@ -0,0 +1,11 @@
+# packages/data/src/host/
+
+> L2 | 父级: ../CLAUDE.md
+
+define-tool.ts - 将 DSH 参数字段表包成 object schema；保留执行与渲染回调。
+
+parameters 是字段表；output.schema 已含根类型。
+两者进入递归转换前采用不同入口。
+字段上的 required 布尔值只进入父节点的 required 数组。
+
+[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md

package/src/host/define-tool.ts

@@ -0,0 +1,38 @@
+/**
+ * [INPUT]: 接收 DSH 参数字段表与输出 schema DSL；不依赖宿主内部包。
+ * [OUTPUT]: defineTool 返回工具注册定义，参数根节点固定为 object。
+ * [POS]: data 的宿主适配层；将字段 required 标记提升到父节点数组。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+type Spec = Record<string, any>
+
+function toJsonSchema(spec: Spec): any {
+  if (spec && spec.type === 'object' && spec.properties) {
+    return {
+      type: 'object',
+      additionalProperties: spec.additionalProperties ?? false,
+      required: spec.required ?? Object.keys(spec.properties).filter((k) => spec.properties[k]?.required),
+      properties: Object.fromEntries(Object.entries(spec.properties).map(([k, v]) => [k, toJsonSchema(v as Spec)])),
+    }
+  }
+  const out: Spec = {}
+  if (spec?.type) out.type = spec.type
+  if (spec?.description) out.description = spec.description
+  if (spec?.enum) out.enum = spec.enum
+  if (spec?.items) out.items = toJsonSchema(spec.items)
+  if (spec?.properties) out.properties = toJsonSchema({ type: 'object', properties: spec.properties })
+  if (spec?.additionalProperties !== undefined) out.additionalProperties = spec.additionalProperties
+  return out
+}
+
+export function defineTool(spec: any) {
+  return {
+    name: spec.name,
+    description: spec.description,
+    // parameters 是字段表，先补 object 根节点再递归转换。
+    parameters: toJsonSchema({ type: 'object', properties: spec.parameters ?? {} }),
+    output: { schema: toJsonSchema(spec.output?.schema ?? {}), render: spec.output.render },
+    ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
+    execute: spec.execute,
+  }
+}

package/src/index.ts

@@ -0,0 +1,193 @@
+/**
+ * [INPUT]: 依赖全局 webServer；注册工厂接收 preset 的 tools 上下文；核心逻辑在 ./core/*
+ *          （guard 安全阀 / drivers 双驱动 / materialize 取数出口——自 Next.js 版逐字迁移）
+ * [OUTPUT]: ① 发布 limixDatasource.register；只在调用方上下文注册 datasource 工具
+ *           ② 同源路由 /limix-datasource/config (GET/POST) 与 /limix-datasource/test (POST)——设置页后端
+ * [POS]: LimiX Agent 的数据源接入插件 Node 半。安全三闸：guard 语句白名单 →
+ *        驱动会话级只读+语句超时 → 用户侧只读账号约定。materialize 落 CSV 进会话工作目录，
+ *        与 limix 工具 / better-sidebar 文件区 / 时序图表通道天然衔接
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+import { writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { defineTool } from "./host/define-tool.ts";
+import { getDriver } from "./core/drivers.ts";
+import { materializeQuery, previewQuery } from "./core/materialize.ts";
+import {
+  deleteSource, ensureConfigFile, getSource, listSources, toConn, upsertSource,
+  type StoredSource,
+} from "./core/store.ts";
+import { DATA_SOURCE_KINDS } from "./core/types.ts";
+
+export const inject = ["webServer"];
+
+/** 无 Date.now 顾虑（Node 半普通运行时）；文件名时间戳与原版口径一致 */
+function stamp(): string {
+  return new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+}
+
+/** 面向 agent 的源身份信息（凭据永不出层——原版纪律） */
+function publicSource(s: StoredSource) {
+  return { id: s.id, 名称: s.name, 类型: s.kind, 库名: s.database, schema: s.schema ?? null, 演示源: !!s.isDemo };
+}
+
+const DESCRIPTION = `连接客户数据库取数（数据的第二个来源，另一来源是上传/样本 CSV）。全链路只读。
+子命令：list（列出已配置数据源）；inspect --source <id> [--table 表名]（不传 table 回表清单，传了回列结构+中文注释+采样5行）；query --source <id> --sql <单条SELECT/WITH> [--mode preview|materialize] [--file-name 名.csv] [--workdir 目录]。
+工作流（铁律）：list → 对要用的每张表 inspect 看结构与注释 → **生成的 SQL 必须先在回复里用代码块展示给用户并用一句中文解释取的是什么（可见/可确认/可纠正），不要偷偷执行** → query mode=preview 自查（≤100行）→ 确认无误再 mode=materialize 落 CSV 进文件区 → 照常用 limix 工具预测。
+**多表 JOIN 拼成一张宽表是本工具的核心用法**（如电价+气象+预测按省份和时间拼宽表）。只允许单条只读查询，写操作会被安全阀拒绝。materialize 上限 50 万行。`;
+
+export function registerDatasourceTool(ctx: any): void {
+  // ── datasource 工具 ──────────────────────────────────────────────────────
+  ctx.tools.register(defineTool({
+    name: "datasource",
+    description: DESCRIPTION,
+    parameters: {
+      command: { type: "string", required: true, enum: ["list", "inspect", "query"], description: "子命令" },
+      source: { type: "string", description: "数据源 id（来自 list）" },
+      table: { type: "string", description: "inspect 用：表名；不传返回表清单" },
+      sql: { type: "string", description: "query 用：单条只读 SQL（SELECT/WITH），执行前必须已在回复中展示给用户" },
+      mode: { type: "string", enum: ["preview", "materialize"], description: "query 用：preview 自查（默认）/ materialize 落盘 CSV" },
+      fileName: { type: "string", description: "materialize 落盘文件名（.csv 可省略），不传自动命名" },
+      workdir: { type: "string", description: "materialize 落盘目录（默认：调用方会话的工作目录）" },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          command: { type: "string", required: true },
+          ok: { type: "boolean", required: true },
+          text: { type: "string", required: true },
+        },
+      },
+      render: (_args: unknown, value: { text: string }) => [{ type: "text", text: value.text }],
+    },
+    async execute(args: {
+      command: string; source?: string; table?: string; sql?: string;
+      mode?: string; fileName?: string; workdir?: string;
+    }) {
+      const J = (v: unknown) => JSON.stringify(v, null, 2);
+      const fail = (reason: string) => ({ command: args.command, ok: false, text: J({ 错误: reason }) });
+      try {
+        if (args.command === "list") {
+          const sources = listSources();
+          if (!sources.length) {
+            return { command: "list", ok: true, text: J({ 数据源: [], 提示: "当前没有可用的数据源。请用户到 设置 → 数据源 里添加连接（支持 postgres/mysql），配置只读账号。" }) };
+          }
+          return { command: "list", ok: true, text: J({ 数量: sources.length, 数据源: sources.map(publicSource) }) };
+        }
+
+        const src = args.source ? getSource(args.source) : null;
+        if (!src) return fail(`未找到数据源: ${args.source ?? "(未传 source)"}——先用 list 子命令看可用清单`);
+
+        if (args.command === "inspect") {
+          const driver = getDriver(src.kind);
+          if (!args.table) {
+            const tables = await driver.listTables(toConn(src));
+            return { command: "inspect", ok: true, text: J({
+              数据源: src.name, 库名: src.database, 表数量: tables.length,
+              表清单: tables.map((t) => ({ 表名: t.name, 注释: t.comment })),
+              下一步: "对要用到的每张表分别调用 inspect(source, table=<表名>) 看列结构与采样，再写 SQL。",
+            }) };
+          }
+          const info = await driver.describeTable(toConn(src), args.table, 5);
+          return { command: "inspect", ok: true, text: J({
+            数据源: src.name, 表名: info.name, 表注释: info.comment,
+            列: info.columns.map((c) => ({ 列名: c.name, 类型: c.dataType, 注释: c.comment })),
+            采样5行: info.sampleRows,
+          }) };
+        }
+
+        if (args.command === "query") {
+          if (!args.sql) return fail("query 需要 sql 参数（单条 SELECT/WITH）");
+          const mode = args.mode === "materialize" ? "materialize" : "preview";
+          if (mode === "preview") {
+            const r = await previewQuery(src, args.sql);
+            return { command: "query", ok: true, text: J({
+              模式: "preview", 数据源: src.name, 列: r.columns, 行数: r.rowCount, 已截断: r.truncated,
+              数据: r.rows,
+              下一步: "与用户确认数据无误后，用 mode=materialize 落盘成 CSV，再用 limix 工具预测。",
+            }) };
+          }
+          const r = await materializeQuery(src, args.sql);
+          const name = args.fileName
+            ? (/\.csv$/i.test(args.fileName) ? args.fileName : `${args.fileName}.csv`)
+            : `ds_查询结果_${stamp()}.csv`;
+          const dir = args.workdir && isAbsolute(args.workdir) ? args.workdir : resolve(process.cwd(), args.workdir ?? ".");
+          const full = join(dir, name);
+          writeFileSync(full, r.csv, "utf8");
+          return { command: "query", ok: true, text: J({
+            模式: "materialize", 数据源: src.name, 文件: full, 列: r.columns, 行数: r.rowCount, 已截断: r.truncated,
+            下一步: "宽表已落文件区。用 limix 工具（forecast/classify/regress）对该文件预测，或先剖析数据。",
+          }) };
+        }
+        return fail(`未知子命令: ${args.command}`);
+      } catch (e: any) {
+        return fail(String(e?.message ?? e));
+      }
+    },
+  }));
+
+}
+
+export function apply(ctx: any): void {
+  ensureConfigFile();
+  // 全局只发布工厂；由 preset 的工具插件传入其会话上下文。
+  ctx.provide("limixDatasource", { register: registerDatasourceTool });
+
+  // ── 设置页后端：同源只读/写路由（与 /limix-ui/csv 同款手法） ─────────────
+  const readBody = (req: any): Promise<string> => new Promise((res, rej) => {
+    let b = ""; req.on("data", (c: any) => { b += c }); req.on("end", () => res(b)); req.on("error", rej);
+  });
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: "exact", path: "/limix-datasource/config",
+    handler: async (req: any, res: any) => {
+      try {
+        if (req.method === "GET") {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({ sources: listSources(), kinds: DATA_SOURCE_KINDS }));
+          return;
+        }
+        if (req.method === "POST") {
+          const body = JSON.parse(await readBody(req));
+          // 全量替换语义：settings UI 每次提交完整清单；逐条校验后 upsert，缺席的删除
+          const incoming: StoredSource[] = Array.isArray(body?.sources) ? body.sources : [];
+          for (const s of incoming) {
+            if (!DATA_SOURCE_KINDS.includes(s.kind)) throw new Error(`不支持的类型: ${s.kind}`);
+            if (!s.name || !s.host || !s.database || !s.username) throw new Error("name/host/database/username 必填");
+            const port = Number(s.port);
+            if (!(port >= 1 && port <= 65535)) throw new Error(`端口非法: ${s.port}`);
+          }
+          const keep = new Set<string>();
+          for (const s of incoming) keep.add(upsertSource(s).id);
+          for (const s of listSources()) if (!keep.has(s.id)) deleteSource(s.id);
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify({ ok: true, sources: listSources() }));
+          return;
+        }
+        res.writeHead(405); res.end();
+      } catch (e: any) {
+        res.writeHead(400, { "content-type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: String(e?.message ?? e) }));
+      }
+    },
+  }), "limix-datasource: config 路由");
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: "exact", path: "/limix-datasource/test",
+    handler: async (req: any, res: any) => {
+      try {
+        if (req.method !== "POST") { res.writeHead(405); res.end(); return }
+        const body = JSON.parse(await readBody(req));
+        const s: StoredSource = body?.source;
+        const r = await getDriver(s.kind).testConnection(toConn(s));
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify(r));
+      } catch (e: any) {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: String(e?.message ?? e) }));
+      }
+    },
+  }), "limix-datasource: 测试连接路由");
+}

package/tsdown.config.ts

@@ -0,0 +1,62 @@
+/**
+ * [INPUT]: 依赖 tsdown；构建契约照抄 packages/limix-ui/tsdown.config.ts（本仓开发法则第 3 条）
+ * [OUTPUT]: lib/index.js（Node 半 ESM；pg/mysql2 external 留给运行时动态 import）
+ *           + lib/client.js（浏览器半 CJS 闭包工厂）
+ * [POS]: limix-datasource 的构建入口
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+import { defineConfig } from 'tsdown'
+
+const ID = 'dsh-limix-data'
+
+const CLIENT_EXTERNALS = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-web-react',
+  '@deepseek-ai/dsh-client-ui-primitives',
+  '@deepseek-ai/dsh-client-ui-attachment',
+  '@deepseek-ai/dsh-client-schema-form',
+  '@deepseek-ai/dsh-client-runtime/client',
+]
+
+export default defineConfig([
+  {
+    // ── Node 半：工具 + 路由；数据库驱动运行时动态 import，不打包 ──
+    entry: { index: 'src/index.ts' },
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    dts: false,
+    clean: false,
+    fixedExtension: false,
+    external: ['pg', 'mysql2', 'mysql2/promise'],
+  },
+  {
+    // ── 浏览器半：CJS 闭包工厂（宿主 ModuleLoader 契约）──
+    entry: { client: 'src/client/index.tsx' },
+    outDir: 'lib',
+    format: ['cjs'],
+    platform: 'browser',
+    dts: false,
+    clean: false,
+    sourcemap: false,
+    fixedExtension: false,
+    external: CLIENT_EXTERNALS,
+    noExternal: (id: string) => (CLIENT_EXTERNALS.includes(id) ? undefined : true),
+    define: {
+      'process.env.NODE_ENV': JSON.stringify('production'),
+      'import.meta.env.MODE': JSON.stringify('production'),
+      'import.meta.env': JSON.stringify({ MODE: 'production' }),
+    },
+    outputOptions: {
+      entryFileNames: 'client.js',
+      banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(ID)}, factory: (require) => {`,
+      footer: 'return module.exports; } });',
+      intro: 'var module = { exports: {} }; var exports = module.exports;',
+    },
+  },
+])

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.