核心功能
Stormglass Surf Skill 是一个面向自动化工作流的冲浪条件数据获取工具，通过调用 Stormglass 海洋气象 API，提供机器可读的冲浪相关海洋数据。该工具支持通过地名或坐标两种模式定位冲浪点，返回包含当前实况和 1-3 天预报的完整数据集，涵盖浪高、涌浪周期、潮汐、风速阵风及水温等关键指标。
显著优点
数据专业性与覆盖度：Stormglass 作为专业海洋气象服务商，整合了全球多个数据源（NOAA、MetOffice、DWD 等），提供高分辨率的波浪、潮汐和风场数据，对冲浪运动具有直接指导价值。
灵活的定位模式：支持自然语言地名输入（通过 Google Geocoding 或 OpenStreetMap Nominatim 解析）和直接坐标输入，适应不同使用场景。Google Geocoding 作为备选方案提升了地址解析的准确性。
结构化输出设计：JSON 优先的设计理念使输出可直接嵌入 cron 定时任务和下游代理流水线，稳定的字段契约（waveHeightM、swellPeriodS、tides 等）降低了集成复杂度。
离线测试支持：--mock 模式提供确定性测试数据，无需真实 API 密钥即可验证流水线，这对 CI/CD 和开发调试至关重要。
潜在局限
API 依赖与成本：核心功能依赖 STORMGLASS_API_KEY，该服务为付费 API（虽有免费额度），高频自动化调用可能产生费用。Google Geocoding 同样存在配额限制。
地理编码风险：地名解析存在歧义可能（如同名海滩），虽提供国家/区域限定选项，但自动化场景下仍可能定位偏差。OSM Nominatim 作为 fallback 的可靠性低于 Google。
数据粒度限制：预报窗口以摘要形式呈现（best windows），而非逐小时原始数据，对需要精细时间规划的高级用户可能不足。
错误处理层级：外部 API 故障（exit code 4）和解析失败（exit code 5）的区分虽清晰，但实际排查仍需人工介入日志分析。
适用人群
- 构建自动化冲浪报告系统的开发者与气象数据工程师
- 运营区域冲浪社区、需要定时推送浪况的媒体/俱乐部
- 开发冲浪 spot 推荐算法的机器学习团队
- 需要标准化海洋数据源进行研究的学术用户
常规风险
密钥管理风险：STORMGLASS_API_KEY 和 GOOGLE_GEOCODING_API_KEY 需妥善保管，硬编码或日志泄露可能导致配额被盗用。建议通过环境变量或密钥管理服务注入。
服务可用性风险：Stormglass 或地理编码服务的临时中断会影响数据 freshness，cron 任务需配置超时和重试机制。
数据解释风险：null 值与零值的语义区分（not provided vs calm）若被下游误读，可能导致错误的冲浪条件判断。