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 包安装

npx @maptec/webapi-skills install

安装完成后，默认目录为：~/.agents/skills/webapi-skills

（2）自定义安装目录

支持用环境变量 MAPTEC_SKILL_INSTALL_DIR 指定安装父目录：

MAPTEC_SKILL_INSTALL_DIR=/path/to/skills npx @maptec/webapi-skills install

（3）GitHub 开源地址

webapi-skills 已开源到 GitHub 的 maptec-api/webapi-skills 仓库，可以查看源码、了解目录结构，或在本地按需扩展 Web Services API 能力文档：

https://github.com/maptec-api/webapi-skills

Maptec Web Services API 接入

业务项目中的接口主机、鉴权格式和 Key 申请流程见 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 配置为本机环境变量，不要写入源码或粘贴到对话中：

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. 不要发明未文档化的字段或限制，文档未说明时如实说明。