@maptec/cli 1.0.0

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

@@ -0,0 +1,240 @@
+# 轨迹动画参考
+
+当用户要求车辆、人员、设备、船舶等图标沿路线移动，或者要求轨迹回放、暂停、继续、停止、视角跟随、相机过渡、相机绕点旋转时，使用本参考。
+
+## 能力范围
+
+`maptec-js` 已公开导出以下动画能力：
+
+- `Maptec.AnimationManager`
+- `Maptec.AnimationKeyFrameTrack`
+- `Maptec.PointKeyFrameTrack`
+- `Maptec.PolylineKeyFrameTrack`
+- `Maptec.CameraKeyFrameTrack`
+- `Maptec.CameraOrbitKeyFrameTrack`
+
+常见组合：
+
+- 使用 `PolylineOverlay` 展示完整轨迹线。
+- 使用 `PointKeyFrameTrack` 驱动 `Marker` 或 `CircleOverlay` 沿路径移动。
+- 使用 `PolylineKeyFrameTrack` 驱动 `PolylineOverlay` 逐步增长，展示行驶轨迹。
+- 使用 `CameraKeyFrameTrack` 实现镜头过渡。
+- 使用 `CameraOrbitKeyFrameTrack` 实现相机绕点旋转。
+- 真实道路路径来自路线规划时，先使用 `Driving` / `TruckDriving` 获取路线，再把路线坐标用于动画。
+
+## 基础轨迹动画
+
+```js
+const path = [
+  [103.8318, 1.3048],
+  [103.8198, 1.3521],
+  [103.7764, 1.2966]
+];
+
+const fullLine = new Maptec.PolylineOverlay({
+  positions: path,
+  strokeColor: "#c4b5fd",
+  strokeWeight: 6,
+  strokeOpacity: 0.45
+});
+
+const animatedLine = new Maptec.PolylineOverlay({
+  positions: path,
+  strokeColor: "#7c3aed",
+  strokeWeight: 6,
+  strokeOpacity: 0.95,
+  showDirection: true
+});
+
+const vehicle = new Maptec.Marker({
+  position: path[0],
+  color: "#ef4444",
+  scale: 1.1
+});
+
+map.on("load", () => {
+  map.addOverlay([fullLine, animatedLine, vehicle]);
+
+  const lineTrack = new Maptec.PolylineKeyFrameTrack(animatedLine, {
+    duration: 8,
+    interpolation: "linear"
+  });
+
+  const vehicleTrack = new Maptec.PointKeyFrameTrack(vehicle, {
+    path,
+    duration: 8,
+    interpolation: "linear",
+    autoRotate: true,
+    rotateOffset: 0
+  });
+
+  map.animation.add(lineTrack);
+  map.animation.add(vehicleTrack);
+
+  lineTrack.play();
+  vehicleTrack.play();
+});
+```
+
+## 播放控制
+
+`PointKeyFrameTrack`、`PolylineKeyFrameTrack` 等轨道继承自 `AnimationKeyFrameTrack`，常用控制方法包括：
+
+- `play()`
+- `pause()`
+- `stop()`
+- `reset()`
+
+```js
+const track = new Maptec.PointKeyFrameTrack(vehicle, {
+  path,
+  duration: 10,
+  autoRotate: true,
+  rotateOffset: 0
+});
+
+map.animation.add(track);
+
+playButton.onclick = () => track.play();
+pauseButton.onclick = () => track.pause();
+stopButton.onclick = () => {
+  track.stop();
+  track.reset();
+};
+```
+
+## 车头朝向
+
+`PointKeyFrameTrack` 支持 `autoRotate`。当移动目标是 `Marker` 时，轨道会根据路径方向设置 `marker.rotation`。如果自定义图标素材的“正前方”不是默认方向，用 `rotateOffset` 修正。
+
+```js
+const carTrack = new Maptec.PointKeyFrameTrack(carMarker, {
+  path,
+  duration: 12,
+  interpolation: "linear",
+  autoRotate: true,
+  rotateOffset: 90
+});
+```
+
+## 视图跟随轨迹
+
+可以监听轨道更新，把地图中心移动到当前 Marker 位置。高频调用时建议使用较短 `duration` 或在业务侧做节流。
+
+```js
+const track = new Maptec.PointKeyFrameTrack(droneMarker, {
+  path,
+  duration: 12,
+  autoRotate: true,
+  rotateOffset: 0
+});
+
+track.on("update", () => {
+  map.easeTo({
+    center: droneMarker.position,
+    zoom: 14,
+    duration: 180
+  });
+});
+
+map.animation.add(track);
+track.play();
+```
+
+## 镜头过渡
+
+```js
+const cameraTrack = new Maptec.CameraKeyFrameTrack([
+  { center: [103.8198, 1.3521], zoom: 11, pitch: 0, bearing: 0 },
+  { center: [103.8519, 1.2903], zoom: 15, pitch: 55, bearing: 120 }
+], {
+  duration: 8,
+  interpolation: "easeInOut"
+});
+
+map.animation.add(cameraTrack);
+cameraTrack.play();
+```
+
+## 相机绕点旋转
+
+```js
+const orbitTrack = new Maptec.CameraOrbitKeyFrameTrack({
+  duration: 10,
+  center: [103.8519, 1.2903],
+  radius: 1000,
+  startBearing: 0,
+  bearingRange: 360,
+  iteration: "INFINITE",
+  interpolation: "linear"
+});
+
+map.animation.add(orbitTrack);
+orbitTrack.play();
+```
+
+## 与路线规划结合
+
+如果用户说“沿真实驾车路线移动”“从 A 到 B 轨迹回放”，不能手写虚假路径。应先使用 `Geocode` 转换地址，再用 `Driving.search` 或 `TruckDriving.search` 获取路线。
+
+```js
+const driving = new Maptec.Driving({
+  map,
+  enableDrawRoute: true,
+  strokeColor: "#2563eb",
+  strokeWeight: 6
+});
+
+driving.search(origin, destination, (error, result) => {
+  if (error) {
+    console.error("路线规划失败", error);
+    return;
+  }
+
+  const route = result?.routes?.[0];
+  const path = route?.path || [];
+  if (path.length < 2) {
+    console.warn("路线结果没有可用于动画的轨迹坐标");
+    return;
+  }
+
+  const vehicle = new Maptec.Marker({ position: path[0] });
+  const track = new Maptec.PointKeyFrameTrack(vehicle, {
+    path,
+    duration: 15,
+    autoRotate: true
+  });
+
+  map.addOverlay(vehicle);
+  map.animation.add(track);
+  track.play();
+});
+```
+
+## 常见意图映射
+
+| 用户说法 | 实现方式 |
+|---|---|
+| “让小车图标沿路线移动” | `Marker` + `PointKeyFrameTrack` |
+| “行驶轨迹要显示出来” | `PolylineOverlay` 展示底线，`PolylineKeyFrameTrack` 驱动动画线增长 |
+| “车头一直朝轨迹方向” | `PointKeyFrameTrack({ autoRotate: true, rotateOffset })` |
+| “实现轨迹回放并支持暂停、继续、停止” | 使用轨道的 `play/pause/stop/reset` |
+| “视角跟随车辆/无人机” | 监听轨道 `update`，调用 `map.easeTo({ center })` |
+| “镜头从 A 点飞到 B 点” | `CameraKeyFrameTrack` |
+| “绕建筑或中心点旋转” | `CameraOrbitKeyFrameTrack` |
+
+## 注意事项
+
+- 不要发明 `Maptec.TrackAnimation`、`Maptec.MoveAnimation` 等未公开类。
+- 不要用手写播放循环替代 JSAPI 已提供的关键帧轨道能力。
+- 真实道路轨迹必须走路线规划结果。
+- `autoRotate` 只会在移动目标是 `Marker` 时更新 `rotation`；若图标方向不对，用 `rotateOffset` 调整。
+- 组件卸载时停止轨道并移除 Marker、PolylineOverlay 等覆盖物。
+
+## Agent 规则
+
+- 轨迹动画优先使用 `PointKeyFrameTrack`、`PolylineKeyFrameTrack` 和 `map.animation.add(track)`。
+- 轨迹线使用 `PolylineOverlay`，不要生成 `Maptec.Polyline`。
+- 移动图标使用 `Marker`；需要自动朝向时设置 `autoRotate: true` 和合适的 `rotateOffset`。
+- 用户要求真实道路轨迹时，必须先使用路线规划获取路线坐标。
+- 播放器必须提供停止或销毁逻辑，清理时停止轨道并移除轨迹线和移动 Marker。

