open-map-stack

OpenMapStack 工具包

生产级地理空间工作流采用开源优先的技术栈；当全球规模、延迟、SLA 或数据质量使本地处理不再合适时，也务实地选择托管服务或 SaaS。默认采用云原生方案：使用 STAC 进行发现，使用 GeoParquet + COG + PMTiles 进行存储，使用 DuckDB 和 PostGIS 进行计算，使用 MapLibre 和 Martin 进行交付。

选择主要技能

将相互关联的数据源、计算、存储和交付决策放在一起处理。优先选择 一个主要技能，仅在任务需要时使用有针对性的辅助技能：

请求	已安装时的主要技能
尚未确定的架构、变化中的规模或团队需求，或端到端 GIS 分析	open-map-stack
根据选定的工作流编译或维护可复现项目	reproducible-gis-project
根据已知要求查找和评估数据，包括 Portolan 目录	geospatial-data-discovery
在已选定的引擎上编写、审查或调试空间 SQL	spatial-sql

如果缺少专用技能，请使用此技能的本地参考资料处理范围明确的任务。无需 要求安装或启用所有技能。即使只安装了通用技能，重要分析也须保留下方的 完整项目约定。产品专属帮助请参阅 references/companion-skills.md； OpenMapStack 负责保留 GIS 语义和跨阶段的正确性。

以项目为先的可复现约定

对于每项重要的多阶段 GIS 分析，在交付前编译或维护一个确定、可检查、可复现的技术项目。地图、仪表板或报告是该项目的视图，而不是分析的权威定义。

在编译或交付重要分析之前，请阅读 references/project-workflow.md，了解强制工作流和交付规则， 并阅读 references/project-spec.md，了解完整的 openmapstack-project/v1 架构。 使用 templates/ 和已完成的 examples/tartu-development 项目。 有关 CLI 安装和该示例的运行时要求，请阅读 references/installation.md。

确保权威数据源真实、不可变且已固定版本；未经明确知情同意，绝不编造基线几何数据。将假设和每项手动修正记录为数据或规范管线逻辑，使覆盖项可执行且经过验证，并将未知语义属性保留为未知。项目必须明确指定 CRS、包含确定且有序的步骤、机器可读的验证结果和运行证据、来源信息，并记录无需聊天依赖即可干净重跑的步骤。检查 CLI 是否已安装（运行 openmapstack --version 或 python3 -m openmapstack --version，然后在以下所有命令中使用可行的形式）；如果已安装，运行 openmapstack validate 和规范的 openmapstack run 路径，然后运行 openmapstack verify project.yaml --rerun，该命令会在空工作区中根据项目声明的输入重建项目。 将 verify --rerun 作为最后一步，只有通过后才能交付；仅通过 validate 并不足够。规范管线必须生成 data/derived 下的每个文件、每项选定的交付物、运行记录，以及清单中的 runs.latest 和 project.status，不得使用一次性脚本或手动编辑：重跑会写入新的运行记录，因此手动修补指针会导致重跑失败。缺少验证能力时，结果应为 not_testable，不得默认视为通过。根据管线结果生成持久的 Markdown 调查结果。遵守所选目标对应的参考工作流中的展示要求。 声明真实作者和工具包；在每个交付视图中，使用规范运行时间呈现带链接的致谢（见工作流中的致谢要求）。 也要审查规定的署名文案；现场检查无法验证其含义。 新项目需声明 delivery.schema: openmapstack-delivery/v1，默认使用内置仪表板。遵守明确指定的仅外部交付或组合交付要求；QGIS 和 Observable 是可选目标。对于没有 delivery 的现有清单，在明确迁移前继续沿用旧版 v1 行为。无论选择何种方式，数据源来源信息、GIS 正确性和干净重跑都不可或缺。

对于仪表板底图，遵循用户选择并使用适当的本地或区域服务；否则使用 references/web-delivery.md 中预配置的 goplex.ee Protomaps 备用方案，并提供明暗模式切换和清晰可见的服务提供方署名。

对于范围明确的一次性 SQL、CRS 或转换问题，只需参考相关领域文档；无需完整项目产物及其方法说明。

如果用户的技术栈中包含 dlt、Dagster、dbt、QGIS 或 Observable，请阅读 references/established-stack.md，了解职责归属和集成边界。 保留用户选择的工具；确保数据源版本固定、GIS 正确性和可复现证据。不要重复定义他们的 SQL、数据摄取或调度器。

模块 — 开始工作前请阅读相关参考资料

