geoai-orchestrator

GeoAI Orchestrator

18 个地理空间技能模块的中心枢纽。用于路由或组合流水线，而不是作为每项空间任务都必须经过的包装层。它的职责是：（1）诊断用户实际遇到的空间问题类型，（2）设计跨阶段的流水线，（3）将每个阶段路由给合适的专业技能，以及（4）强制执行所有阶段都必须遵守的模块级不变量。

路由门槛 — 输出任何内容前请先阅读

此 Orchestrator 通过调用进行路由，绝不只是提及名称。以下门槛优先于本文档的所有其他部分，包括流水线模板。

1. 调用，不要罗列。 你选择的每项专业技能都必须在选择它的同一响应中通过 Skill 工具调用。在表格、计划或文字中提及技能不算交接。即使诊断再准确，如果响应识别出了正确的专业技能却未调用它，也表示此技能未能完成其核心功能。
2. 路由每一项修正，而非只路由第一项。 当请求包含多个发现、缺陷或阶段时，每一项都必须单独做出路由决定并单独调用。路由一项，却在行内处理其余项，属于部分失败；路由项数必须与发现项数相同。
3. 绝不要以是否获得许可作为路由条件。 不要写“说一声我就帮你路由过去”“如果你愿意，我可以转交”“告诉我，我就请专业人员来处理”或任何类似表达。提出稍后再路由是此技能最常见的失败。如果你已确定专业技能，现在就调用它。
4. 澄清不能代替路由。 缺少关于范围的细节（要交付什么、研究区域在哪里）并不妨碍你路由已经识别出的阶段。在同一响应中提出范围问题并进行路由。只有整个请求的领域都无法确定时，才可以不进行路由；此时必须说明每种候选答案对应可调用的专业技能。
5. 审计请求属于 deliver 请求。 “审计这个计划”“审查这个流水线”“这个工作流有什么问题”都要求在一个响应中给出完整审计、路由相关修正，并提供修订后的计划。不要只返回发现，却把修正留到后续轮次。

如果你无法满足此门槛，请勿启用此技能 — 直接将请求路由给范围最窄的单一专业技能。

模块地图 — 按问题类型路由

阶段 / 问题	专家技能
数据获取、格式、CRS、切片、管道	geo-data-engineering
卫星 / 航空影像、光谱指数、分类	remote-sensing-analysis
行星尺度档案、GEE Python API、云合成	google-earth-engine
EO 数据上的 CNN/U-Net/ViT、分割、检测	geo-deep-learning
自相关、热点、聚类、空间回归	spatial-statistics
选址、适宜性、AHP / 加权叠加	mcda-suitability-analysis
基于点样本的插值、克里金法、变异函数	geostatistics-interpolation
DEM、坡度、流域、流量、视域分析	terrain-hydrology
LiDAR / 点云、DTM/DSM/CHM、PDAL	point-cloud-lidar
路径规划、服务区、可达性、OD 矩阵	network-accessibility-analysis
GPS 轨迹、移动轨迹、停留 / 行程、地图匹配	movement-trajectory
多时相比较、土地覆盖变化、趋势	change-detection
地图设计、分级设色图、网络地图、出版用图	cartography-geoviz
空间 SQL、PostGIS、大规模空间连接	postgis-spatial-sql
本地 ArcGIS Pro、ArcPy、.aprx 或 .gdb 执行	arcgis-pro-automation

此表用于选择专家技能；不会自动将任务交接给它们。每个选中的条目都必须在路由关卡下调用。对于跨领域的方法标准（数据泄漏、指标、可复现性），在规则适用时调用 ml-experiment-standards 和 swe-devops-standards。

管道设计协议

对于任何多阶段请求，都必须先生成简短的管道计划，再编写代码；随后在同一回复中调用计划中列出的专家技能：

## Pipeline: <goal>
1. <stage> → <skill> → output: <artifact> → check: <verification criterion>
2. ...
Success criterion: <what the user can inspect to accept the result>

该计划是路由清单，而不是等待批准的提案。发布计划后就此停下，正是这项技能旨在避免的失败模式。路由前不要等待确认；仅在确定范围（交付内容、范围区域、决策事项）时才征求确认，并且必须在路由各阶段的同时提出，不能以确认代替路由。

每个阶段都必须有一项验证标准。空间处理中的错误往往悄无声息（CRS 错误、连接结果为空、坐标轴颠倒，都会产生看似合理的垃圾结果），因此没有检查的阶段不算一个阶段。

全模块通用不变量（每个阶段都必须遵守）

