blue-ribbon-nearby

Blue Ribbon Nearby

此技能的作用

根据用户提供的当前位置查找蓝丝带指南（Blue Ribbon Survey）的官方 zone，并通过 k-skill-proxy 展示附近的蓝丝带餐厅。

• 不会自动推测位置。
• 必须先询问当前位置。
• 将位置字符串与官方 zone 列表匹配，再通过附近 JSON endpoint 缩小范围。
• 如果直接提供坐标，可以进行更精准的附近搜索。
• 附近搜索默认通过 k-skill-proxy（/v1/blue-ribbon/nearby）进行。代理必须配置 BLUE_RIBBON_SESSION_ID。

适用场景

• “帮我找附近的餐厅”
• “这附近有什么蓝丝带餐厅？”
• “推荐光化门附近不错的餐厅”
• “只显示我附近的蓝丝带餐厅”

路由规则

• 用户询问美食／附近的餐厅／附近的饭店时，默认优先考虑此技能。
• 但如果用户明确指定蓝丝带以外的标准（例如芒果盘、Naver 地图评价、预订某家餐厅），则优先使用该平台或标准。

前置条件

• 互联网连接
• node 18+
• 此存储库中的 blue-ribbon-nearby package 或相同逻辑

必须先询问

不要在没有位置信息的情况下直接搜索，必须先询问。

• 推荐问题：请告诉我您当前的位置。您可以用街区／车站名称／地标／纬度·经度等方便的格式发送，我会帮您查找附近的蓝丝带餐厅。
• 位置不明确时：请再告诉我一次附近的车站名称或街道名称。
• 收到坐标后，直接用于附近搜索。

可接受的位置输入

• 街区／商圈：圣水洞、光化门、板桥
• 车站名称／地标：江南站、首尔站、COEX
• 纬度／经度：37.573713, 126.978338

地标会通过内部别名匹配到最近的官方 Blue Ribbon zone 名称。例如：COEX → 三成洞/大峙洞

Blue Ribbon 官方页面

• zone 目录：https://www.bluer.co.kr/search/zone
• 附近搜索 JSON：https://www.bluer.co.kr/restaurants/map
• 搜索页面：https://www.bluer.co.kr/search

主要附近搜索参数：

• zone1
• zone2
• zone2Lat
• zone2Lng
• isAround=true
• ribbon=true
• ribbonType=RIBBON_THREE,RIBBON_TWO,RIBBON_ONE
• distance=500|1000|2000|5000

直接按坐标搜索时，使用 latitude1、latitude2、longitude1、longitude2 bounding box。

工作流

1. 先询问当前位置

未询问位置前，不要开始搜索。

2. 确定位置

• 收到街区／车站名称／地标后，先与官方 https://www.bluer.co.kr/search/zone 列表进行匹配。
• 对于 COEX 这类并非官方 zone 名称的知名地标，先扩展为最近的官方 zone 别名。
• 收到纬度／经度后，直接进行基于坐标的附近搜索。
• 如果有多个最有可能的 zone 候选项，只列出 2～3 个并再次确认。

3. 查询附近的 Blue Ribbon endpoint

默认通过 k-skill-proxy 获取附近搜索结果。

const { searchNearbyByLocationQuery } = require("blue-ribbon-nearby");

const result = await searchNearbyByLocationQuery("광화문", {
  distanceMeters: 1000,
  limit: 5
});

console.log(result.anchor);
console.log(result.items);

内部会先匹配 zone，再将坐标和距离传给代理的 /v1/blue-ribbon/nearby。代理使用高级会话调用 Blue Ribbon 上游服务。

如果需要直接调用，可以使用 useDirectApi: true 选项；但没有高级会话时会出现 premium_required 错误。

4. 简要汇总餐厅信息并回复

通常简要整理 3～5 家。

• 餐厅名称
• 蓝丝带数量
• 代表菜系类别
• 地址
• 距离

完成条件

• 已先确认用户的当前位置。
• 至少找到 1 条官方 Blue Ribbon 附近搜索结果，或者说明因未配置代理等原因无法获取结果，并提出后续问题。
• 按距离顺序简要整理结果。

浏览器备用方案（绕过机器人拦截）

如果 bluer.co.kr 阻止自动化访问（403），且已安装 rebrowser-playwright，则会自动通过真实 Chrome 浏览器启用备用方案。

条件

• 必须安装 rebrowser-playwright：npm install rebrowser-playwright
• 系统必须安装 Google Chrome
• 以 headed 模式运行（需要显示环境）

工作方式

1. 如果现有 fetch 请求返回 403，则自动启用浏览器备用方案
2. 应用 stealth 补丁（移除 webdriver、伪装 plugins/languages 等）
3. 使用真实 Chrome 调用 zone 目录或 nearby API
4. 将结果原样传递给现有流程

只需安装 rebrowser-playwright，无需额外配置即可自动运行。如果未安装，则与之前一样直接抛出 403 错误。

失败情况

• 位置字符串可能无法与官方 zone 准确匹配。
• 同一关键词可能涵盖多个商圈，需要进一步确认。
• 如果 Blue Ribbon 网站更改结构／参数，zone 解析或 nearby endpoint 可能会失效。
• 如果代理的 BLUE_RIBBON_SESSION_ID 过期（30 天），则需要续期。
• 浏览器备用方案仅支持 headed 模式，因此无法在服务器（CI）环境中运行。

注意事项

• 此技能用于查询。
• 不会自动追踪用户位置，只使用对话中收到的位置。
• 对于美食咨询，默认优先使用此技能；如果明确指定蓝丝带以外的标准，则优先采用该标准。