Geo-Perception

三层地理空间认知系统：感知(L1) → 理解(L2) → 推理(L3) 为 LLM Agent 提供空间感知、模式识别与因果推理能力

架构

┌─────────────────────────────────────────────┐
│  L3 空间推理 (Spatial Reasoning)             │
│  聚类识别 · OD流向 · 因果前提检验 · 空间叙事   │
├─────────────────────────────────────────────┤
│  L2 空间理解 (Spatial Comprehension)         │
│  空间权重 · Moran/LISA/Gi* · 语义标注         │
├─────────────────────────────────────────────┤
│  L1 空间感知 (Spatial Perception)             │
│  坐标变换 · 距离 · 缓冲区 · 拓扑 · 地理编码    │
└─────────────────────────────────────────────┘

双路径设计：Skill 定义认知流程（知识注入），MCP Server 提供计算能力（工具调用）。

MCP 工具（18个）

层级	工具	功能
L1 感知	geo_transform_crs	坐标系转换
	geo_calculate_distance	距离与方位角
	geo_buffer	缓冲区生成
	geo_bbox	边界框计算
	geo_spatial_relation	单拓扑关系判断
	geo_all_relations	全拓扑关系（DE-9IM）
	geo_scale_analysis	尺度推断与MAUP风险评估
	geo_geocode	地址→坐标（高德API）
	geo_reverse_geocode	坐标→地址（高德API）
	geo_bbox_from_places	多地名联合边界框
L2 理解	geo_spatial_weights	空间权重矩阵（Queen/Rook/KNN）
	geo_moran_global	全局 Moran's I
	geo_moran_local	局部 LISA（HH/LL/HL/LH）
	geo_getis_ord	Getis-Ord Gi* 热点分析
	geo_semantic_label	拓扑→语义标注映射
L3 推理	geo_cluster_detect	双模式聚类（点DBSCAN/面空间约束）
	geo_od_flow	OD流量聚合与主导流向
	geo_causal_check	因果前提检验（空间自相关+样本量+共同支撑）

Skills（认知流程）

Skill	决策链	内容
geo-perception	5步	坐标→距离→几何→拓扑→尺度
geo-comprehension	6步	权重→全局模式→局部模式→异质性→语义
geo-reasoning	6步	聚类→流向→因果检验→因果分析→叙事
air-pollution（插件）	—	AQI指标/监测网络/暴露/模式

离线代码模板

慢计算（>2s）不放入MCP，提供离线指南：

模板	位置
GWR 地理加权回归	skills/geo-comprehension/references/gwr-offline-guide.md
空间DID	skills/geo-reasoning/references/spatial-did-guide.md
空间断点设计(RDD)	skills/geo-reasoning/references/spatial-rdd-guide.md
空间工具变量(IV)	skills/geo-reasoning/references/spatial-iv-guide.md

快速开始

安装

# 克隆
git clone https://github.com/kevics1/geo-perception.git
cd geo-perception

# 安装依赖（推荐 uv）
uv pip install -e .
# 或 pip
pip install -e .

启动 MCP Server

# 直接启动
python run.py

# 或通过 MCP CLI
mcp run src.server:mcp

在 Hermes / Claude Code / 其他 Agent 中配置

{
  "geo-perception": {
    "command": "python",
    "args": ["path/to/geo-perception/run.py"],
    "env": {
      "PROJ_LIB": "path/to/proj/data",
      "AMAP_API_KEY": "your-amap-key"
    }
  }
}

加载 Skills

将 skills/ 目录下的三个 Skill 复制到你的 Agent 的 skills 目录中：

cp -r skills/geo-perception ~/.hermes/skills/geoai/
cp -r skills/geo-comprehension ~/.hermes/skills/geoai/
cp -r skills/geo-reasoning ~/.hermes/skills/geoai/

设计原则

原则	说明
MCP 响应 <2s	慢计算走离线模板，MCP 只做快速响应
知识+工具双路径	Skill 注入认知流程，MCP 提供计算能力
几何优先	L2/L3 工具传 geometries 而非序列化权重 JSON
降级优雅	工具不可用时返回 fallback + 说明
点面双模式	聚类等工具按几何类型自动选算法

技术栈

• MCP Server: FastMCP
• 空间计算: Shapely, pyproj, GeoPandas, PySAL (libpysal + esda)
• 聚类: scikit-learn (DBSCAN, AgglomerativeClustering)
• 地理编码: 高德 (Amap) API
• Python: 3.10+

项目结构

geo-perception/
├── src/                          # MCP Server 代码
│   ├── server.py                 # 18个MCP工具定义
│   └── core/
│       └── spatial_engine.py     # 计算引擎
├── skills/                       # 认知流程（知识层）
│   ├── geo-perception/           # L1: 5步感知链 + 6 refs + 1 template + air-pollution插件
│   ├── geo-comprehension/        # L2: 6步理解链 + 8 refs
│   └── geo-reasoning/            # L3: 6步推理链 + 5 refs + 1 template
├── tests/                        # 测试
├── pyproject.toml
├── run.py                        # 启动脚本
└── README.md

测试

python -m pytest tests/ -v

License

MIT

致谢

• PySAL — 空间统计生态
• Shapely — 几何计算
• FastMCP — MCP 协议实现