@caoguo/maplibre-ai 0.0.2 → 0.0.4

package/dist/nlpg/index.d.cts

@@ -0,0 +1,160 @@
+import { DeepSeekClient } from '../llm/index.cjs';
+
+/**
+ * NLPG 自然语言 → PostGIS SQL 生成（PRD phase-0 §5.7 N-1/N-2/N-3）
+ *
+ * 支持：
+ *   - 属性过滤（字段 + 操作符 + 值，AND/OR 组合）
+ *   - 空间关系（ST_DWithin / ST_Within / ST_Intersects / ST_Contains / ST_Buffer）
+ *   - 混合查询（空间 + 属性）
+ *
+ * v1 采用「字段词典 + 规则匹配」方案（不依赖大模型），SQL 生成后必须经
+ * `validateSql` 安全校验层通过方可执行（见 sqlValidator.ts）。
+ */
+type NlpgIntent = 'attribute_filter' | 'spatial_nearby' | 'spatial_within' | 'mixed' | 'unknown';
+type Operator = '>' | '<' | '>=' | '<=' | '=' | '!=' | 'LIKE';
+interface AttributeCondition {
+    /** 字段名（白名单字段） */
+    field: string;
+    operator: Operator;
+    /** 字面量值 */
+    value: string | number;
+}
+interface SpatialCondition {
+    /** 空间关系 */
+    relation: 'dwithin' | 'within' | 'intersects' | 'contains' | 'buffer';
+    /** 参考点 [lng, lat]（dwithin/buffer 用） */
+    point?: [number, number];
+    /** 距离（米，dwithin 用） */
+    radius?: number;
+    /** 目标几何字段 */
+    geometryColumn: string;
+}
+interface GeneratedQuery {
+    intent: NlpgIntent;
+    /** 目标表（白名单表） */
+    table: string;
+    /** 属性条件 */
+    conditions: AttributeCondition[];
+    /** 空间条件 */
+    spatial: SpatialCondition | null;
+    /** 生成的 SQL */
+    sql: string;
+    /** 置信度 0-1 */
+    confidence: number;
+}
+declare function detectTable(text: string): string;
+declare function detectField(text: string): string | null;
+declare function detectValue(text: string, field: string): string | number | null;
+declare function detectSpatial(text: string, geometryColumn?: string): SpatialCondition | null;
+interface GenerateOptions {
+    /** 参考点（空间查询用，默认武汉中心） */
+    center?: [number, number];
+    /** 目标几何字段 */
+    geometryColumn?: string;
+}
+declare function generatePostGISQuery(text: string, opts?: GenerateOptions): GeneratedQuery;
+
+/**
+ * NLPG SQL 安全校验层（PRD phase-0 §5.7 N-5 / §5.7.3）
+ *
+ * 所有 LLM/规则生成的 SQL 必须经过以下校验方可执行：
+ *   1. 语法校验（引号/括号配对、非空）
+ *   2. 白名单表检查（只允许查询授权表）
+ *   3. 危险操作拦截（DROP/DELETE/UPDATE/INSERT/ALTER/TRUNCATE/GRANT 等全部拒绝）
+ *   4. 仅允许 SELECT 只读查询
+ *   5. 参数化占位（防止 SQL 注入的字面量转义）
+ *
+ * 纯函数，可在 Node/浏览器两侧运行。
+ */
+interface ValidationIssue {
+    severity: 'error' | 'warning';
+    rule: string;
+    message: string;
+}
+interface ValidationResult {
+    /** 是否通过（无 error 级问题） */
+    valid: boolean;
+    issues: ValidationIssue[];
+}
+/** 默认白名单表（只读授权） */
+declare const DEFAULT_ALLOWED_TABLES: string[];
+/**
+ * 校验 SQL。
+ * @param sql 待校验 SQL
+ * @param allowedTables 白名单表（默认 DEFAULT_ALLOWED_TABLES）
+ */
+declare function validateSql(sql: string, allowedTables?: string[]): ValidationResult;
+/** 参数化：把 SQL 中的字符串字面量替换为 $n 占位符（防注入） */
+declare function parameterize(sql: string): {
+    sql: string;
+    params: string[];
+};
+
+/**
+ * NLPG v1 主入口（PRD phase-0 §5.7）
+ *
+ * 自然语言 → PostGIS SQL → 安全校验 → 可执行结果。
+ *
+ * 用法：
+ *   const result = nlpgQuery('查出使用超过 20 年的铸铁燃气管');
+ *   result.sql         // 生成的 SQL
+ *   result.valid       // 是否通过安全校验
+ *   result.validation  // 校验详情
+ */
+
+interface NlpgResult {
+    /** 生成的查询 */
+    query: GeneratedQuery;
+    /** 是否通过安全校验 */
+    valid: boolean;
+    /** 校验详情 */
+    validation: ValidationResult;
+    /** 参数化后的 SQL（$n 占位符） */
+    parameterized?: {
+        sql: string;
+        params: string[];
+    };
+}
+/**
+ * 自然语言查询入口。
+ */
+declare function nlpgQuery(text: string, opts?: GenerateOptions): NlpgResult;
+
+/**
+ * NLPG LLM 模式（PRD phase-0 §5.7 N-6「LLM 生成 SQL」）
+ *
+ * 在规则引擎（sqlGenerator.ts）基础上，接入 DeepSeek 实现：
+ *   - 复杂自然语言 → PostGIS SQL（突破固定字段/空间模板）
+ *   - LLM 优先，失败自动降级规则引擎
+ *   - 生成的 SQL 必经 sqlValidator 安全校验层方可执行
+ */
+
+interface LlmNlpgConfig {
+    client: DeepSeekClient;
+    enabled?: boolean;
+    /** 授权表白名单（传给校验层） */
+    allowedTables?: string[];
+}
+declare class LlmNlpg {
+    private client;
+    private enabled;
+    private allowedTables;
+    constructor(config: LlmNlpgConfig);
+    /**
+     * 自然语言查询。
+     * LLM 优先，失败或校验不过时降级到规则引擎。
+     */
+    query(text: string): Promise<{
+        query: GeneratedQuery;
+        valid: boolean;
+        parameterized?: {
+            sql: string;
+            params: string[];
+        };
+    }>;
+    private queryWithLlm;
+    private queryWithRules;
+}
+
+export { type AttributeCondition, DEFAULT_ALLOWED_TABLES, type GenerateOptions, type GeneratedQuery, LlmNlpg, type LlmNlpgConfig, type NlpgIntent, type NlpgResult, type Operator, type SpatialCondition, type ValidationIssue, type ValidationResult, detectField, detectSpatial, detectTable, detectValue, generatePostGISQuery, nlpgQuery, parameterize, validateSql };

