Geosql: A Claude/Codex skill for geospatial data
AI 深度解读
背景
随着大语言模型（LLM）在代码生成领域的普及，数据分析师和科学家开始尝试用自然语言与数据库交互。然而，地理空间数据（Geospatial Data）具有特殊的复杂性：空间 SQL 函数（如 ST_INTERSECTS、ST_DISTANCE）、坐标系转换、几何验证等环节容易出错，仅靠文本循环很难发现。现有 AI 助手（如 Claude、Codex、GitHub Copilot）在处理地理空间任务时，常因缺乏对空间几何的直观理解而生成错误结果。Geosql 正是在这一背景下诞生的——它将地图渲染纳入 Agent 的反馈循环，让 AI 能“看见”自己的输出并自我修正，从而显著提升地理空间数据分析的准确性和效率。
核心内容
Geosql 是一个面向数据科学家和分析师的开源技能（Skill），专为处理 PostGIS、BigQuery、Snowflake 和 Wherobots 上的地理空间数据而设计。它无需任何 SaaS 账户，完全在本地或自托管环境中运行。通过将地图渲染纳入 Agent 的循环，Geosql 在地理空间任务上实现了 4 倍的性能提升。
安装与使用
安装方式简单，通过 pip 安装后即可交互式运行：
pip install geosql && geosql
然后可以直接将技能安装到支持的 AI Agent 中：
geosql install claude
geosql install codex
geosql install copilot
在 Claude Code 中，还可以通过插件市场安装：
/plugin marketplace add dekart-xyz/geosql
/plugin install geosql
安装完成后，用户可以在 VS Code Copilot 或 Copilot CLI 中使用自然语言提示词，例如：
/geosql Show EV charger density along major roads and render a map
底层可视化引擎：Dekart
Geosql 可选地使用 Dekart 作为后端渲染引擎。Dekart 是一个开源工具，基于 Kepler.gl 构建，支持 PostGIS、BigQuery、Snowflake 等数据源。用户可以用一条 Docker 命令在本地运行：
docker run -p 8080:8080 dekartxyz/dekart
随后安装 Dekart CLI 并初始化连接：
pip install dekart && dekart init
典型应用场景
- 房地产分析：
/geosql Show buildings with low school accessibility in Ottawa, render as a map - 选址分析：
/geosql Find the top 10 locations for Sporting Goods Store in Seattle based on POI co-location and distance to the nearest competitor. Create a map. - 充电基础设施：
/geosql create map EV charger density along major Romanian roads, highlighting how many charging stations are within 5 km of each motorway, trunk, or primary road segment.
核心工作流程：带地图的 Agent 循环
Geosql 的核心是一个包含四个步骤的 Agent 循环：
-
发现（Discovery）：Agent 自动探索数据仓库的元数据（表名、列名、数据类型），而不是猜测表结构。它支持 Overture Maps 在 BigQuery 和 Snowflake 上的共享数据集，以及用户私有的 PostGIS、BigQuery、Snowflake、Wherobots 表。
-
SQL 生成：Agent 根据目标引擎编写正确的空间 SQL，使用正确的函数（如
ST_INTERSECTS、ST_DISTANCE、H3 索引、bbox 重叠用于分区裁剪等）。 -
成本检查（Cost Check）：在 BigQuery 上，每次查询都会先进行干运行（dry-run）来估算扫描字节数，默认强制 10 GiB 的计费上限。超出预算的查询会被自动重写为更廉价的版本（收紧 bbox、降低 H3 分辨率、增加过滤条件），而不是直接执行。
-
几何验证与地图反馈：Agent 会计算总面积（多边形）或总长度（线）作为合理性检查，并与领域知识交叉验证。当可用时，Agent 通过 Dekart 渲染结果，查看渲染后的图像，并纠正仅靠文本循环无法发现的几何错误。正是这个“地图反馈循环”带来了 4 倍的提升。
安全与认证
Geosql 使用用户本地的 CLI 认证（bq、snow、dekart），因此数据仓库的凭据永远不会发送给 Agent，保证了安全性。
可复现的评估套件
Geosql 附带了一个可复现的评估套件，位于 evals/ 目录下。每个测试用例不仅验证“Agent 是否回答了”，还验证具体行为：成本护栏、验证步骤、结果正确性。当前评估套件的平均结果为：每日轮 3,085 tokens，每轮耗时 72 秒。
4 倍提升的对比图表明，如果没有地图循环，Agent 的纯文本验证会遗漏几何类错误（例如将社区多边形误认为都会区边界、重复计算重叠要素、在坐标系上选择错误的连接键）。加入渲染地图作为工具调用后，Agent 能够看到这些错误并自我修正。
用户可以通过以下命令运行评估套件：
python evals/run.py
详细设置和添加新用例的方法见 evals/RUNBOOK.md，欢迎提交包含新评估用例的 PR。
关键要点
- 专为地理空间数据优化：Geosql 针对 PostGIS、BigQuery、Snowflake、Wherobots 等主流地理空间引擎，提供空间 SQL 生成、元数据探索和几何验证能力。
- 地图循环带来 4 倍提升：通过将 Dekart 渲染的地图作为 Agent 的视觉反馈，GeoSQL 能够发现并纠正纯文本循环无法察觉的几何错误（如范围误判、重叠计数错误、坐标系误用）。
- 完全本地/自托管：无需注册任何 SaaS 账户，凭证不出本地，满足数据安全要求。
- 成本控制机制：在 BigQuery 上自动干运行估算扫描量，默认 10 GiB 计费上限，超预算查询自动重写为更经济的版本。
- 灵活的安装方式：支持在 Claude、Codex、Copilot 中直接安装，也支持在 Claude Code 中通过插件市场安装。
- 可复现的评估套件：附带正式的测试用例，验证成本护栏、验证步骤和结果正确性，而非仅检查“是否回答”。
- 开源社区友好：项目鼓励用户提交新的评估用例，帮助持续改进性能。
意义与影响
Geosql 的出现标志着 LLM 辅助地理空间数据分析进入了一个新阶段。传统上，AI 代码助手在处理空间查询时，由于