前言¶
在 Web 里接腾讯地图 JavaScript GL（JSAPI GL），常见问题不是「能不能画出来」，而是文档分散、示例版本不一、覆盖物与图层组合容易踩坑。用通用大模型写地图代码时，还容易出现初始化参数、事件绑定或 Key 使用方式与当前 API 不一致的情况。
下面介绍 SkillHub 上的企业级 Skill「腾讯地图JSAPI GL开发技能」，由腾讯地图位置服务团队发布，用于在编写、审查或调试腾讯地图 API 相关代码时，让 Agent 按同一套开发指南行事。
这是什么¶
「腾讯地图JSAPI GL开发技能」是面向腾讯地图 JavaScript GL（JSAPIGL）的开发指南型 Skill，坐标为 @tencent-adm/tencentmap-jsapi-gl-skill，当前版本 1.0.4，来源标注为 enterprise，SkillHub 分类为 dev-programming。Skill 页标注 requires_api_key=true，实际开发需要配置腾讯地图 JSAPI 的 Key。
官方入口：
- API 页：https://api.skillhub.cn/tencent-adm/tencentmap-jsapi-gl-skill
- SkillHub 展示页：https://www.skillhub.cn/skills/tencent-adm/tencentmap-jsapi-gl-skill
核心功能¶
Skill 简介中列出的适用任务范围如下，均来自官方说明，可按模块理解 Agent 在哪些问题上会对齐指南：
- 地图基础：地图初始化、图层控制、事件处理、控件交互。
- 展示与渲染：覆盖物展示、可视化渲染、三维模型展示、性能优化。
- 地图能力：地图工具、检索、路线规划、查地址、行政区划、IP 定位、几何计算。
触发方式：当对话中出现「腾讯地图」「jsapi」「jsapi-gl」或相关地图开发需求时，适合加载该 Skill。
加载后的强制行为（官方原文要求）：第一个动作必须是检查是否存在正式 Key——环境变量 TMAP_JSAPI_KEY，或用户已在对话中提供 Key。若已有正式 Key，直接处理用户请求；若没有，须先向用户展示 Key 选择提示（正式 Key 注册引导 + 预设体验 Key 选项），在用户选择之前不得进行分析、读文件、规划或写代码。
安装与启用¶
通过 SkillHub CLI 安装¶
先确认本机是否已安装 skillhub：
command -v skillhub && skillhub --version
未安装时，可按 SkillHub 安装文档执行（完整安装或仅 CLI）：
# 完整安装（CLI + 默认 Skill，推荐）
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
# 仅安装 CLI
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
安装本 Skill 时，必须用 --dir 指向当前 Agent 的 skills 目录；否则默认装到 ./skills/，Agent 可能无法识别。各客户端路径不同，安装文档中给出的常见示例如下：
| 环境 | skills 目录（示例） |
|---|---|
| Cursor | ~/.cursor/skills/ |
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ 或项目下的 .agents/skills/ |
安装命令形式：
skillhub install @tencent-adm/tencentmap-jsapi-gl-skill --dir <你的 Agent skills 目录>
也可在 SkillHub 技能页，将提示词发给 AI，让其按 https://skillhub.cn/install/skillhub.md 完成安装：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@tencent-adm/tencentmap-jsapi-gl-skill`。
Key 配置¶
正式 Key 可通过环境变量提供给 Agent 与本地工程：
export TMAP_JSAPI_KEY="你的腾讯地图 JSAPI Key"
未配置时，Skill 要求 Agent 先引导用户选择正式 Key 或体验 Key，再继续后续开发步骤。
典型用法¶
经过上面的安装与 Key 准备，典型工作流可以概括为：
- 在 Cursor、Claude Code、Codex 等支持 Skills 的客户端中启用
@tencent-adm/tencentmap-jsapi-gl-skill。 - 发起与腾讯地图 JSAPI GL 相关的需求（例如初始化地图、加覆盖物、路线规划、地址检索等）。
- Agent 按 Skill 规则先校验
TMAP_JSAPI_KEY或对话中的 Key；通过后再编写、审查或调试代码。 - 涉及检索、路线、行政区划、IP 定位等能力时，由 Skill 内的开发指南约束实现方式，减少与官方 API 用法偏离。
公开资料未提供完整 SKILL.md 正文或可复制运行的官方示例片段，具体 API 调用以 Skill 加载后 Agent 遵循的指南及腾讯地图 JSAPI GL 官方文档为准。
适用场景与注意¶
适合谁
- 正在做地图应用或内部地图工具的前端 / 全栈开发者。
- 希望 Agent 参与代码审查、联调排错，且需要统一腾讯地图 JSAPI GL 用语与流程的团队。
使用注意
- 必须预留 Key：标签
requires_api_key=true，且 Skill 强制先处理 Key，未选 Key 时 Agent 不会直接改代码。 - 安装路径要对：务必
skillhub install ... --dir <Agent skills 目录>，避免装到默认./skills/导致不生效。 - 版本与数据：Skill 当前为 v1.0.4；SkillHub 页展示的评分为 100000，下载 3795 次，安装 4 次（以页面展示为准，会随时间变化）。
结尾¶
「腾讯地图JSAPI GL开发技能」把腾讯地图位置服务团队整理的 JSAPI GL 开发指南封装成 Agent Skill，覆盖从地图初始化到检索、路线、几何与性能等常见任务，并在加载后优先处理 Key 合规问题。若你使用 Cursor 等工具做腾讯地图相关开发，可从 SkillHub 安装 @tencent-adm/tencentmap-jsapi-gl-skill，并配置 TMAP_JSAPI_KEY 后接入日常对话。
官方地址：https://api.skillhub.cn/tencent-adm/tencentmap-jsapi-gl-skill
