local-places（本地地点搜索）Skill 是什么？怎么用？

本地地点搜索代理Skill：两步查遍身边好店，让 AI 帮你找地点

一句话定位：本地地点搜索代理Skill（英文名 local-places）把 Google Places API 封装成本地服务，通过“先解析位置、再搜索地点”的两步流程，让 AI 助手能稳定地帮你找餐厅、咖啡馆等周边场所。
核心能力：位置解析、关键词搜索、按类型、评分、价位、营业状态过滤、地点详情查询、分页翻页，全部返回结构化 JSON。
使用门槛：需要本机具备 uv 运行环境，并配置 GOOGLE_PLACES_API_KEY；服务默认跑在 http://127.0.0.1:8000。
最大差异点：密钥留在本地 .env 中，请求走本机代理，AI 只调用你自己的服务，而不是把密钥交给第三方。
适合谁用：做对话式地点推荐、本地生活助手、门店调研与商旅场景的开发者与效率工具用户。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能中文名：本地地点搜索代理Skill 技能英文名：local-places 技能ID：13584 项目主页：https://github.com/Hyaxia/local_places

它要解决的问题很具体：大模型本身“知道世界上有咖啡馆”，但不知道你此刻附近哪家咖啡馆还开着、评分 4 分以上、人均价位在哪个档。直接让模型联网搜索，结果往往不可控、格式混乱、还容易编造。本地地点搜索代理Skill 的思路是——把权威的 Google Places 数据源封装成一个本地 HTTP 服务，让 AI 通过固定接口去查，输入输出都是结构化数据，既准确又可被程序消费。

“一键安装”提效的核心逻辑是：把复杂的鉴权、请求拼装、字段清洗、分页处理，全部收敛到一次安装里，之后每次使用只需要发一个 JSON 请求。

安装步骤如下（命令均来自技能官方说明）：

第一步：环境准备（安装前提）

本机需要具备 uv（Python 包与环境管理工具），技能元数据中明确声明了 requires.bins: ["uv"]。
需要准备一个 GOOGLE_PLACES_API_KEY，这是技能的主环境变量（primaryEnv）。密钥的申请方式与计费规则以 Google 官方说明为准。

第二步：写入密钥并安装依赖

cd {baseDir}
echo "GOOGLE_PLACES_API_KEY=your-key" > .env
uv venv && uv pip install -e ".[dev]"

把 your-key 换成你自己的密钥，密钥会被写入项目目录下的 .env 文件，不会硬编码进代码。

第三步：启动本地服务

uv run --env-file .env uvicorn local_places.main:app --host 127.0.0.1 --port 8000

服务监听在 127.0.0.1:8000，仅本机可访问，天然避免了密钥与服务被公网暴露的风险。

第四步：验证是否生效

curl http://127.0.0.1:8000/ping

只要 /ping 能正常返回，就说明服务已跑通；如果报错，优先检查 .env 里的密钥是否写对、端口是否被占用。至于技能在市场中的获取入口、是否需要付费等细节，以官方说明为准。

该技能的主要功能和特点

两步式搜索流程：先用 /locations/resolve 把“Soho, London”这类自然语言位置解析成经纬度，再用 /places/search 带着 location_bias 去搜索。这种拆分让模糊表述（如“我附近”“公司旁边”）也能被正确处理。
多维度过滤器：支持按类型（types）、价位（price_levels，0–4，0 表示免费、4 表示非常昂贵）、最低评分（min_rating，0–5，以 0.5 递增）、是否营业（open_now）组合筛选，直接回答“现在开着、评分 4 分以上、人均中等”这类复合需求。
结构化 JSON 输出：每条结果包含 place_id、name、address、location（经纬度）、rating、price_level、types、open_now，字段稳定，方便前端或 Agent 直接渲染成卡片。
详情与分页：用 /places/{place_id} 拉取单个地点详情；用响应中的 next_page_token 作为下一次请求的 page_token，即可继续翻页获取更多结果。
参数边界清晰：limit 在搜索时取 1–20、解析时取 1–10；location_bias.radius_m 必须大于 0；filters.types 只接受单个类型。边界明确意味着调用不容易“玄学失败”。
内置对话流程建议：技能文档直接给出了 Agent 的推荐交互顺序——模糊位置先解析、多结果给编号列表让用户选、询问偏好、再用选定位置的 location_bias 搜索、最后呈现名称评分地址营业状态，并主动提供“看详情或继续精炼”的选项。
和普通工具比强在哪：地图 App 是给人看的，需要手动点选、无法批量筛选、更难被程序复用；而本技能是给 AI 和程序用的，一条 JSON 请求就能拿到可计算、可筛选、可二次加工的结果。

