基于Umami官方API的只读数据分析工具，通过环境变量安全配置，支持云版与自托管双模式，为运营决策提供实时流量、事件追踪与归因分析能力。
说明：
**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密钥权限和查询参数的正确性。
会员专属
