内容
# 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` |
## 快速开始
### 安装
```bash
# 克隆
git clone https://github.com/kevics1/geo-perception.git
cd geo-perception
# 安装依赖（推荐 uv）
uv pip install -e .
# 或 pip
pip install -e .
```
### 启动 MCP Server
```bash
# 直接启动
python run.py
# 或通过 MCP CLI
mcp run src.server:mcp
```
### 在 Hermes / Claude Code / 其他 Agent 中配置
```json
{
"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 目录中：
```bash
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](https://github.com/modelcontextprotocol/python-sdk)
- **空间计算**: 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
```
## 测试
```bash
python -m pytest tests/ -v
```
## License
MIT
## 致谢
- [PySAL](https://pysal.org/) — 空间统计生态
- [Shapely](https://shapely.readthedocs.io/) — 几何计算
- [FastMCP](https://github.com/modelcontextprotocol/python-sdk) — MCP 协议实现