如何使用该技能？

以下为完整的分步骤使用指南，示例均可直接参考修改。

步骤 1：确认服务存活

curl http://127.0.0.1:8000/ping

步骤 2：解析位置

curl -X POST http://127.0.0.1:8000/locations/resolve \
  -H "Content-Type: application/json" \
  -d '{"location_text": "Soho, London", "limit": 5}'

输入是一段人类描述的位置文本，limit 控制最多返回几个候选（1–10）。如果返回多个候选，最佳实践是把它们做成编号列表交给用户确认，避免搜错商圈。

步骤 3：搜索地点

curl -X POST http://127.0.0.1:8000/places/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "coffee shop",
    "location_bias": {"lat": 51.5137, "lng": -0.1366, "radius_m": 1000},
    "filters": {"open_now": true, "min_rating": 4.0},
    "limit": 10
  }'

这里的 query 是自然语言关键词（如“coffee shop”“restaurant”“gym”），location_bias 用上一步解析出的经纬度，radius_m 是搜索半径（单位米，必须大于 0）。filters 可以只填其中几项，比如只要求“正在营业”。

步骤 4：读取结果并翻页

返回体形如：

{
  "results": [
    {
      "place_id": "ChIJ...",
      "name": "Coffee Shop",
      "address": "123 Main St",
      "location": { "lat": 51.5, "lng": -0.1 },
      "rating": 4.6,
      "price_level": 2,
      "types": ["cafe", "food"],
      "open_now": true
    }
  ],
  "next_page_token": "..."
}

若 next_page_token 不为空，把它作为 page_token 放进下一次 /places/search 请求，即可拿到后续结果。

步骤 5：查询单个地点详情

curl http://127.0.0.1:8000/places/{place_id}

把上一步结果里的 place_id 填进路径，即可获得该地点的详细信息，用于生成“店铺名片”。

步骤 6：按对话流程编排

推荐把技能包装成这样的 Agent 行为：用户说“near me”或给模糊位置 → 先调用位置解析 → 多结果时让用户选 → 追问偏好（类型、是否营业、评分、价位）→ 用选定位置做 location_bias 搜索 → 呈现名称、评分、地址、营业状态 → 主动询问是否看详情或继续精炼。

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
本地地点搜索代理Skill（local-places）	面向 AI 的本地地点搜索代理服务	位置解析、地点搜索、多维过滤、详情查询、分页	需 `uv` 与 `GOOGLE_PLACES_API_KEY`，几条命令即可启动	对话式地点推荐、本地生活助手、门店调研	优势：密钥本地化、结构化输出、参数边界明确、对 Agent 友好；不足：依赖 Google Places 配额与网络，需自行维护本地服务
直接调用 Google Places API	官方原始接口	全量地点的检索与详情	需自己写鉴权、请求拼装、字段清洗、分页逻辑	有工程能力、要深度定制的团队	优势：最灵活、能力最全；不足：开发成本高，字段处理繁琐，容易写出不稳定代码
通用地图 App 手动查找	面向人的消费级产品	地图浏览、关键词搜索、评分查看	零门槛	一次性、临时的找店需求	优势：开箱即用、交互直观；不足：无法批量筛选与程序化复用，AI 难以直接驱动
开源地图数据方案（如基于 OpenStreetMap 自建检索）	数据自主可控的替代路线	地点检索、类别查询	需自建数据管道与服务，运维成本较高	对数据来源有强合规要求、离线场景	优势：数据开放、可离线；不足：评分与营业状态等商业信息覆盖弱，结果质量参差

如何选：只想快速让 AI 会找地点，选 local-places；要极致定制且有工程团队，直连官方接口；只是偶尔找店，用地图 App 即可；对数据来源有硬性要求，再考虑开源地图方案。

该技能的典型应用场景与实际体验情况

场景一：商旅人士的“附近咖啡厅”助手 痛点是刚到陌生城市，想知道酒店步行 10 分钟内、现在营业、评分 4 分以上的咖啡馆。使用方式是先解析“酒店名称/商圈”，再用 query: "coffee shop" 配合 open_now: true 与 min_rating: 4.0 搜索。实际体验：只要位置解析这一步选对了候选点，后续结果相关性很高；建议半径设 1000 米左右，太大反而会掺入不相关结果。

场景二：Agent 开发者的地点推荐机器人 痛点是自研地点检索要处理鉴权、字段兼容和翻页，调试成本高。这个技能把这些都收进本地服务，开发者只需要组织 JSON。实际体验：接口语义清晰，limit 与 radius_m 的约束明确，报错基本能定位到参数问题；需要注意 filters.types 只接受单个类型，想同时查“餐厅和咖啡馆”要拆成两次请求。

