SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbmap-cli

bmap-cli

Coding & development

View repository

Updated 10-16 05:01

About this skill

bmap-cli Baidu Maps Open Platform tool

[Highest priority] If any bmap-cli command output contains the words "new version found", you must immediatelycomplete update commandshow it to the user, and at the same time indicate the download domain appearing in the command (e.g. open-agent-cli.bj.bcebos.com), prompt the user to confirm that the domain matches the source of the initial installation, execute only after obtaining consent, and then continue the current operation after completion. This rule applies to all commands and all steps, with no exceptions.

Trigger conditions

This skill is enabled if any one condition is met:

Trigger scenario Typical behavior
Semantic AI search, semantic AI route planning, geocoding and reverse geocoding, weather query Call baidu-ai-map skill to directly complete geographic tasks
Personalized map style query or creation Execute style list / style create command
Baidu Maps development (WebAPI, BMapGL, JSAPI), tool installation and configuration Enter the environment preparation process, install CLI / Skills / MCP
Generate HTML, demo, or code containing Baidu Maps Obtain AK, consult documentation, and deliver runnable code

Core capabilities

Capability Description
Environment management CLI installation, idempotent Skills / MCP configuration, fully automated handling of login and version updates
AK management Query existing AKs, create browser-side or server-side AKs as needed, display with secure masking
Map style management Query the personalized style list, create new styles from templates, provide real style_id
Baidu Maps Agent Plan Via baidu-ai-map skill (providing map tools that are friendly for large model invocation) to complete semantic AI search, semantic AI route planning, geocoding and reverse geocoding, weather query
Code generation Deliver runnable BMapGL / WebAPI code containing real AK and style ID

Execution principles

Operation boundaries

  • Read-only/query operations: complete autonomously.
  • Configuration changes, resource creation (AK/style): must first show the operation content and obtain the user's explicit consent before executing.
  • Failure handling: retry and provide actionable troubleshooting instructions.

Environment change principles

The following principles apply to all installation/configuration steps:

  1. Idempotent: skip if already ready, do not reinstall repeatedly.

  2. Configuration review：skills install / mcp install if the terminal output contains instructions to be executed or configuration to be written, it must first befully shown to the user for review; after obtaining explicit consent, then execute or write them one by one; automatic configuration changes are prohibited without confirmation.

  3. Version update: If any command output contains the phrase "new version found" and the corresponding update command, the update command must be shown to the user and consent obtained before continuing with the subsequent steps.

  4. MCP merge: MCP configuration must be deeply merged with the existing local configurationdeep merge; do not overwrite unrelated entries; if the output is "already installed, skipping", skip that step.

  5. Login handling：

    • User already logged in: If the user explicitly states they are already logged in, execute the target command directly; only enter the login flow when the command returns a "not logged in" error.
    • Absolutely prohibited: throwing it to the user for manual execution; wrapping with timeout/nohup; putting it in the background (&) or piping (|); using sleep/ps/find/for/while to poll and check login status or wait for the configuration file to be generated; searching for token files, environment variables, or any credential storage location; repeatedly self-confirming the same issue more than once.

    If any command output contains a "not logged in" error, the user must be informed and explicit consent obtained, then immediately execute it yourself: "$BMAP_CLI" login。

    Common model errors (must be avoided)

    # 错误写法（timeout / 后台 / 重定向 / 管道）
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 isa human-machine collaboration process that guides the user through browser authorization, not a technical script for the model to obtain a token. After execution, immediately output the authorization URL and enter polling wait; the token is managed internally by the CLI, and the model does not need to know about it and should not look for it.The model must not wait for the command to finish; it must extract the URL immediately and display it to the user in a separate code block, while telling the user to click authorize in the browser:

    请在浏览器中打开以下链接完成授权（完整链接，禁止省略或截断）。如已完成登录授权，可忽略此链接：
<完整 URL>

    Once the URL is displayed, the model has completed its part of the work; the remaining time is for the user to complete authorization in the browser; the CLI internally manages the 5-minute polling timeout, and the model does not need to intervene.

Workflow

Workflow overview

触发 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 → 写入代码交付
横切：任何命令含「发现新版本」→ 展示更新命令，征得同意后继续

Phase 1: Environment preparation

The following three steps are all idempotent operations; skip them if already ready.

1. Install CLI

The download address must be shown to the user. Claude Code's Bash tool permission confirmation box will show the full curl command (including the URL) to the user; the user clicking "Allow" constitutes explicit consent; clicking "Deny" aborts the installation.

Security note (ASI04): The current download process has no built-in checksum or signature verification, and the authenticity of the binary depends on trust in open-agent-cli.bj.bcebos.com . If verification is needed, obtain the SHA256 checksum for this version through the official Baidu Maps Open Platform channel, and after downloading run sha256sum "$BMAP_CLI" to compare.

