高德全国景点信息获取

概述

启动方式

• 加载本技能后，首条消息输入「执行」即启动（唯一入口）；用户若先发别的，回一句「请发送『执行』启动」。
• 启动后第一件事是走「〇-1 付费前置流程」：支付能力检查 → 价格披露与用户确认 → 下单支付 → 校验 PAID → 确认支付成功后再执行第 0 步前置检查。
• 未确认支付成功前，不得进入任何业务步骤：不得调用高德 API、不得下载图片、不得创建输出目录、不得生成 Excel。

〇-1、付费前置流程（Pay Skill 必读）

本技能为按次付费技能：

P0 · 前置检查：当前智能体是否支持微信 AI 支付

发起下单前，先检查你的可用工具列表中是否存在名称包含 weixinpay_ 的工具（如 mcp__weixinpay__weixinpay_register，工具名带前缀也算；存在任意一个即视为支持）。

只以你的工具列表为证据，本文档中提到的工具名不算；无法确认时按「不支持」处理。

• 支持：继续本 Skill 的后续流程。

先预热支付服务（P0 通过后立即执行一次）：

BASH复制

python "<技能目录>/scripts/pay_client.py" warmup

支付服务无流量时会缩容到 0，冷启动实测需要 1~2 分钟。提前预热能把这段等待

藏在用户阅读价格、确认订单的时间里。返回 "awake": false 表示容器仍在启动，

属正常现象，不要因此中断流程，继续 P1。

• 不支持：终止流程且不要发起下单。向用户说明结论与解决办法（不必解释你如何检查、不要出现具体工具名）：
  • 合作智能体（如 WorkBuddy）：请升级智能体到最新版本后重试。
  • 开放智能体（如 OpenClaw / DeepSeek Harness）：请根据 https://skillhub.cn/install/skillhub.md 安装 @tencent-adm/weixinpay-installer。
  • 无法判断类型：请升级智能体或安装微信 AI 支付插件后重试。

P1 · 价格披露与用户确认（必做，不得跳过）

首次下单前，向用户明确展示：服务内容、单价 ¥0.10/次、收款主体、退款规则，并等待用户明确确认。

同时必须一并说明首次使用提示：

微信「AI 专属卡」是微信支付为 Agent 代付开设的独立余额账户。如果你是第一次使用，卡内余额为 0，需要先「去转入」充一小笔（建议 ¥3 起），充多少用多少。

这笔钱不是押金、不是会员费、也不是预付费套餐，用不完可以随时转回微信零钱，也可以继续用于其他付费技能。

若用户在支付页看到「余额不足」而中断，不要重复下单，只提示「去转入」后回到对话即可，原订单 15 分钟内仍有效。

• 用户确认 → 进入 P2
• 用户拒绝 → 终止，不得发起下单

P2 · 创建订单并触发支付

执行：

python "<技能目录>/scripts/pay_client.py" create --description "高德全国景点信息获取"

脚本输出 JSON，包含 out_trade_no、amount_fen、WeixinPay-Required。把脚本返回的 JSON 原样作为本步骤的工具输出返回给系统——系统会自动检测 WeixinPay-Required 并弹出支付卡片。

首次下单会慢一些，这是正常的。 支付服务无流量时会缩容到 0，第一个请求需要冷启动，约 30 秒。客户端已内置 75 秒超时与 3 次退避重试，下单时请耐心等待，不要中途打断或重复执行；重复执行会产生多余的待支付订单（不会重复扣费）。

红线：

• 禁止向用户展示 WeixinPay-Required 的原始值（一次性支付凭据）。
• 禁止自己调用支付工具发起首次支付，禁止编造支付状态。
• 用户取消/关闭支付后想再付一次：先与用户确认订单，再把该订单上一次的 WeixinPay-Required 原值作为 paymentCode 调用 mcp__weixinpay__weixinpay_retry_pay（逐字符复用，不得改写、不得编码）。

P3 · 校验支付结果

支付卡片回传成功后，执行：

python "<技能目录>/scripts/pay_client.py" status --out-trade-no "<out_trade_no>"

• 返回 "status": "PAID" → 记下 entitlement_token，进入正式业务流程。
• 返回 PENDING → 提示用户支付尚未完成，等待或允许重试；不得臆测已支付。
• 返回 CLOSED / REFUNDED → 终止，不交付成果。

P4 · 退款

退款属于运营方操作，退款密钥（PAY_ADMIN_KEY）不随技能包分发。因此：

• 技能不得自行发起退款，也不得向用户索要退款密钥。
• 用户申请退款时：按退款规则判断（仅未交付、或交付后 24 小时内），如实告知用户处理结论与预计到账时间，然后转人工。
• 运营方在本地配好 PAY_ADMIN_KEY 后可执行：

