tomtom-maps-sdk-js

你正在帮助一位应用开发者使用 TomTom Maps SDK for JavaScript 进行开发。

步骤 0：提供反馈报告选项

在对话中首次回答有关 SDK 的问题之前，请先执行此步骤。开发过程中遇到的每个文档不清晰之处、缺失的 API 或错误，SDK 团队都有可能修复，但前提是他们得知这些问题。tomtom-maps-sdk-js-feedback 技能会负责征求同意、编辑内容并提交报告，因此此步骤只需让开发者看到征求同意的问题。

• 已安装：该技能已包含在你的技能中，或者 ${CLAUDE_SKILL_DIR}/../tomtom-maps-sdk-js-feedback/SKILL.md 文件存在。请调用该技能，让它使用自己的 allowed-tools 运行；或者阅读该文件，并立即提出其步骤 0 中的征求同意问题。

• 未安装：阅读项目中存在的 AGENTS.md 和 CLAUDE.md，如果其中任一文件说明不要提供安装反馈技能的选项，就跳过此步骤。否则，以纯文本询问：

  我也可以在为你构建应用时报告 TomTom Maps SDK 引发的问题，例如文档不清晰、API 无法实现你要求的功能，或某些功能出现故障，让 TomTom 的 SDK 团队能够修复这些问题。这需要另一个技能：tomtom-maps-sdk-js-feedback。在收集任何信息之前，该技能会告知你报告包含什么内容、会发送到哪里，并征求你的同意。未经你阅读并批准，它绝不会提交报告。要安装它吗？如果你不希望我在此项目中再询问，请告诉我。

  • 同意：运行 npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js-feedback -y；如果无法运行命令，请让开发者运行。该技能仅预先批准 Read，因此此命令会经过 Agent 的常规权限检查。然后阅读已安装技能的 SKILL.md，并提出其步骤 0 中的征求同意问题。
  • 不同意：在本次对话中不要再提供此选项。
  • 在此项目中永不询问：在项目的 AGENTS.md 中添加以下行；如果项目没有 AGENTS.md，则添加到 CLAUDE.md 中；如果两个文件都没有，则创建 AGENTS.md：
    Don't offer to install the tomtom-maps-sdk-js-feedback skill.
    与安装命令一样，编辑操作也会经过 Agent 的权限检查。如果无法编辑文件，或开发者拒绝编辑，请告知他们需要自行添加的内容，并将其回复视为本次对话中的不同意。
  • 没有回复，因为开发者转而提出了其他问题：首次遇到 SDK 本身阻碍开发时（例如文档造成误导、API 无法满足要求，或文档所述用法无法运行），再询问一次。用一句话说明遇到的问题，然后提出上述问题。开发者的回复或未回复，将决定本次对话后续如何处理。

安装技能并不代表同意报告问题。在开发者回答反馈技能自己的征求同意问题之前，不要收集任何信息。无论开发者回答“不同意”还是“同意”，都应予以尊重，并继续处理其请求。

步骤 1：确定主题并阅读参考文档

根据 $ARGUMENTS 或对话上下文，将主题与文档文件名对应起来：