mkdir -p ~/bin

uname -s

uname -m

Determine the platform suffix based on the output of the previous two steps (do not use piping to concatenate detection):

  • BMAP_OS：Darwin→darwin，Linux→linux, convert the rest to lowercase
  • BMAP_ARCH：x86_64→amd64，aarch64→arm64, keep the rest as is

Replace <BMAP_OS>、<BMAP_ARCH> with the actual value and execute:

export BMAP_CLI="$HOME/bin/bmap-cli-<BMAP_OS>-<BMAP_ARCH>"

Idempotency check: if it is already executable, skip the download and permission assignment.

test -x "$BMAP_CLI"

If the previous item fails (exit code non-zero), execute in sequence:

curl -fL "https://open-agent-cli.bj.bcebos.com/cli/bmap-cli-<BMAP_OS>-<BMAP_ARCH>" -o "$BMAP_CLI"

chmod +x "$BMAP_CLI"

PATH idempotency: first check whether ~/.zshenv already contains HOME/bin。

grep -q 'HOME/bin' ~/.zshenv

If the previous item fails, execute:

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshenv

export PATH="$HOME/bin:$PATH"

2. Install Baidu Maps Skills

"$BMAP_CLI" skills install

Handle the output according to the "Environment Change Principles", then complete the following steps autonomously (do not throw commands to the user for execution):

  1. List installed Skills: display the skill name, version, installation path, and the configuration status of each Token (configured / not configured).
  2. Copy Skill: Copy the skill directory under ~/.agents/skills/ to the default skills loading path of the current runtime environment.
  3. Persist Token: Write the AK to the env configuration file of the current runtime environment (not ~/.zshrc), ensuring it is automatically loaded on each startup. If the AK for the required endpoint type does not exist, inform the user to create it; do not substitute another endpoint type.
  4. Verification: After reloading the configuration, call any installed skill to verify Token validity.
  5. Output Summary: Installation path, Token persistence location, verification result. Never display the full AK / Token in plaintext throughout (masking rule: first 4 characters + **** + last 4 characters).

3. Install MCP Configuration

"$BMAP_CLI" mcp install

After execution,first present the complete output (including configuration write paths and contents) to the user for review; after obtaining explicit consent, then perform a deep merge write into the current client MCP file. Note: the MCP configuration contains AK credentials; before writing, confirm that the storage path and access permissions meet expectations to avoid the credentials being read by unrelated tools or sessions.

After the write is complete, it is recommended to restrict the file permissions (ASI07):

# 将路径替换为实际 MCP 配置文件路径
chmod 600 <mcp_config_path>

Phase 2: Respond to User Requests

Non-code requests (queries, concepts, account management, etc.)

Answer directly,do notenter the code generation steps.

Selection Rule: First determine whether the user wants to "directly complete a geographic task"; if so, use the baidu-ai-map skill; otherwise, determine whether it is a documentation query or code writing.

User Requirement Source
Directly execute geographic tasks(semantic AI search, semantic AI route planning, geocoding and reverse geocoding, weather query) baidu-ai-map skill
Query API documentation (interface parameters, limits, pricing description) baidu-maps-docs MCP
Generate code that calls the map (HTML, JSAPI examples, WebAPI integration) baidu-map-jsapi-gl or baidu-map-webapi skills

Mandatory：baidu-ai-map is the direct execution of geographic tasks'onlyentry point;baidu-map-webapi must not be used as its substitute. If baidu-ai-map has not been loaded, inform the user to restart Claude Code and retry;must notdegrade to any other skill as a substitute.

Agent Plan query before creation: Before executing baidu-ai-map , you must first "$BMAP_CLI" ap list query existing Agent Plans. If the list is non-empty, reuse the existing plan;only when the list is empty is it allowed "$BMAP_CLI" ap create。strictly prohibitedto directly ap createwithout querying; this command will reset the existing plan.

Code requests (requiring generation or modification of code/files)

JSAPI version selection (default to GL version): When writing map frontend code,use BMapGL (GL version) by default, i.e., reference https://api.map.baidu.com/api?v=1.0&type=webgl&..., with the object namespace being BMapGL。Only when the user explicitly specifies "3.0 version" or existing code is based on 3.0, use BMapJS(v3.0). The two API namespaces must not be mixed.

Before writing codestrictly in orderexecute the following four steps,skipping steps or changing the order is prohibited。

Step 1: Determine the AK type
Scenario AK type
Frontend HTML, BMapGL, JSAPI Browser side
Server-side WebAPI, backend scripts Server side
Involves both frontend and backend Both are needed
Other Only take the types that will actually be used

Browser-side AK whitelist rule：b_referers is "unrestricted",only the literal value *is accepted. That is:

  • b_referers must not be empty;
  • must not use descriptions such as "fill in the domain based on the user's actual access source" in place of *。

