Skill: 街道商户清单生成器

基本信息

• ID: street-merchant-list
• 名称: 街道商户清单生成器
• 版本: 1.3.0
• 作者: 江老师

功能描述

根据用户提供的城市和街道名称（或中心点+半径），自动采集该区域内所有商户信息，生成按门牌号排序的 Excel 清单。

触发词

• "找出{city}{street}的所有商户"
• "生成{city}{street}商户清单"
• "{city}{street}门店列表"
• "{city}{street}有哪些店"
• "查询{center}周边{radius}公里商户"
• "{city}{center}附近商户"

核心功能

1. 双模式查询

2. 多源数据采集

• 高德地图 API（主数据源）
• 腾讯地图 API
• 百度地图 API
• AI 网络搜索（补充验证，需标注来源）

3. 智能数据处理

• 门牌号提取: 从地址正则提取门牌号
• 去重规则:
• 名称 100% 相同 → 合并为一条
• 名称 80-99% 相似 → 保留两条，备注"可能重复"
• 排序规则:
• 有门牌号 → 按门牌号升序
• 无门牌号 → 按经纬度相对位置排序

4. 防幻觉机制

• API 数据优先，AI 仅做补充
• 网络搜索结果必须有可验证的网页来源
• 所有商户必须有具体地址（门牌号或经纬度）
• 用户确认环节：展示统计摘要后生成 Excel

输出格式

Excel 字段

Excel 样式

• 首行冻结 + 筛选器
• 按业态大类着色（不同颜色区分）
• 自动列宽
• 区域模式：每街道一个 Sheet

技术架构

scripts/
├── __init__.py
├── main.py              # 主流程入口
├── api_clients/         # API客户端
│   ├── __init__.py
│   ├── amap_client.py   # 高德
│   ├── tencent_client.py # 腾讯
│   └── baidu_client.py  # 百度
├── data_processor.py    # 数据处理（清洗/去重/排序）
├── web_searcher.py      # 网络搜索补充
└── excel_generator.py   # Excel生成

数据源策略与配置（v1.3，优先走 WorkBuddy 已接通连接器）

> 统一按下列阶梯降级，命中即停：
> > 第 1 级：已接通连接器 → 腾讯地图 tencent-map（少量/单次 POI 搜索、地址解析） > 第 2 级：其他 MCP 配置 → amap-maps / baidu-maps（全量分页采集用） > 第 3 级：env Key 脚本兜底 → AMAP_KEY / BAIDU_AK（走 scripts/api_clients/） > 第 4 级：以上均无 → 提醒用户接通地图连接器（推荐腾讯地图） >
> 分工：本 Skill 目标是"街道级全量商户清单"，需分页遍历至饱和；腾讯地图连接器无分页能力，故批量采集主通道为高德（amap-maps MCP 或 AMAP_KEY 脚本通道），腾讯地图连接器用于少量点位补充与地址解析。

API Keys（环境变量配置）

> 配额口径说明：上表为搜索类（周边/关键字）个人免费配额，是硬约束；地理编码配额更高（数千次/天），不构成瓶颈。单条街道三源全开约消耗 100-160 次调用/源，请按天规划、避免同日内对过多街道连跑满三源（详见「限制与注意事项」第 3 条）。

> 三源覆盖：街道模式下三源全用，区域模式下高德为主+腾讯/百度补充。三个数据源共同覆盖可将商户覆盖率提升至 90%+。

依赖

requests>=2.25.0
openpyxl>=3.0.0
difflib  # Python内置，用于字符串相似度

使用示例

示例1：街道模式

用户: 找出上海南京东路的商户
系统: 
  1. 采集数据...（高德91条/腾讯XX条/百度36条）
  2. 清洗去重...（50条有效）
  3. 展示摘要：
     - 总计商户: 50家
     - 门牌号范围: 6号-830号
     - 来源分布: 高德37条(74%), 百度13条(26%)
     - 可能重复: 3组
  4. 用户确认 → 生成 Excel

示例2：区域模式

用户: 查询上海人民广场周边3公里商户
系统:
  1. 采集数据...（半径3公里内所有POI）
  2. 按街道分组...（南京东路/西藏中路/福州路等）
  3. 展示摘要：
     - 总计商户: 286家
     - 涉及街道: 8条
     - 每街道商户数: 南京东路50家, 西藏中路42家...
  4. 用户确认 → 生成多Sheet Excel