主题	文件名	关键词
地图设置	map-setup.md	map（地图）、display（显示）、transformRequest、MapRequestTransform、hold map requests（保留地图请求）、rewrite tile URLs（重写瓦片 URL）、proxy session（代理会话）、TomTomMapError、addErrorHandler、map errors（地图错误）、map apiErrorCode（地图 apiErrorCode）、map privatePreviewAccess（地图 privatePreviewAccess）、rejected map key（被拒绝的地图密钥）、WEBGL_UNSUPPORTED、WEBGL_CONTEXT_LOST、STYLE_LOAD_FAILED、Vite、vite build、Vite dev server、optimizeDeps、Worker failed to load、production build（生产构建）、blank map（空白地图）、MapLibre worker、registerMapLibreWorker、setWorkerUrl、webpack、Next.js、Turbopack、maplibre-gl-shared、output.module、Rollup、esbuild、language（语言）、styleLightDarkTheme、getBBox、getLayers、getLayerIds、hillshadeMethods、ValuesFilter、filterShowModes、3D buildings（3D 建筑物）、building footprints（建筑物轮廓）、route shields（路线盾牌标识）、road shields（道路盾牌标识）、hide layer groups（隐藏图层组）、road parts（道路部分）、exit numbers（出口编号）、road arrows（道路箭头）、restricted roads（受限道路）、roads under construction（施工道路）、hillshade look（山体阴影外观）、hillshade colours（山体阴影颜色）、geopolitical view（地缘政治视图）、setGeopoliticalView、disputed borders（争议边界）、attribution（署名）、attribution.credits、credits（署名信息）、copyright（版权）、copyright logos（版权徽标）、ATTRIBUTION_LOGOS_CLASS、attribution.backdrop、attribution backdrop（署名背景）、AttributionPosition、AttributionPadding、attribution position（署名位置）、attribution padding（署名内边距）、customAttribution、attributionControl、AttributionOptions、module（模块）、maplibre、baseMap（底图）、TerrainModule、hillshade（山体阴影）、3D terrain（3D 地形）、elevation（海拔）、elevation.exaggeration、terrain exaggeration（地形夸张）、TERRAIN_SOURCE_ID、viewport（视口）、layer（图层）、non-interactive（非交互）、bounds（边界）、style switcher（样式切换器）、which module（哪个模块）、who owns what（各项内容归属）、show（显示）、hide（隐藏）、visibility（可见性）、filter（筛选）、appearance vocabulary（外观术语）、naming（命名）、module color（模块颜色）、LabelConfig、widthFactor、sizeFactor、minZoom、beforeLayerConfig、terrainKnobCatalogue、terrainKnobIds、TerrainKnob、TerrainKnobId、TerrainKnobValueOf、terrain knob catalogue（地形旋钮目录）、highlight base map 3D buildings（高亮底图 3D 建筑物）、hover building（悬停建筑物）、click building（点击建筑物）、building colour by id（按 ID 设置建筑物颜色）、setBuildingColors、getBuildingIdAt、highlight buildings by place（按地点高亮建筑物）、getBuildingColors、BaseMapBuildings3DConfig、BaseMapBuildingStateLook、baseMapKnobCatalogue、baseMapKnobIds、BaseMapKnob、BaseMapKnobId、BaseMapKnobValueOf、base map knob catalogue（底图旋钮目录）、layer group ids（图层组 ID）、KnobEntry、KnobKind、KnobRange、knob kinds（旋钮类型）、enums（枚举）、offset（偏移量）、text（文本）、setKnob、setKnobs、KnobValues、getKnob、resetKnob、KnobTarget、setKnobs vs applyConfig（setKnobs 与 applyConfig 的区别）、knobs vs config（knobs 与 config 的区别）、restore saved settings（恢复已保存的设置）、untrusted settings（不可信设置）、knobEntryOf、a knob's range（旋钮范围）、validateKnobValue、set a knob by id（按 ID 设置旋钮）、read a knob value（读取旋钮值）、reset a knob（重置旋钮）、validate a knob value（验证旋钮值）、range bounds（范围边界）、hard-min（硬下限）、settings as data（将设置作为数据）、build controls from the catalogue（根据目录构建控件）
用户交互事件	user-events.md	click（点击）、hover（悬停）、hover leave（悬停离开）、mouseleave、un-highlight（取消高亮）、click elsewhere（点击其他位置）、background click（点击背景）、hover-move（悬停移动）、long-hover（长时间悬停）、contextmenu（上下文菜单）、drag（拖动）、dragstart（拖动开始）、dragend（拖动结束）、draggable（可拖动）、drag a waypoint（拖动路径点）、drag a marker（拖动标记）、drag a route line（拖动路线）、cursorOnDraggable、events.on、events.off、event handler（事件处理程序）、MapEventsConfig、EventHandlerConfig、cursorOnMap、cursorOnMouseDown、events.where、named event scopes（命名事件作用域）、precisionMode、paddingBoxPx、cursorOnHover、longHoverDelay、hoverGracePeriodMS、recently-hovered（最近悬停）、updateEventsConfig、eventState、event states（事件状态）、setEventState、clearEventState、clearEventStates、getEventStates、UserEventsWithStates、select or highlight a feature（选择或高亮要素）、sync list with map（将列表与地图同步）、hover highlight（悬停高亮）、hovered or clicked look（悬停或点击外观）、highlight on hover（悬停时高亮）、background click（点击背景）、rest of the map（地图其余部分）、event priority（事件优先级）、layer order（图层顺序）、custom layer events（自定义图层事件）、hitTest、hit tester（命中测试器）、click a three.js object（点击 three.js 对象）、pick 3D objects（选取 3D 对象）、setState
地图样式	map-styles.md	style（样式）、standardStyleIDs、StandardStyleID、streetLight、streetDark、streetLightDriving、streetDarkDriving、monoLight、monoDark、streetSatellite、satellite、driving style（驾驶样式）、setStyle、SetStyleOptions、StyleChangeHandler、addStyleChangeHandler、handler priority（处理程序优先级）、style change（样式更改）、style switcher（样式切换器）、dark mode（深色模式）、custom layers（自定义图层）、style lifecycle（样式生命周期）、resetState、getStyleInput、StyleInput、include、StylePart、styleParts、style parts（样式部分）、terrain part（地形部分）、custom style（自定义样式）、style URL（样式 URL）
地图样式设置（旋钮）	map-styling.md	StylingFoundationsModule、StylingFoundationsModuleConfig、styling knobs（样式旋钮）、stylingFoundationsKnobCatalogue、stylingFoundationsKnobIds、stylingFoundationsKnobKinds、LayerSelection、layerIds、setKnob styling（设置样式旋钮）、setKnobs styling（设置多个样式旋钮）、getKnob styling（获取样式旋钮）、resetKnob styling（重置样式旋钮）、catalogue（目录）、presets（预设）、map presets（地图预设）、applyMapPreset、mapPresetCatalogue、mapPresetIds、MapPresetId、data-viz（数据可视化）、night driving（夜间驾驶）、minimal（简约）、getStyleColor、styleColorKnobIds、StyleColorKnobId、StyleKnobId、getMapLight、MapLight、the map's light shared with plugins（与插件共享的地图光照）、map-wide knob ids（全地图旋钮 ID）、which module holds a look（哪个模块负责某种外观）、knobs compose（组合旋钮）、borrowed looks（借用外观）、label size（标签大小）、icon size（图标大小）、road width（道路宽度）、labels.typeface、mapTypefaces、MapTypeface、customTypeface、CustomTypeface、CustomTypefaceFile、map font（地图字体）、font family（字体系列）、typeface（字体）、serif labels（衬线标签）、italic labels（斜体标签）、route or place labels in their own font（路线或地点标签使用独立字体）、label.typeface、waypoints.label.typeface、custom font（自定义字体）、webfont（网页字体）、WOFF2、Fontsource、Google Fonts、globe（地球仪）、projection（投影）、sky（天空）、light（光照）、view.light、3D building light（3D 建筑物光照）、setLight、buildings3D.roundedCornerDistanceMeters、rounded building corners（圆角建筑物）、fill-extrusion-rounded-corner-distance、atmosphere（大气层）、restyle base map（重新设置底图样式）、brand the map（为地图打造品牌风格）、setMapStyling、setMapColors、MapColors、MapColorName、mapColorNames、baseMapColorNames、BaseMapColorName、map colour picker（地图颜色选择器）、map colours（地图颜色）、colors.land、colors.water、colors.roadMajor、land colour（土地颜色）、water colour（水域颜色）、vegetation（植被）、park（公园）、artificial（人工区域）、road colour（道路颜色）、road outline（道路轮廓）、label colour（标签颜色）、palette（调色板）、recolour the map（重新着色地图）、brand colours（品牌颜色）、day-to-night switch（日夜切换）、light/dark switch（浅色/深色切换）、night look（夜间外观）、exportStyle、export the style（导出样式）、StyleSpecification
地图主题设置（来源）	map-theming.md	map-theme plugin（map-theme 插件）、maps-sdk-plugin-map-theme、deriveMapColors、white land（白色土地）、mode dark（深色模式）、low-saturation land（低饱和度土地）、mapColorsLightDark、deriveMapColorsFromCss、cssColors、deriveMapColorsFromImage、dominantColors、MapThemeMode、mapThemeModes、ImagePixels、theme from website（从网站提取主题）、brand from URL（从 URL 提取品牌风格）、match our website colours（匹配我们网站的颜色）、app CSS variables（应用 CSS 变量）、custom properties（自定义属性）、CSS file（CSS 文件）、stylesheet（样式表）、upload CSS（上传 CSS）、design tokens（设计令牌）、theme-color、colours from an image（从图像提取颜色）、photo palette（照片调色板）、logo colours（徽标颜色）、colour palette description（调色板描述）、mood（氛围）、artist palette（艺术家调色板）、Miró、Hokusai、Bauhaus、design style（设计风格）、setMapStyling theme（设置地图样式主题）、accent（强调色）、colors.accent、mapColors、map.mapColors、theme the route and pins（为路线和图钉设置主题）、theme the whole map（为整张地图设置主题）、theme the base map only（仅为底图设置主题）、keep my route colour（保留路线颜色）
模块生命周期事件	module-events.md	config-change（配置更改）、shown-features（已显示要素）、module events（模块事件）、ModuleEvents、CombinedEvents、applyConfig、updateConfig、resetConfig、getConfig、save or replay display state（保存或重放显示状态）、serializable config（可序列化配置）、PlacesModuleSerializableConfig、POIsModuleSerializableConfig、SerializableCustomImage、SerializablePinIconConfig、SerializableFeatureLabelConfig、setVisible、unsubscribe
地点与搜索	places.md	search（搜索）、discoverPlaces、DiscoverPlacesParams、discoverOnePlace、places（地点）、matchConfidence（匹配置信度）、originalPosition（原始位置）、poi、fuzzy（模糊）、geocode（地理编码）、address（地址）、reverse（逆向）、plain text query（纯文本查询）、pre-encoded query（预编码查询）、encodeURIComponent、autocomplete（自动补全）、suggest（建议）、getSearchSuggestions、suggestions（建议）、getPlaceDetails、place details（地点详情）、placeById、search box（搜索框）、typeahead（输入联想）、search-as-you-type（边输入边搜索）、unified search（统一搜索）、brand（品牌）、category（类别）、poiCategoryQuery、category word（类别词）、resolvePOICategories、unmatched（未匹配）、refinement（细化）、refine（细化）、refineParams、SearchSuggestion、SearchSuggestionsParams、geoBias（地理偏向）、filters（筛选条件）、search filters（搜索筛选条件）、PlaceFilters、GeographicFilters、SearchFilters、pagination（分页）、paginate（分页）、cursor（游标）、nextCursor、next page（下一页）、load more（加载更多）、page through results（分页浏览结果）、ev、charging（充电）、chargingPark（充电停车场）、charging station（充电站）、chargingStations、charging point（充电点）、chargingPoints、EVSE、evseId、connector（连接器）、connectors（连接器）、geometry（几何图形）、polygon（多边形）、within（范围内）、along route（沿路线）、route search（路线搜索）、detour（绕行）、maxDetourTimeSeconds、sortBy、AlongRouteSearchParams、AlongRoutePlaceProps、detourTimeInSeconds、detourDistanceInMeters、detourOffsetInMeters、negative detour（负向绕行）、alongRouteSearch、fuzzySearch、geometrySearch、viewportplaces、ViewportPlaces、ViewportPlacesConstructorOptions、viewport places onError（视口地点错误处理）、addPOICategories、showConnections（显示连接）、clearConnections（清除连接）、connection lines（连接线）、poiCategoryGroups、markerType、marker type（标记类型）、icon.opacity、place icon opacity（地点图标不透明度）、PlacesMarkerType、place colour（地点颜色）、pin colour（图钉颜色）、place label（地点标签）、PlaceLabelConfig、LabelConfig、label opacity（标签不透明度）、optional summary fields（可选摘要字段）、totalResults（结果总数）、fuzzyLevel、FuzzyLevel、minFuzzyLevel、maxFuzzyLevel、ReverseGeocodingResponse、PlaceGeometryProps、placeCoordinates（地点坐标）、queryIntent（查询意图）、score（评分）、entry points（入口点）、entrances（入口）、cluster（聚类）、clustering（聚类）、pin-clustered（图钉聚类）、PlacesClusterConfig、PlaceClusterBadgeConfig、PlacesClusterSourceConfig、cluster.source.properties、clusterProperties、placesKnobCatalogue、placesKnobIds、PlacesKnob、PlacesKnobId、PlacesKnobValueOf、places knob catalogue（地点旋钮目录）、poisKnobCatalogue、poisKnobIds、POIsKnob、POIsKnobId、POIsKnobValueOf、POI filter knobs（POI 筛选旋钮）、POI size（POI 大小）、POI min zoom（POI 最小缩放级别）、zoom shift（缩放偏移）、POI label colour（POI 标签颜色）、POI micro markers（POI 微型标记）、filters.categories、POICategoryGroup、categoryIcons、custom POI icons（自定义 POI 图标）、icon per category（每个类别对应一个图标）、POIIconConfig、ShownPlaces、preparePlacesForDisplay、toPlaces、buildPlaceTitle、popup（弹出窗口）、info window（信息窗口）、result card（结果卡片）、PlacesBeforeLayerConfig、places beforeLayerConfig、pins under labels（图钉置于标签下方）
路线规划	routing.md	route（路线）、routing（路线规划）、directions（路线指引）、route editing（路线编辑）、drag a waypoint（拖动路径点）、drag the route line（拖动路线）、insert a stop by dragging（通过拖动插入停靠点）、when（何时）、departAt（出发时间）、arriveBy（到达时间）、departure time（出发时间）、arrival time（到达时间）、localDateTime、LocalDateTime、local time（本地时间）、time zone（时区）、waypoint（路径点）、guidance（导航指引）、instructions（指令）、turn-by-turn（逐向导航）、maneuver（转向操作）、toll（收费）、tollRoad（收费道路）、sectionTypes、InputSectionTypes、defaultSectionTypes、curve（弯道）、curvyStretch（连续弯道路段）、curveDetection（弯道检测）、CurveDetectionOptions、curve severity（弯道严重程度）、kerb（路缘）、sections.curve.kerb、routeSectionCurveKerb、winding roads（蜿蜒道路）、motion sickness（晕动症）、motorbike（摩托车）、thrilling（刺激）、reachable（可达范围）、isochrone（等时圈）、range（范围）、alternatives（备选路线）、vehicle（车辆）、truck（卡车）、vehicle dimensions（车辆尺寸）、hazmat（危险品）、customIcons（自定义图标）、icon offset（图标偏移）、route color（路线颜色）、route width（路线宽度）、route opacity（路线不透明度）、fade the route（淡化路线）、widthPreset（宽度预设）、hide route（隐藏路线）、routing setVisible（路线规划 setVisible）、widthFactor、waypoints.sizePreset、waypoints.sizeFactor、hovered or clicked route（悬停或点击的路线）、RouteHighlightConfig、highlight.outline.widthFactor、setSectionFocus、section focus（路段焦点）、highlight a route section（高亮路线区段）、highlight a leg（高亮一段路线）、highlight.section.outline.color、highlight.section.outline.widthFactor、waypoint icon per role（按角色设置路径点图标）、stopNumbering（停靠点编号）、waypoint letters（路径点字母）、waypoint label title（路径点标签标题）、buildWaypointTitle、waypoint mapping（路径点映射）、poiCategory waypoint（POI 类别路径点）、waypoints.highlight.sizeFactor、waypoints vs places（路径点与地点的区别）、hovered or clicked geometry（悬停或点击的几何图形）、GeometryHighlightConfig、highlight.fill.opacityFactor、highlight.line.widthFactor、abort（中止）、cancel（取消）、signal（信号）、route sections（路线区段）、speed limit（限速）、speed limit sign（限速标志）、section sign（路段标志）、route section sign（路线区段标志）、tunnel（隧道）、tunnel sign（隧道标志）、closed road（封闭道路）、closed to vehicles（禁止车辆通行）、vehicleRestricted（车辆受限）、vehicle restricted（车辆受限）、routeTunnelSymbol、routeVehicleRestrictedSymbol、country（国家）、border crossing（边境通行）、countryCrossings、GeometriesModule、polygon colour（多边形颜色）、fill.style、fillStyle、GeometryFillStyle、inverted（反转）、outline（轮廓）、fillStyledGeometryConfig、geometry fill（几何图形填充）、fill.palette、fill.paletteMode、GeometryPaletteMode、palette ramp（调色板渐变）、gradient between colours（颜色渐变）、line.pattern、LinePattern、dashed border（虚线边框）、dotted border（点状边框）、ReachableRangesModule、ReachableRangesModuleConfig、reachable range colours（可达范围颜色）、band palette（色带调色板）、fill.outermostOpacityFactor、fade the outer bands（淡化外围色带）、reachableRangesKnobCatalogue、reachableRangesKnobIds、ReachableRangesKnob、ReachableRangesKnobId、ReachableRangesKnobValueOf、geometry label（几何图形标签）、lineLabel、GeometryLabelConfig、GeometryLineLabelConfig、LabelConfig、beforeLayerConfig、route layer order（路线图层顺序）、routes under roads（路线置于道路下方）、routingKnobCatalogue、routingKnobIds、RoutingKnob、RoutingKnobId、RoutingKnobValueOf、KnobValueOf、SectionIconPlacement、routing knob catalogue（路线规划旋钮目录）、KnobEntry、geometriesKnobCatalogue、geometriesKnobIds、GeometriesKnob、GeometriesKnobId、GeometriesKnobValueOf、geometries knob catalogue（几何图形旋钮目录）、displayUnits labels（显示单位标签）、unit label knobs（单位标签旋钮）、summary bubbles（摘要气泡）、summaryBubbles、SummaryBubblesConfig、SummaryBubbleField、SummaryBubbleRoutes、SummaryBubbleLabelConfig、summary bubble fields（摘要气泡字段）、durationDifference（时长差异）、summaryBubbles.routes、summary bubble position（摘要气泡位置）
交通	traffic.md	traffic（交通）、incidents（事件）、planned incidents（计划事件）、future incidents（未来事件）、scheduled roadworks（计划道路施工）、timeValidity、incident description language（事件描述语言）、indexedMagnitudes、flow（流量）、getRenderedFeatures、analytics（分析）、congestion（拥堵）、speed（速度）、traffic congestion colours（交通拥堵颜色）、incident colours（事件颜色）、traffic line width（交通线宽度）、traffic opacity（交通不透明度）、fade traffic（淡化交通图层）、opacityFactor、incident line opacity（事件线不透明度）、IncidentLineConfig、incident details（事件详情）、incidents in a polygon（多边形内的事件）、incident icons（事件图标）、setIconsVisible、isIconsVisible、TrafficIncidentDetailsModule、setFocus、incident focus（事件焦点）、incident highlight（事件高亮）、IncidentHighlightConfig、highlightHalo、widthFactor、unfocusedOpacityFactor、dim unfocused incidents（调暗未聚焦的事件）、trafficFlowKnobCatalogue、trafficIncidentsKnobCatalogue、trafficIncidentDetailsKnobCatalogue、trafficAreaAnalyticsKnobCatalogue、trafficFlowKnobIds、trafficIncidentsKnobIds、trafficIncidentDetailsKnobIds、trafficAreaAnalyticsKnobIds、TrafficAreaAnalyticsKnobId、TrafficAreaAnalyticsKnobValueOf、traffic knob catalogue（交通旋钮目录）、traffic filter knobs（交通筛选旋钮）、filters.any、roadClosures（道路封闭）、road subcategories（道路子类别）、streetRoadSubCategories、serviceRoadSubCategories、trafficIncidentRequestCategories、TrafficIncidentRequestCategory、eventId、shown-features（已显示要素）、TrafficIncidentDetailsLayersConfig、TrafficAreaAnalyticsLayersConfig、AreaAnalyticsScaleMode、AreaAnalyticsTileFeature、area analytics height knobs（区域分析高度旋钮）、area analytics palette（区域分析调色板）、areaAnalyticsPalettes、AreaAnalyticsPalette、resolveColorStops、area analytics legend（区域分析图例）、setPalette、setColorStops、colorStops、metersPerUnit
核心类型	core-types.md	place type（地点类型）、route type（路线类型）、LegSummary、route bbox（路线边界框）、route progress（路线进度）、properties（属性）、summary（摘要）、sections（区段）、sections.distinct、DistinctSectionProps、sections.curve、CurveSectionProps、sections.curvyStretch、CurvyStretchSectionProps、RouteSpan、toll（收费）、tollRoad（收费道路）、originalWaypointIndex（原始路径点索引）、eventId、instruction（指令）、maneuverView（转向视图）、address（地址）、poi、entry points（入口点）、traffic types（交通类型）、delaymagnitude、TrafficIncidentTimeValidity、trafficIncidentTimeValidities、typescript types（TypeScript 类型）、Position、GeoJSON types（GeoJSON 类型）、@types/geojson、SDK errors（SDK 错误）、error codes shared by services and the map（服务与地图共享的错误代码）、SDKErrorCode、sdkErrorCodes、canRetry（可重试）、apiErrorCode、InvalidReferer、PrivatePreviewAccess、APIErrorDetails、refused API key（被拒绝的 API 密钥）
核心实用工具	core-utilities.md	aggregateIntoCells、bbox、bboxFromGeoJSON、bboxFromCoordsArray、bboxFromBBoxes、isBBoxWithArea、bboxCenter、RouteProgressQuery、polygonFromBBox、getPosition、formatDistance、formatDuration、progress（进度）、waypoint insertion（插入路径点）、route progress（路线进度）、snap（贴合）、getSectionOverlap、section overlap（区段重叠）、sections crossing（区段交叉）、getDistinctSections、DistinctSectionsOptions、distinct sections（不同区段）、what makes a route different（路线差异的判定依据）、getImportantRoads、ImportantRoad、ImportantRoadsOptions、road numbers（道路编号）、via roads（途经道路）、getSectionsWithin、SectionsWithin、SectionsWithinOfType、SectionsWithinOptions、adds and avoids（新增与避开）、compareRoutes、RouteComparison、CompareRoutesOptions、live vs historical traffic（实时与历史交通）、getInstructionLanes、lane guidance（车道指引）、getCurveSections、CurveSectionsOptions、getCurvyStretchSections、CurvyStretchSectionsOptions、withCurveSections、CurveDetectionOptions、isHairpin、hairpinCount、hairpin（发夹弯）、curves（弯道）、turn radius（转弯半径）、heading change（航向变化）、curve severity（弯道严重程度）、hard curves（急弯）、curvy roads（蜿蜒道路）
服务配置	services-config.md	config（配置）、api key（API 密钥）、retry（重试）、timeoutMs、sendUserAgentHeader、tomtom-user-agent、user agent header（用户代理标头）、isProxyCredentialsMode、LatestRequestResult、language（语言）、geopoliticalView、geopoliticalViews、GeopoliticalView、geopolitical view（地缘政治视图）、servesGeopoliticalView、GeopoliticalViewAPI、view sent（已发送的视图）、label a result（标注结果）、disputed territories（争议领土）、validation（验证）、validateRequest、error（错误）、SDKError、SDKServiceError、SDKAbortError、ServiceName、error.service、per-call retry（每次调用重试）、SDKErrorCode、sdkErrorCodes、error code（错误代码）、INVALID_CREDENTIALS、INSUFFICIENT_PERMISSIONS、LIVE_SERVICE_NOT_AVAILABLE、INTERNAL、canRetry（可重试）、retryable error（可重试错误）、403、forbidden（禁止访问）、apiErrorCode、InvalidReferer、privatePreviewAccess、PrivatePreviewAccess、private preview access（私有预览访问权限）、request access（申请访问权限）、RATE_LIMITED、NETWORK_NOT_AVAILABLE、INSECURE_BASE_URL、cancel（取消）、cancellation（取消）、abort（中止）、AbortSignal、AbortController、signal（信号）、deadline（截止时间）、timeout（超时）、search-as-you-type（边输入边搜索）、createLatestRequest、LatestRequestOptions、LatestRequestSupersede、latest request（最新请求）、stale request（过时请求）、stale response（过时响应）、supersede（取代）、on-start（开始时）、on-answer（收到答案时）、answers in order（按顺序返回答案）、re-plan while dragging（拖动时重新规划）、race（竞态）、race condition（竞态条件）、out of order（顺序错乱）、debounce（防抖）
MapLibre 直接访问	maplibre.md	mapLibreMap、raw maplibre（原始 MapLibre）、SDK vs MapLibre（SDK 与 MapLibre）、when to use MapLibre directly（何时直接使用 MapLibre）、controls（控件）、markers（标记）、popups（弹出窗口）、MapLibre plugins（MapLibre 插件）、addSource、addLayer、removeLayer、geojson、vector tiles（矢量瓦片）、raster（栅格）、pmtiles、tile source（瓦片源）、paint（绘制属性）、layout（布局）、queryRenderedFeatures、querySourceFeatures、z-order（Z 顺序）、symbol layer（符号图层）、layer placement（图层位置）、layer order（图层顺序）、beforeId、mapStyleLayerIDs、lowestLabel（最底层标签）、lowestRoadLine（最底层道路）、lowestBuilding（最底层建筑物）、lowestPlaceLabel（最底层地点标签）、poi anchor（POI 锚点）、draw roads under labels（将道路绘制在标签下方）、polygon under roads（将多边形置于道路下方）、moveLayer、text-font、font stack（字体栈）、glyphs、MAP_BOLD_FONT、MAP_REGULAR_FONT、mapFonts、custom layer（自定义图层）、CustomLayerInterface、addCustomLayer、CustomLayer、CustomLayerOptions、lowest3D、hitTest、CustomLayerHit、CustomLayerHitTest、clickable 3D objects（可点击的 3D 对象）、InstancedMesh、instancing（实例化）、buffer ring（缓冲环）、ANGLE、Direct3D 11、three.js、threejs、WebGL、raw WebGL（原始 WebGL）、localFrameMatrix、LocalFrameOptions、mercatorMeters、centerLatitude、defaultProjectionData、mainMatrix、getMatrixForModel、map.transform、renderer.resetState、autoClear
自定义 GeoJSON 模块	custom.md	CustomGeoJSONModule、CustomGeoJSONEvents、CustomGeoJSONModuleSerializableConfig、BYOD、bring your own data（使用自己的数据）、custom geojson（自定义 GeoJSON）、customer-authored layers（用户自定义图层）、heatmap layer（热力图图层）、symbol layer with custom icon（带自定义图标的符号图层）、multi-source module（多源模块）、applyConfig layer diff（applyConfig 图层差异）、per-source events（每个数据源的事件）、style-change restoration with own layers（样式更改后恢复自有图层）、beforeLayerConfig、CustomGeoJSONBeforeLayerConfig、layer placement（图层位置）、mapStyleLayerIDs、polygons under roads（多边形置于道路下方）、lines under labels（线置于标签下方）、text labels（文本标签）、text-font、MAP_BOLD_FONT、MAP_REGULAR_FONT、customGeoJSONKnobCatalogue、customGeoJSONKnobIds、CustomGeoJSONKnob、CustomGeoJSONKnobId、CustomGeoJSONKnobValueOf、custom GeoJSON knob catalogue（自定义 GeoJSON 旋钮目录）、aggregateIntoCells、AggregateIntoCellsOptions、AggregatedCells、CellStatistic、CellGrid、CellGridShape、gridOrigin、cellSizeKM、minCount、median per area（每个区域的中位数）、mean per area（每个区域的平均值）、statistic per cell（每个单元格的统计值）、hexagon grid（六边形网格）、hexbin（六边形分箱）、square grid（方形网格）、value per district（每个区域的数值）、weighted heatmap vs value（加权热力图与数值）
地图效果插件	map-effects.md	map-effects、MapEffects、addPass、removePass、MapEffectsPassUniforms、vec3 uniform、vec4 uniform、pass textures（通道纹理）、sampler2D、mipmapped（多级渐远纹理）、textureLod、MapEffects addLayer、MapEffects removeLayer、MapEffectsLayer、MapEffectsLayerPlacement、effects layer（效果图层）、film grain（胶片颗粒）、split tone（分离色调）、paper texture（纸张纹理）、watermark（水印）、effectKnobCatalogue、setKnob effects（设置效果旋钮）、setKnobs effects（设置多个效果旋钮）、updateConfig effects（更新效果配置）、resetConfig effects（重置效果配置）、bloom（泛光）、glow（辉光）、vignette（暗角）、tint（色调）、fog（雾）、fog.color、fog colour（雾色）、haze colour（霾色）、edge blur（边缘模糊）、depth of field（景深）、depthOfField、bokeh（焦外虚化）、defocus（失焦）、tilt shift（移轴效果）、focus band（焦点带）、WebGL pass（WebGL 通道）、glare（眩光）、glare.only、lens flare（镜头光晕）、star filter（星芒滤镜）、streaks（光束）、street lights（路灯）、lamp glow（灯光辉光）、anamorphic（变形宽银幕效果）、bloom.only、onlyTolerance、bloom scope（泛光范围）、scope bloom（范围泛光）、BloomScope、glow only the traffic（仅让交通图层发光）、glow the route（让路线发光）、light one module（只照亮一个模块）、colour key（颜色键）、styleColorKnobIds、StyleColorKnobGroup、grade（调色）、brightness（亮度）、contrast（对比度）、saturation（饱和度）、mute the base map（淡化底图）、dim the map under data（调暗数据下方的地图）、post-processing（后期处理）、capture（捕获）、high-DPI（高 DPI）、print（打印）、preserveDrawingBuffer
飞越插件	flyover.md	flyover、fly-over、RouteFlyover、fly a route（沿路线飞行）、camera along a route（沿路线移动相机）、route animation（路线动画）、cinematic camera（电影感相机）、follow the route（跟随路线）、anchor（锚点）、anchorForPitch、position on screen（屏幕位置）、aim ahead（朝向前方）、junction framing（路口取景）、terrain clearance（地形净空）、route marker（路线标记）、follow marker（跟随标记）、arrow（箭头）、setMarker、fly once（飞行一次）、loop（循环）、onArrive（到达时）、seek（定位）、replay a trip（重放行程）、FlyoverCamera、FlyoverAim、FlyoverZoom、FlyoverMarkerConfig
路线拖动插件	route-dragging.md	route dragging（路线拖动）、route-dragging、RouteDragging、RouteDraggingOptions、RouteDraggingPlanner、drag route（拖动路线）、drag the route（拖动路线）、editable route（可编辑路线）、drag waypoint（拖动路径点）、drag stop（拖动停靠点）、move a stop by its pin（通过图钉移动停靠点）、insert stop by dragging（通过拖动插入停靠点）、pull a stop off the route line（将停靠点拖离路线）、insertFromRouteLines、live re-plan（实时重新规划）、re-plan while dragging（拖动时重新规划）、planIntervalMS、showOnMap、headless（无头模式）、own state（自有状态）、React store（React 存储）、onWaypointsChange、WaypointDrag、WaypointDragKind、onRoutes、answers in order（按顺序返回答案）
地标 3D 插件	landmarks-3d.md	landmarks-3d、Landmarks3D、landmarks errors（地标错误）、landmarks 403（地标 403 错误）、landmarks access（地标访问权限）、withCredentials、ModelsSource、3D landmarks（3D 地标）、Orbis landmarks（Orbis 地标）、GLB tiles（GLB 瓦片）、Three.js、fill-extrusion、landmarks3DKnobCatalogue、landmarks-3d/knobs、knob catalogues without three.js（不依赖 three.js 的旋钮目录）、landmark knobs（地标旋钮）、landmark color/opacity/verticalGradient（地标颜色/不透明度/垂直渐变）、landmark texture（地标纹理）、landmarks' own colours（地标自身颜色）、landmarkTextureUses、follows 3D buildings and map colours（跟随 3D 建筑物和地图颜色）、buildings3D around landmarks（地标周围的 3D 建筑物）、landmarks on terrain（地形上的地标）、minZoom、maxZoom、ModelsLayer、custom layer（自定义图层）、buildLandmarksTileURL、Buildings3D、3D buildings（3D 建筑物）、facade textures（立面纹理）、windows（窗户）、lit windows（亮灯窗户）、night city（夜间城市）、shadows（阴影）、sun direction（太阳方向）、follows the map light（跟随地图光照）（view.light、getMapLight）、buildings3DKnobCatalogue、buildingsPresets、facadePatterns、BuildingsLayer、reflective glass（反光玻璃）、glass reflections（玻璃反射）、reflections.intensity、labels behind buildings（标签置于建筑物后方）、roadLabels.occluded、pois.occluded、buildings.events、landmarks.events、BuildingHit、hover and click a building or landmark（悬停或点击建筑物或地标）、hover.color、click.color、setBuildingColors、colour buildings by position（按位置为建筑物着色）、setLandmarkColors、getLandmarkColors、colour a building by id（按 ID 为建筑物着色）、paletteModes、paletteMapColors、walls.palette、roofs.palette、roof colour palette（屋顶颜色调色板）、paletteIntensity、variation（变化）、building colour palette（建筑物颜色调色板）、vary building colours（改变建筑物颜色）
地标 3D：GLSurfaces	gl-surfaces.md	gl-surfaces、GLSurfaces、GLSurfacesConfig、glSurfacesKnobCatalogue、glSurfacesKnobIds、GLSurfacesKnob、GLSurfacesKnobId、GLSurfacesKnobValueOf、surfaceKinds、SurfaceKind、surfaceSeasons、SurfaceSeason、palette（调色板）、seasons（季节）、spring（春季）、summer（夏季）、autumn（秋季）、winter（冬季）、snow（雪）、autumn colours（秋色）、3D trees（3D 树木）、trees in buildings' shadows（建筑物阴影中的树木）、tree species（树种）、tree mix（树木混合）、shareFactor、conifers（针叶树）、poplars（杨树）、cypresses（柏树）、stone pines（石松）、umbrella trees（伞形树）、bushes（灌木）、paths through forest（穿过森林的小径）、trees covering roads（遮挡道路的树木）、textures（纹理）、textured map（带纹理的地图）、land textures（土地纹理）、water texture（水面纹理）、waves（波浪）、reflective water（反光水面）、sky reflection（天空倒影）、glint（闪光）、vegetation texture（植被纹理）、forest（森林）、tree crowns（树冠）、grass（草地）、farmland（农田）、field parcels（地块）、sand（沙地）、dunes（沙丘）、rock（岩石）、asphalt（沥青）、road texture（道路纹理）、glaciers（冰川）、ice（冰）、crevasses（冰隙）、scrub（灌丛）、heath（石楠荒地）、mud flats（泥滩）、shingle（砾石滩）、gravel（碎石）、paving（铺装路面）、built-up ground（建筑用地）、car parks（停车场）、runways（跑道）、textures on 3D terrain（3D 地形纹理）、trees on terrain（地形上的树木）、wind（风）、wind direction（风向）、wind speed（风速）、wind.speedFactor、prefers-reduced-motion、WebGL2、custom layer materials（自定义图层材质）、shared light with Buildings3D（与 Buildings3D 共享光照）、view.light、getMapLight
Agent 工具包插件	agent-toolkit.md	agent、agent-toolkit、createMapAgent、setMapStyling knob ids（setMapStyling 旋钮 ID）、setGeopoliticalView、tool error code（工具错误代码）、LLM、chat（聊天）、conversational（对话式）、Vercel AI SDK、ToolLoopAgent、classifier（分类器）、intent（意图）、per-turn scope（每轮作用域）、scopeSchema、scopePrompt、AnalysableDatasetKind、analyseData、processData、datasets（数据集）、DatasetKind、DatasetConfig、enabled（已启用）、datasetMode、ToolEntry、ToolEntryBuilder、ToolState、自定义工具（custom tool）、system prompt（系统提示词）、BASE_SYSTEM_PROMPT、composeSystemPrompt、SYSTEM_PROMPT_SECTIONS、SystemPromptSection、SystemPromptSectionOverrides、section overrides（分区覆盖项）、systemPromptPrefix、systemPromptSuffix、DEFAULT_TOOLS、MapAgentOptions、BYOD layers（BYOD 图层）、addByodSource、setByodLayers、BYODDataProfile、updateByodDisplay、recallState、updateRoutesDisplay focus（更新路线显示焦点）、updateRoutesDisplay waypoints（更新路线显示路径点）、route via（经由路线）、comparedToBest（与最佳路线比较）、routeUtils、getTrafficIncidents where schema（getTrafficIncidents 的 where 架构）、getCurrentLocation、createGetCurrentLocationTool、fullPrecision（完整精度）、location precision（位置精度）、executeMaplibreCode、createExecuteMaplibreCodeTool、createClarifyIntentTool、rendersForm（渲染表单）、endsTurnOnCall（调用后结束轮次）、alwaysActive（始终启用）、getStateDigest、formatStateDigestDiff、StateDigest、onToolExecute、stepProviderOptions、prepareStep、maxHistoryMessages、classifyUserIntent、extractLastUserText、MIN_VIEWPORT_BIAS_ZOOM、monitorAnalysis、getDefaultToolPrompts、TOOLS_BY_DATASET_KIND、loadWorkerLibrarySource、sandbox timeout（沙箱超时）、allowMainThreadFallback（允许回退到主线程）、getCodeExecutionMode、CodeExecutionMode、sandbox CSP（沙箱 CSP）、privacy（隐私）、personal data（个人数据）、GDPR、DPA、data retention（数据保留）
直接读取 ${CLAUDE_SKILL_DIR}/docs/<filename> — 路径是固定的，无需搜索步骤；${CLAUDE_SKILL_DIR} 会解析为此技能的安装位置。对于涉及多个主题的任务，请读取多个文件。