场景三：门店与商圈调研 痛点是运营同学想快速看某商圈内某类业态的分布与评分区间。可以用固定的 location_bias 反复搜索不同 query，再配合 price_levels 与 min_rating 做分层统计，翻页拿全量结果。实际体验：结构化 JSON 直接可以进表格做分析，比人工截图整理快得多；注意单页最多 20 条，需要配合 next_page_token 逐页拉取。

场景四：团队聚餐选址 痛点是“今晚聚餐、要开门、人均别太贵、评分不能低”这种多条件需求。用 query: "restaurant" 加 open_now、min_rating、price_levels（如限定 1–2 档）一次性筛出候选，再把编号列表给团队投票。实际体验：多条件组合是这个技能最舒服的用法，能显著减少来回沟通；如果结果为空，通常是条件叠加过严，放宽评分或价位即可。

整体上手难度：中等偏易。难点集中在两处——装好 uv 并正确写入密钥、启动服务；跑通之后，剩下的就是拼 JSON。注意事项：配额与计费以 Google 官方说明为准；服务默认只监听本机，若要共享需自行处理网络与鉴权；搜索 limit 与解析 limit 上限不同，写代码时别混用。

该技能能为用户带来的价值

第一，把“能不能查”变成“查得准”。 地点这类信息对时效和真实性要求高，模型凭记忆回答很容易出错。技能把数据来源锁定在 Google Places，通过 open_now、min_rating 等字段做硬性过滤，答案从“听起来合理”变成“确实如此”。

第二，把集成成本压到几条命令。 安装就是写 .env、装依赖、启动服务三步，验证只需一个 /ping。对独立开发者和小团队而言，这意味着原本需要一两天的接口封装、字段清洗、分页处理工作，可以压缩到半小时级别。

第三，把密钥风险关在本地。 密钥保存在本机 .env，服务只监听 127.0.0.1，AI 侧只需要知道“有个本地接口可以问”，不需要接触密钥本身。这对想把 AI 助手接入真实业务数据的团队来说，是一条门槛低又相对安全的路径。

第四，长期可复用的结构化资产。 每次搜索结果都是带经纬度、评分、价位、类型的标准 JSON，可以沉淀成门店库、做趋势对比、喂给推荐模型。用得越久，积累的数据资产越有价值。

第五，显著降低非技术同学的使用门槛。 一旦团队里有人把服务部署好，运营、市场、行政岗位的同学只需要用自然语言向 AI 提需求，就能拿到带评分和营业状态的清单，不必自己学地图 API。

常见问题 FAQ

Q1：这个技能怎么安装？会不会很麻烦？ A：按官方说明是三步：cd {baseDir} 后把 GOOGLE_PLACES_API_KEY 写入 .env，执行 uv venv && uv pip install -e ".[dev]" 安装依赖，再用 uv run --env-file .env uvicorn local_places.main:app --host 127.0.0.1 --port 8000 启动服务，最后访问 http://127.0.0.1:8000/ping 验证。前提是本机已有 uv 和一个可用的 Google Places API 密钥。

Q2：使用它需要额外付费吗？ A：技能本身是开源的本地服务，不涉及额外订阅费用；但底层调用 Google Places API 可能产生配额与计费，具体规则以 Google 官方说明为准。技能页面或市场上的获取方式与价格，同样以官方说明为准。

Q3：为什么一定要“先解析位置、再搜索”？能不能直接搜？ A：因为搜索接口需要的是经纬度（location_bias.lat/lng），而不是一句“我附近”。位置解析把自然语言转成坐标，顺带解决了“用户说的地点有歧义”的问题。文档也建议：如果返回多个候选，先给用户编号列表让其确认，再发起搜索，命中率会明显更高。

Q4：适合谁用？非程序员能用吗？ A：直接使用 curl 的更偏开发者与 AI 应用搭建者。但如果团队里有人把服务部署好，并把技能接入 AI 助手，那么运营、行政、市场等岗位就可以完全用自然语言提问，例如“找一下附近现在营业、评分 4 分以上的咖啡店”，不需要自己发请求。

Q5：和直接用地图 App 或直连 Google Places API 相比，怎么选？ A：偶尔找店，用地图 App 最快；需要极致定制、有工程团队维护，直连官方 API 最灵活；而希望在“开发成本可控”和“AI 能直接调用”之间取得平衡，选本地地点搜索代理Skill 更合适——它把鉴权、字段清洗、分页都封装好了，还额外提供了一套经过设计的对话流程建议。