| name | bmap-cli |
| description | 百度地图开放平台 CLI。凡涉及百度地图开发、HTML/demo、WebAPI/BMapGL、AK/个性化地图样式/配额等，须先触发本 skill 并完成环境与 AK 流程，再查文档或写代码。涵盖：CLI 安装、Skills/MCP 配置、账户与 AK、个性化地图样式、地点/路线/地址解析等；同时支持百度地图 Agent Plan（无需开发者账户，提供大模型友好调用的地图工具，支持语义化 AI 搜索、语义化 AI 路线规划、地理编码与逆地理编码、天气查询）。 |
bmap-cli 百度地图开放平台工具
[最高优先级] 任何 bmap-cli 命令输出若包含「发现新版本」字样，须立即将完整更新命令展示给用户，同时标注命令中出现的下载域名（如 open-agent-cli.bj.bcebos.com），提示用户确认该域名与初次安装来源一致，征得同意后再执行，完成后再继续当前操作。此规则适用于所有命令、所有步骤，无例外。
触发条件
满足任一条即启用本 skill：
| 触发场景 | 典型行为 |
|---|
| 语义化 AI 搜索、语义化 AI 路线规划、地理编码与逆地理编码、天气查询 | 调用 baidu-ai-map skill 直接完成地理任务 |
| 个性化地图样式查询或创建 | 执行 style list / style create 命令 |
| 百度地图开发（WebAPI、BMapGL、JSAPI）、工具安装与配置 | 进入环境准备流程，安装 CLI / Skills / MCP |
| 生成含百度地图的 HTML、demo 或代码 | 获取 AK、查询文档并交付可运行代码 |
核心能力
| 能力 | 说明 |
|---|
| 环境管理 | CLI 安装、Skills / MCP 幂等配置，登录与版本更新全自动处理 |
| AK 管理 | 查询现有 AK、按需创建浏览器端或服务端 AK，安全遮掩展示 |
| 地图样式管理 | 查询个性化样式列表、从模板创建新样式，提供真实 style_id |
| 百度地图 Agent Plan | 通过 baidu-ai-map skill（提供大模型友好调用的地图工具）完成语义化 AI 搜索、语义化 AI 路线规划、地理编码与逆地理编码、天气查询 |
| 代码生成 | 交付含真实 AK 与样式 ID 的 BMapGL / WebAPI 可运行代码 |
执行原则
操作边界
- 只读/查询类操作：自主完成。
- 配置变更、资源创建（AK/样式）：须先展示操作内容并获得用户明确同意，再执行。
- 失败处理：重试并给出可执行的排查说明。
环境变更原则
以下原则适用于所有安装/配置步骤：
-
幂等：已就绪则跳过，勿重复安装。
-
配置审阅：skills install / mcp install 的终端输出若包含待执行指令或待写入配置，须先完整展示给用户审阅；获得明确同意后，再逐条执行或写入；未经确认禁止自动变更配置。
-
版本更新：任何命令输出若包含「发现新版本」字样及对应更新命令，须向用户展示该更新命令并征得同意，完成后再继续后续步骤。
-
MCP 合并：MCP 配置须与本地已有配置深度合并，勿覆盖无关条目；若输出为「已安装，跳过」则跳过该步。
-
登录处理：
- 用户已登录：若用户明确表示已登录，直接执行目标命令；仅当命令返回「未登录」错误时才进入登录流程。
- 绝对禁止：抛给用户手动执行；包裹 timeout/nohup；放后台（
&）或管道（|）；用 sleep/ps/find/for/while 轮询检查登录状态或等待配置文件生成；查找 token 文件、环境变量或任何凭证存储位置；同一问题反复自我确认超过一次。
任何命令输出若包含「未登录」错误，须告知用户并征得明确同意后，立即自行执行 "$BMAP_CLI" login。
模型常见错误（必须避免）
timeout 60 "$BMAP_CLI" login
"$BMAP_CLI" login &
"$BMAP_CLI" login > /tmp/out.txt 2>&1 &
"$BMAP_CLI" login | head -20
**唯一正确写法**：`"$BMAP_CLI" login`
login 是引导用户完成浏览器授权的人机协作流程，不是模型获取 token 的技术脚本。执行后立刻输出授权 URL 并进入轮询等待；token 由 CLI 内部管理，模型不需要知道也不应该去查找。模型不得等待命令结束，必须在第一时间提取 URL 并以独立代码块展示给用户，同时告知用户在浏览器中点击授权：
请在浏览器中打开以下链接完成授权（完整链接，禁止省略或截断）。如已完成登录授权，可忽略此链接：
<完整 URL>
URL 展示后即表示模型已完成本分工作，剩余时间由用户在浏览器侧完成授权；CLI 内部管理 5 分钟轮询超时，模型无需干预。
工作流程
工作流总览
触发 skill
↓
阶段一（幂等）: ① 安装 CLI → ② skills install → ③ mcp install
↓ 输出含「未登录」? → bmap-cli login（前台阻塞，禁止 timeout/&）→ 重试后继续
↓
阶段二（响应请求）
├─ 语义化 AI 任务 ────────── baidu-ai-map skill（唯一入口）
├─ 查文档 ──────────────── baidu-maps-docs MCP
└─ 写代码（严格四步）
① 确定 AK 类型（浏览器端 / 服务端）
② 需样式? → style list 先查，无则 style create
③ ak list
④ 选/建 AK → 写入代码交付
横切：任何命令含「发现新版本」→ 展示更新命令，征得同意后继续
阶段一：环境准备
以下三步均为幂等操作，已就绪则跳过。
1. 安装 CLI
必须将下载地址展示给用户。Claude Code 的 Bash 工具权限确认框会将完整 curl 命令（含 URL）展示给用户，用户点击「允许」即为明确同意；点击「拒绝」则中止安装。
安全提示（ASI04）：当前下载流程无内置校验和或签名验证，二进制文件真实性依赖对 open-agent-cli.bj.bcebos.com 的信任。如需验证，请通过百度地图开放平台官方渠道获取该版本的 SHA256 校验值，下载后执行 sha256sum "$BMAP_CLI" 比对。
mkdir -p ~/bin
uname -s
uname -m
根据上两步输出确定平台后缀（勿用管道拼接探测）：
BMAP_OS：Darwin→darwin，Linux→linux，其余转小写BMAP_ARCH：x86_64→amd64，aarch64→arm64，其余保持原样
将 <BMAP_OS>、<BMAP_ARCH> 替换为实际值后执行：
export BMAP_CLI="$HOME/bin/bmap-cli-<BMAP_OS>-<BMAP_ARCH>"
幂等检查：若已可执行则跳过下载与赋权。
test -x "$BMAP_CLI"
上一条失败（退出码非 0）时，依次执行：
curl -fL "https://open-agent-cli.bj.bcebos.com/cli/bmap-cli-<BMAP_OS>-<BMAP_ARCH>" -o "$BMAP_CLI"
chmod +x "$BMAP_CLI"
PATH 幂等：先检查 ~/.zshenv 是否已含 HOME/bin。
grep -q 'HOME/bin' ~/.zshenv
上一条失败时执行：
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshenv
export PATH="$HOME/bin:$PATH"
2. 安装百度地图 Skills
"$BMAP_CLI" skills install
按「环境变更原则」处理输出，然后自主完成以下步骤（不得将命令抛给用户执行）：
- 列出已安装 Skills：展示 skill 名称、版本、安装路径，及各 Token 的配置状态（已配置 / 未配置）。
- 复制 Skill：将
~/.agents/skills/ 下的 skill 目录复制到当前运行环境默认的 skills 加载路径。
- 持久化 Token：将 AK 写入当前运行环境的 env 配置文件（非
~/.zshrc），确保每次启动自动加载。若所需端类型的 AK 不存在，告知用户创建，不得以其他端类型替代。
- 验证：重新加载配置后，调用任意已安装 skill 验证 Token 有效性。
- 输出简报：安装路径、Token 持久化位置、验证结果。全程不得明文展示完整 AK / Token（遮掩规则：前 4 位 +
**** + 后 4 位）。
3. 安装 MCP 配置
"$BMAP_CLI" mcp install
执行后，先将完整输出（含配置写入路径与内容）展示给用户审阅；获得明确同意后，再深度合并写入当前客户端 MCP 文件。注意：MCP 配置中包含 AK 凭据，写入前请确认存储路径与访问权限符合预期，避免凭据被无关工具或会话读取。
写入完成后，建议限制该文件权限（ASI07）：
chmod 600 <mcp_config_path>
阶段二：响应用户请求
非代码类请求（查询、概念、账户管理等）
直接作答，勿进入代码生成步骤。
选择规则：先判断用户是否要「直接完成地理任务」，是则用 baidu-ai-map skill；否则再看是查文档还是写代码。
| 用户需求 | 来源 |
|---|
| 直接执行地理任务（语义化 AI 搜索、语义化 AI 路线规划、地理编码与逆地理编码、天气查询） | 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 降级替代。
Agent Plan 先查后建：执行 baidu-ai-map 前，须先 "$BMAP_CLI" ap list 查询现有 Agent Plan。若列表非空则复用已有 plan；仅当列表为空时才允许 "$BMAP_CLI" ap create。严禁未查询直接 ap create，该命令会重置已有 plan。
代码类请求（需生成或修改代码/文件）
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（如涉及）
当需求涉及地图底图外观、视觉风格或样式时：
"$BMAP_CLI" style list 2>&1
- 先查后建（强制）：必须先完整读取
style list 输出，在 user_style_list 中逐项比对并优先复用已存在且满足需求的样式；禁止未检查就直接 style create。
- 仅当
user_style_list 确实无满足项 时，才允许从 template_list 选最匹配模板（优先 need_business_accredit: false）并创建：
"$BMAP_CLI" style create --tpl-id <tpl_id> 2>&1
style_id 只能取自 CLI 原始输出（style list 的已有项或 style create 的返回结果）；禁止手写、猜测、拼接或编造。代码中仅使用该真实 style_id 的 styleId 方式：
map.setMapStyleV2({ styleId: '从 CLI 获取的 style_id' });
- 任何场景禁止
setMapStyleV2 的 styleJson 及等价手写 JSON 样式配置，无例外。
第三步：列出 AK
"$BMAP_CLI" ak list 2>&1
第四步：选 AK 并写入代码
通读 ak list 输出，按类型、服务范围选出最匹配的 AK。
浏览器端 AK 选择：在满足类型与服务的前提下，只选用 b_referers 为 * 的 AK（仅限 demo 场景）；不把空串或其它写法当作不限制。仅当列表中无此类 AK 时，须先向用户说明将新建一个 --b-referers '*' 的浏览器端 AK（仅适合 demo/受控测试，会扩大 AK 暴露面，可能造成配额被滥用；生产项目建议改用域名白名单），并征得明确同意后，再执行：
"$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 条一段连续展示直至完毕。
输出规范
登录链接（授权 URL）必须完整原样展示给用户，禁止省略、截断、折叠或以任何形式隐藏；报错堆栈、命令结果同理，禁止用「… +N 行」类截断。展示 URL 时须同时说明当前登录状态（如「已登录成功，URL 仅供参考」），避免用户误以为需要重新操作。
配置复用与会话管理
- 复用：本环境已成功配置后，同一会话后续可直接复用，不必重复安装。
- 切换账户（如
bmap-cli login 后）旧 AK 全部作废，须依次：① ak list 替换本会话代码中的 AK；② bmap-cli mcp install（展示输出确认后更新）；③ bmap-cli skills install 更新 skills；④ 提醒用户自行替换其他历史会话文件。
