CDN Traffic Report

自動化 CDN 流量報表工具，從 Akamai Control Center 與 AWS CloudFront 擷取數據；同時是 Claude Code Plugin，可直接讓 AI agent 調用

TestsCoverage
Python 3.11agent-browserAkamaiAWS CloudFrontClaude Code Plugin1Passwordpytest / codecov
GitHubResume
🧩 問題 / 為什麼用 Browser Automation

Akamai V2 API 只能取到部分流量指標，但 Control Center 週報需要的多 CP code 彙總、地理流量表、hostname 分類，並沒有穩定對應的 API 端點。

所以改走 browser automation 直接讀 Control Center SPA，再用 URL hash 帶入參數，把對前端操作流程的依賴降到最低。

與直接打 API 的路線取捨，完整比較見 COMPARISON.md（對照 akamai-reports 的 V2 API 版本）。

讀 COMPARISON.md →
🏗 架構 / 資料流
CLI User / Claude Code Agent → cdn-traffic-report
  ├── Akamai: 1Password op → agent-browser (Chromium) → SPA DOM → JSON
  └── CloudFront: AWS CLI → CloudWatch → JSON
→ output/ JSON + weekly.csv
💡 核心能力
1

SPA 瀏覽器自動化

Akamai Control Center 是純 SPA、無官方報表 API。以 agent-browser 驅動 Chromium，直接擷取 KPI 卡片與地理流量表格的 DOM 數值，補足 API 拿不到的 UI-only 指標。

2

Claude Code Plugin / Skill

包裝成 /cdn:cdn-report skill，AI agent 直接調用、跑腳本、讀 JSON、格式化成表格回傳。不只是腳本，是 AI-native、可被 workflow 串接的能力模組。

3

雙層防 UI 改版

contract_check 對真實 Akamai UI 比對 selector baseline，偵測改版；mock_site 在 CI 用假 SPA 離線驗證 DOM 擷取。改版前先抓到失效，避免靜默產出空值。

其他亮點
1Password TOTP 整合從 op CLI 讀帳密與 TOTP，登入後保持瀏覽器開著維持 session cookie，避免每次重登。
URL Hash 參數化用 URL hash 帶 cpcodes / start / end / timezone，跳過 calendar 與 CP 選擇器 UI，縮小改版影響面（SPA 自動化的延伸）。
週報 CSV 自動化每次完整執行後自動 append 一行到 weekly.csv，欄位對應人工維護的週流量試算表，省去手動抄寫。
🤖 Agent Skill 互動流程
使用者 ↔ Claude Code Agent
# 使用者只下一句 skill 指令
> /cdn:cdn-report 2026-01-25 2026-01-31

# Agent 自動執行：
  1. 讀 SKILL.md 取得指令模板
  2. 跑 scripts.akamai_report --start … --end …
  3. 讀 output/report_*.json
  4. 依 SKILL.md 規則格式化
  5. 回傳結構化表格
Agent 回傳（示意）
指標流量
Edge12.34 TB
Origin4.56 TB
Midgress7.89 GB
Offload56.78 %

數字為去識別化示意值，非真實流量。

🛡 測試策略 / 防 UI 改版
第一層：Contract Check（對真實 UI）

contract_check 用 --save 存下 DOM selector baseline，之後用 --diff 比對真實 Akamai UI；selector 失效時在改版當下就抓到，不會靜默產出空值。

uv run python -m scripts.contract_check --headed --save   # 存 baseline
uv run python -m scripts.contract_check --headed --diff   # 比對偵測改版
第二層：Mock Integration（CI 離線）

tests/mock_site/ 是假的 Akamai SPA（index.html + mock_data.js）。agent-browser 對它跑 integration test，驗證 DOM 擷取邏輯，不需真實帳密、CI 可離線重跑。

uv run pytest tests/test_mock_integration.py -v   # 離線跑 agent-browser
⚡ 使用方式
Step 1: Session 登入
uv run python -m scripts.refresh_session
Step 2: 產出報表
uv run python -m scripts.akamai_report \
  --start 2026-05-10 --end 2026-05-16 \
  --reuse-browser --close-when-done
Claude Code Skill
/cdn:cdn-report 2026-01-25 2026-01-31
/cdn:cdn-report 2026-01-25 2026-01-31 geography
/cdn:cdn-report 2026-01-25 2026-01-31 cloudfront
Contract Check
uv run python -m scripts.contract_check \
  --headed --diff
📄 輸出格式
Akamai / CloudFront JSON
{
  "date_range": {
    "start": "2026-01-25",
    "end":   "2026-01-31"
  },
  "type":    "summary",
  "traffic": {
    "edge":     12.34,
    "origin":    4.56,
    "offload":  56.78
  },
  "unit": "TB"
}
Geography JSON
{
  "type": "geography",
  "geography": {
    "TW":   9.87,
    "SG":   2.10,
    "ID":   0.05
  },
  "unit": "TB"
}
weekly.csv 欄位
年度 | 週期
edge流量TB | origin流量TB
ID | TW | SG
v1流量TB | v3流量TB
Trailer/EPK | live流量GB
TVA流量GB | home流量GB
🗂 專案結構
.claude-plugin/plugin.json     # Claude Code Plugin 清單
skills/cdn-report/SKILL.md     # Skill 定義
scripts/
  akamai_report.py             # 主程式 + CLI
  refresh_session.py           # Session + 1Password 登入
  browser_helpers.py           # agent-browser 封裝
  data_extract.py              # DOM 擷取 (KPI + 地理表格)
  contract_check.py            # DOM selector 合約驗證
  cloudfront.py                # AWS CloudWatch 指標
config/settings.yaml.template  # 設定範本
tests/
  mock_site/                   # 本地 mock Akamai SPA