Umami Stats 是一款专为网站数据分析设计的只读API技能，旨在帮助用户安全、高效地获取Umami Cloud或自托管实例中的流量统计、页面访问、事件追踪及会话数据。作为数据访问层的轻量化实现，该技能通过Python标准库构建，无需额外依赖，即可实现与Umami v2 API的无缝对接。
核心用法
该技能采用环境变量驱动的配置模式，用户需设置UMAMI_API_KEY作为身份凭证，可选配置UMAMI_BASE_URL、UMAMI_WEBSITE_ID及部署模式（cloud/self-hosted）。通过scripts/umami_query.py脚本，用户可灵活调用各类只读端点，如获取网站列表、统计数据、页面浏览量、事件序列及归因报告。脚本内置时间预设（today、last7d、last30d等）和自定义时间戳功能，支持路径自动映射（云版/v1/与自托管/api/的智能转换），极大简化了跨平台使用的复杂度。
显著优点
安全性设计突出：仅执行GET只读操作，从根本上杜绝了数据误删或篡改风险；API密钥通过环境变量管理，避免硬编码泄露。零依赖架构：仅使用Python标准库（urllib、argparse、json等），消除了外部供应链攻击面，部署极其轻量。双模式兼容：无论是Umami Cloud用户还是自托管用户，均可通过--deployment参数无缝切换，自动适配不同的认证头（Cloud使用x-umami-api-key，自托管使用Authorization: Bearer）。查询灵活性高：支持参数化查询、自动默认值填充（如metrics端点自动补充type=url），以及完善的错误处理和超时机制（默认30秒）。
局限性与约束
作为只读工具，该技能无法执行任何数据修改操作（如创建网站、更新设置或删除记录），仅适用于数据分析和监控场景。此外，其来源为T3级社区项目（openclaw/skills），虽代码质量通过A级安全认证，但非Umami官方维护，长期更新与兼容性保障需依赖社区贡献。用户还需自行准备有效的Umami API密钥，对于无技术背景的用户存在一定配置门槛。
目标用户群体
该技能特别适合网站运营人员进行日常流量监控和趋势分析，产品经理验证功能使用情况和用户行为路径，数据分析师获取原始JSON数据进行深度加工，以及开发者在CI/CD流程中集成网站健康检查。对于需要定期生成营销效果报告、A/B测试数据支持或实时监控大屏数据的团队，此工具提供了可靠的自动化数据获取能力。
使用风险与注意事项
尽管安全评级为A级，用户仍需注意：API密钥管理是关键风险点，应确保环境变量不被意外提交到版本控制，并在团队成员间安全共享；网络依赖性方面，脚本执行受限于Umami服务可用性和网络状况，虽有过期机制但仍可能因服务端问题导致查询失败；数据隐私上，虽然脚本本身不收集用户数据，但查询结果可能包含敏感的业务指标，需妥善处理返回的JSON数据；权限范围上，Umami Cloud的普通用户API密钥可能无法访问/v1/users/*端点（返回403），这属于预期的权限限制，非技能缺陷。建议在正式环境使用前，先在测试环境验证API密钥权限和查询参数的正确性。