@maptec/webapi-skills

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。不同接口的鉴权格式：

• Search、Geocoding 类接口使用 Authorization: YOUR_API_KEY。
• Directions、Distance Matrix 接口使用 Authorization: Bearer <YOUR_API_KEY>。
• IP Location 接口使用 X-API-KEY: your_api_key。
• 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. 不要发明未文档化的字段或限制，文档未说明时如实说明。