客户端报告自动化

从多个数据源拉取指标，生成品牌化报告，并自动交付给客户。专为需要稳定、专业报告能力，同时又无需手动操作的代理机构和自由职业者设计。

安装配置

依赖项

pip3 install requests jinja2

API 密钥（在 config.json 中配置）

• Google Analytics 4 — GA4_PROPERTY_ID 及服务账号密钥
• Google Search Console — 服务账号密钥（参见 seo-audit-suite 相关说明）
• 社交平台 — 与 social-media-autopilot 技能所用凭证一致
• SendGrid — 用于邮件投递（SENDGRID_API_KEY）

工作区结构

client-reports/
├── config.json           # 全局配置，含 API 密钥
├── clients/              # 每个客户的独立配置
│   └── client-name/
│       ├── config.json   # 客户专属配置（如 property ID、品牌信息等）
│       ├── reports/      # 生成的报告文件
│       └── data/         # 缓存的指标数据
├── templates/            # 报告模板（Jinja2 HTML 格式）
└── schedules.json        # 自动化投递排期配置

运行 scripts/init-workspace.sh 脚本可自动创建该目录结构。

核心工作流

1. 添加客户

scripts/add-client.sh --name "acme-corp" --domain "acme.com" --email "ceo@acme.com"

该命令将创建客户目录及基础配置模板。请编辑 clients/acme-corp/config.json，补充以下内容：

• GA4 property ID
• Search Console 站点 URL
• 社交平台账号（handles）
• 品牌信息（Logo URL、品牌色）
• 报告偏好（需包含的指标、生成频率）

2. 拉取指标数据

为指定客户获取最新数据：

scripts/pull-metrics.sh --client "acme-corp"                    # 所有数据源
scripts/pull-metrics.sh --client "acme-corp" --source ga4       # 仅 Google Analytics
scripts/pull-metrics.sh --client "acme-corp" --source gsc       # 仅 Search Console
scripts/pull-metrics.sh --client "acme-corp" --source social    # 仅社交平台数据
scripts/pull-metrics.sh --client "acme-corp" --period 30d       # 过去 30 天

支持的数据源与指标如下：

Google Analytics 4：

• 会话数（Sessions）、用户数（Users）、新用户数（New Users）、跳出率（Bounce Rate）
• 浏览量最高的页面（Top pages by views）
• 流量来源分布（Traffic sources breakdown）
• 转化事件（Conversion events）
• 设备与浏览器分布（Device/browser breakdown）

Google Search Console：

• 总点击量、展现量、点击率（CTR）、平均排名（Avg position）
• 按点击量排序的关键词（Top queries by clicks）
• 按展现量排序的页面（Top pages by impressions）
• 相较上一周期的排名变化（Position changes vs previous period）

社交平台：

• 粉丝数 / 关注数变化（Followers/following changes）
• 帖子互动数据（点赞、转发、评论）
• 表现最佳的帖子（Top performing posts）
• 触达人数 / 展现量（Reach/impressions）

3. 生成报告

scripts/generate-report.sh --client "acme-corp" --type monthly
scripts/generate-report.sh --client "acme-corp" --type weekly --format html
scripts/generate-report.sh --client "acme-corp" --type custom --metrics "traffic,rankings,social"

报告类型：

• weekly —— 7 日快照，含周环比变化
• monthly —— 30 日深度分析，含月环比趋势
• quarterly —— 90 日战略级概览
• custom —— 自定义选择具体指标

输出格式：

• Markdown —— 默认格式，适用于 Slack 或邮件正文
• HTML —— 品牌化、专业化、可直接通过邮件发送
• PDF —— 通过 HTML-to-PDF 转换生成（需安装 wkhtmltopdf 或同类工具）

4. 自动投递报告

scripts/deliver-report.sh --client "acme-corp" --latest         # 发送最新生成的报告
scripts/deliver-report.sh --client "acme-corp" --via email      # 邮件投递
scripts/deliver-report.sh --client "acme-corp" --via slack      # Slack webhook 投递

5. 设置周期性报告排期

在 schedules.json 中配置：

{
  "schedules": [
    {
      "client": "acme-corp",
      "type": "weekly",
      "day": "monday",
      "time": "09:00",
      "timezone": "America/Los_Angeles",
      "deliver_via": "email",
      "enabled": true
    },
    {
      "client": "acme-corp",
      "type": "monthly",
      "day_of_month": 1,
      "time": "09:00",
      "timezone": "America/Los_Angeles",
      "deliver_via": "email",
      "enabled": true
    }
  ]
}

配合 OpenClaw cron 使用以实现自动化：每日检查排期，自动生成并投递到期报告。

6. KPI 仪表盘

快速查看任意客户的终端仪表盘：

scripts/dashboard.sh --client "acme-corp"

展示当前周期与上一周期对比：流量、搜索排名、社交增长、转化情况等关键指标。

报告模板系统

模板基于 Jinja2 构建，存放于 templates/ 目录下：

  
月度报告 — {{ client.name }}
  
{{ period.start }} 至 {{ period.end }}
  
  
流量概览
  

    
会话数
{{ ga4.sessions }}
{{ ga4.sessions_change }}%
    
用户数
{{ ga4.users }}
{{ ga4.users_change }}%
  
  
  
搜索表现
  

可通过在 clients//templates/ 下放置同名模板文件，实现按客户定制化覆盖。

Cron 集成

• 每日执行：为所有启用中的客户拉取最新指标数据
• 每周执行：生成并投递周报（每周一上午）
• 每月执行：生成并投递月报（每月 1 日）
• 每季度执行：生成季度复盘报告

参考文档

• references/ga4-setup.md — Google Analytics 4 API 配置说明及可用指标列表
• references/report-customization.md — 模板与指标自定义方法指南