package/skills/jsapi-skills/scripts/validate_jsapi_skill.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Validate jsapi-skills structure and public-facing guardrails."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+REQUIRED_SKILL_SECTIONS = [
+    "安装接入",
+    "鉴权",
+    "功能列表",
+    "能力路由",
+    "强约束",
+    "输出要求",
+]
+
+REQUIRED_README_SECTIONS = [
+    "简介",
+    "功能列表",
+    "安装 Skill",
+    "如何被 Agent 使用",
+]
+
+REAL_KEY_PATTERNS = [
+    re.compile(r"Maptec\.apiKey\s*=\s*[\"'](?!YOUR_|<你的|YOUR_MAPTEC_KEY)[A-Za-z0-9_-]{16,}[\"']"),
+    re.compile(r"Authorization:\s*Bearer\s+(?!\$MAPTEC_JSAPI_KEY)[A-Za-z0-9._-]{16,}"),
+]
+
+
+def line_of(text: str, index: int) -> int:
+    return text.count("\n", 0, index) + 1
+
+
+def check_frontmatter(skill_md: Path, text: str) -> list[str]:
+    findings: list[str] = []
+    if not text.startswith("---\n"):
+        return [f"{skill_md}:1: missing YAML frontmatter"]
+
+    end = text.find("\n---", 4)
+    if end == -1:
+        return [f"{skill_md}:1: malformed YAML frontmatter"]
+
+    frontmatter = text[4:end]
+    if not re.search(r"^name:\s*jsapi-skills$", frontmatter, re.M):
+        findings.append(f"{skill_md}:1: missing or invalid name")
+    if not re.search(r"^description:\s*.{40,}$", frontmatter, re.M):
+        findings.append(f"{skill_md}:1: missing or too-short description")
+    return findings
+
+
+def find_reference_links(text: str) -> set[str]:
+    return set(re.findall(r"references/[A-Za-z0-9_.-]+\.md", text))
+
+
+def check_skill_md(skill_dir: Path) -> list[str]:
+    findings: list[str] = []
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return [f"{skill_md}: missing SKILL.md"]
+
+    text = skill_md.read_text(encoding="utf-8", errors="ignore")
+    findings.extend(check_frontmatter(skill_md, text))
+
+    for section in REQUIRED_SKILL_SECTIONS:
+        if f"## {section}" not in text:
+            findings.append(f"{skill_md}:1: missing section '## {section}'")
+
+    for required in ["不要发明", "需确认", "[lng, lat]", "MAPTEC_JSAPI_KEY"]:
+        if required not in text:
+            findings.append(f"{skill_md}:1: missing required guardrail '{required}'")
+
+    for ref in find_reference_links(text):
+        if not (skill_dir / ref).exists():
+            findings.append(f"{skill_md}:1: missing referenced file {ref}")
+
+    return findings
+
+
+def check_readme(skill_dir: Path) -> list[str]:
+    findings: list[str] = []
+    readme = skill_dir / "README.md"
+    if not readme.exists():
+        return [f"{readme}: missing README.md"]
+
+    text = readme.read_text(encoding="utf-8", errors="ignore")
+    for section in REQUIRED_README_SECTIONS:
+        if f"## {section}" not in text:
+            findings.append(f"{readme}:1: missing section '## {section}'")
+
+    for ref in find_reference_links(text):
+        if not (skill_dir / ref).exists():
+            findings.append(f"{readme}:1: missing referenced file {ref}")
+
+    return findings
+
+
+def check_references(skill_dir: Path) -> list[str]:
+    findings: list[str] = []
+    refs_dir = skill_dir / "references"
+    if not refs_dir.exists():
+        return [f"{refs_dir}: missing references directory"]
+
+    refs = sorted(refs_dir.glob("*.md"))
+    if not refs:
+        return [f"{refs_dir}: no reference files"]
+
+    for ref in refs:
+        text = ref.read_text(encoding="utf-8", errors="ignore")
+        if "## Agent 规则" not in text and "## Agent Rules" not in text:
+            findings.append(f"{ref}:1: missing Agent 规则 section")
+        if "TODO" in text:
+            findings.append(f"{ref}:1: unresolved TODO")
+        for linked_ref in find_reference_links(text):
+            if not (skill_dir / linked_ref).exists():
+                findings.append(f"{ref}:1: missing referenced file {linked_ref}")
+
+    return findings
+
+
+def check_key_leaks(skill_dir: Path) -> list[str]:
+    findings: list[str] = []
+    for path in sorted(skill_dir.rglob("*")):
+        if ".git" in path.parts or "node_modules" in path.parts or not path.is_file():
+            continue
+        if path.suffix not in {".md", ".yaml", ".yml", ".py", ".js", ".ts", ".html"}:
+            continue
+
+        text = path.read_text(encoding="utf-8", errors="ignore")
+        for pattern in REAL_KEY_PATTERNS:
+            for match in pattern.finditer(text):
+                findings.append(f"{path}:{line_of(text, match.start())}: possible real key or bearer token")
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    skill_dir = Path(argv[1]) if len(argv) > 1 else Path.cwd()
+    if not skill_dir.exists():
+        print(f"ERROR: {skill_dir} does not exist")
+        return 2
+
+    findings: list[str] = []
+    findings.extend(check_skill_md(skill_dir))
+    findings.extend(check_readme(skill_dir))
+    findings.extend(check_references(skill_dir))
+    findings.extend(check_key_leaks(skill_dir))
+
+    if findings:
+        for finding in findings:
+            print(finding)
+        return 1
+
+    print("OK: jsapi-skills passes validation")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/skills/webapi-skills/README.md

