@maptec/cli 1.0.0

package/skills/jsapi-skills/references/place-search.md

@@ -0,0 +1,411 @@
+# Maptec PlaceSearch Reference
+
+本文件对应功能 **POI检索**：面向 POI 检索场景，支持关键词检索、周边检索、类型检索、详情检索。
+
+| 用户需求 | 优先实现 |
+|---|---|
+| “搜索新加坡所有咖啡馆并标注在地图上” | `PlaceSearch.search`，`keyword`/`type: "Cafe"`，分页，Marker 渲染 |
+| “乌节路附近的餐厅” | 先地理编码乌节路，再 `searchNearby`，`types: "Restaurant"` |
+| “搜索某个地点详情” | 先搜索获得 `placeId`，再详情检索 |
+| “搜索框输入建议” | `suggest` / autocomplete 能力 |
+
+## 检索功能与适用场景
+
+| 功能 | 适用场景 |
+|---|---|
+| 关键词检索 | 用户输入明确地点名、品牌名、商户名或自然语言关键词时使用，例如“搜索 Starbucks”“搜索新加坡国立大学”。 |
+| 类型检索 | 用户按 POI 类别查找地点时使用，例如“搜索咖啡馆”“搜索新加坡所有餐厅”。需要传入最接近的 `type`，并按分页获取更多结果。 |
+| 周边检索 | 用户要求“附近”“周边”“指定半径内”地点时使用，例如“乌节路附近的餐厅”“当前位置 3 公里内的酒店”。必须提供 `locationLimit.center`，可配置 `radius` 和 `types`。 |
+| 详情检索 | 已获得 `placeId` 后，需要查询地点详情时使用，例如展示电话、地址、营业时间、照片、摘要等更完整信息。 |
+
+## When To Use Which Search
+
+| User scenario | Use | Required parameters |
+|---|---|---|
+| "Search Starbucks", "标记新加坡国立大学" | Text search | `keyword`, `region` |
+| "Show restaurants in Thailand", "泰国所有餐厅" | Type search | `keyword`, `region`, `type` |
+| "Restaurants near me", "周边 3km 餐厅" | Nearby search | `locationLimit.center`, `locationLimit.radius`, optional `types`, `region` |
+| "POIs inside this area" | Bounded/range search | `keyword`, `region`, `locationLimit` bounds |
+| "All / as many as possible" | Search plus pagination | `nextPageToken`, `pageToken`, `pageSize`, max pages |
+| "Search box autocomplete", "搜索框输入建议" | Suggest | `query`, optional `sessionToken`, `types`, `locationBias` |
+| "Show details for this POI", "查看地点详情" | Place details | `placeId`, optional `sessionToken`, `language`, `region` |
+
+## Region Selection
+
+Use `new Maptec.PlaceSearch({ region })`.
+
+Common region codes:
+- Singapore: `sg`
+- Thailand: `th`
+- Japan: `jp`
+- South Korea: `kr`
+- Malaysia: `my`
+- Indonesia: `id`
+- Vietnam: `vn`
+- China: `cn`
+- United States: `us`
+- United Kingdom: `gb`
+
+If the user does not specify a location, ask a clarifying question or use the product default only if the product already defines one.
+
+## POI Type Mapping
+
+Use the closest supported `type` value from `references/poi-categories.md`. Do not invent unsupported values.
+
+Important rules:
+
+- `search(keyword, options, callback)` uses singular `type`.
+- `searchNearby(options, callback)` uses comma-separated `types`.
+- Do not pass broad natural-language labels as type values. For example, do not use `school`, `restaurant`, `hotel`, `parking`, `cafe`, `tourist_attraction` unless that exact value is confirmed in `poi-categories.md`.
+- If the user gives an exact place name, brand, campus, landmark or address, prefer keyword search without `type`; type filtering can accidentally remove the correct POI.
+- If a type-filtered request returns `ZERO_RESULTS`, retry the same keyword without `type/types`, then report that the category filter was too restrictive.
+
+Common mappings:
+
+- 大学 / university / college: `College_University`
+- 中学: `Middle_School`
+- 小学: `Primary_School`
+- 幼儿园: `Kindergarten`
+- 培训机构: `Training_Institution`
+- 餐厅 / 餐馆 / restaurant: `Restaurant`
+- 咖啡 / cafe: `Cafe`
+- 酒店 / hotel: `Hotels`、`Star_Rated_Hotel`、`Budget_Hotel_Chain`、`Luxury_Hotel`
+- 停车场 / parking: `Parking`、`Indoor_Parking`、`Outdoor_Parking`、`Roadside_Parking`
+- 加油站 / gas station: `Gas_Station`
+- 充电站 / EV charging: `Ev_Charging_Station`
+- 地铁站 / MRT / subway: `Subway_Light_Rail_Station`
+- 火车站: `Train_Station`
+- 公交站: `Bus_Stop`
+- 机场: `Airport`
+- 医院 / hospital: `General_Hospital`、`Specialized_Hospital`、`Emergency_Center`
+- 诊所 / clinic: `Clinics`、`Private_Clinic`、`Community_Clinic`、`Dental_Clinic`
+- 药房 / pharmacy: `Pharmacy`
+- 银行 / bank: `Bank`
+- ATM: `Atm`
+- 商场 / mall: `Shopping_Mall`、`Shopping_Center`
+- 超市 / supermarket: `Supermarket`
+- 便利店: `Convenience_Store`
+- 景点 / attraction: `Tourism_Culture`、`Historic_Site`、`Observation_Deck`
+- 公园: `Urban_Park`、`National_Park`、`Nature_Reserve`
+- 博物馆: `Museum`
+- 图书馆: `Library`
+- 健身房: `Gym`
+
+## Service And Option Types
+
+`PlaceSearchOptions` for constructor defaults:
+
+- `language?: string`. Default `"en"`.
+- `region?: string`. ccTLD region code.
+- `timeout?: number`. Default `10000`.
+
+`PlaceSearchTextOptions` for `search(keyword, options, callback)`:
+
+- `language?: string`
+- `region?: string`
+- `type?: string`. Single POI category.
+- `locationBias?: PlaceSearchLocationArea`. Bias results; mutually exclusive with `locationLimit`.
+- `locationLimit?: PlaceSearchLocationArea`. Restrict results; mutually exclusive with `locationBias`.
+- `rank?: "RELEVANCE" | "DISTANCE" | "POPULARITY"`. Default `"POPULARITY"`.
+- `pageSize?: number`. Range `[1, 20]`, default `20`.
+- `pageToken?: string`. Request next page.
+
+`PlaceSearchTextResult`:
+
+- `status: string`. Typical values include `"OK"`, `"ZERO_RESULTS"`, `"ERROR"`.
+- `places?: PlaceSearchPlace[] | null`.
+- `nextPageToken?: string | null`. Use this as `pageToken` for the next request.
+- `error?: { code: string; message: string } | null`.
+
+`PlaceSearchNearbyOptions` for `searchNearby(options, callback)`:
+
+- `locationLimit: { center: LngLatLike; radius?: number }`. Required circular search area, radius default `500` meters.
+- `types?: string`. Comma-separated type list, for example `"hotel,restaurant"`.
+- `resultLimit?: number`. Range `[1, 20]`, default `20`.
+- `rank?: "RELEVANCE" | "DISTANCE" | "POPULARITY"`. Default `"DISTANCE"`.
+- `language?: string`
+- `region?: string`
+
+`PlaceSearchNearbyResult`:
+
+- `status: string`.
+- `places?: PlaceSearchPlace[] | null`.
+- `error?: { code: string; message: string } | null`.
+
+`PlaceSearchLocationArea` can be either:
+
+- `LngLatBoundsLike`: rectangle, for example `[[103.8, 1.3], [103.9, 1.4]]`.
+- `{ center: LngLatLike; radius: number }`: circle, radius in meters. Radius defaults to `500` meters where the option allows it.
+
+`PlaceSearchPlace` common fields:
+
+- `id: string`、`name: string`、`displayName: { text: string; languageCode: string }`、`formattedAddress: string`、`location: { latitude: number; longitude: number }`、`types: string[]`、`viewport: { northeast: { latitude: number; longitude: number }; southwest: { latitude: number; longitude: number } }`、`phoneNumber: string`、`openingHours`、`photos`、`summary: { text: string; languageCode: string }`。
+
+> **重要**：`location` 是 `{ latitude, longitude }` 对象，直接取值即可。不要把 `location` 写成 `geometry.location`——后者是 Google Maps API 的结构，Maptec 中不存在。
+
+Callback types:
+
+- `PlaceSearchCallback = (error?, result?) => void`, result type `PlaceSearchTextResult`.
+- `PlaceSearchNearbyCallback = (error?, result?) => void`, result type `PlaceSearchNearbyResult`.
+- `PlaceSearchDetailsCallback = (error?, result?) => void`, result type `PlaceSearchDetailsResult`.
+- `PlaceSearchSuggestCallback = (error?, result?) => void`, result type `PlaceSearchSuggestResult`.
+
+## Text Search
+
+Use `search(keyword, callback)` or `search(keyword, options, callback)` for keyword/type search.
+
+```js
+const placeSearch = new Maptec.PlaceSearch({
+  language: "zh-CN",
+  region: "sg"
+});
+
+placeSearch.search("restaurant", {
+  type: "Restaurant",
+  region: "sg",
+  language: "zh-CN",
+  pageSize: 20,
+  rank: "POPULARITY"
+}, (error, result) => {
+  if (error) return console.error(error);
+  const places = result?.places || [];
+  console.log(places);
+});
+```
+
+Use `locationBias` to bias results near an area, and `locationLimit` to restrict results to an area. They are mutually exclusive.
+
+```js
+placeSearch.search("hotel", {
+  locationBias: {
+    center: [103.8198, 1.3521],
+    radius: 5000
+  },
+  rank: "DISTANCE"
+}, callback);
+
+placeSearch.search("restaurant", {
+  locationLimit: [[103.8, 1.3], [103.9, 1.4]]
+}, callback);
+```
+
+## Type Search Template
+
+Use this when the user asks for category results in a region, such as "泰国所有餐厅".
+
+```html
+<script>
+Maptec.apiKey = "YOUR_MAPTEC_KEY";
+
+const map = new Maptec.Map({
+  container: "map",
+  style: "https://test-api.maptec.com/maps/v1/styles?style_id=style_00001",
+  center: [100.5018, 13.7563],
+  zoom: 6
+});
+
+map.on("load", () => {
+  const search = new Maptec.PlaceSearch({ region: "th" });
+  const renderLimit = 80;
+  const collectedPlaces = [];
+  const renderedKeys = new Set();
+
+  const toLngLat = (location) => {
+    if (!location) return null;
+    if (Array.isArray(location)) return location;
+    const lng = location.longitude ?? location.lng ?? location.lon;
+    const lat = location.latitude ?? location.lat;
+    return lng == null || lat == null ? null : [lng, lat];
+  };
+
+  const getNextPageToken = (result) =>
+    result?.nextPageToken || result?.next_page_token || result?.pageToken || result?.nextToken;
+
+  const mergeUniquePlaces = (places) => {
+    const seen = new Set(collectedPlaces.map((place) => {
+      const position = toLngLat(place.location);
+      return `${place.id || place.placeId || place.name}:${position?.[0]},${position?.[1]}`;
+    }));
+
+    places.forEach((place) => {
+      const position = toLngLat(place.location);
+      const key = `${place.id || place.placeId || place.name}:${position?.[0]},${position?.[1]}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        collectedPlaces.push(place);
+      }
+    });
+  };
+
+  const renderMarkers = () => {
+    collectedPlaces.slice(0, renderLimit).forEach((place) => {
+      const position = toLngLat(place.location);
+      if (!position) return;
+      const markerKey = `${place.id || place.placeId || place.name}:${position[0]},${position[1]}`;
+      if (renderedKeys.has(markerKey)) return;
+      renderedKeys.add(markerKey);
+
+      const title = place.displayName?.text || place.name || "Unknown place";
+      const address = place.formattedAddress || place.address || "";
+      const type = place.types?.[0] || "";
+      const popup = new Maptec.Popup({
+        offset: 25,
+        html: `<div style="padding: 5px;">
+          <strong style="font-size: 14px;">${title}</strong><br>
+          <small style="color: #666;">${address}</small>
+          ${type ? `<br><small style="color: #999;">${type}</small>` : ""}
+        </div>`
+      });
+      map.addOverlay(new Maptec.Marker({ position, popup }));
+    });
+  };
+
+  const loadPage = (pageToken) => {
+    const options = pageToken
+      ? { type: "Restaurant", language: "zh-CN", region: "th", pageSize: 20, pageToken }
+      : { type: "Restaurant", language: "zh-CN", region: "th", pageSize: 20 };
+
+    search.search("餐厅", options, (error, result) => {
+      if (error) {
+        console.error("PlaceSearch failed", error);
+        return;
+      }
+
+      mergeUniquePlaces(result?.places || []);
+      renderMarkers();
+
+      const nextPageToken = getNextPageToken(result);
+      if (nextPageToken && collectedPlaces.length < renderLimit) {
+        loadPage(nextPageToken);
+      }
+    });
+  };
+
+  loadPage();
+});
+</script>
+```
+
+## Nearby Search Template
+
+Use this when the user explicitly asks for nearby/radius/range. `searchNearby` receives one options object; it does not receive a keyword as the first argument.
+
+```js
+const search = new Maptec.PlaceSearch({ region: "sg" });
+
+search.searchNearby({
+  locationLimit: {
+    center: [103.8198, 1.3521],
+    radius: 3000
+  },
+  types: "restaurant",
+  resultLimit: 20,
+  language: "zh-CN"
+}, (error, result) => {
+  if (error) return console.error(error);
+  const places = result?.places || [];
+  // Render with Maptec.Marker + Maptec.Popup.
+});
+```
+
+## Suggest Search
+
+Use `suggest(options, callback)` for autocomplete/search-box suggestions. Use the same `sessionToken` for the user typing session and the subsequent detail lookup when applicable.
+
+`PlaceSearchSuggestOptions`:
+
+- `query: string`.
+- `language?: string`. Default `"en"`.
+- `region?: string`. Default `"SG"` in the SDK docs.
+- `types?: string`. Comma-separated types, for example `"restaurant,cafe"`.
+- `resultLimit?: number`. Range `[1, 20]`, default `20`.
+- `sessionToken?: string`.
+- `locationBias?: PlaceSearchLocationArea`.
+- `locationLimit?: PlaceSearchLocationArea`.
+
+`PlaceSearchSuggestResult`:
+
+- `status: string`.
+- `suggestions?: PlaceSearchSuggestion[] | null`.
+- `error?: { code: string; message: string } | null`.
+
+`PlaceSearchSuggestion`:
+
+- `placeId: string`.
+- `placeName: string`.
+- `text?: { languageCode: string; text: string } | null`.
+
+```js
+const sessionToken = crypto.randomUUID();
+
+placeSearch.suggest({
+  query: "rest",
+  sessionToken,
+  types: "restaurant,cafe",
+  resultLimit: 10,
+  region: "SG",
+  locationBias: {
+    center: [103.8198, 1.3521],
+    radius: 5000
+  }
+}, (error, result) => {
+  if (error) return console.error(error);
+  const suggestions = result?.suggestions || [];
+  console.log(suggestions.map((item) => item.text?.text));
+});
+```
+
+## Place Details
+
+Use `getPlaceDetails(options, callback)` when you already have a `placeId` from `search`, `searchNearby`, or `suggest` and need richer place information.
+
+`PlaceSearchDetailsOptions`:
+
+- `placeId: string`. Required.
+- `language: string`. Use when you need localized details.
+- `region: string`. Use when you need regional bias/context.
+- `sessionToken: string`. Use the same token from `suggest` when details are selected from autocomplete.
+
+`PlaceSearchDetailsResult`:
+
+- `status: string`.
+- `places?: PlaceSearchPlace | null`. Details returns a single place object, not an array.
+- `error?: { code: string; message: string } | null`.
+
+```js
+placeSearch.getPlaceDetails({
+  placeId: "osm-node-10004862482_v0.1",
+  sessionToken,
+  language: "zh-CN",
+  region: "SG"
+}, (error, result) => {
+  if (error) return console.error(error);
+  const place = result?.places;
+  console.log(place?.displayName?.text, place?.formattedAddress, place?.phoneNumber);
+});
+```
+
+## Known Pitfalls
+
+- **字段名 `places` 而非 `results`**：`PlaceSearchTextResult` 和 `PlaceSearchNearbyResult` 的结果数组字段是 `places`，不是 `results`。不要写成 `result.results`，这是 Google Maps API 的字段名，Maptec 中不存在。
+- **字段名 `location` 而非 `geometry.location`**：`PlaceSearchPlace` 的坐标字段是 `location`，直接包含 `latitude` 和 `longitude` 属性。不要写成 `place.geometry?.location`，这是 Google Maps API 的结构，Maptec 中不存在。正确用法：`place.location.latitude`、`place.location.longitude`，或使用 `toLngLat(place.location)` 辅助函数转为 `[lng, lat]`。
+- A single text search page returns at most `pageSize` results, with documented range `[1, 20]`. Use `nextPageToken` from the result as `pageToken` for broad requests.
+- Nearby search returns at most `resultLimit` results, with documented range `[1, 20]`.
+- `nextPageToken` is for pagination, not for choosing the search type.
+- `type` is what makes text search category/type constrained; `types` is used by nearby search.
+- Do not use `locationBias` for a whole-country category search unless the user asked for biasing near a location.
+- Use `locationLimit` for nearby/radius search and bounded search.
+- Do not pass a keyword to `searchNearby`; nearby search is `searchNearby(options, callback)`.
+- Do not treat details result `places` as an array; `PlaceSearchDetailsResult.places` is a single `PlaceSearchPlace | null`.
+- Keep the same `sessionToken` across `suggest` and `getPlaceDetails` for one autocomplete session when using interactive search.
+- Do not reuse Singapore defaults for Thailand, China, or other regions. The `region`, map center, and zoom must match the user's requested geography.
+- Do not render fake markers for real-world search results. If `PlaceSearch` returns no valid coordinates, show the failure or empty state.
+- If the SDK does not return any pagination token, state that only one page can be rendered from the front end.
+- Keep generated code and actual map rendering logic identical.
+
+## Agent 规则
+
+- 真实 POI 必须来自 `Maptec.PlaceSearch` 返回结果，不要伪造咖啡馆、餐厅、酒店、地址或坐标。
+- 关键词检索和类型检索使用 `search(keyword, options, callback)`；周边检索使用 `searchNearby(options, callback)`。
+- “全部”“尽可能多”等需求必须说明分页、前端渲染上限和 `nextPageToken` 限制。
+- 结果为空、服务错误、坐标缺失时必须显式处理，不要渲染假 Marker。

package/skills/jsapi-skills/references/poi-categories.md

@@ -0,0 +1,123 @@
+# POI 类目补充
+
+当用户要求按类别检索 POI，或者需要填写 `PlaceSearch.search` 的 `type` / `PlaceSearch.searchNearby` 的 `types` 时，使用本参考。
+
+## 参数规则
+
+- 文本检索：`placeSearch.search(keyword, { type }, callback)`，`type` 为单个类目值。
+- 周边检索：`placeSearch.searchNearby({ locationLimit, types }, callback)`，`types` 为逗号分隔类目值。
+- 类目值必须使用本文件确认的英文枚举，大小写保持一致。
+- 不要使用未确认的通用词作为类型，例如 `school`、`restaurant`、`hotel`、`parking`、`cafe`、`tourist_attraction`。
+- 用户输入明确地点名、品牌、校区、地标或地址时，优先只用关键词检索；不确定类目时不要强塞 `type/types`。
+- 如果带 `type/types` 返回 `ZERO_RESULTS`，应使用同一关键词去掉类型过滤重试。
+
+## 常用映射
+
+| 用户表达 | 推荐 type/types |
+|---|---|
+| 大学、学院、university、college | `College_University` |
+| 中学 | `Middle_School` |
+| 小学 | `Primary_School` |
+| 幼儿园 | `Kindergarten` |
+| 培训机构 | `Training_Institution` |
+| 餐厅、餐馆、restaurant | `Restaurant` |
+| 咖啡馆、咖啡、cafe | `Cafe` |
+| 酒店、hotel | `Hotels`；细分可用 `Star_Rated_Hotel`、`Budget_Hotel_Chain`、`Luxury_Hotel`、`Resort` |
+| 停车场、parking | `Parking`；细分可用 `Indoor_Parking`、`Outdoor_Parking`、`Roadside_Parking` |
+| 加油站、gas station | `Gas_Station` |
+| 充电站、EV charging | `Ev_Charging_Station` |
+| 地铁站、MRT、subway | `Subway_Light_Rail_Station` |
+| 火车站 | `Train_Station` |
+| 公交站 | `Bus_Stop` |
+| 机场 | `Airport` |
+| 医院、hospital | `General_Hospital`；细分可用 `Specialized_Hospital`、`Emergency_Center` |
+| 诊所、clinic | `Clinics`；细分可用 `Private_Clinic`、`Community_Clinic`、`Dental_Clinic` |
+| 药房、pharmacy | `Pharmacy` |
+| 银行、bank | `Bank` |
+| ATM | `Atm` |
+| 商场、购物中心、mall | `Shopping_Mall`；泛化可用 `Shopping_Center` |
+| 超市、supermarket | `Supermarket` |
+| 便利店 | `Convenience_Store` |
+| 公园 | `Urban_Park`；细分可用 `National_Park`、`Nature_Reserve` |
+| 博物馆 | `Museum` |
+| 图书馆 | `Library` |
+| 健身房 | `Gym` |
+
+## 一级类目
+
+- `Transport_Mobility`：交通设施。
+- `Entertainment_Leisure`：休闲娱乐。
+- `Accommodation`：住宿服务。
+- `Corporations_Industry`：公司企业。
+- `Health_Medical`：医疗保健。
+- `Residential`：房产住宅。
+- `Tourism_Culture`：旅游与文化。
+- `Government_Organizations`：机构团体。
+- `Automotive_Services`：汽车服务。
+- `Services_Daily_Life`：生活服务。
+- `Geography`：自然地理。
+- `Shopping_Retail`：购物零售。
+- `Sports_Fitness`：运动健身。
+- `Food_Drink`：餐饮美食。
+
+## 交通设施
+
+- 停车服务：`Parking`、`Park_And_Ride`、`Indoor_Parking`、`Roadside_Parking`、`Outdoor_Parking`
+- 公路客运：`Bus_Coach`、`Bus_Stop`、`Tourist_Bus_Station`、`Coach_Station`
+- 水路出行：`Water_Transport`、`Port_Wharf`、`Marina`、`Ferry_Terminal`
+- 空港出行：`Air_Travel`、`Airport`、`Airport_Bus_Stop`、`Helipad`
+- 能源补给：`Energy_Facilities`、`Gas_Refill_Station`、`Gas_Station`、`Battery_Swap_Station`、`Ev_Charging_Station`
+- 铁路出行：`Rail_Transport`、`Entrance_Exit`、`Ticket_Office`、`Subway_Light_Rail_Station`、`Tram_Stop`、`Train_Station`
+
+## 休闲娱乐与住宿
+
+- 主题乐园：`Theme_Parks`、`Zoo`、`Botanical_Garden`、`Water_Park`、`Aquarium`、`Amusement_Park`
+- 休闲场所：`Recreation`、`Ktv`、`Escape_Room_Larp`、`Chess_Card_Room`、`Arcade`、`Internet_Cafe_Esports`
+- 影剧院：`Cinema_Theater`、`Theater`、`Opera_House`、`Cinema`、`Concert_Hall`
+- 放松疗养：`Wellness`、`Spa`、`Bath_Center_Sauna`、`Beauty_Salon`、`Foot_Massage`
+- 住宿服务：`Accommodation`、`Rv_Park`、`Campground`、`Inn`、`Homestay_Short_Term_Rental`、`Motel`、`Hostel`、`Hotels`、`Resort`、`Star_Rated_Hotel`、`Budget_Hotel_Chain`、`Luxury_Hotel`
+
+## 医疗、教育与公共机构
+
+- 医疗保健：`Health_Medical`、`Medical_Examination_Center`、`Veterinary_Clinic`、`Blood_Donation_Station`、`Pharmacy`、`Hospitals`、`Specialized_Hospital`、`Emergency_Center`、`General_Hospital`、`Clinics`、`Psychological_Counseling`、`Dental_Clinic`、`Community_Clinic`、`Private_Clinic`
+- 教育机构：`Education`、`Middle_School`、`Training_Institution`、`College_University`、`Primary_School`、`Kindergarten`、`Driving_School`
+- 政府机关：`Government`、`Embassy_Consulate`、`City_Hall_Government_Office`、`Courthouse`、`Fire_Station`、`Police_Station`
+- 社会团体：`Social_Orgs`、`Association_Society`、`Welfare_House_Nursing_Home`、`Ngo`
+
+## 旅游文化、自然地理与运动
+
+- 公园广场：`Parks_Plazas`、`National_Park`、`Urban_Park`、`Nature_Reserve`、`Street_Plaza`
+- 博览场馆：`Museums_Galleries`、`Museum`、`Library`、`Planetarium`、`Archives`、`Science_Museum`、`Art_Gallery`
+- 名胜古迹：`Landmarks`、`World_Heritage`、`Historic_Site`、`Historic_Building`、`Monument_Statue`、`Observation_Deck`
+- 宗教场所：`Religious_Places`、`Temple`、`Church`、`Mosque`、`Shrine`、`Taoist_Temple`
+- 自然地理：`Geography`、`Island`、`River`、`Beach_Coastline`、`Lake`、`Peak`、`Forest`、`Desert`
+- 运动健身：`Sports_Fitness`、`Bowling_Alley`、`Climbing_Gym`、`Ski_Resort`、`Tennis_Court`、`Badminton_Court`、`Golf_Course`、`Swimming_Pool`、`Basketball_Court`、`Stadium`、`Soccer_Field`、`Gym`、`Yoga_Pilates_Studio`、`Dance_Studio`
+
+## 购物、生活与公司服务
+
+- 购物中心：`Shopping_Centers`、`Duty_Free_Shop`、`Pedestrian_Street`、`Outlets`、`Department_Store`、`Shopping_Center`、`Shopping_Mall`
+- 超市便利：`Groceries`、`Convenience_Store`、`Supermarket`、`Organic_Food_Store`、`Community_Supermarket`、`Market`
+- 服饰鞋包：`Fashion_Accessories`、`Clothing_Store`、`Jewelry_Store`、`Luggage_Leather_Goods`、`Sports_Brand_Store`、`Watch_Shop`、`Shoe_Hat_Store`
+- 家居建材：`Home_Garden`、`Hardware_Store`、`Furniture_Store`、`Home_Decor`、`Building_Materials_Market`、`Flower_Shop_Garden_Center`
+- 生活服务：`Services_Daily_Life`、`Public_Toilet`、`Real_Estate_Agency`、`Laundry`、`Photo_Studio`、`Barber_Shop`、`Repair_Shop`
+- 商务服务：`Business`、`Conference_Center`、`Coworking_Space`、`Consulting_Firm`、`Law_Firm`、`Travel_Agency`
+- 金融服务：`Financial`、`Atm`、`Insurance_Company`、`Currency_Exchange`、`Bank`
+- 公司办公：`Corporations_Industry`、`Offices`、`Corporate_Headquarters`、`Office_Building`、`Industrial_Park`
+
+## 餐饮美食
+
+- 中餐：`Chinese_Cuisine`、`Chinese_Fast_Food`、`Northern_Chinese_Cuisine`、`Sichuan_Cuisine`、`Dim_Sum`、`Halal_Lanzhou_Lamian`、`Hunan_Cuisine`、`Hot_Pot`、`Cantonese_Cuisine`、`General_Chinese_Cuisine`
+- 亚洲餐厅：`Asian_Cuisine`、`Southeast_Asian_Cuisine`、`Indian_Cuisine`、`Japanese_Cuisine`、`Thai_Cuisine`、`Vietnamese_Cuisine`、`Korean_Cuisine`
+- 咖啡茶饮：`Cafe_Tea_Dessert`、`Ice_Cream_Shop`、`Cafe`、`Milk_Tea_Juice_Shop`、`Dessert_Cake_Shop`、`Teahouse`、`Bakery`
+- 快餐小吃：`Fast_Food_Snacks`、`Sandwich_Shop`、`Branded_Fast_Food`、`Salad_Light_Meal`、`Fried_Chicken_Shop`、`Deli`、`Street_Food`
+- 西餐：`Western_Cuisine`、`Turkish_Kebab`、`Mexican_Latin_American_Cuisine`、`German_Cuisine`、`Italian_Cuisine`、`French_Cuisine`、`American_Cuisine`、`Spanish_Cuisine`
+- 通用餐饮：`Dining_General`、`Restaurant`
+- 酒吧夜生活：`Bars_Nightlife`、`Night_Club`、`Izakaya`、`Lounge_Bar`、`Craft_Beer_Bar`、`Bar_Pub`、`Cocktail_Bar`
+
+## Agent 规则
+
+- 用户明确输入类目英文枚举时，按原样使用；只修正明显大小写错误。
+- 中文类目要映射到最具体的英文枚举；例如“大学”使用 `College_University`，不是 `school`。
+- 用户只说“学校”且无法判断学段时，可以不用 `type`，或询问用户要大学/中学/小学/幼儿园。
+- 用户只说“餐饮/吃饭”时，优先用 `Restaurant`；如果用户说咖啡、茶饮、甜品、快餐、火锅等，使用更具体类目。
+- 对精准地点名、品牌名、校区名、地标名，不要默认增加类型过滤；类型过滤只用于“按类别找一批地点”的需求。

package/skills/jsapi-skills/references/popup.md

@@ -0,0 +1,146 @@
+# 信息窗口能力参考
+
+当用户要求打开信息窗口、点击地图显示经纬度、Marker 绑定气泡、展示 POI 信息或自定义弹窗内容时，使用本参考。
+
+## 能力范围
+
+- 创建 `Maptec.Popup`。
+- 设置位置、HTML、纯文本、偏移、宽度、关闭行为。
+- 作为独立信息窗口添加到地图。
+- 绑定到 `Maptec.Marker`。
+- 监听打开、关闭事件。
+
+## 点击地图增加信息窗口展示经纬度
+
+```js
+let popup = null;
+
+const onMapClick = (event) => {
+  const position = Maptec.LngLat.convert(event.lngLat).toArray();
+  const text = `经度：${position[0].toFixed(6)}，纬度：${position[1].toFixed(6)}`;
+
+  if (!popup) {
+    popup = new Maptec.Popup({
+      position,
+      text,
+      closeButton: true,
+      closeOnClick: false
+    });
+    map.addOverlay(popup);
+  } else {
+    popup.position = position;
+    popup.text = text;
+  }
+};
+
+map.on("click", onMapClick);
+
+function cleanup() {
+  map.off("click", onMapClick);
+  if (popup) {
+    map.removeOverlay(popup);
+    popup.destroy?.();
+  }
+}
+```
+
+## 基础信息窗口
+
+```js
+const popup = new Maptec.Popup({
+  position: [103.8198, 1.3521],
+  html: "<strong>Singapore</strong>",
+  offset: [0, -15],
+  maxWidth: "300px",
+  closeButton: true,
+  closeOnClick: true
+});
+
+map.addOverlay(popup);
+```
+
+## Marker 绑定信息窗口
+
+```js
+const popup = new Maptec.Popup({
+  offset: 25,
+  html: "<strong>National University of Singapore</strong>"
+});
+
+const marker = new Maptec.Marker({
+  position: [103.7764, 1.2966],
+  color: "#2563eb",
+  popup
+});
+
+map.addOverlay(marker);
+```
+
+## 常用配置
+
+- `position`: 信息窗口坐标
+- `anchor`: 信息窗口锚点，未指定时 SDK 通常会动态调整。
+- `html`: HTML 内容
+- `text`: 纯文本内容
+- `offset`: 像素偏移
+- `maxWidth`: 最大宽度
+- `className`: 自定义样式类
+- `closeButton`: 是否显示关闭按钮
+- `closeOnClick`: 点击地图时是否关闭
+- `closeOnMove`: 地图移动时是否关闭
+- `padding`: 用于让 Popup 避开地图边缘。
+
+常用方法：
+
+- `setDOMContent(element)`
+- `getElement()`
+- `isOpen()`
+- `addClassName(className)`
+- `removeClassName(className)`
+- `destroy()`
+- `isDestroyed()`
+
+## DOM 内容
+
+用户内容来自输入、服务结果或外部数据时，优先使用 `text` 或对 HTML 做清洗。
+
+```js
+const content = document.createElement("div");
+content.textContent = "自定义 DOM 内容";
+
+const popup = new Maptec.Popup({
+  position: [103.8198, 1.3521]
+});
+
+popup.setDOMContent(content);
+map.addOverlay(popup);
+```
+
+## 事件
+
+```js
+const onOpen = () => console.log("信息窗口打开");
+const onClose = () => console.log("信息窗口关闭");
+
+popup.on("open", onOpen);
+popup.on("close", onClose);
+
+function cleanupPopupEvents() {
+  popup.off("open", onOpen);
+  popup.off("close", onClose);
+}
+```
+
+## 注意事项
+
+- 独立信息窗口必须有 `position`。
+- Marker 绑定信息窗口时，优先设置 `offset`，避免遮挡 Marker。
+- 不要把用户输入直接拼接进 `html`。
+- 清理时移除 Popup，并取消事件监听。
+
+## Agent 规则
+
+- 信息窗口必须使用 `new Maptec.Popup(...)`，并通过 `map.addOverlay(popup)` 或 Marker 绑定方式使用。
+- 展示用户输入、POI 服务结果或外部数据时，优先使用 `text` 或安全 DOM，不要直接拼接到 `html`。
+- 独立 Popup 必须提供 `position`；Marker 绑定 Popup 时应设置合理 `offset`。
+- Popup 打开、关闭事件必须保存 handler，并在清理阶段解绑。