首次使用时，请阅读 setup.md 以获取集成指南。该技能将配置存储在 ~/matomo/ 中。
何时使用
用户需要查询 Matomo 分析数据、生成报告、跟踪目标或管理自托管分析时。Agent 处理 API 查询、数据分析、访客洞察和转换跟踪。
架构
内存存储在 ~/matomo/ 中。请参阅 memory-template.md 以获取结构。
~/matomo/
├── memory.md # 站点、凭证引用、首选项
├── reports/ # 保存的报告模板
└── queries/ # 可重用的 API 查询模板
快速参考
主题 文件
设置过程 setup.md
内存模板 memory-template.md
API 参考 api.md
报告模板 reports.md
核心规则
令牌存储在系统密钥链或环境变量中，永远不要存储在内存文件中
仅通过引用名称引用凭证
如果用户在聊天中粘贴令牌，请警告并建议安全存储
# 基本模式
curl -s "https://{matomo_url}/index.php?module=API&method={method}&idSite={site_id}&period={period}&date={date}&format=json&token_auth={token}"
常用方法：
VisitsSummary.get — 访客、访问次数、页面浏览量
Actions.getPageUrls — 顶级页面
Referrers.getWebsites — 流量来源
Goals.get — 转换数据
周期 日期格式 示例
天 YYYY-MM-DD 2025-01-15
周 YYYY-MM-DD 包含该日期的周
月 YYYY-MM 2025-01
年 YYYY 2025
范围 YYYY-MM-DD,YYYY-MM-DD 2025-01-01,2025-01-31
特殊日期：today、yesterday、last7、last30、lastMonth、lastYear
始终在查询前确认站点
将站点列表存储在 memory.md 中，使用 idSite 映射
如果配置了默认站点，则使用最常用的站点
将百分比四舍五入到 1 位小数
对大数字使用 K/M 后缀
在上下文中比较周期（与上周/月相比）
突出显示显著的变化（>10% 的 delta）
将相关查询批处理到单个日期范围中（如果可能）
在内存中缓存最近的结果以供后续问题使用
避免在对话中重复查询相同的数据
段过滤数据以访客属性。
将 &segment= 添加到任何查询中：
# 仅移动访客
&segment=deviceType==smartphone
# 来自特定国家
&segment=countryCode==US
# 返回访客谁转换
&segment=visitorType==returning;goalConversionsSome>0
# 结合 AND (;) 或 OR (,)
&segment=browserCode==CH;operatingSystemCode==WIN
常见段维度：
deviceType — 智能手机、平板电脑、台式机
browserCode — CH（Chrome）、FF（Firefox）、SF（Safari）
countryCode — ISO 2 位代码
visitorType — 新、返回
referrerType — 直接、搜索、网站、活动
Matomo 陷阱
错误的 idSite → 查询错误的属性，误导性数据。
始终在查询前确认站点。
忘记 token_auth → 403 或空响应。
令牌对于所有非公共方法都是必需的。
日期与周期不匹配 → 混乱的结果。
周期=范围需要日期=开始，结束格式。
预期 GA 术语 → Matomo 使用“访问”而不是“会话”，“操作”而不是“事件”。
在脑海中翻译。
忽略段 → 缺乏真正的洞察力。
段过滤数据以访客属性。
外部端点
端点 数据发送 目的
{user_matomo_url}/index.php API 方法、站点 ID、日期范围、身份验证令牌 查询分析数据
没有其他数据被发送到外部。
所有请求都发送到用户自己的 Matomo 实例。
安全性和隐私
离开您机器的数据：
发送到用户的 Matomo 实例的 API 查询
包含在请求中的身份验证令牌（用户控制）
本地存储的数据：
~/matomo/ 中的站点配置
报告模板
没有数据被发送到第三方。
该技能不：
以明文存储身份验证令牌
将数据发送到除用户的 Matomo 之外的任何服务
访问 ~/matomo/ 之外的文件
相关技能
如果用户确认：使用 clawhub install 安装
分析 — 一般分析模式
Umami — 隐私关注的分析
API — REST API 集成
反馈
如果有用：clawhub star matomo
保持更新：clawhub sync
by