mcpField
F
fallback-and-resilience

fallback-and-resilience

github.com/borskiAgent 工作流78071 次安装2 天前更新
代码仓库

关于 fallback-and-resilience

为旅行规划 Agent 提供故障恢复指南，列出航班、酒店等搜索来源的替代方案，并说明工具报错、限流及访问限制时的处理方式。

主要功能

  1. 01按来源列出备用方案
  2. 02提供 API 与服务器故障处理规则
  3. 03指导识别 IP 白名单错误
  4. 04说明浏览器自动化常见故障
  5. 05规范故障时的信息披露

适用场景

  1. 01航班搜索来源发生故障时切换服务
  2. 02API 限流时寻找替代数据源
  3. 03首次调用遭遇 IP 拒绝时排查
  4. 04搜索结果为空时核实航线是否运营

MCP 相关

该技能说明 MCP 服务调用失败后的处理方式，包括尝试替代来源；要求实际调用后再判断服务是否不可用。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/borski/travel-hacking-toolkit --skill fallback-and-resilience

安装后在 Claude Code 中输入/fallback-and-resilience确认已加载。

详细介绍

故障回退与韧性

工具会停用，API 会出故障。每次搜索都要准备备用方案。

主要工具失效时的情况备用方案
DuffelAPI 错误或超时Ignav、Google Flights 技能、Skiplagged
IgnavAPI 错误Duffel、Google Flights 技能、Skiplagged
Google Flightsagent-browser 错误Duffel、Ignav、Skiplagged
Skiplagged502/超时（Cloudflare 问题）Kiwi.com MCP、Duffel、Ignav
Kiwi.com服务端错误Skiplagged MCP、Duffel
Seats.aeroAPI 错误或数据过时直接查看航空公司网站，使用 Duffel 查询 GDS 库存
SouthwestSW 限流或机器人检测等几分钟后重试。如果在本地运行失败，请使用 Docker（ghcr.io/borski/sw-fares）。如需快速备用方案，可使用 Google Flights 技能查询 SW 现金票价。
SerpAPI达到速率限制（免费版每月 100 次）酒店查询用 Trivago，目的地发现用网页搜索
Trivago服务端错误酒店查询用 LiteAPI，或使用 SerpAPI Google Hotels
LiteAPI身份验证错误（401）Trivago MCP、SerpAPI Google Hotels
Airbnb抓取被拦截建议用户直接查看 airbnb.com
AwardWalletAPI 错误直接询问用户的积分余额
Ferryhopper服务端错误使用 SerpAPI 或网页搜索查询渡轮路线
Atlas Obscura脚本错误搜索 "unusual things to do in [destination]"
Chase Travel登录失败或 CSRF 问题使用 Duffel/Ignav 查询现金票价。请注意，Points Boost 和 Edit 检测仅适用于 Chase。
Amex Travel登录失败或表单变更使用 Duffel/Ignav 查询现金票价。请注意，IAP 票价和 FHR/THC 检测仅适用于 Amex。
Deutsche Bahn（db-vendo）库出错或 bahn.de 停运使用 SerpAPI Google Travel Explore、搜索 "DB train [origin] [dest]"，或改为确认可选航班。
Wikipedia 机场API 速率限制（罕见）或页面缺失搜索 "[airport name] airlines destinations"，通过 Google 获取相同数据。
票价工具显示 "no results"可能是无余票，也可能是没有航线使用 wikipedia-airports 确认该航线是否实际运营。 如果 Wikipedia 列出了该目的地，说明票价工具在该日期没有余票。如果 Wikipedia 未列出该目的地，则该航线不存在。这样可以避免让用户重试永远不会成功的搜索。

一般规则

  • **如果 MCP 服务返回错误，**尝试使用基于 curl 的技能替代方案（反之亦然）。
  • **如果付费 API 达到速率限制，**切换到免费替代方案。
  • **一个工具失效后绝不要放弃。**至少尝试一个备用方案。
  • 告知用户你使用了哪个来源。“Skiplagged 无法使用，所以我改查了 Kiwi.com。”