---

基础设置

npm i @tomtom-org/maps-sdk

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

---

全局约定

• 坐标：[longitude, latitude] — 经度在前（GeoJSON 顺序）
• 地点、路线、范围、几何图形和交通服务返回 GeoJSON：Place = Feature<Point>，Places = FeatureCollection<Point>；getPlaceDetails 返回一个 Place 或 undefined，reverseGeocode 返回一个 Place 或不含 properties 的查询点（检查 properties 以缩小类型范围），geometryData 返回多边形。非 GeoJSON：getPOICategories、getPOICategoryCodes 和 getSearchSuggestions
• 地图模块为异步模块：对于数据所有的模块（Places、Routing、Geometries、ReachableRanges、CustomGeoJSON、TrafficIncidentDetails、TrafficAreaAnalytics — 每次调用都创建一个新的独立实例），使用 await Module.create(map)；对于样式所有的模块（BaseMap、POIs、TrafficFlow、TrafficIncidents、Terrain、StylingFoundations — 共享控制器），使用 await Module.get(map)
• 如果没有结果，geocodeOne() 会抛出异常 — 不确定时请使用 geocode()
• 如果没有结果，discoverOnePlace() 会抛出异常 — 不确定时请使用 discoverPlaces()
• geocode、geocodeOne、discoverPlaces 和 discoverOnePlace 使用相同的参数格式 — 参见 places.md § 搜索 → 在地图上显示
• 服务可在 Node.js 中运行 — 无需浏览器或地图
• 地图容器 CSS：地图 div 以及 html, body 都需要显式设置高度（height: 100% 或 100vh）和 margin: 0 — 否则地图会以零高度渲染。回答中始终包含完整的 HTML + CSS 样板，而不只是 TypeScript。
• 优先使用 SDK，再使用 MapLibre：map.mapLibreMap 是真正的 MapLibre Map，因此任何 MapLibre API、控件或插件都可使用 — 但只要有对应的 SDK 功能，就应优先使用：它能在 setStyle 和样式升级后继续工作、协调事件，并遵循地图主题。自定义 GeoJSON 应通过 CustomGeoJSONModule（custom.md）添加，即使只有一个图层也一样；原生 addSource/addLayer 仅用于瓦片叠加层。哪些 SDK 功能可替代哪些原生调用：参见 maplibre.md § 优先使用 SDK。
• 图层位置：MapLibre 的 beforeId 会将原生图层插入到任意样式图层下方，但应使用来自 @tomtom-org/maps-sdk/map 的 mapStyleLayerIDs 锚点 — 它们在不同样式间保持稳定；CustomGeoJSONModule 在 beforeLayerConfig 中接收其键名。默认将线条和多边形放置在 mapStyleLayerIDs.lowestLabel 处，确保所有标签都显示在其上方（这是 SDK 自身的默认值）；点和标记放在最上层，无需锚点。锚点表见 maplibre.md（原生 addLayer）和 custom.md（CustomGeoJSONModule 规格）。
• 为事件处理程序提供可见的 UI 反馈（提示、面板、信息栏） — 不要只使用 console.log。构建真实、可用且用户能够看到并交互的 UI。

