Mapbox

在 Web 应用和 API 集成中开展实际的 Mapbox 平台工作时，使用本技能。

工作流

1. 首先确认运行时环境：纯 HTML、Vite、React、Next.js 或其他框架。
2. 确认涉及的 Mapbox 表面（surface）：GL JS 地图渲染、样式（styles）、矢量切片集（tilesets）、地理编码（geocoding）、路径规划（directions）或静态图片（static images）。
3. 从最小可运行地图开始，再逐步添加自定义数据源、图层、控件或 API 调用。
4. 除非用户明确要求仅限本地演示，否则请勿将访问令牌（access token）写入源文件或示例中。
5. 排查 Bug 时，需隔离问题根源：容器尺寸、令牌/权限范围（token/scopes）、样式 ID / 数据源 ID、坐标顺序，还是图层绘制顺序。

实现约束准则

• 优先使用 mapbox-gl，并显式导入模块及显式加载 CSS。
• 调试渲染问题前，务必确保地图容器具有实际高度（非 0 或 auto）。
• 统一采用 lng, lat 顺序表示 Mapbox 坐标数组。
• 先添加数据源（source），再添加图层（layer）；保持图层 ID 稳定，便于后续更新。
• 轻量级覆盖图（overlay）优先使用 GeoJSON；大规模数据集则迁移至矢量切片（vector tiles）或 tileset。
• 在 React 或其他单页应用（SPA）框架中，卸载组件时需销毁地图实例，防止内存泄漏。
• 将访问令牌视为配置项处理：从环境变量或运行时配置中读取，而非硬编码。

常见故障检查项

• 地图空白：验证访问令牌、样式 URL、CSS 是否正确引入，以及容器是否具备有效高度。
• 图层不可见：验证数据源是否存在、source-layer 名称是否匹配、缩放级别是否在可见范围内，以及 paint/layout 属性中的可见性设置。
• 位置错误：验证坐标顺序与坐标参考系（CRS）假设；Mapbox 默认采用 WGS84 坐标系，且顺序为 lng,lat。
• 性能问题：减少标记（marker）数量、对点数据启用聚类（clustering），并优先使用数据驱动型图层（data-driven layers），而非大量 DOM 标记。
• API 调用失败：验证令牌权限范围（scopes）、端点类型、速率限制（rate limits）及请求参数是否正确。

任务边界

• 本技能专用于 Mapbox 相关的具体实现、调试及集成模式。
• 通用 CRS / 投影推理，请使用 project 或 wgs84 技能。
• 确定性的桌面 GIS 批处理任务，请使用 qgis 技能。
• CesiumJS 球体（globe）渲染，请使用 cesium 技能。

OpenClaw + ClawHub 注意事项

• 示例应保持通用性、可移植性，并确保令牌安全。
• 禁止硬编码私有数据集、私有样式 URL 或机器特定路径。
• 若面向 clawhub.ai 发布，请确保内容可复现且符合语义化版本规范（semver-friendly）；详细示例应放入参考资料中，避免膨胀 SKILL.md 主文件。

本技能所含参考文档

• 生成或修复 Mapbox GL JS 或 API 集成代码时，请查阅 {baseDir}/references/patterns.md。