@@ -0,0 +1,73 @@
+# webapi-skills
+
+为 AI Agent 提供 Maptec Web Services API 能力的 Skill 集合，覆盖文本检索、周边检索、输入提示、地点详情、地理编码、逆地理编码、路线规划、距离矩阵、IP 定位等服务，并包含 API Key 申请与鉴权签名指引。
+
+## 简介
+
+`webapi-skills` 把 Maptec Web Services API 能力整理成结构化文档，供 AI Agent 进行能力归类、接口选型、参数约束、鉴权处理、代码生成和代码审查。核心入口是 `SKILL.md`，各项能力的详细规则在 `references/` 目录下。
+
+## 功能列表
+
+| 能力 | 说明 | 用户示例 |
+|---|---|---|
+| 快速接入 | 账号注册、项目创建、API Key 创建、服务授权、首个请求、SK/HMAC 签名 | “我没有 Key，怎么开始调用接口” |
+| 文本检索 | 关键词检索 POI，支持 `query`、`type`、`locationBias`、`locationLimit`、分页、排序、语言、区域 | “搜索新加坡所有咖啡馆” |
+| 周边检索 | 圆形范围周边检索，支持 `locationLimit`、`types`、`resultLimit`、排序、语言、区域 | “乌节路附近 1 公里的餐厅” |
+| 输入提示 | 关键词输入联想提示，支持 `query`、`types`、`locationBias`、`locationLimit`、`resultlimit`、语言、区域 | “输入‘乌节’返回提示词” |
+| 地点详情 | 根据 `placeId` 获取地点详情，支持 `language`、`region` | “获取某个地点的详细信息” |
+| 距离矩阵 | 计算起终点距离与时间矩阵，支持 1xN 与 MxN 限制 | “计算多个起点到多个终点的距离” |
+| 路线规划 | 驾车路线规划，支持起终点、途经点、避让规则、route/leg/step 响应 | “规划 A 到 B 的驾车路线” |
+| IP 定位 | 根据公网 IP 返回位置信息 | “我现在在哪” |
+| 地理编码 | 地址转经纬度，支持 `address`、`components`、location bias、geometry、地址组件 | “把某个地址转换为坐标” |
+| 逆地理编码 | 经纬度转地址，支持 `location`、结果过滤、geometry、地址组件 | “把坐标转换为详细地址” |
+
+## 安装 Skill
+
+用于将 `webapi-skills` 安装到本机 Agent Skills 目录，供 AI Agent 识别和使用。
+
+### （1）通过 npm 包安装
+
+```bash
+npx @maptec/webapi-skills install
+```
+
+安装完成后，默认目录为：`~/.agents/skills/webapi-skills`
+
+### （2）自定义安装目录
+
+支持用环境变量 `MAPTEC_SKILL_INSTALL_DIR` 指定安装父目录：
+
+```bash
+MAPTEC_SKILL_INSTALL_DIR=/path/to/skills npx @maptec/webapi-skills install
+```
+
+### （3）GitHub 开源地址
+
+`webapi-skills` 已开源到 GitHub 的 [maptec-api/webapi-skills](https://github.com/maptec-api/webapi-skills) 仓库，可以查看源码、了解目录结构，或在本地按需扩展 Web Services API 能力文档：
+
+[https://github.com/maptec-api/webapi-skills](https://github.com/maptec-api/webapi-skills)
+
+## Maptec Web Services API 接入
+
+业务项目中的接口主机、鉴权格式和 Key 申请流程见 [SKILL.md](SKILL.md)。当前集成示例统一使用测试环境主机 `https://test-api.maptec.com`。不同接口的鉴权格式：
+
+- Web Services API 默认使用 `Authorization: YOUR_API_KEY`。
+- 具体接口如在参考文档中另有说明，以对应 `references/*.md` 为准。
+- Secret Key 校验在以上基础上附加 `X-Timestamp` 与 `X-Signature`（对 `apiKey + timestamp + path + query` 做小写 hex HMAC-SHA256）。
+
+推荐将 Key 配置为本机环境变量，不要写入源码或粘贴到对话中：
+
+```bash
+export MAPTEC_API_KEY="YOUR_API_KEY"
+```
+
+## 如何被 Agent 使用
+
+Agent 使用本 Skill 时，应遵循以下流程：
+
+1. 先根据用户需求归类到功能列表中的一个或多个能力。
+2. 根据 `SKILL.md` 的 Workflow，只读取相关 `references/*.md`，并在需要鉴权/首次调用时读取 `references/quick-start-cn.md`。
+3. 严格保留参考文档中的接口 URL、HTTP 方法、鉴权格式、参数名、枚举值、限制和 JSON 响应结构。
+4. 生成代码前说明命中的能力和使用的接口。
+5. 用户要求实际调用接口时，先检查 `MAPTEC_API_KEY` 是否存在（不打印其值），缺失则先给出申请与配置流程。
+6. 不要发明未文档化的字段或限制，文档未说明时如实说明。

package/skills/webapi-skills/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: webapi-skills
+description: Maptec Web Services API documentation assistant for Search, Geocoding, Reverse Geocoding, Place Details, Nearby Search, Suggest, Directions, Distance Matrix, and IP Location APIs, including API Key setup and quick-start guidance. Use when Codex needs to answer questions, draft integration code, compare request/response fields, validate parameters, guide users without an API Key, configure credentials, sign requests, or explain endpoint usage for these Maptec Web Service APIs.
+---
+
+# WebAPI Skills
+
+Use this skill to answer Maptec Web Services API questions from bundled references synced from the official website and Yuque documentation.
+
+## Workflow
+
+1. Identify the requested API or workflow.
+2. Open only the matching reference file from `references/`. Also open `references/quick-start-cn.md` when the user needs setup, credential, authorization, first-call, or signing guidance.
+3. Answer from the reference. Preserve endpoint URLs, HTTP methods, auth format, parameter names, enum values, limits, and JSON response shapes exactly as documented.
+4. When drafting code, use the auth header documented by the relevant reference. Web Services APIs, including IP Location, use `Authorization: <YOUR_API_KEY>`. Do not add `Bearer` unless the specific reference requires it.
+5. Use `https://test-api.maptec.com` as the current base host for integration examples. Treat production host migration as a later environment swap.
+6. If a user asks across APIs, read the relevant files and summarize differences in a table.
+
+## API Key Setup
+
+When the user wants to call an API but has no key configured:
+
+1. Do not stop after reporting that `MAPTEC_API_KEY` is missing. Proactively provide the complete setup flow below in the same response.
+1. Explain that a MapTec developer account is required.
+2. Direct them to register at `https://test-lbs.maptec.com/auth/register` or log in at `https://test-lbs.maptec.com/auth/login`.
+3. Have them create a project in `https://test-lbs.maptec.com/console/project-asset`.
+4. Have them create a Key inside the project and select application restriction type `Rest API (Server)` for Web Services API.
+5. If IP restrictions are needed, tell them to enter server IP/CIDR values without ports; blank means unrestricted.
+6. Have them authorize only the needed services before finishing Key creation.
+7. Recommend setting the key locally as `MAPTEC_API_KEY` instead of pasting it into chat:
+
+```bash
+export MAPTEC_API_KEY="YOUR_API_KEY"
+```
+
+For questions such as “我现在在哪” or “where am I,” treat the request as an attempt to call IP Location rather than merely a documentation question:
+
+1. Check whether `MAPTEC_API_KEY` is available without printing its value.
+2. If it is missing, give the complete account, project, Key, IP restriction, service authorization, and environment-variable setup flow above. Explicitly tell the user to authorize the IP Location service.
+3. Explain that IP Location requires a public IPv4 or IPv6 address as the `ip` request field; a local timezone is not proof of physical location.
+4. After configuration, obtain or ask for the user's public IP as appropriate, then call the IP Location endpoint from `references/ip-location.md` with JSON body `{"ip":"..."}` and the documented `Authorization` header.
+
+For Secret Key (SK) verification, read `references/quick-start-cn.md` and include `X-Timestamp` plus `X-Signature`. The signature is lowercase hex HMAC-SHA256 over `apiKey + timestamp + path + query`.
+
+## References
+
+- `references/quick-start-cn.md`: account registration, project creation, API Key creation, service authorization, first request, and optional SK/HMAC signing.
+- `references/text-search.md`: Text Search API, `query`, `type`, `locationBias`, `locationLimit`, pagination, rank, language, and region.
+- `references/nearby-search.md`: Nearby Search API, circle `locationLimit`, `types`, `resultLimit`, rank, language, and region.
+- `references/suggest.md`: Suggest API, `query`, `types`, `locationBias`, `locationLimit`, `resultlimit`, language, and region.
+- `references/places.md`: Place Details API, `placeId`, `language`, and `region`.
+- `references/matrix-api.md`: Distance Matrix API, origins/destinations, 1xN and MxN matrix limits.
+- `references/direction-api.md`: Directions API, origin/destination, waypoints, avoid rules, route/leg/step response.
+- `references/ip-location.md`: IP Location API, IP request body and location response.
+- `references/geocoding.md`: Geocoding API, address, components, location bias, geometry, and address components.
+- `references/reverse-geocoding.md`: Reverse Geocoding API, `location`, result filters, geometry, and address components.
+
+## Response Guidance
+
+- Prefer concise integration-ready answers: endpoint, method, auth, required parameters, example request, and expected response.
+- If a user asks to actually call an API, first check whether `MAPTEC_API_KEY` is available in the local environment without printing it. If it is missing, provide the setup flow above instead of attempting a call.
+- Use the test host consistently even when the source document shows an older `api.maptec.com` or `api.maptech.com` host.
+- Do not invent undocumented fields or limits. Say the reference does not specify them.

package/skills/webapi-skills/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@maptec/webapi-skills",
+  "version": "1.0.4",
+  "description": "Maptec Web Services API Agent Skill package",
+  "type": "module",
+  "bin": {
+    "webapi-skills": "bin/webapi-skills.js"
+  },
+  "files": [
+    "bin",
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "references",
+    "scripts"
+  ],
+  "scripts": {
+    "validate": "python3 scripts/validate_webapi_skill.py ."
+  },
+  "keywords": [
+    "maptec",
+    "webapi",
+    "web-services",
+    "agent",
+    "skill",
+    "maps"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}