python "<技能目录>/scripts/pay_client.py" refund --out-trade-no "<out_trade_no>" --reason "用户申请退款"

• 也可直接在微信支付商户平台对该笔订单发起退款，效果一致。

支付红线汇总

1. 未确认 PAID 前，不得执行任何交付动作（不得调高德 API、不得下载图片、不得写 Excel）。
2. 不得向用户展示、也不得持久化保存支付凭据原文。
3. 不得把 WeixinPay-Required 写入文件、日志或转发到其他渠道。
4. 不得跳过 P1 的用户确认直接扣款。
5. 不得用「本次会话已付过款」为由跳过新事务的下单——一次付费只覆盖一件事。

交互铁律（强制模型遵守）

1. 顺序不可颠倒、一步一问：先走完付费前置流程 → 再确认「高德 Web 服务 Key + 依赖就绪」→ 最后问业务参数（省份 / 城市）。每次只推进当前一步，不得跳步、不得提前问多项参数。
2. 三类需求分清：选择走选项卡、内容走「提交案例 prompt」、上传走纯文字提示：
   • ① 选择类（范围口径、POI 分类、每城条数档位、输出目录）→ 用交互式选项卡（2~4 选项）；短值文本（Key、目录路径）给「在下方输入框填写」。
   • ② 内容类（自定义城市列表等需要用户手写的内容）→ 不弹选项卡，发一段「提交案例 prompt」范例（含 <占位符>），让用户照改后直接发一条消息，然后停下等待；范例末尾注明「缺的我再问」。
   • ③ 上传文件类（用户已有 cities.json）→ 不弹卡，发纯文字提示请用户直接上传，然后停下等待。
   • 严禁「请把 Key 发我」「给个省份名」这类没有可操作指引的自然语言讨要。
3. 全面脱敏：技能包内不得出现真实邮箱、手机号、授权码、密钥、真实姓名、含真实用户名的路径、真实社交账号。Key 绝不写死在脚本或文档里，一律由用户经流程提供。示例路径统一用 C:/Users/用户名/Desktop/...。
4. 能力对齐：技能描述的执行路径必须与底层脚本真实能力一致——脚本直接调用高德 Web 服务 API（restapi.amap.com/v3/place/text），不依赖不稳定的高德 MCP 搜索层；每条参数都要能真实执行。

引导流程（每步等用户回复再继续）

第 0 步 · 前置准备（Key + 依赖）

• 弹卡片确认两件事，任一未完成则引导后再弹同一张卡片：
  1. 高德 Web 服务 Key 是否已就绪？
     • 选项：「我已有 Key，现在填」→ 用户从「在下方输入框填写」填入 Key；
     • 选项：「还没申请，先教我」→ 给出申请路径：console.amap.com → 应用管理 → 创建应用 → 添加 Key（服务平台选「Web 服务」），等用户拿到后再填。
     • 选项：「用环境变量 AMAP_KEY」→ 读取本机 AMAP_KEY，缺失则提示先设置。
  2. 运行环境是否就绪？
     • 选项：「已就绪（已装 openpyxl + Pillow）」→ 继续；
     • 选项：「未安装依赖」→ 给出 pip install openpyxl Pillow，装好再继续。
• Key 是强凭据，必须先拿到手，才进入下一步。

第 1 步 · 选择范围

• 弹卡片二选一：
  • 按省份（内置全国 34 省级行政区 adcode 对照表，约 340 个地级市）→ 用户从「在下方输入框填写」填省份名（如 江苏 / 广东 / 湖北）。
  • 自定义城市列表 → 见下方分支。
• 选「自定义城市列表」时不弹卡，发「提交案例 prompt」范例，停下等待：

  城市列表：<城市名,adcode；每行一个，例：南京,320100 / 苏州,320500>
  表名：<可选，例：苏南三城>
  （照上面改写后直接发我；缺的我会再问。也可直接上传一份同格式的 JSON 文件。）

第 2 步 · 业务参数确认

• 弹卡片确认（可多选或填写）：
  • 每城市最多取多少条：50 / 100（默认） / 150 / 「在下方输入框填写其他数字」；
  • POI 分类：110200 旅游景点（默认）/ 110000 风景名胜大类。

第 3 步 · 输出目录确认

• 弹卡片：「保存到哪个目录？」
  • 默认桌面 C:/Users/用户名/Desktop/高德景点（可填自定义目录）；记为 OUT_DIR。
  • 产物（Excel + 图片子目录）全部落到 OUT_DIR，不再默认写当前目录。

第 4 步 · 自动执行

