surfline

核心用法

Surfline 技能通过调用 Surfline 官方公开 API（services.surfline.com），为用户提供完整的冲浪数据查询服务。主要包含三大功能模块：

1. 浪点搜索：通过 surfline_search.py 脚本按名称搜索全球冲浪地点，获取稳定的 spot ID（如 "Cardiff Reef"、"D Street" 等经典浪点）。

2. 单点预报：使用 surfline_report.py 输入 spot ID，可获取该地点的详细冲浪报告，包括浪高、浪向、周期、风速风向、潮汐等关键指标，支持纯文本或 JSON 格式输出。

3. 收藏汇总：通过配置 ~/.config/surfline/favorites.json 文件，使用 surfline_favorites.py 一键汇总多个常去浪点的当前状况，便于快速对比选择最佳冲浪地点。

所有脚本内置智能缓存机制（默认 600 秒 TTL，可通过环境变量调整），有效减少对 API 的重复请求，既提升响应速度也避免触发服务限制。

显著优点

• 零门槛使用：无需注册账号、无需 API Key、无需 Cookie，开箱即用，极大降低了冲浪数据获取的门槛。
• 纯标准库实现：仅依赖 Python 3 内置模块（json、urllib、pathlib 等），无第三方包依赖，部署简单，兼容性强。
• 数据权威可靠：直接对接 Surfline 官方数据源，预报精度与专业冲浪 App 一致，覆盖全球数千个浪点。
• 输出灵活：支持人类可读的文本报告和机器可解析的 JSON 格式，便于个人查看或集成到其他工作流。
• 缓存友好：本地缓存设计合理，路径经过安全处理，支持自定义 TTL，平衡实时性与性能。

潜在缺点与局限性

• 功能只读受限：仅能查询公开数据，无法访问 Surfline 会员专属的高级预报（如 16 天延长预报、高清摄像头等）。
• API 依赖风险：Surfline 可能随时调整公开端点或字段结构，需手动更新 surfline_client.py 适配，存在维护成本。
• 无实时推送：需主动发起查询，不具备条件达标自动提醒功能。
• 地理覆盖盲区：部分小众或新兴浪点可能未被 Surfline 收录，搜索功能受限。
• 速率限制不明：虽内置缓存，但未明确暴露 Surfline 的速率限制策略，高频调用仍存在被封禁风险。

适合的目标群体

• 冲浪爱好者：日常查看本地浪况，规划周末冲浪行程。
• 冲浪教练/俱乐部：批量监控多个教学浪点条件，优化课程安排。
• 冲浪旅行规划者：跨地区对比浪点预报，制定冲浪旅行路线。
• 开发者/数据爱好者：将冲浪数据集成到个人仪表盘、自动化脚本或数据分析项目。

使用风险

• 服务可用性：Surfline 公开 API 为非官方承诺接口，存在未来关闭或变更的可能。
• 缓存一致性：默认 10 分钟缓存可能导致数据非实时，极端天气快速变化场景下需手动刷新。
• 网络依赖：需稳定访问 services.surfline.com，部分地区可能存在连接问题。
• 配置误操作：favorites.json 格式错误会导致收藏汇总功能失败，需确保 JSON 语法正确。