地图点位查看器 (map-points-viewer)

XpertAI 插件 — 接收点位信息，生成 Leaflet 地图 HTML 并在地图上可视化展示点位分布。

插件简介

map-points-viewer 是一个 XpertAI 工具类插件。它接收用户传入的一组点位数据（经纬度+名称+描述等），通过 Leaflet + 高德/腾讯/OSM 瓦片底图渲染出可嵌入的 HTML 地图页面，支持：

• ✅ Marker 标记 + Popup 弹窗
• ✅ 多分类自动着色（图例）
• ✅ 自动 fitBounds 视野适配
• ✅ 客户端纯静态 HTML，可直接保存或嵌入 iframe
• ✅ 无需后端服务，无需 API Key

适用场景

• 在 XpertAI 对话中输入一组点位，立即看到地图分布
• 业务系统的站点/门店/设备分布可视化
• 水质监测站、摄像头、传感器等 IoT 设备位置展示
• 任意需要"点位集合 → 一张地图"的场景

目录结构

map-points-viewer/
├── .xpertai-plugin/
│   └── plugin.json
├── index.js                  # 入口，导出 XpertPlugin
├── package.json              # npm 包定义
├── README.md
├── src/
│   ├── map-points-viewer.module.js          # NestJS 模块
│   ├── map-points-viewer.service.js         # 地图渲染服务
│   ├── schemas/
│   │   ├── config.schema.js                 # 配置 Schema
│   │   └── tool.schema.js                   # 工具输入输出 Schema
│   └── mcp/
│       └── map-points-viewer.mcp-server.js  # MCP 工具集
└── examples/
    └── request.example.json                 # 请求示例

安装

# npm 包名: @timmy_hu/map-points-viewer
# 版本: 1.0.0

配置项

| 配置项 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | tileLayer | enum | 否 | amap | 瓦片底图：amap-高德矢量 / tencent-腾讯矢量 / openstreetmap-OSM | | defaultCenter | [lng,lat] | 否 | 自动计算 | 默认中心点 | | defaultZoom | number | 否 | 12 | 默认缩放 1-20 | | markerColor | string | 否 | #3388ff | Marker 默认颜色 | | autoFitBounds | boolean | 否 | true | 是否自动视野适配 |

MCP 工具列表

render-map（渲染地图）

入参：

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | points | array | 是 | 点位数组 | | title | string | 否 | 地图标题 | | height | number | 否 | 地图高度（像素），默认 600 | | width | number/string | 否 | 地图宽度，默认 100% |

点位对象：

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | lng | number | 是 | 经度，-180 ~ 180 | | lat | number | 是 | 纬度，-90 ~ 90 | | name | string | 是 | 点位名称 | | category | string | 否 | 分类（用于分组着色） | | description | string | 否 | 弹窗描述（HTML） | | color | string | 否 | 自定义 marker 颜色 | | iconSize | number | 否 | marker 像素大小，默认 25 |

返回：

| 字段 | 类型 | 说明 | |---|---|---| | success | boolean | 是否成功 | | html | string | 完整地图 HTML 代码 | | center | [lng, lat] | 地图中心点 | | zoom | number | 初始缩放 | | pointCount | number | 点位数量 |

调用示例

const mcpTool = require('@timmy_hu/map-points-viewer');

// 渲染地图
const result = await mcpTool['render-map'].handler({
  title: '水质监测站点分布',
  points: [
    { lng: 120.155, lat: 30.274, name: '西湖站', category: '饮用水' },
    { lng: 120.213, lat: 30.210, name: '钱塘江口站', category: '地表水' }
  ]
});

console.log(result.html);   // 完整 HTML
console.log(result.center);  // [120.184, 30.242]

返回的 html 可以：

• 直接保存为 .html 文件双击打开
• 嵌入到 iframe：<iframe srcdoc="..."></iframe>
• 嵌入到任何支持 HTML 的容器中

常见错误和处理

| 错误 | 原因 | 处理方式 | |---|---|---| | 点位数组不能为空 | 未传 points 或为空数组 | 至少传入 1 个点位 | | 经纬度超范围 | lng 不在 -180~180 或 lat 不在 -90~90 | 校验坐标有效性 | | 地图加载慢 | 网络无法访问 unpkg.com | 自托管 Leaflet 或切换瓦片源 |

安全注意事项

• 所有点位数据嵌入到 HTML 字符串中，确保点位数据不含敏感信息
• 使用 escapeHtml 防止 XSS 注入
• 弹窗 description 字段支持 HTML，使用方需自行确保内容可信

使用方式

1. 在 XpertAI 平台安装此插件
2. 在 AI 对话中传入点位数组，触发 render-map 工具
3. 将返回的 HTML 嵌入到展示页面或直接打开

下一步

前往 XpertAI 平台 使用此插件。