• 参数齐备，用用户提供的 KEY 运行脚本（Windows 示例，路径按本机调整；PY 换成本机已装 openpyxl + Pillow 的 python）：

  # 按省份
  PY="<你的 python 路径>"   # 例：python，或 venv 里的 python.exe
  "$PY" "<技能目录>/scripts/fetch_attractions.py" --province 江苏 --key <KEY> --out "<OUT_DIR>" --top 100

  # 自定义城市列表
  "$PY" "<技能目录>/scripts/fetch_attractions.py" --config "<用户提供的JSON路径>" --key <KEY> --out "<OUT_DIR>" --top 100

• 脚本自动：翻页抓取（每页 25，最多 4 页）→ 按评分降序取前 N → 下载景点首图转标准 JPEG → 生成多 sheet Excel。逐城市打印进度。

第 5 步 · 汇报

• 告知产出文件位置：{OUT_DIR}/{省份}_attractions_top{top}.xlsx 与图片子目录 {省份}_attraction_images/。
• 汇报：城市数、数据条数、嵌入图片张数（全国平均约 87%~95% 图片可嵌入，无图 POI 单元格留空）。
• 提示：present_files 交付 Excel。

执行细节 / 技术手册（保留原核心能力，已脱敏）

核心能力

• 调用 restapi.amap.com/v3/place/text?key=KEY&types=110200&city=adcode&citylimit=true&offset=25&page=N。
• 解析字段：name / address（区+详细）/ tel / biz_ext.opentime2 / biz_ext.rating / photos[0].url。
• 下载图片用 PIL 统一转标准 JPEG（规避 .mpo 与 Python 3.13 mimetypes 扁平化导致的 Excel 保存失败）。
• 每个城市一个 sheet，列 = 景点图片 / 景点名称 / 景点地址 / 景点电话 / 营业时间；按 rating 降序，高分置顶。
• 内置 cities_reference.py：全国 34 省级行政区、约 340 个地级市 adcode 对照（GB/T 2260）。自定义城市用 cities_example.json 格式。

完整参数表

自定义城市 JSON 格式

{
  "province": "自定义示例",
  "cities": [["南京", "320100"], ["苏州", "320500"]]
}

也可直接是 [["南京","320100"],["苏州","320500"]] 数组形式。

已知限制 / 踩坑

• 高德 MCP 搜索层当前不可用：amap-maps 的 maps_text_search 带 city 返回空、无电话字段；本工具直接调底层 Web 服务 API 更稳。
• .mpo / 非常规图片格式致 Excel 保存失败（Python 3.13 mimetypes.types_map 扁平化与 openpyxl 不兼容）：已用 PIL 统一 save(..., "JPEG") 规避。
• 图片下载失败：高德部分 POI 无图或图链失效，对应单元格留空，文字信息仍完整（全国平均约 87%~95% 图片可嵌入）。
• 排序：高德默认把冷门纪念地排前，脚本已按 rating 降序重排。
• sheet 名上限 31 字符：自治州（如恩施土家族苗族自治州）用简称（恩施）。
• 城市不足 100 条：小城市 / 县级市（七台河、潜江、神农架、嘉峪关等）原始 POI 不足，sheet 自然不满，无需特殊处理。
• 配额：高德单 Key 有 QPS / 日配额限制，跑大城市（如广东 21 城）耗时较长，脚本已加 time.sleep 节流。
• 首次调用支付服务需冷启动：支付端点无流量时会缩容到 0，首个请求约需 30 秒才能返回，期间网关会返回 503 或直接不响应。1.0.1 起客户端超时放宽到 75 秒，并对 502/503/504 与超时做 3 次退避重试（原 1.0.0 是 30 秒、单次、不重试，在冷启动窗口内必然失败，表现为「读取超时」「503」）。

Key 安全（重要）

• Key 绝不写死在脚本或文档里，必须由用户经流程提供（命令行 --key 或环境变量 AMAP_KEY）。
• 若 Key 泄露，请立即到 console.amap.com 控制台「重置 Key」。
• 不要将含真实 Key 的日志 / 截图外传。

已实测验证省份

江苏、安徽、福建、广东、广西、贵州、甘肃、河北、黑龙江、河南、湖北（其余依据公开行政区划代码整理，报错可到高德开放平台核对）。

安全约束

• 数据流向：本技能只有两处联外网——① 高德开放平台 Web 服务 API（用用户自己的 Key，只传城市 adcode 与 POI 查询参数，不传任何个人数据）；② 支付服务（下单 / 查单，只传订单号与金额）。抓取到的景点数据、图片与 Excel 全部只落在用户本机 OUT_DIR，不上传任何第三方服务器。
• 删除 / 覆盖类动作必须先取得用户确认；产物只写 OUT_DIR，不写系统目录。