package/dist/nlpg/index.d.ts

@@ -0,0 +1,160 @@
+import { DeepSeekClient } from '../llm/index.js';
+
+/**
+ * NLPG 自然语言 → PostGIS SQL 生成（PRD phase-0 §5.7 N-1/N-2/N-3）
+ *
+ * 支持：
+ *   - 属性过滤（字段 + 操作符 + 值，AND/OR 组合）
+ *   - 空间关系（ST_DWithin / ST_Within / ST_Intersects / ST_Contains / ST_Buffer）
+ *   - 混合查询（空间 + 属性）
+ *
+ * v1 采用「字段词典 + 规则匹配」方案（不依赖大模型），SQL 生成后必须经
+ * `validateSql` 安全校验层通过方可执行（见 sqlValidator.ts）。
+ */
+type NlpgIntent = 'attribute_filter' | 'spatial_nearby' | 'spatial_within' | 'mixed' | 'unknown';
+type Operator = '>' | '<' | '>=' | '<=' | '=' | '!=' | 'LIKE';
+interface AttributeCondition {
+    /** 字段名（白名单字段） */
+    field: string;
+    operator: Operator;
+    /** 字面量值 */
+    value: string | number;
+}
+interface SpatialCondition {
+    /** 空间关系 */
+    relation: 'dwithin' | 'within' | 'intersects' | 'contains' | 'buffer';
+    /** 参考点 [lng, lat]（dwithin/buffer 用） */
+    point?: [number, number];
+    /** 距离（米，dwithin 用） */
+    radius?: number;
+    /** 目标几何字段 */
+    geometryColumn: string;
+}
+interface GeneratedQuery {
+    intent: NlpgIntent;
+    /** 目标表（白名单表） */
+    table: string;
+    /** 属性条件 */
+    conditions: AttributeCondition[];
+    /** 空间条件 */
+    spatial: SpatialCondition | null;
+    /** 生成的 SQL */
+    sql: string;
+    /** 置信度 0-1 */
+    confidence: number;
+}
+declare function detectTable(text: string): string;
+declare function detectField(text: string): string | null;
+declare function detectValue(text: string, field: string): string | number | null;
+declare function detectSpatial(text: string, geometryColumn?: string): SpatialCondition | null;
+interface GenerateOptions {
+    /** 参考点（空间查询用，默认武汉中心） */
+    center?: [number, number];
+    /** 目标几何字段 */
+    geometryColumn?: string;
+}
+declare function generatePostGISQuery(text: string, opts?: GenerateOptions): GeneratedQuery;
+
+/**
+ * NLPG SQL 安全校验层（PRD phase-0 §5.7 N-5 / §5.7.3）
+ *
+ * 所有 LLM/规则生成的 SQL 必须经过以下校验方可执行：
+ *   1. 语法校验（引号/括号配对、非空）
+ *   2. 白名单表检查（只允许查询授权表）
+ *   3. 危险操作拦截（DROP/DELETE/UPDATE/INSERT/ALTER/TRUNCATE/GRANT 等全部拒绝）
+ *   4. 仅允许 SELECT 只读查询
+ *   5. 参数化占位（防止 SQL 注入的字面量转义）
+ *
+ * 纯函数，可在 Node/浏览器两侧运行。
+ */
+interface ValidationIssue {
+    severity: 'error' | 'warning';
+    rule: string;
+    message: string;
+}
+interface ValidationResult {
+    /** 是否通过（无 error 级问题） */
+    valid: boolean;
+    issues: ValidationIssue[];
+}
+/** 默认白名单表（只读授权） */
+declare const DEFAULT_ALLOWED_TABLES: string[];
+/**
+ * 校验 SQL。
+ * @param sql 待校验 SQL
+ * @param allowedTables 白名单表（默认 DEFAULT_ALLOWED_TABLES）
+ */
+declare function validateSql(sql: string, allowedTables?: string[]): ValidationResult;
+/** 参数化：把 SQL 中的字符串字面量替换为 $n 占位符（防注入） */
+declare function parameterize(sql: string): {
+    sql: string;
+    params: string[];
+};
+
+/**
+ * NLPG v1 主入口（PRD phase-0 §5.7）
+ *
+ * 自然语言 → PostGIS SQL → 安全校验 → 可执行结果。
+ *
+ * 用法：
+ *   const result = nlpgQuery('查出使用超过 20 年的铸铁燃气管');
+ *   result.sql         // 生成的 SQL
+ *   result.valid       // 是否通过安全校验
+ *   result.validation  // 校验详情
+ */
+
+interface NlpgResult {
+    /** 生成的查询 */
+    query: GeneratedQuery;
+    /** 是否通过安全校验 */
+    valid: boolean;
+    /** 校验详情 */
+    validation: ValidationResult;
+    /** 参数化后的 SQL（$n 占位符） */
+    parameterized?: {
+        sql: string;
+        params: string[];
+    };
+}
+/**
+ * 自然语言查询入口。
+ */
+declare function nlpgQuery(text: string, opts?: GenerateOptions): NlpgResult;
+
+/**
+ * NLPG LLM 模式（PRD phase-0 §5.7 N-6「LLM 生成 SQL」）
+ *
+ * 在规则引擎（sqlGenerator.ts）基础上，接入 DeepSeek 实现：
+ *   - 复杂自然语言 → PostGIS SQL（突破固定字段/空间模板）
+ *   - LLM 优先，失败自动降级规则引擎
+ *   - 生成的 SQL 必经 sqlValidator 安全校验层方可执行
+ */
+
+interface LlmNlpgConfig {
+    client: DeepSeekClient;
+    enabled?: boolean;
+    /** 授权表白名单（传给校验层） */
+    allowedTables?: string[];
+}
+declare class LlmNlpg {
+    private client;
+    private enabled;
+    private allowedTables;
+    constructor(config: LlmNlpgConfig);
+    /**
+     * 自然语言查询。
+     * LLM 优先，失败或校验不过时降级到规则引擎。
+     */
+    query(text: string): Promise<{
+        query: GeneratedQuery;
+        valid: boolean;
+        parameterized?: {
+            sql: string;
+            params: string[];
+        };
+    }>;
+    private queryWithLlm;
+    private queryWithRules;
+}
+
+export { type AttributeCondition, DEFAULT_ALLOWED_TABLES, type GenerateOptions, type GeneratedQuery, LlmNlpg, type LlmNlpgConfig, type NlpgIntent, type NlpgResult, type Operator, type SpatialCondition, type ValidationIssue, type ValidationResult, detectField, detectSpatial, detectTable, detectValue, generatePostGISQuery, nlpgQuery, parameterize, validateSql };

