设置

首次使用时，请阅读 setup.md 文件了解集成指南。该技能将配置信息存储在 ~/matomo/ 目录中。

适用场景

当用户需要查询 Matomo 分析数据、生成报表、追踪目标转化或管理其自托管的分析服务时，可使用本技能。Agent 负责处理 API 查询、数据分析、访客洞察及转化追踪任务。

架构

记忆数据（Memory）存放在 ~/matomo/ 目录中。其结构详见 memory-template.md。

~/matomo/
├── memory.md         # 站点列表、凭证引用、用户偏好
├── reports/          # 已保存的报表模板
└── queries/          # 可复用的 API 查询模板

快速参考

核心规则

1. 绝不暴露凭证

• Token 存储于系统密钥链或环境变量中，**绝不可**写入 memory 文件
• 仅通过引用名称（reference name）引用凭证
• 若用户在聊天中粘贴了 token，请发出警告并建议使用安全方式存储

2. 读取操作统一使用 Reporting API

# 基础请求模式
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 — 获取目标转化数据

3. 正确理解日期范围参数

特殊日期关键字：today、yesterday、last7、last30、lastMonth、lastYear

4. 支持多站点配置

• 执行查询前，必须确认当前操作的目标站点
• 在 memory.md 中维护站点列表及其 idSite 映射关系
• 如已配置，默认使用最常使用的站点

5. 面向人类优化数据展示格式

• 百分比保留一位小数
• 大数值使用 K（千）、M（百万）后缀缩写
• 在上下文有益时，提供与上一周/上一月的对比数据
• 显著变化（变化幅度 >10%）需高亮提示

6. 尊重速率限制

• 尽可能将相关查询合并为单个日期范围内的请求
• 将近期查询结果缓存在本地 memory 中，用于后续问题的快速响应
• 避免在一次对话中重复查询相同数据

7. 使用 Segment 获取深度洞察

Segment 可基于访客属性对数据进行筛选。可在任意查询中添加 &segment= 参数：

# 仅限移动设备访客
&segment=deviceType==smartphone

# 来自特定国家的访客
&segment=countryCode==US

# 曾返回且完成过目标转化的访客
&segment=visitorType==returning;goalConversionsSome>0

# 使用 AND（分号 ;）或 OR（逗号 ,）组合多个条件
&segment=browserCode==CH;operatingSystemCode==WIN

常用 Segment 维度：

• deviceType — smartphone（智能手机）、tablet（平板）、desktop（桌面端）
• browserCode — CH（Chrome）、FF（Firefox）、SF（Safari）
• countryCode — ISO 两位国家代码
• visitorType — new（新访客）、returning（回访访客）
• referrerType — direct（直接访问）、search（搜索引擎）、website（外部网站）、campaign（广告活动）

Matomo 常见陷阱

• 错误的 idSite → 查询了错误的站点，导致数据误导。务必先确认目标站点。
• 遗漏 token_auth → 返回 403 错误或空响应。所有非公开 API 方法均需提供 token。
• date 与 period 不匹配 → 结果混乱。period=range 必须配合 date=start,end 格式使用。
• 套用 Google Analytics 术语习惯 → Matomo 使用 “visits”（非 “sessions”）、“actions”（非 “events”）。请在思维中做对应转换。
• 忽略 Segment → 错失关键洞察。Segment 是按访客属性筛选数据的核心机制。

外部端点

除此之外，不向任何外部服务发送其他数据。所有请求均发往用户自己的 Matomo 实例。

安全与隐私

离开您设备的数据：

• 仅向用户的 Matomo 实例发送 API 查询请求
• 请求中包含认证 token（由用户完全控制）

保留在本地的数据：

• 存放在 ~/matomo/ 中的站点配置
• 报表模板
• 不向任何第三方服务发送数据

本技能明确不执行以下操作：

• 以明文形式存储 auth token
• 向用户 Matomo 实例以外的任何服务发送数据
• 访问 ~/matomo/ 目录之外的任何文件

相关技能

若用户确认安装，可使用命令 clawhub install 安装以下技能：

• analytics — 通用分析模式
• umami — 注重隐私的分析工具
• api — REST API 集成支持

反馈

• 若本技能有用：运行 clawhub star matomo
• 保持更新：运行 clawhub sync