限制与注意事项

1. 数据覆盖: 依赖地图API收录，新开业或小微商户可能缺失
2. 门牌号完整度: 约60-70%商户有明确门牌号
3. API配额: 免费额度有限（高德约100次/日、腾讯约200次/日、百度约100次/日搜索类），单条街道约消耗 100-160 次调用/源，请勿在同日内对过多街道连续跑满三源
4. 腾讯地图接入：已连接器化，走 tencent-map 连接器（mcp__tencent-map__），无需配置 TENCENT_KEY、无需 IP 白名单
5. 网络搜索: AI补充的数据会明确标注来源，需人工复核

执行流程与性能（v1.2 并发改造）

执行顺序

1. Step 1 地理编码：高德为必选（提供中心点坐标）；腾讯/百度地理编码仅在未禁用对应源时执行（--no-tencent / --no-baidu）。
2. Step 2 多源采集：三源并发（高德/腾讯/百度各一个线程），每源内部再按关键词有限并发（最多 3 个关键词同时拉取）。
3. Step 3 过滤+清洗+去重+排序 → Step 4 统计摘要 → Step 5 生成 Excel。

预期耗时（单条街道，默认半径 2000m）

• 县城/稀疏街道：约 10-30 秒（多数关键词提前翻页结束）。
• 市区/繁华街道（原始 POI 2000+）：约 1-2 分钟（v1.1 串行同口径约 3-7 分钟）。
• 单源故障或限流时，该源会被优雅跳过，其余源照常输出，不会整体卡死。

失败处理 / 跳过规则（重要）

• 高德地理编码失败 → 无中心点，整体中止并报错（高德为必选数据源）。
• 某源采集异常/超时（单关键词 60s 超时、单源 120s 总预算）→ 该关键词或该源被跳过，打印 ⚠️/❌ 提示，其余源结果正常并入。
• 某源被限流/配额耗尽 → API 返回错误状态，fetch_all_* 提前结束（返回已采集部分），不重试、不阻塞。
• 单源预算超时 → 停止提交剩余关键词，已提交任务收尾后并入。
• 禁止为每个地点手工编写一套采集脚本（如 collect_v2.py/finalize.py）——统一走 main.py，差异仅通过命令行参数表达。

标准命令

cd scripts
python main.py --city <城市> --district <区县> --street <街道名> --radius 2000 --output <输出.xlsx>
# 跳过某源：--no-tencent / --no-baidu
# 缩小范围省配额：--radius 500（县城）~ 2000（市区）

半径与覆盖率指引

• 单条街道建议半径 1000-2000m；半径过小会漏掉临街商户，过大则混入邻街噪声、且翻页更多、更耗配额。
• 三源全开覆盖率约 90%+；若配额紧张，优先保留高德（主源）+ 腾讯，百度作补充。

安全与配置约定

• 地图 Key 一律走环境变量（AMAP_KEY / BAIDU_AK）或已接通连接器（腾讯地图 tencent-map），严禁将 Key 明文写入脚本或会话目录。腾讯地图不再设 TENCENT_KEY（连接器已托管密钥）。
• 依赖隔离：通过托管 Python 虚拟环境安装 requests / openpyxl，不污染本机全局环境。

更新日志

v1.3.0 (2026-10-13)

• 资源调用优先连接器：新增「数据源策略」四级阶梯；腾讯地图改为 tencent-map 连接器；批量分页采集主通道明确为高德（amap-maps MCP / AMAP_KEY）。
• 修正遗留：清理「安全与配置约定」中过时的 TENCENT_KEY；删除与 SKILL.md 重复且版本滞后的 README.md、使用说明.txt。

v1.2.0

• 三源并发采集改造（每源内关键词有限并发），单条街道耗时降至 10 秒–2 分钟（v1.1 串行同口径约 3-7 分钟）；单源故障优雅跳过、超时预算。

v1.1.x

• 区域模式多 Sheet、去重规则与门牌号排序优化（历史版本）。

v1.0.0 (2026-03-27)

• 初始版本
• 支持高德/腾讯/百度三源数据采集
• 支持街道模式和区域模式
• 支持AI网络搜索补充