@caoguo/maplibre-ai 0.0.2 → 0.0.5

package/dist/llm/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/llm/deepseek.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * DeepSeek LLM 客户端（PRD phase-0 §5.5 / §5.7 的 v1 后端能力）\n *\n * DeepSeek API 与 OpenAI Chat Completions 协议兼容：\n *   base_url: https://api.deepseek.com\n *   模型:     deepseek-chat（通用对话）/ deepseek-reasoner（深度推理）\n *   鉴权:     Authorization: Bearer <API_KEY>\n *\n * 设计：\n *   - 依赖注入的 fetch（浏览器/Node 均可运行，Node 18+ 原生 fetch）\n *   - 自动重试（指数退避）\n *   - 失败降级（可传入 fallback，规则引擎兜底）\n *   - 支持流式（onChunk 回调）与 JSON 输出\n */\n\nexport interface DeepSeekConfig {\n  /** API Key */\n  apiKey: string;\n  /** 基础地址，默认 https://api.deepseek.com */\n  baseUrl?: string;\n  /** 模型，默认 deepseek-chat */\n  model?: 'deepseek-chat' | 'deepseek-reasoner' | (string & {});\n  /** 温度 0-2 */\n  temperature?: number;\n  /** 最大 token */\n  maxTokens?: number;\n  /** 超时（ms），默认 30s */\n  timeoutMs?: number;\n  /** 重试次数，默认 2 */\n  retries?: number;\n  /** 注入 fetch（测试/Node 环境），默认 globalThis.fetch */\n  fetchImpl?: typeof fetch;\n}\n\nexport interface ChatMessage {\n  role: 'system' | 'user' | 'assistant';\n  content: string;\n}\n\nexport interface ChatOptions {\n  /** 是否启用 JSON 模式（要求模型返回纯 JSON） */\n  json?: boolean;\n  /** 流式回调 */\n  onChunk?: (delta: string) => void;\n}\n\nexport interface ChatResult {\n  /** 完整回复文本 */\n  content: string;\n  /** 消耗 token */\n  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };\n  /** 使用的模型 */\n  model: string;\n}\n\n/** 已解析的 JSON 回复 */\nexport interface JsonChatResult<T> {\n  /** 解析出的 JSON 对象 */\n  data: T;\n  /** 原始文本 */\n  raw: string;\n  model: string;\n}\n\nconst DEFAULT_BASE_URL = 'https://api.deepseek.com';\nconst DEFAULT_MODEL = 'deepseek-chat';\n\n/** 把中文异常文案简化为错误码 */\nfunction normalizeError(body: string): Error {\n  const err = new Error(body || 'DeepSeek API 请求失败');\n  err.name = 'DeepSeekError';\n  return err;\n}\n\nexport class DeepSeekClient {\n  private config: Required<Omit<DeepSeekConfig, 'fetchImpl'>> & { fetchImpl: typeof fetch };\n  private lastRequestId = 0;\n\n  constructor(config: DeepSeekConfig) {\n    if (!config.apiKey) throw new Error('DeepSeekClient: apiKey 不能为空');\n    this.config = {\n      apiKey: config.apiKey,\n      baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, ''),\n      model: config.model ?? DEFAULT_MODEL,\n      temperature: config.temperature ?? 0.3,\n      maxTokens: config.maxTokens ?? 2048,\n      timeoutMs: config.timeoutMs ?? 30000,\n      retries: config.retries ?? 2,\n      fetchImpl: config.fetchImpl ?? ((globalThis as { fetch?: typeof fetch }).fetch ?? fetch),\n    };\n  }\n\n  /** 发起一次聊天补全 */\n  async chat(messages: ChatMessage[], opts: ChatOptions = {}): Promise<ChatResult> {\n    return this.requestWithRetry(messages, opts);\n  }\n\n  /** 聊天 + JSON 解析 */\n  async chatJson<T>(messages: ChatMessage[]): Promise<JsonChatResult<T>> {\n    const result = await this.chat(messages, { json: true });\n    const raw = result.content.trim();\n    // 去除可能的 ```json 围栏\n    const cleaned = raw.replace(/^```(?:json)?\\s*/i, '').replace(/\\s*```$/, '');\n    let data: T;\n    try {\n      data = JSON.parse(cleaned) as T;\n    } catch (e) {\n      // 尝试从文本中提取首个 JSON 对象\n      const match = cleaned.match(/\\{[\\s\\S]*\\}|\\[[\\s\\S]*\\]/);\n      if (match) {\n        data = JSON.parse(match[0]) as T;\n      } else {\n        throw new Error(`DeepSeek 返回了非 JSON 内容: ${raw.slice(0, 200)}`);\n      }\n    }\n    return { data, raw, model: result.model };\n  }\n\n  private async requestWithRetry(messages: ChatMessage[], opts: ChatOptions): Promise<ChatResult> {\n    let lastError: Error | null = null;\n    for (let attempt = 0; attempt <= this.config.retries; attempt++) {\n      try {\n        return await this.requestOnce(messages, opts);\n      } catch (e) {\n        lastError = e as Error;\n        // 仅对可重试错误（网络/429/5xx）重试\n        const retryable = !(e instanceof Error) || !e.name.includes('DeepSeek') || this.isRetryable(e as Error);\n        if (!retryable && !this.isRetryable(e as Error)) break;\n        if (attempt < this.config.retries) {\n          await this.sleep(Math.min(1000 * 2 ** attempt, 8000));\n        }\n      }\n    }\n    throw lastError ?? new Error('DeepSeek 请求失败');\n  }\n\n  private isRetryable(err: Error): boolean {\n    const msg = err.message ?? '';\n    return /429|500|502|503|504|timeout|network|ECONN|abort|fetch failed/i.test(msg);\n  }\n\n  private async requestOnce(messages: ChatMessage[], opts: ChatOptions): Promise<ChatResult> {\n    const { fetchImpl } = this.config;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);\n\n    const body: Record<string, unknown> = {\n      model: this.config.model,\n      messages,\n      temperature: this.config.temperature,\n      max_tokens: this.config.maxTokens,\n      stream: Boolean(opts.onChunk),\n    };\n    if (opts.json) {\n      body.response_format = { type: 'json_object' };\n    }\n\n    try {\n      const res = await fetchImpl(`${this.config.baseUrl}/chat/completions`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          Authorization: `Bearer ${this.config.apiKey}`,\n        },\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n\n      if (!res.ok) {\n        const text = await res.text().catch(() => '');\n        throw normalizeError(`DeepSeek HTTP ${res.status}: ${text}`);\n      }\n\n      // 流式\n      if (opts.onChunk && res.body) {\n        return this.parseStream(res.body, opts.onChunk);\n      }\n\n      // 非流式\n      const json = (await res.json()) as {\n        choices: Array<{ message: { content: string } }>;\n        usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };\n        model?: string;\n      };\n      const content = json.choices?.[0]?.message?.content ?? '';\n      return {\n        content,\n        model: json.model ?? this.config.model,\n        usage: json.usage\n          ? { promptTokens: json.usage.prompt_tokens, completionTokens: json.usage.completion_tokens, totalTokens: json.usage.total_tokens }\n          : undefined,\n      };\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n\n  /** 解析 SSE 流式响应 */\n  private async parseStream(\n    body: ReadableStream<Uint8Array>,\n    onChunk: (delta: string) => void\n  ): Promise<ChatResult> {\n    const reader = body.getReader();\n    const decoder = new TextDecoder();\n    let content = '';\n    let buffer = '';\n\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n      buffer += decoder.decode(value, { stream: true });\n      const lines = buffer.split('\\n');\n      buffer = lines.pop() ?? '';\n      for (const line of lines) {\n        const trimmed = line.trim();\n        if (!trimmed.startsWith('data:')) continue;\n        const data = trimmed.slice(5).trim();\n        if (data === '[DONE]') continue;\n        try {\n          const json = JSON.parse(data) as { choices?: Array<{ delta?: { content?: string } }> };\n          const delta = json.choices?.[0]?.delta?.content ?? '';\n          if (delta) {\n            content += delta;\n            onChunk(delta);\n          }\n        } catch {\n          // 忽略无法解析的行\n        }\n      }\n    }\n    return { content, model: this.config.model };\n  }\n\n  private sleep(ms: number): Promise<void> {\n    return new Promise((r) => setTimeout(r, ms));\n  }\n}\n\n/** 便捷工厂：创建默认配置的客户端 */\nexport function createDeepSeekClient(config: DeepSeekConfig): DeepSeekClient {\n  return new DeepSeekClient(config);\n}\n"]}