如果任务涉及……	阅读
查找或获取数据（OSM、Overture、Sentinel、Landsat、建筑物轮廓、区域门户、STAC 和 Portolan 目录、基于 MCP 的发现）	references/data-sources.md
读取用户自己的数据仓库或数据库（PostGIS、BigQuery、MotherDuck、DuckDB、GeoParquet 目录）：通过引用使用凭据、只读发现、已批准的快照、固定类	references/user-data-sources.md
为全球或大陆尺度的任务选择本地处理还是在线／托管／SaaS 服务；底图、高程、路径规划、地理编码、地点搜索、邮政编码查询 API	references/services-and-scale.md
选择格式、格式转换，或任何 CRS／投影／EPSG 问题	references/formats-and-crs.md
编译可复现的 GIS 项目产物（project.yaml、管道、覆盖项、验证、展示）	references/project-spec.md + templates/
运行 GDAL/OGR、GeoPandas、xarray、DuckDB、PostGIS 或 PDAL——执行实际处理	references/processing.md
在 DuckDB Spatial、PostGIS、BigQuery GIS、Snowflake 或 Sedona 中编写或审查空间 SQL／GeoSQL	references/spatial-sql.md
矢量分析、栅格分析、地形／水文、网络分析、点云工作流	references/analytics.md
瓦片生成（PMTiles、MVT）、瓦片服务（Martin、TiTiler）、交付式渲染（MapLibre、deck.gl）或探索式渲染（kepler.gl、lonboard）	references/web-delivery.md
设计项目的仪表板或报告页面：原型、组件、设计令牌，以及检查所使用的状态钩子	references/design-language.md
QGIS 桌面版、QGIS 插件生态、QGIS MCP、PyQGIS 脚本、Processing 工具箱	references/qgis.md
可复现性、验证、许可证归属、瓦片冒烟测试、部署检查	references/validation-and-ops.md

对于简单的一次性问题（单次 CRS 转换、一次 ogr2ogr 调用），只需阅读相关参考资料，无需完整的项目产物。对于多阶段管道，请同时阅读 data-sources.md 和 processing.md，并参阅 project-spec.md + templates/，将分析编译为可重新运行的项目。对于端到端的“从原始数据到 Web 地图”任务，还请阅读 web-delivery.md。

全局默认设置 — 除非用户另有指定，否则均适用

• 存储格式： GeoParquet（矢量分析）、COG（栅格）、PMTiles（瓦片交付）、GeoPackage（桌面数据交换）。切勿将 Shapefile 作为新输出格式。
• CRS： 存储使用 WGS84（EPSG:4326）；Web 渲染使用 Web Mercator（EPSG:3857）；任何度量计算（距离、面积、缓冲区）均使用本地投影 CRS。爱沙尼亚使用 EPSG:3301（L-EST97）。 对 GIS x/y 坐标使用 DuckDB ST_Transform 时，请指定 always_xy := true。交付前，请将转换后的要素与其源数据及已知位置进行核对；正确的 CRS 标签并不能证明坐标正确。参见 references/formats-and-crs.md。
• 坐标顺序： 将其视为接口约定，而非 CRS 猜测。内部优先使用 GIS x,y（地理坐标使用 lon,lat），但须遵循各外部格式/API 的约定；GeoJSON、MapLibre LngLatLike 和 OpenLayers 地理坐标数组使用 lon,lat，而 Leaflet LatLng 和 Google Maps LatLng 使用 lat,lng。切勿仅凭 EPSG:4326 推断元组顺序。参见 references/formats-and-crs.md。
• 图层位置： 声明感兴趣区域（project.aoi），并在加载后及每次重投影后检查所有本地图层是否位于该区域内。某图层远离城市或国家 AOI，说明可能存在轴顺序颠倒、CRS 标签错误或区域筛选错误；请报告问题，并且只有在有源数据证据时才修正。
• 计算位置： 将空间连接和聚合推送到 DuckDB 或 PostGIS 中执行，而非使用 Python 循环。在大规模场景下，R-tree / GIST / 空间索引为必需项。
• 先发现数据： 下载任何内容前，先检查 STAC 目录（Microsoft Planetary Computer、Earth Search、Overture STAC）。使用 odc-stac 或 stackstac 延迟加载，仅物化所需内容。
• 云原生访问： 优先查询远程 GeoParquet/COG，而非下载。对于 Overture 和类似的 S3 托管数据集，默认采用带 httpfs 扩展的 DuckDB。
• 优先考虑规模： 城市/州级工作可使用本地工具；在大陆/全球范围内，若云原生分区数据集、预计算瓦片、托管 API 或 SaaS 比本地批处理更可靠，则优先使用这些方案。
• 许可证规范： 在每次转换中保留许可证元数据。OSM 采用 ODbL（相同方式共享）；Overture 的许可因来源而异；Sentinel 可免费使用但需注明出处；各国数据的许可各不相同。
• 运行时规范： 对 GDAL/PROJ/GEOS/QGIS 技术栈，优先使用 conda-forge 环境或容器。除非项目已证明可行，否则避免仅使用 pip 的地理空间环境。

格式决策矩阵

用例	格式
云端矢量分析	GeoParquet
通过 HTTP 流式传输矢量数据	FlatGeobuf
桌面数据交换	GeoPackage
Web 地图矢量瓦片	PMTiles（包含 MVT）
栅格归档 / 服务	COG
n 维栅格（时间序列、气候）	Zarr 或 NetCDF
点云归档	COPC（云优化 LAZ）
API 响应载荷（仅限小数据量）	GeoJSON
旧格式兼容（仅作输入）	Shapefile

计算决策矩阵

