夜雨聆风一、先说说大家都曾遇到的痛点
二、我的解决方案：Tile Download AI Chat
node cli.js ai --text "下载北京海淀区高德卫星10-12级瓦片，合并成GeoTIFF并按边界裁剪"
三、项目亮点，每一个都戳中痛点
node cli.js download -s "高德-卫星影像" --lat1 39.9 --lon1 116.3 --lat2 39.92 --lon2 116.32 -z1 10 -z2 12 -o ./tiles
node cli.js ai --text "下载北京高德卫星10-12级瓦片"
○ 识别数据源：高德-卫星影像
○ 识别范围：北京市（自动计算外包矩形）
○ 识别层级：10–12级
○ 自动生成参数、创建输出目录、执行下载任务
○ 下载瓦片（支持经纬度范围、行政区划两种方式）
○ 预览离线瓦片（无需额外部署，本地起服务）
○ 导出行政区划边界（支持GeoJSON、SHP、GPKG三种格式）
○ 裁剪GeoTIFF（按行政区划或自定义矢量文件）
○ 栅格切片（将GeoTIFF切成标准XYZ瓦片，供Leaflet使用）
○ 下载+合并+裁切一条龙流水线（一条指令完成全流程）
○ 高德：卫星影像、矢量路网（无需密钥，可直接使用）
○ 腾讯：卫星影像、矢量电子（矢量电子需配置TENCENT_MAP_KEY）
○ 天地图：卫星影像、矢量路网、地形晕渲、注记等（需配置TIANDITU_KEY）
○ ESRI：全球卫星、街道、地形、海洋底图等（无需密钥，可直接使用）
○ 其他：Bing（卫星、道路）、Google（卫星）、OSM（矢量路网）、Mapbox（卫星、街道）等
a. 下载：支持断点续传、并发控制、请求延时，避免下载中断、触发图源反爬
b. 任务规划：用plan命令可提前估算瓦片数量、存储空间和下载时间，避免磁盘空间不足
c. 合并：将下载的小瓦片合并成PNG、JPEG或GeoTIFF格式，支持指定缩放级别
d. 裁剪：按行政区划或自定义矢量文件裁剪GeoTIFF，精准保留目标区域（需安装gdal-async依赖）
e. 栅格切片：把合并、裁剪后的GeoTIFF切成标准XYZ瓦片，供离线预览或第三方瓦片引擎使用
f. 离线预览：本地起Leaflet服务，打开浏览器即可查看已下载的瓦片，无需访问外网CDN
g. 错误诊断：用diagnose命令输入报错信息（如“Request failed with status code 403”），自动分析失败原因并给出解决方案
node cli.js ai --text "下载西安ESRI卫星12级，合并GeoTIFF并按西安市区划裁剪，再切成8-12级XYZ瓦片"
○ 原始瓦片文件（存储在out/tiles/目录下）
○ 合并后的完整GeoTIFF大图
○ 按西安市区划裁剪后的GeoTIFF
○ 可直接预览的离线XYZ瓦片（存储在out/raster_xyz/目录下）
node cli.js chat-ui
○ 左侧：图源选择、历史任务列表（可筛选、删除任务）
○ 中间：AI对话窗口，输入中文指令即可生成并执行任务
○ 右侧：任务状态实时展示、瓦片预览、栅格切片操作
○ 一键执行AI解析后的任务，无需手动输入命令
○ 查看任务历史、任务统计，追溯操作记录
○ 直接预览离线瓦片，无需额外启动预览命令
○ 对裁切后的GeoTIFF一键进行栅格切片
○ 删除任务并同步清理磁盘文件，避免占用空间
○ 按省：--admin -province 陕西省
○ 按市：--admin -city 西安市
○ 按区县：--admin -county 未央区
○ 按国标码：--admin -gb 156610100（适合精准定位）
○ admin -bounds：获取指定行政区划的下载用矩形范围（bbox），供download命令使用
○ admin -vector：导出指定行政区划的真实面状边界（非矩形），支持GeoJSON、SHP、GPKG格式，用于GIS分析、裁剪等场景
○ 基于Node.js开发，pnpm install一键安装所有依赖，无需复杂配置
○ 提供\.env\.example模板文件，密钥配置一目了然，复制修改即可使用
○ 数据源集中管理，新增、修改图源只需编辑resources/map\_sources\.json，无需改动核心代码
○ 代码结构清晰，CLI、AI、Server、工具函数分离，便于二次开发、提交PR共建
○ 软件 MIT 开源免费；地图数据须自备合法 Key 并遵守各平台 ToS（见第六节免责声明）
○ 自带Cursor Skill，适配Cursor、Claude Code等主流AI代码工具，开发时可智能生成命令、自动排错
四、快速上手，1分钟跑起来
git clone https://gitee.com/xi-weidong/tile-download-ai-chat
cd tile-download-ai-chat
pnpm install 或 npm install
cp .env.example .env
node cli.js ai --text "下载北京高德卫星10-12级瓦片"
②预览下载结果（默认输出在out/tiles/目录下）
node cli.js preview -o ./out/tiles/高德-卫星影像-10-12/
③启动Web工作台（可视化操作）
node cli.js chat-ui
五、SKILL实测记录：重庆市MapBox影像下载
/tile-download-cli 帮我下载重庆市范围的 mapbox 影像，层级范围：6~12，输出到 skill-out 子目录下。下载完毕之后，请先合并为 geotiff，然后使用重庆市行政区划矢量数据进行裁剪
○ 按 Skill 约定先核对 Mapbox 图源名、重庆市 bbox（约 4173 张，z6–12）
○ 导出 chongqing_boundary.geojson（天地图市界面，供裁切用）
○ 执行下载 → merge -z 12 -f geotiff → clip-raster
○ 汇报产物路径与体积
步骤 | 结果 |
下载 Mapbox 卫星 z6–12（市域外包框） | 4173 张，0 错误 |
合并 GeoTIFF |
|
按市界面裁切 |
|
/tile-download-cli 把裁剪结果切成离线 XYZ 预览，层级范围为：6~15。输出到 skill-out/clip_xyz_tiles 子目录下
● 对 merged_z12_chongqing_clipped.tif 调用 raster-to-tiles（z6–15，约 25.5 万张，耗时会较长，可能后台跑）
● 完成后说明 clip_xyz_tiles/ 目录结构
项 | 结果 |
输出目录 |
|
瓦片数量 | 255069 张，0 失败 |
/tile-download-cli 给出 skill-out/clip_xyz_tiles 子目录下瓦片的预览页面
● 确认切片已完成后执行 preview -o ./skill-out/clip_xyz_tiles
● 提示浏览器地址（常见为 http://127.0.0.1:8765/，以终端输出为准）
也可以用GIS软件打开，做二次数据。
对话1 导出市界 → 下载(外包框) → 合并 z12 → 裁切对话2 GeoTIFF → XYZ 切片 (255069 张)对话3 本地 preview 预览
1. Skill 的价值：区划「下载用矩形、裁切用面」、产物进 skill-out/、Key 不写进代码——由 Skill 约束 Agent，少犯「一句中文下错命令」的错。
2. 对话可以分轮：不必一次说全；下载合并裁切 → 切片 → 预览，三轮更稳。
3. 仍须合规与理性预期：须自备 Mapbox/天地图 Key；z13–15 相对 z12 有上采样；大范围高层级占磁盘、耗时长。请遵守各平台 ToS，先小范围试跑。
六、适合谁用？
● 前端/后端开发者，需要做离线瓦片缓存、离线地图加载
● GIS学生/工程师，频繁做瓦片下载、数据预处理、GIS分析
● 做无人系统、离线演示、内网地图项目的团队
● 不想记复杂命令、想用自然语言操作瓦片工具的人
● 需要交付标准化瓦片+GeoTIFF+切片的开发者、科研人员
● 预算有限的学生党、科研党（软件开源免费；地图数据仍须遵守各平台规则）
七、使用须知
● 是：运行在你本机的命令行 / 工作台工具，帮你编排下载、合并、裁切、切片、预览等流程。
● 不是：地图数据提供商，不授予任何第三方瓦片/影像的下载权、商用权或再分发权。
● 项目以 MIT 许可证 开源（详见仓库 LICENSE），软件可免费使用；不等于 地图数据可免费任意抓取。
● 内置 28 套图源 URL 指向 OSM、高德、腾讯、天地图、Mapbox、ESRI、Google、Bing 等第三方服务，须遵守各自服务条款、配额与密钥政策。
● 需 Key 的图源（如天地图、Mapbox、腾讯矢量等）请使用你自己申请、有权使用的密钥，写入本机 .env，勿提交到 Git、勿写进前端或截图。
● 禁止利用本工具绕过访问控制、压测他人服务器、未授权大规模/高频抓取，或用于任何违法及违约用途。
● 建议：先小范围、低 zoom 试跑，确认 Key、网络与磁盘占用后再扩大任务；高 zoom、大范围会显著增加请求量与存储。
● 省市区下载/导边界依赖天地图相关接口与本地 TDT_XZQHBM.csv，须配置 TIANDITU_KEY 并遵守天地图开放平台规范。
● admin-bounds（外包矩形）与 admin-vector（真实区划面）用途不同，裁切与下载勿混用。
● 自然语言功能依赖你在 .env 中配置的大模型 API，调用费用由你自行承担；解析结果仅供参考，执行前请核对（工作台可先「解析意图」再运行）。
● .env 仅保存在本机，已列入 .gitignore；若曾误提交密钥，请立即在各平台轮换 Key 并清理 Git 历史。
● chat-ui 默认监听 127.0.0.1；若暴露到局域网或公网，请自行设置 TILE_CHAT_RUN_TOKEN 等访问控制。
● 在线瓦片经本机 BFF 代理转发，不会把 Key 下发到浏览器。
项 | 说明 |
GeoTIFF 大图 | 合并/裁切后的单文件 GeoTIFF 建议在 QGIS 等软件中查看； |
GDAL 依赖 | 合并 GeoTIFF、裁切、部分矢量导出需 gdal-async，见仓库 |
实测差异 | 部分图源（如天地图）在 Key 无效或网络限制下可能 403；README 中有小范围实测说明，请以你本机环境为准。 |
责任边界 | 本工具按现状提供，不提供明示或默示担保；作者与贡献者不对因使用导致的账号封禁、法律纠纷、数据损失等承担责任。 |