package/dist/llm/index.d.cts

@@ -0,0 +1,81 @@
+/**
+ * DeepSeek LLM 客户端（PRD phase-0 §5.5 / §5.7 的 v1 后端能力）
+ *
+ * DeepSeek API 与 OpenAI Chat Completions 协议兼容：
+ *   base_url: https://api.deepseek.com
+ *   模型:     deepseek-chat（通用对话）/ deepseek-reasoner（深度推理）
+ *   鉴权:     Authorization: Bearer <API_KEY>
+ *
+ * 设计：
+ *   - 依赖注入的 fetch（浏览器/Node 均可运行，Node 18+ 原生 fetch）
+ *   - 自动重试（指数退避）
+ *   - 失败降级（可传入 fallback，规则引擎兜底）
+ *   - 支持流式（onChunk 回调）与 JSON 输出
+ */
+interface DeepSeekConfig {
+    /** API Key */
+    apiKey: string;
+    /** 基础地址，默认 https://api.deepseek.com */
+    baseUrl?: string;
+    /** 模型，默认 deepseek-chat */
+    model?: 'deepseek-chat' | 'deepseek-reasoner' | (string & {});
+    /** 温度 0-2 */
+    temperature?: number;
+    /** 最大 token */
+    maxTokens?: number;
+    /** 超时（ms），默认 30s */
+    timeoutMs?: number;
+    /** 重试次数，默认 2 */
+    retries?: number;
+    /** 注入 fetch（测试/Node 环境），默认 globalThis.fetch */
+    fetchImpl?: typeof fetch;
+}
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface ChatOptions {
+    /** 是否启用 JSON 模式（要求模型返回纯 JSON） */
+    json?: boolean;
+    /** 流式回调 */
+    onChunk?: (delta: string) => void;
+}
+interface ChatResult {
+    /** 完整回复文本 */
+    content: string;
+    /** 消耗 token */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** 使用的模型 */
+    model: string;
+}
+/** 已解析的 JSON 回复 */
+interface JsonChatResult<T> {
+    /** 解析出的 JSON 对象 */
+    data: T;
+    /** 原始文本 */
+    raw: string;
+    model: string;
+}
+declare class DeepSeekClient {
+    private config;
+    private lastRequestId;
+    constructor(config: DeepSeekConfig);
+    /** 发起一次聊天补全 */
+    chat(messages: ChatMessage[], opts?: ChatOptions): Promise<ChatResult>;
+    /** 聊天 + JSON 解析 */
+    chatJson<T>(messages: ChatMessage[]): Promise<JsonChatResult<T>>;
+    private requestWithRetry;
+    private isRetryable;
+    private requestOnce;
+    /** 解析 SSE 流式响应 */
+    private parseStream;
+    private sleep;
+}
+/** 便捷工厂：创建默认配置的客户端 */
+declare function createDeepSeekClient(config: DeepSeekConfig): DeepSeekClient;
+
+export { type ChatMessage, type ChatOptions, type ChatResult, DeepSeekClient, type DeepSeekConfig, type JsonChatResult, createDeepSeekClient };

