命令行工具

cnmaps 提供了一个轻量的命令行工具，目前主要包括：

AI Skill 安装
行政边界查询后直接导出为矢量文件

总览与帮助

主命令形式如下：

cnmaps <subcommand> [options]

当前主要子命令包括：

install-skill
export
check-boundary

如果你想查看命令行程序自动生成的帮助信息，也可以执行：

cnmaps -h
cnmaps install-skill -h
cnmaps export -h
cnmaps check-boundary -h

这些帮助信息由参数定义自动生成，通常会与当前版本保持同步；不过你通常不需要先看它们，本页已经给出常见用法与参数说明。

`install-skill` 子命令

install-skill 用于把 cnmaps 自带的 AI Skill 描述安装到当前项目目录或用户全局目录。

命令形式：

cnmaps install-skill {codex,cursor,claudecode} [--dir DIR] [--mode {local,global}] [--force]

位置参数：

codex / cursor / claudecode：目标助手类型

常用参数：

--dir DIR：本地安装时指定项目目录，默认是当前目录
--mode local：安装到当前项目目录
--mode global：安装到用户主目录下的全局目录
--force：覆盖已有安装

最常见的本地安装方式：

cnmaps install-skill codex --mode local
cnmaps install-skill cursor --mode local
cnmaps install-skill claudecode --mode local

全局安装方式：

cnmaps install-skill codex --mode global
cnmaps install-skill cursor --mode global
cnmaps install-skill claudecode --mode global

如需覆盖已有安装，可追加 --force：

cnmaps install-skill codex --mode local --force

更多关于 Skill 的背景说明与安装建议，可参见安装。

`export` 子命令

export 用于直接在命令行里完成“查询边界 + 导出文件”。

命令形式：

cnmaps export <output> [--country ...] [--province ...] [--city ...] [--district ...]
              [--level ...] [--source ...] [--provider ...] [--record {all,first}]
              [--engine ENGINE] [--encoding ENCODING] [--gcj02] [--simplify]

位置参数：

<output>：目标输出路径

常用参数：

--country：国家名称或 ISO3 代码，可写多个值
--province：省级名称，可写多个值
--city：市级名称，可写多个值
--district：区县名称，可写多个值
--level：行政等级，例如 国、省、市、区县
--source：数据源筛选，可写多个值
--provider：数据提供者名称
--record all：导出所有匹配记录
--record first：只导出第一条匹配记录
--engine：显式指定导出格式
--encoding：指定输出编码
--gcj02：导出 GCJ02 坐标，而不是默认的 WGS84
--simplify：导出前先简化几何

其中 <output> 是目标输出路径。默认按文件后缀推断格式：

.geojson / .json 对应 GeoJSON
.shp 对应 ESRI Shapefile

如果输出路径后缀不标准，也可以显式指定格式：

cnmaps export ./output/boundary.data --engine GeoJSON --province 河南省 --level 省

常见示例：

cnmaps export ./jingjin.geojson --province 北京市 天津市 --level 省
cnmaps export ./east-asia.geojson --country 中国 JPN KOR --level 国
cnmaps export ./henan.shp --province 河南省 --level 省 --record first

筛选规则

export 的筛选能力尽量与 get_adm_maps 保持一致，常用参数包括：

--country
--province
--city
--district
--level
--source
--provider
--record {all,first}
--simplify
--gcj02

其中 --country、--province、--city、--district、--source 都支持在同一个参数后追加多个值，例如：

cnmaps export ./jingjin.geojson --province 北京市 天津市 --level 省

这表示在同一个等级下批量筛选多个名称，而不是跨等级混合查询。像“日本”和“四川省”这样的组合，仍然需要拆成两次查询。

导出坐标与格式

默认导出 WGS84 坐标
如需导出 GCJ02，可加 --gcj02
GeoJSON 与 Shapefile 都会保留主要属性字段，例如 country、province、city、district、level、source、kind、longitude、latitude

与 Python API 的关系

如果你已经在 Python 代码中拿到了 MapPolygon，仍然可以继续使用 MapPolygon.to_file(...) 导出。

cnmaps export 更适合这些场景：

想在 shell 里直接把边界筛选并导出
不想为了简单导出任务专门写一段 Python 脚本
想把 get_adm_maps 的筛选逻辑复用到命令行工作流中

`check-boundary` 子命令

check-boundary 用于检查一个外部 GeoJSON / Shapefile 是否符合 cnmaps boundary spec，从而可以被 read_boundary_file(...) 稳定读取并转换为 MapPolygon。

命令形式：

cnmaps check-boundary <path> [--json]

位置参数：

<path>：待检查的边界文件路径

常用参数：

--json：以 JSON 形式输出结构化检查结果，便于脚本或 AI 消费；这只是检查结果的输出格式，与输入文件本身是 shp 还是 geojson 无关

当前规范要求：

文件格式为 .geojson / .json / .shp
CRS 必须明确且等价为 WGS84（EPSG:4326）
几何必须全部为 Polygon 或 MultiPolygon
不能包含空几何或无效几何

如果文件包含多个 feature，cnmaps 在读取时会先将它们合并为一个统一边界。

常见示例：

cnmaps check-boundary ./my-boundary.geojson
cnmaps check-boundary ./my-boundary.shp --json  # 将检查结果以 JSON 输出

如果检查通过，就可以继续在 Python 代码中调用 read_boundary_file(...) 读取，并进一步执行 make_mask_array(...)、maskout(...) 或 clip_* 等操作。

命令行工具

总览与帮助

install-skill 子命令

export 子命令

筛选规则

导出坐标与格式

与 Python API 的关系

check-boundary 子命令

`install-skill` 子命令

`export` 子命令

`check-boundary` 子命令