1. 始终明确指定 CRS。 首次接触时报告每个输入的 CRS。绝不在地理坐标系（度）下计算面积 / 距离 / 缓冲区——应重投影到适当的投影坐标系（默认使用本地 UTM 分区，通过 gdf.estimate_utm_crs() 确定；全球面积统计可使用 EPSG:6933 等等面积坐标系）。如果 CRS 未定义，则停止并解决问题；绝不默默猜测。
2. 严守坐标轴顺序。 GeoJSON 使用经度 / 纬度；许多 API 和用户则采用纬度 / 经度。开展大规模管道处理前，先用已知地标验证。
3. 分析前确保几何有效。 检查 is_valid；使用 shapely.make_valid 修复（不要使用 buffer(0)，它可能悄无声息地丢弃部分几何）。
4. 记录行数变化。 每次连接 / 叠加 / 筛选后，都报告输入行数和输出行数。悄无声息的重复或丢失是最常见的地理空间错误。
5. 注意空间自相关。 对空间数据进行随机训练 / 测试集划分会造成数据泄漏。任何 ML 阶段都必须遵循 ml-experiment-standards → references/spatial-cv-protocol.md 中的规范流程。
6. 在列名中标明单位。 使用 area_ha、dist_km、elev_m——绝不要只写 area。单位混淆即使经过代码审查也可能漏掉；列名不会说谎。
7. 结合视觉与数值验证。 每个空间输出都要同时提供汇总表和快速地图检查（.explore()、PNG 或 GIS 软件）。混淆矩阵无法显示空间聚集的错误。
8. 确保可复现性。 固定软件包版本、随机种子并记录参数。中间产物应使用 GeoPackage 或 GeoParquet 保存，绝不要使用 shapefile（列名会被截断至 10 个字符、大小限制为 2 GB，且不支持规范的编码）。

国际化说明

非 ASCII 地区设置中的属性表会导致简单的字符串处理出错。 典型示例：土耳其语带点和不带点的 I——在 Python 中，'İ'.lower() 会生成一个 包含 2 个字符的字符串。在对属性进行任何字符串匹配之前， 先应用区域设置感知的规范化步骤，并显示清理后分类字段的 value_counts()。 优先使用 UTF-8 格式；旧版 shapefile 可能会悄悄带有 cp1252/cp125x 乱码。

选择技术栈

默认使用开放的 Python 技术栈：GeoPandas + Shapely 2 + Rasterio + xarray/rioxarray + PyProj。当数据量超过舒适的内存处理范围（约数百万个要素）， 或需要并发／重复查询时，转而使用 PostGIS；当数据是全球档案而非本地文件时， 转而使用 Earth Engine。批量格式转换使用 GDAL CLI。如果用户使用 ArcGIS Pro 或 QGIS，则生成可无界面运行的脚本（arcpy / PyQGIS），而不是点击操作说明，并确保分析 逻辑可移植。

及早发现的反模式

• 使用度数进行缓冲（“0.01 度缓冲区”）——先重投影。
• 使用 EPSG:4326 → Web Mercator 计算面积统计——Mercator 会严重扭曲远离赤道地区的面积。
• 未对齐坐标参考系（CRS）就连接不同 CRS 的数据集。
• 将 DEM 的 nodata 值（-9999、3.4e38）当作真实高程。
• 未检查云／阴影掩膜就对影像进行分类。
• 未使用空间独立的测试集就报告模型准确率。

执行约定

• **工作流：**明确目标和交付物；分解多阶段问题；使用 Skill 工具调用最精简匹配的技能来处理各阶段；说明交接事项和不变量；整合并验证最终产物。
• **决策规则：**仅在任务含糊或跨领域时调用此协调器；范围明确的单一任务直接交给相应的专业技能。
• **验证协议：**要求进行阶段级验收检查、数量和 CRS 交接断言、端到端溯源，并根据原始问题审查最终产物。返回前，确认响应中提到的每项专业技能都已实际调用，且路由的修正数量与发现的问题数量一致。
• **失败模式：**当责任归属、单位、CRS、时间对齐、证据标准或阶段接口仍不明确时暂停；绝不隐瞒尚未解决的专业技能失败。绝不能以提出路由建议代替实际调用，也不能将已路由的修正推迟到后续轮次。
• **交付物：**流水线计划、技能路由表、阶段输入和输出、验证关卡、风险登记表以及最终集成检查清单。
• **源的新鲜度：**在确定接口之前，查阅权威来源注册表以及所选专业技能的注册表。