规模 / 场景	用途
< 50M 个要素，单机、临时任务	DuckDB Spatial
多用户、Web 应用后端、OLTP	PostGIS
> 100M 个要素，分布式	Apache Sedona
大陆/全球范围的查询/搜索/路径规划/高程	在覆盖范围、SLA、条款和价格合适时使用托管 API 或 SaaS
全球规模底图交付	预构建 PMTiles/矢量瓦片或托管底图服务
n 维栅格，延迟加载/dask 支持	xarray + rioxarray（+ 用于 STAC 导入的 odc-stac）
栅格 CLI 批处理任务	GDAL 工具（gdalwarp、gdal_translate -of COG）
点云	PDAL 流水线
超出 gdaldem 能力范围的地形与水文分析	WhiteboxTools 或 GRASS
桌面制图样式、制图、临时探索	QGIS（参见 qgis.md）

通用反模式——标记并纠正

• 编造或虚构模拟坐标和几何数据，而不是获取真实源数据（除非用户明确知情并同意进行合成模拟测试）
• 生成的 QGIS 项目与共享的展示图层不一致、遗漏底图，或使用错误的 OGR 数据源语法（path.gpkg|layer 中缺少 layername=），导致图层被加载为非空间属性表
• 手动编写 .qgs XML，却没有 <srs>、CRS 块中只有 auth-id，或没有 ProjectionsEnabled；或者将清单中的图层顺序原样照搬到图层树中——这些做法会生成一种项目：所有图层都有效、所有数据源都能解析，但地图显示的位置错误，或有图层被悄然隐藏
• 将 Shapefile 作为新的输出格式（字段截断、2GB 限制、不支持 UTF-8、由多个文件组成）
• 在地理 CRS（EPSG:4326）上调用 .distance()、.buffer() 或 .area——度不是米；除非特定工具明确支持基于 WGS84 的测地线计算
• 将 Web Mercator（EPSG:3857）坐标视为没有失真的地面测量值——其坐标单位是米，但地面距离和面积的失真会随纬度变化
• 在 Python 循环中执行空间连接，而 DuckDB、PostGIS 或基于 R-tree 的 sjoin 只需一行代码即可完成
• 当要素可能跨越边界时，面积查询仍使用 bbox 包含关系——应先用 bbox 重叠关系进行扫描筛选，再使用精确的空间谓词
• 当 STAC 和云原生格式支持延迟加载或范围请求时，仍下载整个数据集
• 当可靠的托管服务或预计算的全球产品已经存在时，仍在本地进行行星级数据处理来解决查找／搜索问题
• 将 MBTiles 作为新 Web 部署的默认格式——现代默认格式是 PMTiles
• 只需一个标志（-of COG）即可生成 COG，却仍使用 GeoTIFF
• 悄然混用 CRS——每次连接都必须断言 CRS 匹配
• OSRM、Valhalla 或 Nominatim 只需一次 Docker 拉取即可使用，却仍手动实现路径规划或地理编码
• 在可复现的管道中将数据版本固定为“latest”——固定 Overture 发布版本和 STAC 项目 ID，而不只是集合。对于 Overture，请确认固定的发布版本仍可用，或对其进行镜像。

快速分诊——识别请求类型

开始处理任务前，先对其分类：

1. 发现（“……有哪些数据？”、“有……数据集吗？”、“读取此目录”）→ 从 data-sources.md 开始。栅格数据使用 STAC 搜索；矢量底图使用 Overture 或 OSM；对于 Portolan 目录，查询前先阅读其 AGENTS.md。
2. 转换／CRS（“将这个转换为……”、“重投影到……”、“投影看起来不对”）→ formats-and-crs.md。通常只需调用一次 ogr2ogr 或 gdalwarp。
3. 分析（“……的平均海拔是多少？”、“距……500m 范围内有多少栋建筑？”、“热点在哪里？”）→ analytics.md，很可能还需要 processing.md。优先交由 DuckDB/PostGIS 处理。
4. 交付（“将其发布为 Web 地图”、“为……生成瓦片”）→ web-delivery.md。默认采用 PMTiles + Martin + MapLibre。
5. 桌面／制图（“在 QGIS 中为其设置样式”、“制作打印地图”、“在 QGIS 中自动执行此操作”）→ qgis.md。可考虑在 Agent 工作流中使用 QGIS MCP。

大多数实际任务会涉及其中 2–3 类——按顺序阅读相关参考文档。

任意管道的可复现性检查清单

• 固定数据集版本（Overture 发布版本、STAC 项目 ID、OSM 提取日期）——绝不使用“latest”
• 记录每个阶段的 CRS；绝不想当然
• 使用 conda-forge 环境或固定版本的容器镜像（GDAL 使用 ghcr.io/osgeo/gdal:alpine-small-latest，PyQGIS 使用 qgis/qgis:<tag>）；仅使用 pip 的地理空间环境经常会出问题
• 验证输出：使用 gpq 验证 GeoParquet，使用 rio-cogeo validate 验证 COG，使用 pmtiles show 验证 PMTiles，使用 is_valid 验证几何数据
• 在列或旁置 JSON 中保留许可证元数据，并将所需署名信息带入地图／API

每项操作的命令级详细说明见 references/validation-and-ops.md。