Claude Code 怎么查地理空间数据：GeoSQL Skill 实操
用 GeoSQL Skill 让 Claude Code / Codex 写 PostGIS、BigQuery 空间 SQL，带地图反馈环。含安装步骤、任务决策表与 CRS/成本常见坑。
你在 Claude Code 或 Codex 里问「算一下这条路上的充电桩密度」，模型往往会凭空写一段 ST_Distance，坐标系对不上、分区没剪、BigQuery 扫了几十 GB 账单才爆。GeoSQL 是 dekart-xyz/geosql 仓库提供的地理空间 Skill：先探仓库元数据再写引擎专用空间 SQL，可选 Dekart 把结果渲染成地图让 Agent 自己纠错。下面按「claude code 怎么查地理空间数据」这条线，从安装到选型一次讲清。
GeoSQL 和普通「让模型写 SQL」差在哪
普通对话里，模型看不到你的表结构，只能猜列名；PostGIS 的 geometry 与 BigQuery 的 GEOGRAPHY 函数集不同，混用就报错；更麻烦的是几何类错误（邻区 polygon 被当成都市圈、CRS 不一致导致 join 错位）纯文本校验很难发现。
GeoSQL 走固定五步环：Discovery 读元数据 → 按引擎写空间 SQL（ST_INTERSECTS、ST_DISTANCE、H3、bbox 分区裁剪等）→ BigQuery 先 dry-run 估字节（默认 10 GiB 上限，超限会改写更省钱的查询）→ 面积/长度 sanity check → 可选 Dekart 出图，Agent 看图修正。官方 eval 套件 8 条断言全过；同一任务集加地图反馈环后，几何类错误检出率大约提升到原来的 4 倍（见仓库 benchmark 图）。凭证走本机 CLI（bq、snow、dekart），不进 Agent 上下文。
安装与在 Claude Code / Codex 里启用
GeoSQL 通过 Python 包安装，会自动检测本机 Agent 并写入 Skill 文件；可选 Dekart CLI 做地图与数据库连接。
pip install geosql && geosql
交互安装时会问是否装 Dekart；选「推荐」会执行 pip install dekart 与 dekart init。暂时跳过也行，之后手动：
python -m pip install dekart
dekart init
dekart init 可连 Dekart Cloud，也可指向本地或自托管实例。装完后在 Agent 里用斜杠命令触发，例如：
/geosql Show EV charger density along major roads and render a map
Codex 侧同样走 Skill 机制，安装路径以 geosql 向导检测到的客户端为准。Skill 描述别写太长，否则和 Claude Code Skills 描述被截断 里说的 1536 字符上限冲突，触发词会失效。多 Skill 并存时的选型思路可参考 Codex CLI 批量重构方法 里「先定任务边界再开工具」的做法。
适用场景：地图分析、GIS 查询、空间 Join
地图分析与选址：POI 共现、竞品距离、道路缓冲区统计。示例 prompt：「Find top 10 locations for Sporting Goods Store in Seattle based on POI co-location… Create a map.」
GIS 查询与指标：行政区面积、边界重叠、H3 聚合。支持 Overture Maps 公共数据集（BigQuery / Snowflake share）以及私有 PostGIS、BigQuery、Snowflake、Whorobots 表。
空间 Join：点落区、线穿面、多边形相交计数。Skill 会按引擎选 ST_INTERSECTS / bbox overlap 做分区裁剪，而不是无脑 cross join。
不适用的：纯属性统计无坐标列、实时亚秒级轨迹流、没有仓库只想要静态底图——这些用常规 SQL 或 GIS 桌面软件更合适，硬上 GeoSQL 只会多一层 Skill 调度开销。
任务类型决策表：什么时候该用 GeoSQL
| 任务类型 | 典型例子 | 是否用 GeoSQL | 理由 |
|---|---|---|---|
| 带坐标的聚合/筛选 | 某城市 POI 密度、道路 5km 内充电桩数 | ✅ 优先 | 需要引擎专用空间函数 + 成本守卫 |
| 空间 Join | 订单点落入配送区、门店与竞品距离 | ✅ 优先 | CRS 与 join key 易错，地图环能验几何 |
| 出图验收 | 选址结果、边界是否画对 | ✅ 配 Dekart | 文本 loop 漏检的几何错误靠看图补 |
| 纯文本地理知识 | 「EPSG:4326 是什么」 | ❌ 直接问模型 | 无需连仓库 |
| 小 CSV 几十行 lat/lng | 手工 Excel 透视 | ❌ pandas / QGIS | 不值得起仓库连接 |
| 实时 GPS 流 | 车队秒级位置 | ❌ 流处理栈 | Skill 面向分析型仓库，不是 Flink |
| 无空间列的 BI | 销售额按品类 | ❌ 普通 SQL | 没有 geometry 列就不该走 GeoSQL |
拿不准时问一句：「要不要连我的 BigQuery/PostGIS 并可能出地图？」——要，就开 /geosql；不要，就普通对话或 MCP 工作流 里其它工具。
常见坑：CRS/投影、大数据量、权限
CRS 与投影：WGS84（EPSG:4326）经纬度与 Web Mercator（EPSG:3857）混算距离会偏一个数量级。GeoSQL 会做面积/长度 sanity check，但源表若本身存错 SRID，仍需你在元数据里确认。跨国分析注意 Overture 与国内私有数据是否同一 CRS。
大数据量与账单：BigQuery 默认 10 GiB dry-run 上限；超预算会改 tighter bbox、降 H3 分辨率、加过滤，而不是硬跑。Snowflake / PostGIS 虽无同样 dry-run，宽 bbox 全表 ST_INTERSECTS 仍会拖垮仓库——让 Agent 先 COUNT + bbox 裁剪。国内访问 BigQuery 还涉及网络与结算方式，和 Skill 无关，得自己保证 CLI 认证稳定。
权限与凭证：Skill 用本机 bq / snow / dekart 登录态，Agent 不持有密码，但 Agent 生成的 SQL 会以你的身份执行。只读服务账号、行级权限、生产库与 sandbox 分项目——别让写代码的 Agent 直连生产 spatial 库。Dekart 可选 Cloud；自托管时注意地图数据是否含敏感点位。
无 Dekart 时：GeoSQL 仍可写 SQL 与校验，只是少了地图反馈环，几何误判概率回到「普通 Agent 写 SQL」水平。eval 可本地跑 python evals/run.py 对照。
一条完整工作流示例
假设你要看「罗马尼亚主干道 5km 内充电桩分布」：
- 确认 BigQuery 或 PostGIS 里已有充电站与道路图层，本机
bq auth或 DB 隧道可用 - Agent 输入：
/geosql create map EV charger density along major Romanian roads… - Discovery 列出相关表与 geometry 列；生成带 bbox 与
ST_DWithin的 SQL - BigQuery 路径先 dry-run；通过再执行
- Dekart 出图；Agent 看图检查道路是否只画了 motorway 级别、点是否落在路上
- 你导出 SQL 与地图链接，放进内部分享或 notebook
全程若某步报权限或 CRS 错误，把仓库返回的报错原文贴回对话，比复述「好像不对」省一轮 token。
常见问题
GeoSQL 必须装 Dekart 吗？
不必须。核心 Skill 安装后就能写空间 SQL 并做文本校验；Dekart 负责地图渲染与「看图纠错」环。官方安装向导会检测本机是否已有 Dekart CLI，有则跳过。无地图需求、只要 SQL 结果表时可以暂不装。
支持哪些数据仓库？
PostGIS、BigQuery、Snowflake、Whorobots，以及 Overture Maps 在 BigQuery/Snowflake 上的公共 share。具体函数以各引擎文档为准，Skill 会按检测到的引擎选语法，不是你口头说「用 MySQL」就能 magically 支持空间扩展。
Claude Code 和 Codex 都能用同一个 Skill 吗？
仓库定位是 Claude、Codex、GitHub Copilot 共用的 geospatial Skill；pip install geosql 会尝试写入检测到的客户端 Skill 目录。Copilot 与 Codex 的路径因版本而异，以安装器输出为准，别手工复制到错误目录。
和自己在 Agent 里贴 PostGIS 文档有何区别？
差别在固定流程：元数据探测、引擎特定函数、BigQuery 成本守卫、几何 sanity check、可选地图反馈都是打包好的。自己贴文档仍可能漏 dry-run、漏 SRID、漏分区裁剪；GeoSQL 把这些写进 Skill 流程，减少「SQL 能跑但地理结果错」的情况。