package/dist/nlpg/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_ALLOWED_TABLES, LlmNlpg, detectField, detectSpatial, detectTable, detectValue, generatePostGISQuery, nlpgQuery, parameterize, validateSql } from '../chunk-ARYB2X4B.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/nlpg/index.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@caoguo/maplibre-ai",
-  "version": "0.0.2",
-  "description": "草果地图 AI 工具链 - 性能诊断 / 样式生成器 v2",
+  "version": "0.0.4",
+  "description": "草果地图 AI 工具链 - MapCopilot 代码生成 / GeoAI 数据入图 / NLPG 自然语言查询 / DeepSeek LLM 接入 / 性能诊断 / 样式生成器 v2",
   "license": "Apache-2.0",
   "author": "caoguo <caoguo@hb.cn>",
   "homepage": "https://github.com/caoguo/map/blob/main/packages/ai/README.md",
@@ -18,12 +18,24 @@
     "caoguo",
     "gis",
     "ai",
+    "copilot",
+    "code-generation",
+    "geoai",
+    "geocoding",
+    "address-parsing",
+    "crs-conversion",
+    "nlpg",
+    "natural-language",
+    "postgis",
+    "sql-generator",
+    "sql-validator",
     "performance-profiler",
     "tile-monitor",
     "memory-leak",
     "style-generator",
     "palette-extraction",
-    "industry-template"
+    "industry-template",
+    "china"
   ],
   "type": "module",
   "main": "./dist/index.cjs",
@@ -44,13 +56,33 @@
       "types": "./dist/stylegen/index.d.ts",
       "import": "./dist/stylegen/index.js",
       "require": "./dist/stylegen/index.cjs"
+    },
+    "./copilot": {
+      "types": "./dist/copilot/index.d.ts",
+      "import": "./dist/copilot/index.js",
+      "require": "./dist/copilot/index.cjs"
+    },
+    "./geoai": {
+      "types": "./dist/geoai/index.d.ts",
+      "import": "./dist/geoai/index.js",
+      "require": "./dist/geoai/index.cjs"
+    },
+    "./nlpg": {
+      "types": "./dist/nlpg/index.d.ts",
+      "import": "./dist/nlpg/index.js",
+      "require": "./dist/nlpg/index.cjs"
+    },
+    "./llm": {
+      "types": "./dist/llm/index.d.ts",
+      "import": "./dist/llm/index.js",
+      "require": "./dist/llm/index.cjs"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@caoguo/theme": "0.0.2"
+    "@caoguo/theme": "0.0.4"
   },
   "publishConfig": {
     "access": "public",