bmap-cli

bmap-cli 百度地图开放平台ツール

［最高優先度］ bmap-cli コマンドの出力に「发现新版本」という文言が含まれている場合は、完全な更新コマンドを直ちにユーザーに提示し、コマンド内に含まれるダウンロードドメイン（例：open-agent-cli.bj.bcebos.com）も明記してください。初回インストール元と同じドメインであることをユーザーに確認するよう促し、同意を得てから実行し、完了後に現在の操作を続けてください。このルールは例外なく、すべてのコマンドとすべての手順に適用されます。

発動条件

次のいずれかに該当する場合、このスキルを有効にします。

発動シナリオ	典型的な動作
セマンティック 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（LLM が使いやすい地図ツールを提供）を通じて、セマンティック AI 検索、セマンティック AI ルート計画、ジオコーディングと逆ジオコーディング、天気の検索を実行します
コード生成	実際の AK とスタイル ID を含む、実行可能な BMapGL ／ WebAPI コードを提供します

実行原則

操作の範囲

• 読み取り／検索のみの操作：自律的に実行します。
• 設定変更、リソース作成（AK／スタイル）：操作内容を事前に提示し、ユーザーの明確な同意を得てから実行します。
• 失敗時の対応：再試行し、実行可能なトラブルシューティング手順を提示します。

環境変更の原則

以下の原則は、すべてのインストール／設定手順に適用されます。

1. 冪等性：準備が完了している場合はスキップし、重複してインストールしないでください。

2. 設定の確認：skills install ／ mcp install のターミナル出力に実行待ちの指示や書き込み予定の設定が含まれている場合は、ユーザーが確認できるよう全内容を提示してください。明確な同意を得てから、項目ごとに実行または書き込みます。確認なしに設定を自動変更することは禁止されています。

3. バージョン更新：コマンド出力に「发现新版本」という文言と対応する更新コマンドが含まれている場合は、その更新コマンドをユーザーに提示し、同意を得てください。完了後に次の手順へ進みます。

4. MCP のマージ：MCP 設定はローカルの既存設定とディープマージし、無関係な項目を上書きしないでください。出力が「已安装，跳过」の場合は、その手順をスキップします。

5. ログインの処理：

   • ユーザーがログイン済みの場合：ユーザーがログイン済みであることを明確に伝えている場合は、対象のコマンドを直接実行します。コマンドが「未登录」エラーを返した場合に限り、ログインフローに進みます。
   • 絶対に禁止：ユーザーに手動実行を求めること、timeout/nohup で囲むこと、バックグラウンド（&）またはパイプ（|）を使うこと、sleep／ps／find／for／while でログイン状態や設定ファイルの生成をポーリングして確認・待機すること、token ファイル、環境変数、または認証情報の保存場所を探すこと、同じ問題について一度を超えて繰り返し自己確認すること。

   コマンド出力に「未登录」エラーが含まれている場合は、ユーザーにその旨を伝え、明確な同意を得た後、直ちに自分で "$BMAP_CLI" login を実行してください。

   モデルによくある誤り（必ず回避してください）

   # 誤った書き方（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 はユーザーをブラウザー認証へ導く、人と連携するフローであり、モデルが 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：環境準備

以下の 3 つの手順はすべて冪等です。準備が完了している場合はスキップします。

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

上の 2 つの手順の出力からプラットフォームのサフィックスを特定してください（検出のためにパイプで連結しないでください）。

• 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

「環境変更の原則」に従って出力を処理し、以下の手順を自律的に実行してください（コマンドをユーザーに渡して実行させてはいけません）。

1. インストール済み Skills の一覧表示：skill 名、バージョン、インストールパス、および各 Token の設定状態（設定済み／未設定）を表示します。
2. Skill のコピー：~/.agents/skills/ にある skill ディレクトリを、現在の実行環境で既定の skills 読み込みパスにコピーします。
3. Token の永続化：AK を現在の実行環境の env 設定ファイル（~/.zshrc 以外）に書き込み、起動のたびに自動で読み込まれるようにします。必要な端種別の AK が存在しない場合は、作成するようユーザーに伝えてください。他の端種別の AK で代用してはいけません。
4. 検証：設定を再読み込みした後、インストール済みの任意の skill を呼び出して Token の有効性を検証します。
5. 概要の出力：インストールパス、Token の永続化先、検証結果を提示します。全工程を通じて、AK ／ Token の全体を平文で表示してはいけません（マスキング規則：先頭 4 文字 + **** + 末尾 4 文字）。

3. MCP 設定のインストール

"$BMAP_CLI" mcp install

実行後、設定の書き込み先と内容を含む出力全体を、まずユーザーに提示して確認してもらいます。明確な同意を得てから、現在のクライアントの MCP ファイルにディープマージで書き込んでください。MCP 設定には AK 認証情報が含まれます。書き込み前に保存先とアクセス権限が想定どおりであり、無関係なツールやセッションから認証情報を読み取られないことを確認してください。

書き込み完了後、このファイルの権限を制限することを推奨します（ASI07）。

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

フェーズ 2：ユーザーのリクエストへの対応

コードを伴わないリクエスト（検索、概念、アカウント管理など）

そのまま回答し、コード生成の手順には進まないでください。

選択ルール：まず、ユーザーが「地理タスクを直接実行」したいか判断します。該当する場合は 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）を使用してください。2 つの API 名前空間を混在させてはいけません。

コードを書く前に、以下の 4 つの手順を必ず順番どおりに実行してください。手順の省略や順序の変更は禁止です。

第一步：AK の種類を決定する

シナリオ	AK の種類
フロントエンド HTML、BMapGL、JSAPI	ブラウザー側
サーバー側 WebAPI、バックエンドスクリプト	サーバー側
フロントエンドとバックエンドの両方に関連する場合	両方
その他	実際に使用する種類のみ

ブラウザー側 AK のホワイトリストルール：b_referers が「制限なし」の場合、文字どおりの * のみを有効とします。つまり：

• b_referers は空にしてはいけません。
• 「ユーザーが実際にアクセスする際のドメインを入力する」などの説明で * を代用してはいけません。

セキュリティに関する注意（ASI03）：b_referers = * のワイルドカード AK は公開範囲が広がり、どのページからでも呼び出せるため、割り当て量が悪用されるリスクがあります。ローカルデモまたは管理されたテスト環境でのみ使用してください。本番／正式なプロジェクトでは、具体的なドメインのホワイトリスト（例：example.com）を使用する AK を推奨します。

ak list では、ブラウザー側 AK に限り、b_referers が * の項目を優先して選択してください（デモ環境のみ）。具体的なドメインのホワイトリストだけを含む項目は選択しないでください。この条件に合う AK がない場合は、--b-referers '*' を含む AK を新規作成する予定であることを先にユーザーに伝えてください（デモ環境のみ適しており、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 の選択：種類とサービスの条件を満たす AK のうち、b_referers が * の AK のみを選択してください（デモ環境のみ）。空文字列やほかの形式を「制限なし」として扱ってはいけません。この条件に合う AK がリストにない場合に限り、--b-referers '*' を指定したブラウザー側 AK を新規作成することを先にユーザーに説明してください（デモ／管理されたテスト環境のみ適しています。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位 などの形式はチャットでの説明にのみ使用でき、ソースコードに記述してはいけません。

• コードを記述する前に、会話内で次の固定形式の宣言を 1 行送信してください：

  > 已获取 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 を更新する。④ ほかの過去のセッションファイルはユーザー自身で置き換えるよう案内する。