百度地图开放平台 CLI。凡涉及百度地图开发、HTML/demo、WebAPI/BMapGL、AK/个性化地图样式/配额等,须先触发本 skill 并完成环境与 AK 流程,再查文档或写代码。涵盖:CLI 安装、Skills/MCP 配置、账户与 AK、个性化地图样式、地点/路线/地址解析等;同时支持百度地图 A...
---
name: bmap-cli
description: 百度地图开放平台 CLI。凡涉及百度地图开发、HTML/demo、WebAPI/BMapGL、AK/个性化地图样式/配额等,须先触发本 skill 并完成环境与 AK 流程,再查文档或写代码。涵盖:CLI 安装、Skills/MCP 配置、账户与 AK、个性化地图样式、地点/路线/地址解析等;同时支持百度地图 Agent Plan(无需开发者账户,可完成找地点、规划路线、查天气、解析 / 反解析地址等能力)。
version: 1.0.1
---
# bmap-cli 百度地图开放平台工具
> **[最高优先级]** 任何 bmap-cli 命令输出若包含「发现新版本」字样,须立即将**完整更新命令**展示给用户,同时标注命令中出现的下载域名(如 `open-agent-cli.bj.bcebos.com`),提示用户确认该域名与初次安装来源一致,征得同意后再执行,完成后再继续当前操作。此规则适用于所有命令、所有步骤,无例外。
## 触发条件
满足任一条即启用本 skill:
- 地点 / POI 搜索、路线导航、地址或坐标解析、天气查询(含 Agent Plan 场景)
- 个性化地图样式查询或创建
- 百度地图开发(WebAPI、BMapGL、JSAPI)、工具安装与配置
- 生成含百度地图的 HTML、demo 或代码
## 执行原则
### 操作边界
- **只读/查询类操作**:自主完成。
- **配置变更、资源创建(AK/样式)**:须先展示操作内容并获得用户明确同意,再执行。
- **失败处理**:重试并给出可执行的排查说明。
### 环境变更原则
以下原则适用于所有安装/配置步骤:
1. **幂等**:已就绪则跳过,勿重复安装。
2. **配置审阅**:`skills install` / `mcp install` 的终端输出若包含待执行指令或待写入配置,须先**完整展示给用户审阅**;获得明确同意后,再逐条执行或写入;未经确认禁止自动变更配置。
3. **版本更新**:任何命令输出若包含「发现新版本」字样及对应更新命令,须向用户展示该更新命令并征得同意,完成后再继续后续步骤。
4. **MCP 合并**:MCP 配置须与本地已有配置**深度合并**,勿覆盖无关条目;若输出为「已安装,跳过」则跳过该步。
5. **登录处理**:任何命令输出若包含「未登录」错误,须告知用户需要登录并征得明确同意;获得同意后立即自行执行 `"$BMAP_CLI" login`(CLI 会自动打开浏览器,等待用户在浏览器点击授权即可),完成后重试原命令;禁止将登录命令抛给用户手动执行。
## 执行流程
### 阶段一:环境准备
以下三步均为幂等操作,已就绪则跳过。
#### 1. 安装 CLI
必须将下载地址展示给用户。Claude Code 的 Bash 工具权限确认框会将完整 curl 命令(含 URL)展示给用户,用户点击「允许」即为明确同意;点击「拒绝」则中止安装。
> **安全提示(ASI04)**:当前下载流程无内置校验和或签名验证,二进制文件真实性依赖对 `open-agent-cli.bj.bcebos.com` 的信任。如需验证,请通过百度地图开放平台官方渠道获取该版本的 SHA256 校验值,下载后执行 `sha256sum "$BMAP_CLI"` 比对。
```bash
mkdir -p ~/bin
BMAP_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
BMAP_ARCH="$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
export BMAP_CLI="$HOME/bin/bmap-cli-${BMAP_OS}-${BMAP_ARCH}"
if [[ ! -x "$BMAP_CLI" ]]; then
curl -fL "https://open-agent-cli.bj.bcebos.com/cli/bmap-cli-${BMAP_OS}-${BMAP_ARCH}" \
-o "$BMAP_CLI" && chmod +x "$BMAP_CLI"
fi
grep -q 'HOME/bin' ~/.zshenv 2>/dev/null || echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshenv
export PATH="$HOME/bin:$PATH"
```
#### 2. 安装百度地图 Skills
```bash
"$BMAP_CLI" skills install
```
按「环境变更原则」处理输出,然后自主完成以下步骤(不得将命令抛给用户执行):
1. **列出已安装 Skills**:展示 skill 名称、版本、安装路径,及各 Token 的配置状态(已配置 / 未配置)。
2. **复制 Skill**:将 `~/.agents/skills/` 下的 skill 目录复制到当前运行环境默认的 skills 加载路径。
3. **持久化 Token**:将 AK 写入当前运行环境的 env 配置文件(非 `~/.zshrc`),确保每次启动自动加载。若所需端类型的 AK 不存在,告知用户创建,不得以其他端类型替代。
4. **验证**:重新加载配置后,调用任意已安装 skill 验证 Token 有效性。
5. **输出简报**:安装路径、Token 持久化位置、验证结果。全程不得明文展示完整 AK / Token(遮掩规则:前 4 位 + `****` + 后 4 位)。
#### 3. 安装 MCP 配置
```bash
"$BMAP_CLI" mcp install
```
执行后,**先将完整输出(含配置写入路径与内容)展示给用户审阅**;获得明确同意后,再深度合并写入当前客户端 MCP 文件。注意:MCP 配置中包含 AK 凭据,写入前请确认存储路径与访问权限符合预期,避免凭据被无关工具或会话读取。
写入完成后,建议限制该文件权限(ASI07):
```bash
# 将路径替换为实际 MCP 配置文件路径
chmod 600 <mcp_config_path>
```
### 阶段二:响应用户请求
#### 非代码类请求(查询、概念、账户管理等)
直接作答,**勿**进入代码生成步骤。
**选择规则**:先判断用户是否要「直接完成地理任务」,是则用 `baidu-ai-map` skill;否则再看是查文档还是写代码。
| 用户需求 | 来源 |
|------|------|
| **直接执行地理任务**(找地点、规划路线、查天气、解析 / 反解析地址) | `baidu-ai-map` skill |
| 查询 API 文档(接口参数、限制、定价说明) | `baidu-maps-docs` MCP |
| 生成调用地图的代码(HTML、JSAPI 示例、WebAPI 集成) | `baidu-map-jsapi-gl` 或 `baidu-map-webapi` skills |
> **强制**:`baidu-ai-map` 是直接执行地理任务的**唯一**入口,`baidu-map-webapi` 不得作为其替代。若 `baidu-ai-map` 尚未加载,须告知用户重启 Claude Code 后重试,**不得**以任何其他 skill 降级替代。
#### 代码类请求(需生成或修改代码/文件)
**JSAPI 版本选择(默认使用 GL 版)**:编写地图前端代码时,**默认使用 BMapGL(GL 版)**,即引用 `https://api.map.baidu.com/api?v=1.0&type=webgl&...`,对象命名空间为 `BMapGL`。**仅当用户明确指定「3.0 版本」或已有代码基于 3.0 时**,才使用 `BMapJS`(v3.0)。两套 API 命名空间不得混用。
写代码前**严格按序**执行下面四步,**禁止跳步或乱序**。
##### 第一步:确定 AK 类型
| 场景 | AK 类型 |
|------|---------|
| 前端 HTML、BMapGL、JSAPI | 浏览器端 |
| 服务端 WebAPI、后端脚本 | 服务端 |
| 同时涉及前后端 | 两种都要 |
| 其他 | 只取实际会用到的类型 |
**浏览器端 AK 白名单规则**:`b_referers` 为「不限制」时,**只认字面值 `*`**。即:
- `b_referers` 不得为空;
- 不得用「按用户实际访问来源填域名」等描述代替 `*`。
> **安全提示(ASI03)**:`b_referers = *` 的通配符 AK 会扩大暴露面,任何页面均可调用,存在配额被滥用风险。**仅适用于本地 demo 或受控测试环境**;生产/正式项目应使用具体域名白名单(如 `example.com`)的 AK。
在 `ak list` 中,浏览器端 AK **仅优先**选用 `b_referers` 等于 `*` 的项(仅限 demo 场景),**勿**选用仅含具体域名白名单的项。若无此类 AK,须**先告知用户将要新建含 `--b-referers '*'` 的 AK**(仅适合 demo,会增大 AK 暴露面并消耗账户资源),征得用户明确同意后,再进入第四步创建。
##### 第二步:获取地图样式 ID(如涉及)
当需求涉及地图底图外观、视觉风格或样式时:
```bash
"$BMAP_CLI" style list 2>&1
```
- **先查后建(强制)**:必须先完整读取 `style list` 输出,在 `user_style_list` 中逐项比对并优先复用已存在且满足需求的样式;**禁止**未检查就直接 `style create`。
- 仅当 `user_style_list` **确实无满足项** 时,才允许从 `template_list` 选最匹配模板(优先 `need_business_accredit: false`)并创建:
```bash
"$BMAP_CLI" style create --tpl-id <tpl_id> 2>&1
```
- `style_id` **只能**取自 CLI 原始输出(`style list` 的已有项或 `style create` 的返回结果);**禁止**手写、猜测、拼接或编造。代码中**仅**使用该真实 `style_id` 的 `styleId` 方式:
```javascript
map.setMapStyleV2({ styleId: '从 CLI 获取的 style_id' });
```
- **任何场景禁止** `setMapStyleV2` 的 `styleJson` 及等价手写 JSON 样式配置,无例外。
##### 第三步:列出 AK
```bash
"$BMAP_CLI" ak list 2>&1
```
##### 第四步:选 AK 并写入代码
通读 `ak list` 输出,按类型、服务范围选出最匹配的 AK。
**浏览器端 AK 选择**:在满足类型与服务的前提下,**只**选用 `b_referers` 为 `*` 的 AK(仅限 demo 场景);不把空串或其它写法当作不限制。**仅当列表中无此类 AK 时**,须先向用户说明将新建一个 `--b-referers '*'` 的浏览器端 AK(**仅适合 demo/受控测试,会扩大 AK 暴露面,可能造成配额被滥用;生产项目建议改用域名白名单**),并征得明确同意后,再执行:
```bash
"$BMAP_CLI" ak create --app-name "<应用名称>" --app-type 3 --b-referers '*' 2>&1
```
新建成功后,**重新执行第三步** `ak list`,再选定新 AK。
**写入代码规范**:
- 代码里**必须**使用列表中的**完整原始 AK 字符串**,禁止凭记忆或推断填写。
- 涉及任何关键标识或精确字段(如 `ak`、`app_id`、`style_id` 等)时,**一律以当前轮次最新 CLI 原始输出为准**;禁止凭记忆、历史截图、先前回复回填。输出较大时必须做字段精确匹配并保证唯一(0 条或多条都先消歧)。
- 用户已明确发出查询指令(如"查询这个 AK 的调用量/配额")时,应按"核验目标 -> 精确取字段 -> 立即执行查询 -> 返回结果"直接执行;除非命令受阻(权限/网络/登录失效),否则禁止只道歉或反问。
- `前4位****后4位` 等形式**仅**用于聊天说明,**禁止**写入源码。
- 写入代码前,在对话中先发一行声明(固定格式):
```
> 已获取 AK:{前4位}****{后4位}({app_type},{app_name},白名单:{b_referers})
```
- 交付代码中**不得**出现占位符、假 AK、「请自行替换」等提示。
## 规范总览
### AK 安全与展示
- **存储**:AK 只写入目标代码文件;勿用 echo/print 把完整 AK 打到终端。
- **展示**:对用户展示时用「前 4 位 + `****` + 后 4 位」(如 `ByM8****KMxw`)。
- **列表展示**:禁止合并、分组、区间省略;保持原始顺序逐条列出;超过 20 条时按每 20 条一段连续展示直至完毕。
### 输出规范
登录链接、报错堆栈、命令结果禁止用「… +N 行」类截断,须完整原样给出。
### 配置复用与会话管理
- **复用**:本环境已成功配置后,同一会话后续可直接复用,不必重复安装。
- **切换账户**(如执行 `bmap-cli login` 后):旧账户 AK 全部作废,须依次:
1. 重新 `ak list`,替换**本会话**已生成代码中的 AK
2. 重新 `bmap-cli mcp install`,**展示输出给用户确认**后更新 MCP 中的 AK
3. 重新 `bmap-cli skills install` 更新 skills 中的 AK
4. 提醒用户:**其他历史会话**产出的文件需自行排查替换,助手无法感知跨会话写入的文件
don't have the plugin yet? install it then click "run inline in claude" again.