未实际调用前，绝不要声称 MCP 不可用

不要只看一眼工具列表就宣称 MCP 服务“不可用”——**先实际调用工具。**Skiplagged 和 Kiwi 服务无需 API 密钥，并且已接入所有受支持的 harness 配置；从仓库目录启动的会话可以使用它们。如果调用确实失败，请向用户说明错误，然后再使用备用方案。

使用备用方案时，**绝不要悄悄用临时浏览器抓取替代工具包的数据源。**临时抓取（例如手动操控浏览器访问 Google Flights）会漏掉市场上的大多数价格。如果不得不采用这种方式，请明确说明，并将抓取到的每个价格标记为低可信度：“MCP 数据源无法访问，因此这里只提供一个抓取到的报价——请将其视为上限，而非市场价格。”

IP 白名单错误（首次使用时的常见故障）

工具包中的多个 API 会对开发者密钥强制实施 IP 白名单。如果你看到以下错误特征，请勿在身份验证或配额问题上钻牛角尖。建议用户先将自己的 IP 加入白名单。

API错误特征白名单页面
AwardWallet{"error": "access_denied", "code": "IP_DENIED"}https://business.awardwallet.com/profile/api
TripAdvisorUser is not authorized to access this resource with an explicit denyhttps://www.tripadvisor.com/developers

首次使用时，如果 API 调用因类似身份验证的错误而失败，请按以下流程排查：

  1. 运行 curl ifconfig.me，获取用户当前的出站 IP。
  2. 检查错误特征是否与 IP 白名单问题相符（见上表，或类似“explicit deny”／“IP_DENIED”／“not whitelisted”的表述）。
  3. 告诉用户：“这看起来是 IP 白名单问题，而不是密钥问题。请在 添加 <their IP>，等待 1-5 分钟，让 AWS 边缘缓存完成传播，然后重试。”
  4. 用户添加白名单期间，请妥善降级处理：继续执行，不使用该数据源，并说明该数据源仍在等待中。不要因此阻塞工作流的其他部分。
  5. 多 IP 注意事项：住宅 CGNAT、VPN 出口、酒店 Wi-Fi 和旅行地点都需要单独添加。如果用户在新网络中遇到相同错误，说明 IP 已变更。

“没有缓存的可用性”并非最终结论

当 Seats.aero 对某个航线与计划组合未返回结果时，这意味着 Seats.aero 最近没有抓取到相关数据，并不意味着该奖励无法预订。如果某个可访问的计划没有缓存结果，请先直接搜索航空公司的网站，再判定奖励已失效。

基于 Patchright 的技能（Southwest、AA、Chase、Amex、TaW）

这些技能通过未被检测到的浏览器直接访问网站。常见故障模式：

  • 登录表单已更改。 网站更新了 DOM，导致选择器失效。请更新技能。
  • 双重身份验证循环。 一些技能（AA、Amex）支持通过电子邮件进行双重身份验证。请确保账户中的双重身份验证接收方式设置正确。
  • 机器人检测。 如果出现“异常活动”或 CAPTCHA 页面，持久化配置文件可能已被标记。请尝试使用新的配置文件，或等待一小时。
  • 无头模式检测。 Patchright 以有头模式运行。如果在本地运行失败，请使用 Docker 镜像（xvfb 提供虚拟显示器）。

Docker 镜像故障

如果 docker pull ghcr.io/borski/... 失败：

  • unauthorized： 运行 docker logout ghcr.io 后重试。也可以使用具有 read:packages 权限的 GitHub PAT 登录，或在本地通过 docker build -t <tag> skills/<skill>/ 构建。
  • 网络超时： 如果你使用 ARM 设备且遇到校验和不匹配，请使用 --platform linux/amd64 重试。

评论

支持 Markdown