核心功能
Stormglass Surf Skill 是一款面向冲浪爱好者和海洋数据自动化系统的专业工具，通过整合 Stormglass 海洋气象 API 与 Google Geocoding 地理编码服务，实现冲浪点的智能解析与多维度海洋条件数据获取。
主要能力
- 智能地点解析：支持冲浪点名称模糊查询（自动调用 Google Geocoding 或 OpenStreetMap Nominatim 回退），或直接输入经纬度坐标
- 多时间窗口预报：提供
now（即时）、24h、48h、72h三种预报跨度，默认72小时覆盖短期冲浪计划需求 - 完整海洋指标：涵盖浪高（waveHeightM）、涌高（swellHeightM）、涌周期（swellPeriodS）、涌向（swellDirectionDeg）、风速/风向/阵风（windSpeedMps/windDirectionDeg/windGustMps）、水温（waterTemperatureC）及潮汐数据
- 机器优先输出：结构化 JSON 格式专为下游 Agent/CRON 管道设计，支持
--mock离线模式用于测试与 CI/CD
显著优点
- API 冗余设计：地理编码具备 Google → OSM 自动回退机制，降低单点故障风险
- 生产级稳健性：明确的退出码体系（0/2/3/4/5）、字段级空值语义规范（null = "未提供"而非零值）、配套测试脚本
test_surf_report.py - 数据源可配置：支持
--source参数指定多个 Stormglass 数据提供商，灵活应对数据质量差异 - 自动化友好：JSON 输出契约稳定，包含
meta/location/now/forecast/tides标准化顶层键
潜在局限与风险
- 外部 API 依赖：核心功能依赖 Stormglass API（需
STORMGLASS_API_KEY），地理编码依赖 Google/OSM，任何服务端故障均会导致exit code 4 - 非商业免费额度限制：Stormglass 免费层存在调用频次与历史数据限制，高频自动化场景需评估付费计划
- 地理编码精度风险：冲浪点名称解析依赖地理编码服务质量，偏远或新兴冲浪点可能存在坐标偏差
- 数据时效性：预报数据为模型输出，实际海况可能因局地微气候偏离预测
- 仅限海洋数据：不提供紫外线、降雨、能见度等辅助气象信息
适合人群
- 自动化系统开发者：需要为冲浪社区、订户推送系统、移动应用后端构建 CRON 驱动的数据管道
- 硬核冲浪爱好者/追浪者：希望集成个人通知系统（如 Slack/Discord Bot、邮件推送）的技术用户
- 冲浪学校/俱乐部：需批量监控多个浪点条件的运营方
- 数据分析师：研究特定区域浪况模式的研究者（可利用历史数据接口）
常规风险提示
- API 密钥管理：
STORMGLASS_API_KEY为核心凭证，建议通过环境变量或密钥管理服务注入，避免硬编码泄露 - 速率限制与成本：生产部署前务必在
test_surf_report.py中验证调用模式，监控 Stormglass 用量避免超额费用 - 坐标验证：关键冲浪点建议先用
--lat/--lon固定精确坐标，减少对地理编码的依赖 - 离线测试习惯：善用
--mock模式验证下游解析逻辑，避免开发阶段消耗真实 API 额度
技术备注
- 运行环境：Python 3
- 主要依赖：
STORMGLASS_API_KEY（必需），GOOGLE_GEOCODING_API_KEY（可选增强） - 项目地址：https://github.com/dgorissen/stormglass-skill