DataFast Analytics 技能

使用此技能调用 DataFast API，并为用户汇总返回结果。

快速工作流

1. 确认请求类型（overview、timeseries、realtime、breakdown、visitor、goals/payments 的创建或删除）。
2. 收集必需的输入参数：
   • 日期范围：需同时提供 startAt 和 endAt，或均不提供（仅 overview/timeseries 支持时间范围）。
   • timezone、fields、interval、limit、offset，以及任意以 filter_* 开头的参数。
3. 构造 HTTP 请求，包含请求头 Authorization: Bearer $DATAFAST_API_KEY 和 Content-Type: application/json。
4. 使用 curl 执行请求并解析 JSON 响应。
5. 以表格形式呈现结果，并辅以简明叙述（含总量统计与关键洞察）。若涉及分页，需一并说明分页信息。

配置步骤

1. 从 DataFast 获取您的 API 密钥（密钥以 df_ 开头）。
2. 将密钥保存至本地：

mkdir -p ~/.config/datafast
echo "df_your_key_here" > ~/.config/datafast/api_key

身份验证

所有请求均需以下认证头：

DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl ... 
  -H "Authorization: Bearer $DATAFAST_API_KEY" 
  -H "Content-Type: application/json"

若用户尚未配置 API 密钥，请提示其完成上述配置步骤。

基础 URL

https://datafa.st/api/v1/

参考文档

有关各端点的详细说明、响应字段及示例，请查阅完整 API 参考文档：{baseDir}/references/datafast-api-docs.md。

端点使用指南

概览（Overview）

• GET /analytics/overview
• 可选参数：startAt、endAt、timezone、fields。

时间序列（Time Series）

• GET /analytics/timeseries
• 常用参数：fields、interval（hour/day/week/month）、startAt、endAt、timezone、limit、offset。
• 支持通过 filter_* 查询参数进行数据切片（segmentation）。
• 注意：fields 为必填项（例如：fields=visitors,sessions）。

实时数据（Realtime）

• GET /analytics/realtime
• GET /analytics/realtime/map

细分分析（Breakdowns）

• GET /analytics/devices
• GET /analytics/pages
• GET /analytics/campaigns
• GET /analytics/goals
• GET /analytics/referrers
• GET /analytics/countries
• GET /analytics/regions
• GET /analytics/cities
• GET /analytics/browsers
• GET /analytics/operating-systems
• GET /analytics/hostnames

访客详情（Visitor Details）

• GET /visitors/{datafast_visitor_id}

目标（Goals）

• 创建目标：POST /goals
• 删除目标：DELETE /goals（至少需指定一个过滤条件或时间范围；执行前须确认作用范围）

支付（Payments）

• 创建支付记录：POST /payments
• 删除支付记录：DELETE /payments（执行前须确认作用范围）

破坏性操作

对于 DELETE /goals 或 DELETE /payments 操作：

• 执行前，务必以自然语言明确确认所使用的全部过滤条件和时间范围。
• 若用户要求“全时段”删除，请额外获取其明确确认。
• 输出即将调用的最终 URL（不含 API 密钥）。

过滤器语法

使用 filter_* 参数实现数据切片（例如：filter_referrer=is:X）。

重要提示：过滤值必须严格匹配细分分析端点中返回的名称。例如，“X/Twitter” 在系统中存储为 "X"（而非 "x.com" 或 "twitter.com"）。如有疑问，请先查询对应细分端点以确认准确值：

curl ... "/analytics/referrers?limit=20"

然后在过滤器中精确使用该 referrer 值。

示例命令模式

GET 请求

DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl -sS "https://datafa.st/api/v1/analytics/overview?startAt=2024-01-01&endAt=2024-01-31&timezone=UTC" 
  -H "Authorization: Bearer $DATAFAST_API_KEY" 
  -H "Content-Type: application/json"

POST 请求

DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl -sS "https://datafa.st/api/v1/goals" 
  -H "Authorization: Bearer $DATAFAST_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"datafast_visitor_id":"...","name":"newsletter_signup","metadata":{"email":"..."}}'

DELETE 请求

DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl -sS -X DELETE "https://datafa.st/api/v1/goals?name=signup&startAt=2023-01-01T00:00:00Z&endAt=2023-01-31T23:59:59Z" 
  -H "Authorization: Bearer $DATAFAST_API_KEY"

输出预期

• 提供简洁摘要及扁平化结果表格。
• 若响应中包含总量、转化率或营收指标，请一并展示。
• 对于时间序列数据，需呈现顶层总量，以及所选时间范围内首条与末条记录的时间戳。
• 若响应含分页信息，请报告 limit、offset 与 total 字段，并询问用户是否需要获取下一页数据。