package/dist/llm/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * DeepSeek LLM 客户端（PRD phase-0 §5.5 / §5.7 的 v1 后端能力）
+ *
+ * DeepSeek API 与 OpenAI Chat Completions 协议兼容：
+ *   base_url: https://api.deepseek.com
+ *   模型:     deepseek-chat（通用对话）/ deepseek-reasoner（深度推理）
+ *   鉴权:     Authorization: Bearer <API_KEY>
+ *
+ * 设计：
+ *   - 依赖注入的 fetch（浏览器/Node 均可运行，Node 18+ 原生 fetch）
+ *   - 自动重试（指数退避）
+ *   - 失败降级（可传入 fallback，规则引擎兜底）
+ *   - 支持流式（onChunk 回调）与 JSON 输出
+ */
+interface DeepSeekConfig {
+    /** API Key */
+    apiKey: string;
+    /** 基础地址，默认 https://api.deepseek.com */
+    baseUrl?: string;
+    /** 模型，默认 deepseek-chat */
+    model?: 'deepseek-chat' | 'deepseek-reasoner' | (string & {});
+    /** 温度 0-2 */
+    temperature?: number;
+    /** 最大 token */
+    maxTokens?: number;
+    /** 超时（ms），默认 30s */
+    timeoutMs?: number;
+    /** 重试次数，默认 2 */
+    retries?: number;
+    /** 注入 fetch（测试/Node 环境），默认 globalThis.fetch */
+    fetchImpl?: typeof fetch;
+}
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface ChatOptions {
+    /** 是否启用 JSON 模式（要求模型返回纯 JSON） */
+    json?: boolean;
+    /** 流式回调 */
+    onChunk?: (delta: string) => void;
+}
+interface ChatResult {
+    /** 完整回复文本 */
+    content: string;
+    /** 消耗 token */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** 使用的模型 */
+    model: string;
+}
+/** 已解析的 JSON 回复 */
+interface JsonChatResult<T> {
+    /** 解析出的 JSON 对象 */
+    data: T;
+    /** 原始文本 */
+    raw: string;
+    model: string;
+}
+declare class DeepSeekClient {
+    private config;
+    private lastRequestId;
+    constructor(config: DeepSeekConfig);
+    /** 发起一次聊天补全 */
+    chat(messages: ChatMessage[], opts?: ChatOptions): Promise<ChatResult>;
+    /** 聊天 + JSON 解析 */
+    chatJson<T>(messages: ChatMessage[]): Promise<JsonChatResult<T>>;
+    private requestWithRetry;
+    private isRetryable;
+    private requestOnce;
+    /** 解析 SSE 流式响应 */
+    private parseStream;
+    private sleep;
+}
+/** 便捷工厂：创建默认配置的客户端 */
+declare function createDeepSeekClient(config: DeepSeekConfig): DeepSeekClient;
+
+export { type ChatMessage, type ChatOptions, type ChatResult, DeepSeekClient, type DeepSeekConfig, type JsonChatResult, createDeepSeekClient };

