OOMOL Yelp 连接器

要解决的问题

把 Yelp 数据接进脚本时，最常见的卡点不是接口复杂，而是凭证。开发者要么把 access token 写进配置、环境变量，要么担心刷新逻辑在部署后失效；轮换密钥、排查过期错误、区分「没授权」和「连接断了」，往往会消耗比写业务逻辑更多的时间。

OOMOL Yelp 连接器把凭证管理从客户端剥离：Yelp 凭据由 OOMOL 服务端注入，本地代码只负责描述要查什么。这样同一个脚本可以在不同机器上运行，不必把 token 抄来抄去，也减少密钥出现在日志和仓库里的风险。

核心能力与工作方式

该技能通过 oo CLI 调用 Yelp connector，暴露 3 个动作：

• get_business_details：按商户 ID 或别名取单个 Yelp 商户详情；
• search_businesses：按关键词 + 地理锚点搜索商户；
• search_businesses_by_phone：用精确电话号码反查 Yelp 商户，适合把线下名片或订单记录对齐到平台档案。

调用前先 oo connector schema 拉取最新输入/输出契约，而不是凭印象拼 payload。运行时 --data 接受 JSON 对象或 @path/to/file.json；响应统一为 { "data": ..., "meta": { "executionId": "..." } }，追踪执行时以 meta.executionId 为准。

授权方面不要主动执行 oo auth login 或帮用户开连接页；先直接跑动作。只有当命令真的返回认证/连接错误时，再按错误类型进入一次性修复：oo: command not found 就补装 CLI；未登录/认证错误就登录 OOMOL；scope_missing、credential_expired、app_not_ready、app_not_found 就以 API key 方式连接 Yelp；HTTP 402 或 OOMOL_INSUFFICIENT_CREDIT 则需先到 OOMOL billing 充值再重试。

适用边界与注意点

这三个动作都是只读检索，适合做商户档案补全、地址去重、电话到店名的映射、离线数据与 Yelp 记录核对。它不负责写状态，也不覆盖 Yelp 管理后台的发布、编辑或删除流程；若要把结果落库、生成报表或写回业务系统，仍需要在自己的代码里完成。

使用 search 类接口时，关键词和地理锚点决定召回质量：锚点太宽会得到大量噪声，太窄又可能漏掉同名但不同区域的商户；按电话号码查询必须保证号码精确，否则无法稳定命中。总体而言，把它当作「带服务端凭证的 Yelp 只读客户端」使用，契约清晰、失败原因明确，也避免把密钥管理混进业务代码。