同一份空间数据能被目录检索，不表示 QGIS、地图前端、Notebook、DuckDB 与 Agent 都能正确读取。空白地图可能是 CORS，少一半要素可能是分页，静态瓦片模板可能无法带认证头。GeoLens Examples 将这些差异写成可运行样例；其工程价值在于建立跨客户端合同，而不是复制某个页面。

研究的九项固定口径

  1. GeoLens Examples 为浏览器、Python 和 DuckDB 提供可复制的集成示例，默认匿名读取公共 demo，cli 目录则向自己的目录发布数据并需要凭据。

  2. GeoLens 提供 OGC API Features 和 Records、STAC 1.0、XYZ MVT 矢量瓦片和栅格瓦片。

  3. 示例使用 GeoLens v1.13.0 或更高版本，且栅格瓦片从该版本起才发送 Access-Control-Allow-Origin。

  4. 示例仓库包含 QGIS 4.2 的 OGC API Features、Records、CQL2、XYZ raster 和 tile-token auth 示例。

  5. 示例的 MapLibre 视窗要素加载会使用 bbox、rel=next 分页、取消过期请求，并在达到上限时提示切换矢量瓦片。

  6. README 说明 numberMatched 与 numberReturned 不相等只表示当前页不完整，分页应以 rel=next 为准。

  7. 不带凭据的跨域读取可使用 Access-Control-Allow-Origin: *，带凭据时必须把页面 origin 列入 CORS_ALLOWED_ORIGINS，且不能使用字面 *。

  8. 静态 XYZ/MVT 模板无法设置请求头时可使用按数据集和有效期范围签发的 tile token。

  9. 示例 CI 会验证数据已加载和地图已绘制，而不把 HTTP 200 当作通过。

核心机制：按客户端选择读取合同

小范围、需要属性的查询可用 OGC API Features；全域大图层应交给 MVT；目录与资产发现分别走 Records 和 STAC。QGIS 示例覆盖 Features、Records、CQL2、XYZ 和 tile token，说明桌面和浏览器不能只共享一个 URL 就宣称兼容。

分页更不能靠猜测计数。numberMatched 与 numberReturned 的差异只说明当前响应未装下全部结果，真正的续页依据是 rel=next。视窗加载还应在地图移动后取消旧请求，并在超过阈值时改用矢量瓦片，避免把完整要素表悄悄塞进浏览器内存。

GIS 场景与技术路径

先用同一脱敏集合完成 QGIS 读取、MapLibre 视窗查询、Python 查询和 DuckDB 分析。浏览器无凭据读公共数据时检查 CORS；需要凭据时把应用 origin 明确加入白名单。静态瓦片模板不能加请求头，才使用短期、单数据集范围的 tile token；不要把长效 API key 写进 HTML。

将示例 CI 的标准迁入自己的回归：验证预期数据加载、关键图层确实绘制、分页没有漏页、受限数据返回正确拒绝。HTTP 200 只证明服务器回复，不证明地图、坐标系、样式或权限正确。

风险与检查清单

  1. 每个客户端是否使用适合数据规模的 Features、STAC 或 tiles 协议？
  2. 是否以 rel=next 走完分页，而没有把一页当全量？
  3. 公共与带凭据 CORS 是否分别验证，且白名单没有使用 *？
  4. token 是否最小范围、短有效期，静态页面是否没有长效密钥？
  5. 是否像示例 CI 一样检查数据和地图实际绘制？

结论

GeoLens Examples 的跨客户端价值，是让服务协议、认证和前端行为可被逐项运行验证。用同一组数据把 QGIS、网页、脚本与 Agent 的读取合同跑通，空间目录才能真正成为共享服务。

资料来源