package/dist/llm/index.js

@@ -0,0 +1,3 @@
+export { DeepSeekClient, createDeepSeekClient } from '../chunk-ZI6ZF26Q.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/llm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/nlpg/index.cjs

@@ -0,0 +1,387 @@
+'use strict';
+
+// src/nlpg/sqlGenerator.ts
+var FIELD_ALIASES = [
+  { field: "material", re: /材质|材料|铸铁|钢管|PE|PVC|球墨|HDPE|铜管/ },
+  { field: "pressure", re: /压力|水压|气压|MPa/ },
+  { field: "diameter", re: /管径|直径|口径|DN/ },
+  { field: "status", re: /状态|运行|停运|故障|检修/ },
+  { field: "install_date", re: /安装日期|投运|建成|敷设/ },
+  { field: "age", re: /年限|使用.{0,2}年|超过.{0,2}年|.{0,2}年以上|年代/ },
+  { field: "voltage", re: /电压|kV|kv|伏/ },
+  { field: "load_rate", re: /负载率|负荷率|利用率|负载|负荷/ },
+  { field: "fault_rate", re: /故障率/ },
+  { field: "flow_rate", re: /流量|流速/ },
+  { field: "water_level", re: /水位/ },
+  { field: "storage_rate", re: /蓄水率|库容/ },
+  { field: "rsrp", re: /RSRP|信号强度|信号/ }
+];
+var TABLE_ALIASES = [
+  { table: "pipelines", re: /管段|管线|管道|管网|燃气管|供水管|排水管|供热管|电力管|通信管/ },
+  { table: "nodes", re: /节点|阀门|泵站|表|井|闸/ },
+  { table: "users", re: /用户|居民|小区|住户|建筑/ },
+  { table: "schools", re: /学校|小学|中学|大学|幼儿园/ },
+  { table: "hospitals", re: /医院|卫生院|诊所/ },
+  { table: "substations", re: /变电站|配变|台区|电站/ },
+  { table: "base_stations", re: /基站|宏站|微站|室分/ },
+  { table: "rivers", re: /河流|水系|河段|支流/ },
+  { table: "reservoirs", re: /水库|大坝/ },
+  { table: "alarms", re: /报警|告警|警报/ },
+  { table: "pois", re: /POI|兴趣点|场所|设施/ }
+];
+var VALUE_DICT = [
+  { field: "material", value: "cast_iron", re: /铸铁/ },
+  { field: "material", value: "ductile_iron", re: /球墨/ },
+  { field: "material", value: "steel", re: /钢(?!筋)/ },
+  { field: "material", value: "pe", re: /PE/ },
+  { field: "material", value: "pvc", re: /PVC/ },
+  { field: "material", value: "hdpe", re: /HDPE/ },
+  { field: "status", value: "normal", re: /正常/ },
+  { field: "status", value: "fault", re: /故障/ },
+  { field: "status", value: "maintenance", re: /检修|维修/ },
+  { field: "status", value: "aging", re: /老化/ }
+];
+function detectOperator(text) {
+  if (/超过|高于|大于|超出|以上|不小于/.test(text)) return text.includes("\u4EE5\u4E0A") || text.includes("\u4E0D\u5C0F\u4E8E") ? ">=" : ">";
+  if (/低于|小于|不到|以下|不足/.test(text)) return text.includes("\u4EE5\u4E0B") ? "<=" : "<";
+  if (/等于|正好|恰好|为\s*\d/.test(text)) return "=";
+  if (/不是|非|不等于/.test(text)) return "!=";
+  if (/包含|含有|含/.test(text)) return "LIKE";
+  return "=";
+}
+function detectTable(text) {
+  for (const t of TABLE_ALIASES) {
+    if (t.re.test(text)) return t.table;
+  }
+  return "pois";
+}
+function detectField(text) {
+  for (const f of FIELD_ALIASES) {
+    if (f.re.test(text)) return f.field;
+  }
+  return null;
+}
+function detectValue(text, field) {
+  for (const v of VALUE_DICT) {
+    if (v.field === field && v.re.test(text)) return v.value;
+  }
+  const numMatch = text.match(/(\d+(?:\.\d+)?)\s*(MPa|mpa|kV|kv|米|m|公里|km|%|％|方|立方米)?/);
+  if (numMatch) {
+    let value = parseFloat(numMatch[1]);
+    const unit = numMatch[2] ?? "";
+    if (/公里|km/.test(unit)) value *= 1e3;
+    if (/%|％/.test(unit)) value /= 100;
+    return value;
+  }
+  const dateMatch = text.match(/(\d{4}-\d{2}-\d{2}|\d{4}年\d{1,2}月)/);
+  if (dateMatch) return dateMatch[1];
+  return null;
+}
+function detectSpatial(text, geometryColumn = "geom") {
+  const nearby = text.match(/(\d+(?:\.\d+)?)\s*(米|m|公里|km|千米)\s*(?:内|以内|范围内|附近|周边)/);
+  if (nearby) {
+    let radius = parseFloat(nearby[1]);
+    if (/公里|km|千米/.test(nearby[2])) radius *= 1e3;
+    return { relation: "dwithin", radius, geometryColumn };
+  }
+  const point = detectReferencePoint(text);
+  if (/缓冲区|缓冲|范围内|区域.{0,2}内/.test(text)) {
+    return { relation: "buffer", point, geometryColumn };
+  }
+  if (/包含|覆盖|涵盖|包围|圈住/.test(text)) {
+    return { relation: "contains", point, geometryColumn };
+  }
+  if (/在.{0,2}内|内部|以内|之中/.test(text)) {
+    return { relation: "within", point, geometryColumn };
+  }
+  if (/相交|叠加|重叠|交叉/.test(text)) {
+    return { relation: "intersects", point, geometryColumn };
+  }
+  return null;
+}
+function detectReferencePoint(text) {
+  const m = text.match(/([1-2]?\d{2,3}(?:\.\d+)?)\s*[,，]\s*(\d{1,3}(?:\.\d+)?)/);
+  if (m) {
+    const lng = parseFloat(m[1]);
+    const lat = parseFloat(m[2]);
+    if (lng >= -180 && lng <= 180 && lat >= -90 && lat <= 90) return [lng, lat];
+  }
+  return void 0;
+}
+function quoteValue(v) {
+  return typeof v === "string" ? `'${v.replace(/'/g, "''")}'` : String(v);
+}
+function buildWhere(conditions, spatial) {
+  const parts = [];
+  for (const c of conditions) {
+    parts.push(`${c.field} ${c.operator} ${quoteValue(c.value)}`);
+  }
+  if (spatial) {
+    const col = spatial.geometryColumn;
+    const refGeom = spatial.referenceColumn ? spatial.referenceColumn : spatial.point ? `ST_Buffer(ST_SetSRID(ST_MakePoint(${spatial.point[0]}, ${spatial.point[1]}), 4326), ${spatial.radius ?? 0})` : null;
+    switch (spatial.relation) {
+      case "dwithin":
+        if (spatial.point && spatial.radius !== void 0) {
+          parts.push(`ST_DWithin(${col}, ST_SetSRID(ST_MakePoint(${spatial.point[0]}, ${spatial.point[1]}), 4326), ${spatial.radius})`);
+        }
+        break;
+      case "buffer":
+        if (refGeom) parts.push(`ST_Intersects(${col}, ${refGeom})`);
+        break;
+      case "within":
+        if (refGeom) parts.push(`ST_Within(${col}, ${refGeom})`);
+        break;
+      case "contains":
+        if (refGeom) parts.push(`ST_Contains(${refGeom}, ${col})`);
+        break;
+      case "intersects":
+        if (refGeom) parts.push(`ST_Intersects(${col}, ${refGeom})`);
+        break;
+    }
+  }
+  return parts.length > 0 ? `WHERE ${parts.join(" AND ")}` : "";
+}
+function generatePostGISQuery(text, opts = {}) {
+  const center = opts.center ?? [114.305, 30.593];
+  const geometryColumn = opts.geometryColumn ?? "geom";
+  const table = detectTable(text);
+  const spatial = detectSpatial(text, geometryColumn);
+  if (spatial && !spatial.point) {
+    spatial.point = center;
+  }
+  if (spatial && spatial.relation !== "dwithin" && spatial.radius === void 0) {
+    spatial.radius = 1e3;
+  }
+  const conditions = [];
+  const field = detectField(text);
+  if (field) {
+    const value = detectValue(text, field);
+    if (value !== null) {
+      conditions.push({ field, operator: detectOperator(text), value });
+    }
+  }
+  let intent;
+  if (spatial && conditions.length > 0) intent = "mixed";
+  else if (spatial) intent = spatial.relation === "dwithin" ? "spatial_nearby" : "spatial_within";
+  else if (conditions.length > 0) intent = "attribute_filter";
+  else intent = "unknown";
+  const where = buildWhere(conditions, spatial);
+  const sql = `SELECT * FROM ${table} ${where}`.trim();
+  let confidence = 0.3;
+  if (conditions.length > 0) confidence += 0.3;
+  if (spatial) confidence += 0.3;
+  if (table !== "pois") confidence += 0.1;
+  confidence = Math.min(0.95, confidence);
+  return { intent, table, conditions, spatial, sql, confidence };
+}
+
+// src/nlpg/sqlValidator.ts
+var DANGEROUS_KEYWORDS = [
+  "DROP",
+  "DELETE",
+  "UPDATE",
+  "INSERT",
+  "ALTER",
+  "TRUNCATE",
+  "GRANT",
+  "REVOKE",
+  "MERGE",
+  "CREATE",
+  "REPLACE",
+  "EXEC",
+  "EXECUTE",
+  "CALL",
+  "COPY",
+  "LOAD",
+  "INTO",
+  "SET",
+  "UNION",
+  "ATTACH",
+  "DETACH",
+  "PRAGMA",
+  "VACUUM",
+  "REINDEX"
+];
+var INJECTION_PATTERNS = [
+  /--/,
+  // SQL 注释
+  /\/\*/,
+  // 块注释
+  /;\s*(DROP|DELETE|UPDATE|INSERT|ALTER|TRUNCATE)/i,
+  // 多语句注入
+  /'\s*OR\s*'/i,
+  // ' OR ' 恒真注入（含 ' OR '1'='1'）
+  /"\s*OR\s*"/i,
+  // " OR " 恒真注入
+  /\bOR\s+\d+\s*=\s*\d+\b/i,
+  // OR 1=1 恒真
+  /\bOR\s+'\w*'\s*=\s*'\w*'/i,
+  // OR 'a'='a' 恒真
+  /UNION\s+SELECT/i
+];
+var DEFAULT_ALLOWED_TABLES = [
+  "pipelines",
+  "nodes",
+  "users",
+  "schools",
+  "hospitals",
+  "substations",
+  "base_stations",
+  "rivers",
+  "reservoirs",
+  "alarms",
+  "pois"
+];
+var ALLOWED_SPATIAL_FUNCTIONS = [
+  "ST_DWithin",
+  "ST_Within",
+  "ST_Intersects",
+  "ST_Contains",
+  "ST_Buffer",
+  "ST_MakePoint",
+  "ST_SetSRID",
+  "ST_Distance",
+  "ST_AsGeoJSON",
+  "ST_Transform"
+];
+function validateSql(sql, allowedTables = DEFAULT_ALLOWED_TABLES) {
+  const issues = [];
+  const upper = sql.toUpperCase().trim();
+  if (!sql.trim()) {
+    issues.push({ severity: "error", rule: "non_empty", message: "SQL \u4E0D\u80FD\u4E3A\u7A7A" });
+    return { valid: false, issues };
+  }
+  if (!upper.startsWith("SELECT")) {
+    issues.push({ severity: "error", rule: "read_only", message: "\u4EC5\u5141\u8BB8 SELECT \u53EA\u8BFB\u67E5\u8BE2" });
+  }
+  for (const kw of DANGEROUS_KEYWORDS) {
+    const re = new RegExp(`\\b${kw}\\b`, "i");
+    if (re.test(sql) && !(kw === "SET" && /ST_SetSRID/i.test(sql))) {
+      issues.push({ severity: "error", rule: "dangerous_keyword", message: `\u68C0\u6D4B\u5230\u5371\u9669\u5173\u952E\u5B57 ${kw}` });
+    }
+  }
+  for (const p of INJECTION_PATTERNS) {
+    if (p.test(sql)) {
+      issues.push({ severity: "error", rule: "injection", message: "\u68C0\u6D4B\u5230 SQL \u6CE8\u5165\u7279\u5F81" });
+    }
+  }
+  const fromMatch = upper.match(/FROM\s+([A-Za-z_][\w]*)/);
+  if (fromMatch) {
+    const table = fromMatch[1].toLowerCase();
+    if (!allowedTables.includes(table)) {
+      issues.push({ severity: "error", rule: "table_whitelist", message: `\u8868 ${table} \u4E0D\u5728\u6388\u6743\u767D\u540D\u5355\u5185` });
+    }
+  }
+  const singleQuotes = (sql.match(/'/g) ?? []).length;
+  if (singleQuotes % 2 !== 0) {
+    issues.push({ severity: "error", rule: "syntax", message: "\u5355\u5F15\u53F7\u672A\u914D\u5BF9" });
+  }
+  const openParen = (sql.match(/\(/g) ?? []).length;
+  const closeParen = (sql.match(/\)/g) ?? []).length;
+  if (openParen !== closeParen) {
+    issues.push({ severity: "error", rule: "syntax", message: "\u62EC\u53F7\u672A\u914D\u5BF9" });
+  }
+  for (const fn of ["ST_"]) {
+    const fnMatch = sql.match(/ST_(\w+)/g) ?? [];
+    for (const m of fnMatch) {
+      if (!ALLOWED_SPATIAL_FUNCTIONS.includes(m)) {
+        issues.push({ severity: "error", rule: "spatial_whitelist", message: `\u7A7A\u95F4\u51FD\u6570 ${m} \u4E0D\u5728\u767D\u540D\u5355\u5185` });
+      }
+    }
+  }
+  return { valid: issues.every((i) => i.severity !== "error"), issues };
+}
+function parameterize(sql) {
+  const params = [];
+  const out = sql.replace(/'([^']*)'/g, (_m, v) => {
+    params.push(v);
+    return `$${params.length}`;
+  });
+  return { sql: out, params };
+}
+
+// src/nlpg/nlpg.ts
+function nlpgQuery(text, opts = {}) {
+  const query = generatePostGISQuery(text, opts);
+  const validation = validateSql(query.sql);
+  const valid = validation.valid;
+  const parameterized = valid ? parameterize(query.sql) : void 0;
+  return { query, valid, validation, parameterized };
+}
+
+// src/nlpg/llmNlpg.ts
+var SYSTEM_PROMPT = `\u4F60\u662F"\u8349\u679C\u5730\u56FE"\u7BA1\u7F51\u81EA\u7136\u8BED\u8A00\u67E5\u8BE2\u52A9\u624B\u3002\u7528\u6237\u7528\u4E2D\u6587\u63CF\u8FF0\u6570\u636E\u67E5\u8BE2\u9700\u6C42\uFF0C\u4F60\u751F\u6210 PostGIS SQL\uFF08\u4EC5 SELECT\uFF09\u3002
+
+\u89C4\u5219\uFF1A
+1. \u53EA\u8FD4\u56DE JSON\uFF1A{"sql":"SELECT ...","table":"...","intent":"..."}
+2. \u8868\u540D\u53EA\u80FD\u6765\u81EA\u4EE5\u4E0B\u767D\u540D\u5355\uFF1A${DEFAULT_ALLOWED_TABLES.join(", ")}
+3. \u7A7A\u95F4\u67E5\u8BE2\u53EF\u7528 ST_DWithin / ST_Within / ST_Intersects / ST_Contains / ST_Buffer / ST_MakePoint / ST_SetSRID / ST_Distance / ST_AsGeoJSON / ST_Transform
+4. \u53EA\u751F\u6210 SELECT \u8BED\u53E5\uFF0C\u7981\u6B62 DROP/DELETE/UPDATE/INSERT/ALTER \u7B49\u5199\u64CD\u4F5C
+5. \u5B57\u6BB5\u540D\u4F7F\u7528 snake_case\uFF0C\u5750\u6807\u4F7F\u7528 WGS84\uFF08SRID 4326\uFF09
+6. \u4E0D\u8981\u8F93\u51FA JSON \u4EE5\u5916\u7684\u4EFB\u4F55\u6587\u5B57\u3002`;
+var LlmNlpg = class {
+  client;
+  enabled;
+  allowedTables;
+  constructor(config) {
+    this.client = config.client;
+    this.enabled = config.enabled ?? true;
+    this.allowedTables = config.allowedTables ?? DEFAULT_ALLOWED_TABLES;
+  }
+  /**
+   * 自然语言查询。
+   * LLM 优先，失败或校验不过时降级到规则引擎。
+   */
+  async query(text) {
+    if (this.enabled) {
+      try {
+        const llmResult = await this.queryWithLlm(text);
+        if (llmResult) return llmResult;
+      } catch {
+      }
+    }
+    return this.queryWithRules(text);
+  }
+  async queryWithLlm(text) {
+    const messages = [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: text }
+    ];
+    const { data } = await this.client.chatJson(messages);
+    const sql = (data.sql ?? "").trim();
+    if (!sql) return null;
+    const validation = validateSql(sql, this.allowedTables);
+    if (!validation.valid) return null;
+    const query = {
+      intent: "mixed",
+      table: data.table ?? "pois",
+      conditions: [],
+      spatial: null,
+      sql,
+      confidence: 0.9
+    };
+    return { query, valid: true, parameterized: parameterize(sql) };
+  }
+  queryWithRules(text) {
+    const query = generatePostGISQuery(text);
+    const validation = validateSql(query.sql, this.allowedTables);
+    return {
+      query,
+      valid: validation.valid,
+      parameterized: validation.valid ? parameterize(query.sql) : void 0
+    };
+  }
+};
+
+exports.DEFAULT_ALLOWED_TABLES = DEFAULT_ALLOWED_TABLES;
+exports.LlmNlpg = LlmNlpg;
+exports.detectField = detectField;
+exports.detectSpatial = detectSpatial;
+exports.detectTable = detectTable;
+exports.detectValue = detectValue;
+exports.generatePostGISQuery = generatePostGISQuery;
+exports.nlpgQuery = nlpgQuery;
+exports.parameterize = parameterize;
+exports.validateSql = validateSql;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map