核心用法
alltrails-fpx 是一项命令行代理技能，用于在没有 AllTrails MCP Server 的环境下获取 AllTrails 平台数据。它通过 @fetchproxy/cli（fpx）工具与浏览器扩展 Transporter 建立桥接，利用用户已登录的浏览器标签页发起同源请求，从而绕过 DataDome 反爬机制。
使用前需完成一次性配置：安装 fpx CLI、创建 alltrails 配置文件、声明 x-at-key 请求头捕获规则，并与浏览器扩展配对。每次调用需动态获取 x-at-key（匿名客户端标识符），并显式附加该头部及 x-at-caller/x-language-locale 方可成功请求 /api/alltrails/* 端点。
支持的查询类型包括：步道搜索、详情获取、评价与照片、天气信息，以及登录用户的保存列表、已完成步道和活动动态。所有端点参考文档位于 references/endpoints.md。
显著优点
1. 免 MCP 部署：无需运行 Node.js MCP Server，单机 CLI 即可工作，降低环境依赖。
2. 抗检测能力强：请求源自用户真实浏览器会话，天然携带 DataDome 认可指纹，较纯 HTTP 客户端更难触发 403。
3. 灵活脚本化：适合 shell 脚本、定时任务或 CI/CD 流水线中批量拉取数据。
4. 用户态数据支持：可访问登录用户的私有列表、完成记录等个人数据。
潜在缺点与局限性
- 手动维护会话：需保持浏览器标签页开启且处于登录状态，无法完全无人值守。
- 动态密钥依赖：
x-at-key非持久化存储，每次会话或密钥轮换后需重新捕获，增加调用复杂度。 - 无写入能力：仅覆盖读操作（GET/只读 POST），无法创建列表、标记完成或提交评价。
- 单位换算负担：距离、海拔等字段返回公制（米），需自行转换为英制单位。
- 错误响应隐蔽：HTTP 200 可能包裹 HTML 拦截页或 DataDome 挑战，需额外校验响应体结构。
适合的目标群体
- 需要在服务器或 CI 环境中集成 AllTrails 数据，但无法/不愿部署 MCP Server 的开发者
- 偏好 shell 脚本自动化、对 Node.js 运行时有限制的运维人员
- 轻量级数据分析师、户外内容创作者，需批量获取公开步道信息进行二次处理
常规使用风险
| 风险类型 | 说明 |
|---------|------|
| 会话失效 | 浏览器标签关闭、登录过期或 DataDome 重挑战均会导致请求失败，需人工重新激活 |
| 密钥过期 | `x-at-key` 可能轮换， stale key 返回 400/401，需捕获重试逻辑 |
| 速率限制 | 高频调用可能触发平台级限流，建议控制并发并加入退避策略 |
| 数据一致性 | 依赖浏览器渲染态的 API 版本，官方随时可能调整端点契约 |
| 合规风险 | 批量爬取需遵守 AllTrails Terms of Service，避免商业性大规模抓取 |
退出码速查
0成功（仍需校验 JSON 结构）2桥接未就绪 → 重新配对3DataDome 拦截 → 刷新标签页4上游非 2xx → 检查密钥有效性