这是一个符合 Agent Plugins 1.0.0 规范的百度地图 Agent Plugin，提供 4 个并列 Skill 和 1 个官方文档检索 MCP。
Plugin 本体位于 baidu-map/，使用标准的 plugin.json、mcp.json 和 skills/
目录结构，不绑定特定 Agent 客户端。本仓库同时提供
.agents/plugins/marketplace.json，可作为 marketplace 在 Codex 中安装；当前版本已在
Codex 0.147.0 完成端到端验证。
baidu-map-marketplace/
├── .agents/plugins/marketplace.json
├── README.md
└── baidu-map/
├── plugin.json
├── mcp.json
├── bin/
├── skills/
└── tools/
baidu-map-marketplace/ 是分发目录；baidu-map/ 是 Agent Plugin 根目录。
Plugin 使用 Agent Plugins 1.0 的根 plugin.json 和 mcp.json，不包含
.codex-plugin/、.claude-plugin/ 或 .mcp.json 兼容清单。
Agent Plugins 规范不定义统一市场，也不限定具体 Agent 客户端。任何完整支持 Agent
Plugins 1.0、Agent Skills 和 stdio MCP 的客户端，都可以按其自身机制加载
baidu-map/。实际兼容性取决于客户端对这些规范的实现，请以对应客户端的文档和验证
结果为准。
.agents/plugins/marketplace.json 是本仓库提供的 Codex 分发清单，不是 Plugin 本体的
一部分，也不表示 Plugin 仅限 Codex 使用。当前完整目录既可以通过本地路径分发，也可以
作为 Git 仓库分发；正式发布到 OpenAI Universal Plugins Directory 需要另外提交审核。
要求：Codex 0.146.0+、Node.js 18+。以下流程已使用
/opt/homebrew/bin/codex 0.147.0 完成隔离端到端测试。
将完整的 baidu-map-marketplace/ 目录交给接收方，然后执行：
codex plugin marketplace add /absolute/path/to/baidu-map-marketplace
codex plugin add baidu-map@baidu-map-marketplace将完整 marketplace 发布为 Git 仓库后执行：
codex plugin marketplace add baidu-maps/bmap-agent-plugin
codex plugin add baidu-map@baidu-map-marketplace也支持 HTTPS 或 SSH Git URL。需要固定版本时，在第一次添加 marketplace 时指定 tag：
codex plugin marketplace add baidu-maps/bmap-agent-plugin --ref v1.2.0
codex plugin add baidu-map@baidu-map-marketplacecodex plugin marketplace list
codex plugin list --marketplace baidu-map-marketplace安装完成后新开一个 Codex 会话。无需单独复制 Skills，也无需在 config.toml 中手工
注册 MCP。baidu-map@baidu-map-marketplace 是”Plugin 名@marketplace 名”，不是路径。
在支持自动发现 Agent Skills 和 MCP 的客户端中，不需要先选择入口 Skill，也不需要
显式调用 MCP。直接在新会话中描述地图需求，客户端会根据各 SKILL.md 的
description 选择 Skill，并在需要精确官方资料时调用 baidu-maps-docs MCP：
帮我找西湖附近适合带孩子的餐厅
写一个 BMapGL 页面显示多个 Marker
用 Node.js 调用百度地图驾车路线规划接口
帮我登录百度地图开放平台并查看现有 AK
查询百度地图官方文档中驾车路线规划的返回字段
不需要写 $baidu-map:...、$baidu-maps-docs 或 mcp://...。显式形式只用于调试、
验证或强制选择组件。
第一次遇到需要百度账号、AK 或 SK 的任务时，Plugin 会按需进入 bmap-cli 登录和凭据
流程，不会在安装阶段要求用户预先配置所有凭据。
Git marketplace 更新后，刷新 marketplace 快照、重新安装 Plugin，然后新开会话：
codex plugin marketplace upgrade baidu-map-marketplace
codex plugin add baidu-map@baidu-map-marketplace本地目录分发时，替换原目录内容后重新执行：
codex plugin add baidu-map@baidu-map-marketplaceCodex 缓存的是 Plugin 快照，不会实时读取源目录。修改 Skill、MCP 或 manifest 后都应 重新安装并新开会话。
卸载 Plugin：
codex plugin remove baidu-map@baidu-map-marketplace确认不再需要该 marketplace 后，可以继续移除来源：
codex plugin marketplace remove baidu-map-marketplace| 组件 | 负责 | 不负责 |
|---|---|---|
baidu-ai-map |
直接回答地点、路线、地理编码、天气等地理问题；复杂地图问题优先考虑 | 生成调用代码、账户资源管理 |
baidu-map-jsapi-gl |
编写、审查、调试 BMapGL 浏览器前端代码 | 服务端 WebAPI、直接地理问答 |
baidu-map-webapi |
编写、审查、调试服务端 WebAPI 调用代码 | 浏览器渲染、直接地理问答 |
bmap-cli |
CLI 自举、登录、AK / SK、样式、配额、消费量和账户资源管理 | 总分诊、地图代码组织 |
baidu-maps-docs MCP |
查询精确、缺失、版本相关或最新的官方 API / SDK 事实 | 决定业务流程和代码架构 |
直接地理结果 -> baidu-ai-map
浏览器地图代码 -> baidu-map-jsapi-gl -> 缺凭据时 bmap-cli
服务端地图代码 -> baidu-map-webapi -> 缺凭据时 bmap-cli
登录 / AK / Agent Plan / 样式 / 配额 -> bmap-cli
精确或最新的官方文档事实 -> baidu-maps-docs MCP
Skill 负责工作流、约束和代码组织，MCP 负责官方事实。代码任务先由业务 Skill 组织； 遇到精确、缺失或版本相关信息时查询 MCP。明确的官方文档问题可以直接使用 MCP。
本包不包含任何凭据。各业务 Skill 只在实际缺少凭据时调用 bmap-cli：
| 变量 | 用途 |
|---|---|
BAIDU_MAP_AUTH_TOKEN |
Agent Plan SK；直接地理问答 |
BMAP_WEBAPI_AK |
服务端 AK；WebAPI 代码 |
BMAP_JSAPI_KEY |
浏览器端 AK；BMapGL 代码 |
BAIDU_MAPS_DOCS_AK / BMAP_AK |
文档 MCP AK；独立运行代理时可用 |
BMAP_CLI |
已有 bmap-cli 路径；跳过自举 |
首次提出需要凭据的请求时，bmap-cli Skill 会检查外部 CLI。若本机没有 CLI，它会先
展示固定下载地址、完整命令和风险，取得用户确认后才安装，再按需启动浏览器登录并获取
正确类型的 AK / SK。
如果文档 MCP 在登录前已启动并因没有 AK 鉴权失败，完成登录后新开一个 Codex 会话，
让 MCP 进程重新从 bmap-cli 登录态解析凭据。只安装 Plugin 的含义是不需要独立安装
Skill 或手工配置 MCP；网络、百度账号登录态和按需运行的 bmap-cli 仍是外部依赖。
Codex 0.147.0 启动 Plugin stdio MCP 时会过滤任意宿主环境变量，只继承 HOME、
PATH 等安全白名单。因此文档代理在 Codex 中通常通过 HOME 找到 bmap-cli，再由
CLI 读取登录态并解析可用 AK。Agent Plugins 1.0 没有可移植的 secret reference 字段，
不能把凭据写入可见的 mcp.json env 或 headers。
Codex 原生读取 baidu-map/plugin.json、baidu-map/mcp.json 与
baidu-map/skills/，并将 Plugin 缓存到：
~/.codex/plugins/cache/baidu-map-marketplace/baidu-map/<version>/
Skill 不会被复制进 ~/.codex/skills/，MCP 也不会作为独立 [mcp_servers] 写入
config.toml。Plugin Skill 带命名空间，可以和用户单独安装的同名 Skill 并存。
${PLUGIN_ROOT} 在 MCP 启动时展开为缓存中的 Plugin 根目录。
在 marketplace 根目录执行静态校验：
node baidu-map/tools/validate.mjs执行 Codex 隔离端到端测试：
bash baidu-map/tools/test-in-codex.sh测试固定使用 /opt/homebrew/bin/codex，将当前完整 marketplace 复制到临时目录，并创建
临时 CODEX_HOME。它不继承单独安装的 Skill、MCP 或 Plugin，也不修改真实 Codex
配置。测试会验证：
- 实际交付的 marketplace 清单可以添加，
baidu-map可以安装并缓存； - 4 个 Plugin Skill 均能完整加载，且没有主提示词截断；
- 不带
$skill的自然语言请求能自动路由到正确 Skill； - 不带
mcp://的官方文档请求能自动发现并实际调用 Plugin MCP； - MCP 调用事件来自
baidu-maps-docs.list_docs，而不是 shell 或代理脚本绕行。
MCP 阶段只恢复真实 HOME，让代理复用由 bmap-cli 管理的登录态；CODEX_HOME 仍
完全隔离。非交互 codex exec 无法响应 MCP 审批，因此测试只在临时配置中为
list_docs 设置 approval_mode="approve"。
baidu-map/bin/docs-mcp-proxy.mjs 需要 Node.js 18+。它按
BAIDU_MAPS_DOCS_AK、BMAP_AK、bmap-cli ak list（优先服务端 AK）的顺序解析
凭据，将 stdio JSON-RPC 转发到 https://docs.map.baidu.com/mcp/，并兼容 JSON 与
SSE 响应。诊断信息只写 stderr。
单独验证：
printf '%s\n%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| node baidu-map/bin/docs-mcp-proxy.mjs