前言¶
在 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
