{"id":51476536,"url":"https://github.com/henrywen98/amap-agent-skill","last_synced_at":"2026-07-06T21:30:51.695Z","repository":{"id":366488030,"uuid":"1276472758","full_name":"henrywen98/amap-agent-skill","owner":"henrywen98","description":"高德地图 Agent Skill（无需 MCP）— geocoding/POI/weather/route planning for Claude Code · pi · any shell agent, pure curl. AMap (Gaode) maps, no MCP server.","archived":false,"fork":false,"pushed_at":"2026-06-22T03:05:13.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T05:04:24.611Z","etag":null,"topics":["agent-skills","amap","bash","china-maps","claude","claude-code","curl","gaode","gaode-map","geocoding","llm-tools","mcp","no-mcp","pi","poi-search","route-planning","weather-api"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/henrywen98.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-22T02:32:19.000Z","updated_at":"2026-06-22T03:05:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/henrywen98/amap-agent-skill","commit_stats":null,"previous_names":["henrywen98/amap-agent-skill"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/henrywen98/amap-agent-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrywen98%2Famap-agent-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrywen98%2Famap-agent-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrywen98%2Famap-agent-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrywen98%2Famap-agent-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/henrywen98","download_url":"https://codeload.github.com/henrywen98/amap-agent-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrywen98%2Famap-agent-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35206987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","amap","bash","china-maps","claude","claude-code","curl","gaode","gaode-map","geocoding","llm-tools","mcp","no-mcp","pi","poi-search","route-planning","weather-api"],"created_at":"2026-07-06T21:30:50.924Z","updated_at":"2026-07-06T21:30:51.673Z","avatar_url":"https://github.com/henrywen98.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# amap-agent-skill\n\n\u003e 高德地图 Agent Skill（**无需 MCP**）—— 给 Claude Code / pi / 任意带 shell 的 AI agent 的高德地图能力：地理编码、逆地理、POI 搜索、天气、路径规划、距离测算、IP 定位。纯 `curl`，**设一个 key 就能用**。\n\u003e\n\u003e *AMap (Gaode) maps as an Agent Skill — geocoding, POI search, weather \u0026 route planning for Claude Code, pi, or any shell agent. Pure curl, no MCP server required.*\n\n[![CI](https://github.com/henrywen98/amap-agent-skill/actions/workflows/lint.yml/badge.svg)](https://github.com/henrywen98/amap-agent-skill/actions/workflows/lint.yml) ![license](https://img.shields.io/badge/license-MIT-blue) ![shell](https://img.shields.io/badge/shell-bash-green) ![no-mcp](https://img.shields.io/badge/MCP-not%20required-orange)\n\n![星合广场租房决策示例](examples/星合广场租房简图.svg)\n\n\u003e 上图：用本 skill 做「找房前的地段决策」——把几个候选小区的通勤与价格画成一张对比图（[examples/](examples/)）。\n\n---\n\n## 这是什么\n\n一个 [Agent Skill](https://agentskills.io/)：一个 `SKILL.md` + 一个 `scripts/amap.sh`（纯 `curl` 封装高德 [Web 服务 REST API](https://lbs.amap.com/api/webservice/summary)）。它把高德官方 MCP 里的 `maps_*` 工具，落成了**不需要 MCP server** 的命令行能力，因此能在**任何带 shell 的 agent**（pi、Claude Code、Codex…）里直接跑。\n\n覆盖能力：\n\n- 🧭 **地理编码 / 逆地理**：地址 ↔ 经纬度、坐标 → 行政区划\n- 📍 **POI 搜索**：关键词搜、周边搜、POI 详情\n- 🌦️ **天气**：实况 + 预报\n- 🚗 **路径规划**：驾车 / 步行 / 骑行 / 公交地铁\n- 📏 **距离测算** \u0026 🌐 **IP 定位**\n\n## 不是什么（边界）\n\n它只读**公开的地理数据**。它**不碰**房源库存、实时报价、成交——那些锁在贝壳/链家/中介手里，是另一回事。所以「找房」这个示例里，本 skill 负责的是**找房前的决策**（哪片区、通勤多久、环境如何），具体房源和价格仍由你去平台/中介获取。\n\n## 示例：找房前的地段决策（实战）\n\n页首那张 `星合广场租房简图`，就是用本 skill 跑出来的一张决策图：以 **时代广场站（1 号线 + 8 号线换乘）** 为锚点，把苏州工业园区 5 个候选片区按「通勤 vs 租金」摊开对比。\n\n| 片区（方位） | 通勤 | 月租（一室 / 两室） | 判定 |\n|---|---|---|---|\n| 时代广场（锚点） | 零通勤 | —— | 最贵 |\n| 南施街（东） | 1 号线 **13 分直达** | 3–4k / 4.5–6k | 中 · 省心 |\n| ⭐ 星塘街·海悦花园（东） | 1 号线 **16 分直达** | **2.5–3.5k / 3.8–5k** | **便宜 · 推荐** |\n| 湖西 CBD（西） | 1 号线 ~15 分 | 同价或更贵 | 贵 · 不推荐（过桥更堵） |\n| 娄葑（西南） | 7 号线 ~33 分换乘 | 2–3k / 3.5–4.8k | 便宜但绕 |\n| 唯亭（东北） | 3 号线 ~45 分换乘 | 1.5–2.5k / 2.8–3.8k | 最便宜 · 最远 |\n\n**结论**：最优是 ⭐ **星塘街·海悦花园**——和南施街几乎一样快（16 vs 13 分，都是 1 号线直达），但明显更便宜，是「通勤/租金」的甜点；往西的湖西 CBD 同价还更堵、纯亏；娄葑/唯亭只有预算特别紧才值得忍受换乘和长通勤。\n\n它**只做决策那一半**：通勤、距离、周边环境用高德算出来，租金只给行情区间，**实际挂牌价交接给贝壳 / 安居客** 按小区名核对。复现命令见 [`examples/rental-decision.md`](examples/rental-decision.md)。\n\n## 为什么不用 MCP\n\n| | MCP 路 | 本 skill |\n|---|---|---|\n| 用户要做的事 | harness 支持 MCP → 配 `.mcp.json` → 拿 key | **放两个文件 → 拿 key** |\n| 依赖 | 一个常驻 MCP server / 客户端 | 只要 `bash` + `curl`（系统自带） |\n| 能跑在哪 | 支持 MCP 的工具 | **任何带 shell 的 agent** |\n\n\u003e 注册一个 key 这一步 MCP 也躲不掉（官方 MCP 地址也是 `mcp.amap.com/mcp?key=…`）。本 skill 没增加凭证负担，只是**拆掉了 MCP 那一层**。\n\n## 快速开始\n\n**1. 安装**（装进一个名为 `amap` 的 skill 目录）\n\n```bash\n# pi（原生发现 ~/.agents/skills）\ngit clone https://github.com/henrywen98/amap-agent-skill.git ~/.agents/skills/amap\n\n# Claude Code（发现 ~/.claude/skills）\ngit clone https://github.com/henrywen98/amap-agent-skill.git ~/.claude/skills/amap\n```\n\n**2. 配 key**（[高德开放平台](https://lbs.amap.com/) → 创建应用 → 「Web 服务」key，需实名）\n\n```bash\nexport AMAP_KEY=你的key            # 或写进当前项目的 .env：AMAP_KEY=你的key\n```\n\n**3. 用**\n\n```bash\namap.sh weather 北京\namap.sh geo \"上海市浦东新区世纪大道100号\"\namap.sh around \"121.5,31.23\" 咖啡 800     # location 一律「经度,纬度」\namap.sh doctor                            # 校验 key + 缓存实时工具清单\n```\n\n或者直接对 agent 说「北京今天天气怎样」「我附近的咖啡馆」「从公司到机场怎么走」，它会读 `SKILL.md` 自己调。\n\n## 命令清单\n\n`location` 一律 `经度,纬度`（longitude 在前）。返回原始高德 JSON（`status:\"1\"` 为成功）。\n\n| 命令 | 说明 |\n|---|---|\n| `geo \u003caddress\u003e [city]` | 地址 → 经纬度 |\n| `regeocode \u003clng,lat\u003e` | 经纬度 → 行政区划地址 |\n| `around \u003clng,lat\u003e [kw] [radius]` | 周边搜 POI（默认 1000m） |\n| `text \u003ckw\u003e [city] [citylimit]` | 关键词搜 POI |\n| `detail \u003cpoiid\u003e` | POI 详情 |\n| `weather \u003ccity\\|adcode\u003e [base\\|all]` | 天气（默认 all=预报） |\n| `driving / walking / bicycling \u003co\u003e \u003cd\u003e` | 驾车 / 步行 / 骑行路径 |\n| `transit \u003co\u003e \u003cd\u003e \u003ccity\u003e [cityd]` | 公交地铁（跨城需 city/cityd） |\n| `distance \u003corigins\u003e \u003cdest\u003e [type]` | 距离（type 0直线/1驾车/3步行） |\n| `ip [ip]` | IP 定位 |\n| `raw \u003cpath\u003e [k v ...]` | 透传任意 v3/v4 接口 |\n| `doctor [--refresh]` | 校验 key + 缓存实时工具清单 |\n\n## 工作原理\n\n- **热路径直连 REST**：每次 query 直接打 `restapi.amap.com`，**不经过 MCP**。命令 → REST 接口的映射，是**打包时**由高德 MCP 的 `tools/list` 自描述输出编译固化进脚本的。\n- **`doctor` = 缓存式自描述**：想看高德当前暴露的工具/参数，`amap.sh doctor` 会一次性拉 `tools/list` 缓存到本地、`--refresh` 重拉。**仅用于发现**，不在 query 主路径（`tools/list` 不返回 REST 地址，日常无需它）。\n- **key 解析**：`$AMAP_KEY`（回退 `$AMAP_MCP_KEY`）\u003e 向上最近的 `.env`。\n\n## 定位（「我在哪 / 附近的…」）\n\n没坐标时，**别默认 IP 定位**（挂代理会定错）。macOS 推荐用 [whereami](https://github.com/lassik/whereami) 走系统定位拿精确坐标；非 mac 让用户给地名或坐标。注意 whereami/GPS 是 **WGS-84**、高德是 **GCJ-02**，国内有约几百米偏移（市区级可忽略，门牌/POI 级要留意）。详见 `SKILL.md`。\n\n## 可视化\n\n需要对比/出图时，skill 会**优先生成 SVG**（像上面那张）；若 harness 无法内联渲染 SVG，则在回复里**直接给 markdown 表 / ASCII 简化版**，并始终附文字结论——绝不只依赖 SVG 被渲染。\n\n## 安全\n\n- 仓库**不含**任何真实 key；只有 `.env.example`。`.env` 已在 `.gitignore`。\n- 自己注册 key，并在高德控制台为它设置**域名/服务白名单 + 配额**，避免泄露被盗刷。\n\n## 致谢 / 相关\n\n- [高德开放平台 · Web 服务 API](https://lbs.amap.com/api/webservice/summary)\n- [Agent Skills 标准](https://agentskills.io/) · [pi coding agent 的 \"No MCP\" 哲学](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)\n\n## 贡献\n\n欢迎 issue / PR。改脚本前请确保 `shellcheck scripts/amap.sh` 与 `bash -n scripts/amap.sh` 通过（CI 也会自动跑）。\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n### English summary\n\n**amap-agent-skill** is an MCP-free [Agent Skill](https://agentskills.io/) wrapping the **AMap / Gaode (高德地图)** Web Service REST API in a single `bash` + `curl` script. It gives **Claude Code**, **pi**, or any shell-capable LLM agent geocoding, reverse geocoding, POI search, weather, route planning (driving / walking / cycling / transit), distance and IP-location tools — **no MCP server, just set an `AMAP_KEY`**. Keywords: AMap, Gaode map, China maps, agent skill, Claude Code skill, MCP alternative, geocoding, POI search, weather API, route planning, LLM tools.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenrywen98%2Famap-agent-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhenrywen98%2Famap-agent-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenrywen98%2Famap-agent-skill/lists"}