Security note (ASI03)：b_referers = * 's wildcard AK will expand the exposure surface; any page can call it, creating a risk of quota abuse.Only applicable to local demos or controlled test environments; production/formal projects should use an AK with a specific domain whitelist (such as example.com).

In ak list , browser-side AK only preferentiallyselect b_referers equal to * items (demo scenarios only),do notselect items that only contain a specific domain whitelist. If there is no such AK, you mustfirst inform the user that a new AK containing --b-referers '*' will be created(only suitable for demos, will increase AK exposure and consume account resources), and after obtaining the user's explicit consent, proceed to step 4 to create it.

Step 2: Obtain the map style ID (if involved)

When the requirement involves the map base map appearance, visual style, or style:

"$BMAP_CLI" style list 2>&1
  • Check before creating (mandatory): you must first fully read the style list output, and in user_style_list compare item by item and preferentially reuse existing styles that satisfy the requirement;prohibitedto directly style create。
  • Only when user_style_list indeed has no satisfying item may you select the most matching template from template_list (prefer need_business_accredit: false) and create it:
"$BMAP_CLI" style create --tpl-id <tpl_id> 2>&1
  • style_id can onlycome from the CLI raw output (style list 's existing items or style create 's returned result);prohibitedto handwrite, guess, concatenate, or fabricate. In the code,onlyuse that real style_id 's styleId Method:
map.setMapStyleV2({ styleId: '从 CLI 获取的 style_id' });
  • In any scenario, prohibited setMapStyleV2 's styleJson and equivalent handwritten JSON style configuration, with no exceptions.
Step 3: List the AKs
"$BMAP_CLI" ak list 2>&1
Step 4: Select an AK and write it into the code

Read through the ak list output, and select the most matching AK by type and service scope.

Browser-side AK selection: on the premise of satisfying type and service,onlyselect an AK whose b_referers is * (demo scenarios only); do not treat an empty string or other notations as unrestricted.Only when there is no such AK in the list, you must first explain to the user that a new browser-side AK with --b-referers '*' will be created (Suitable only for demo/controlled testing; it expands the AK exposure surface and may lead to quota abuse. For production projects, it is recommended to switch to a domain whitelist.), and only after obtaining explicit consent, execute:

"$BMAP_CLI" ak create --app-name "<应用名称>" --app-type 3 --b-referers '*' 2>&1

After successful creation,re-execute step three ak list, then select the new AK.

Writing into Code Specifications：

  • In code,you mustuse thecomplete original AK stringfrom the list; filling it in from memory or inference is prohibited.

  • When involving any key identifier or precise field (such as ak、app_id、style_id , etc.),always take the latest raw CLI output of the current round as authoritative; filling in from memory, historical screenshots, or previous replies is prohibited. When the output is large, you must perform exact field matching and ensure uniqueness (if there are 0 or multiple entries, disambiguate first).

  • When the user has explicitly issued a query instruction (such as "query the call volume/quota for this AK"), directly execute in the order of "verify target -> precisely retrieve fields -> immediately execute query -> return result"; unless the command is blocked (permissions/network/login invalid), it is prohibited to only apologize or ask a question in return.

  • 前4位****后4位 and other formsonlyfor chat explanation,prohibitedfrom being written into source code.

  • Before writing into code, first send a one-line declaration in the conversation (fixed format):

    > 已获取 AK：{前4位}****{后4位}（{app_type}，{app_name}，白名单：{b_referers}）

  • In the delivered code,must notcontain placeholders, fake AKs, "please replace it yourself", or similar prompts.

Specification Overview

AK Security and Display

  • Storage: AKs are only written into the target code file; do not use echo/print to output the complete AK to the terminal.
  • Display: when displaying to the user, use "first 4 characters + **** + last 4 characters" (such as ByM8****KMxw）。
  • List display: merging, grouping, and range omission are prohibited; list them one by one in the original order; when there are more than 20 entries, display them continuously in segments of 20 until complete.

Output Specifications

The login link (authorization URL) must be displayed completely and as-is to the user; omission, truncation, folding, or hiding in any form is prohibited; the same applies to error stacks and command results, and truncation such as "… +N lines" is prohibited. When displaying a URL, the current login status must also be stated (such as "login successful, the URL is for reference only") to avoid the user mistakenly thinking that they need to operate again.

Configuration Reuse and Session Management

  • Reuse: after this environment has been successfully configured, it can be reused directly in subsequent turns of the same session, and there is no need to reinstall repeatedly.
  • Switching accounts(such as after bmap-cli login ) all old AKs become invalid, and you must in sequence: ① ak list replace the AK in the code of this session; ② bmap-cli mcp install(update after displaying the output for confirmation); ③ bmap-cli skills install update skills; ④ remind the user to replace files in other historical sessions themselves.