---

第 2 步：集成预览功能前先确认

此步骤适用于所有 SDK 功能，无论它是服务、地图模块、实用工具、Agent 工具还是插件。以下情况表示某项功能尚未正式发布：

• 文档中有说明：文档或其对应章节顶部有 Public preview 或 Private preview 提示，或者函数、模块、工具或插件名称旁标注了 “public preview” 或 “private preview”。在 node_modules 中，软件包 README 会在简介部分下方注明此信息；应用程序的入口类或工厂的 TSDoc 会链接到 Public Preview 或 Private Preview。
• 随低于 1.0.0 的插件提供：版本为 0.x 的 @tomtom-org/maps-sdk-plugin-* 软件包处于 Public Preview，即使其文档没有相关说明；如果文档有说明，则处于 Private Preview。
• 基于预览功能构建：调用 Private Preview 服务的 Agent 工具也处于 Private Preview。

当开发者要求你将此类功能集成到其应用程序中，也就是编写或修改使用该功能的代码时，请在编写代码前停下。回答有关该功能的问题无需确认。如果一个请求涉及多个此类功能，例如依赖地图主题插件的 Agent 工具包，请在一条通知中列出所有功能，并注明各自所处的阶段。

向开发者展示以下通知，填入功能名称、阶段和该阶段的条款（https://docs.tomtom.com/legal/public-preview 或 https://docs.tomtom.com/legal/private-preview），然后询问是否继续并等待答复：

<feature> 处于 <Public | Private> Preview（条款）。

• TomTom 可以更改或撤回此功能，且无需像正式发布的功能那样提前通知，因此基于该功能构建的代码可能需要在后续版本中修改。
• 仅限 Private Preview： Freemium 和 Pay As You Grow API 密钥无法使用此功能。你的密钥需要获得 TomTom Sales 授予的访问权限，否则该功能会按照文档中的说明失败。

是否要继续使用此功能？

• 是：继续执行第 3 步。每个功能在一次对话中只询问一次。
• 否，或未答复：不使用该功能。继续处理请求的其余部分；如果没有剩余内容，则停止。

第 3 步：作答

说明相关导入，套用文档中的模式，并指出注意事项。然后编写代码。提供完整的 HTML、CSS 和 TypeScript，而不只是 TypeScript。