rainday/google

Google API — 效能檢測

整合 Google PageSpeed Insights 和 CrUX API，為 blog analyze 提供真實效能數據。

指令一覽

| 指令 | 功能 | 需要 API Key | |------|------|-------------| | /smart-blog-skills:google setup | 設定 API key | 否 | | /smart-blog-skills:google pagespeed <URL> | PageSpeed Insights 分析 | 否（建議有） | | /smart-blog-skills:google crux <URL> | CrUX 真實用戶數據 | 是 |

Tier 系統

| Tier | 需要什麼 | 解鎖功能 | 限制 | |------|---------|---------|------| | 0（免費） | 無需任何設定 | PageSpeed Insights（無 key） | 25 次/天（共用配額，可能被限流） | | 1（API Key） | Google Cloud Console 免費 API Key | PageSpeed（專屬配額）+ CrUX | PageSpeed 400 次/天，CrUX 150 次/天 |

如何取得 API Key（免費）

1. 前往 Google Cloud Console
2. 建立專案（或選擇現有專案）
3. 啟用 API：
   • PageSpeed Insights API
   • Chrome UX Report API
4. 建立憑證 → API Key
5. 執行 /smart-blog-skills:google setup 輸入 key

Config 管理

儲存位置

~/.config/smart-blog-skills/
├── config.json          ← API key 和偏好設定
└── .gitignore           ← 防止意外提交

config.json 格式

{
  "google_api_key": "",
  "default_strategy": "mobile",
  "locale": "zh-TW",
  "created": "2026-04-06",
  "updated": "2026-04-06"
}

安全措施

1. 檔案權限：建立後設定 chmod 600 config.json（Unix）
2. 不在專案目錄：config 在 ~/.config/ 下，不會被 git commit
3. config 目錄 .gitignore：額外防護，目錄內含 * 排除規則
4. 環境變數備援：也支援 SMART_BLOG_GOOGLE_API_KEY 環境變數
5. API Key 限制建議：在 Google Cloud Console 設定 HTTP referrer 或 IP 限制

Setup 流程

Step 1：建立 config 目錄

mkdir -p ~/.config/smart-blog-skills
echo '*' > ~/.config/smart-blog-skills/.gitignore

Step 2：詢問 API Key

問使用者：

要設定 Google API Key 嗎？

• 有 Key：輸入 key，解鎖 CrUX + 專屬 PageSpeed 配額
• 沒有 Key：按 Enter 跳過，仍可使用免費 PageSpeed（共用配額）

API Key 儲存在 ~/.config/smart-blog-skills/config.json，不會進入 git。

Step 3：寫入 config

將使用者提供的資訊寫入 ~/.config/smart-blog-skills/config.json。

Step 4：設定檔案權限

chmod 600 ~/.config/smart-blog-skills/config.json

Windows 環境跳過此步驟（NTFS 權限由系統管理）。

PageSpeed 分析流程

Step 1：讀取 Config

1. 讀取 ~/.config/smart-blog-skills/config.json
2. 如果 google_api_key 有值 → Tier 1 模式
3. 如果沒有 → Tier 0 模式（免費端點）

Step 2：呼叫 API

Tier 0（無 key）：

WebFetch: https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={URL}&strategy=mobile&locale=zh-TW

Tier 1（有 key）：

WebFetch: https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={URL}&strategy=mobile&locale=zh-TW&key={API_KEY}

Step 3：解析結果

從回傳的 JSON 提取：

| 指標 | 欄位路徑 | 好 | 待改善 | 差 | |------|---------|---|--------|---| | Performance Score | lighthouseResult.categories.performance.score | ≥0.9 | 0.5-0.89 | <0.5 | | FCP | lighthouseResult.audits.first-contentful-paint | ≤1.8s | 1.8-3s | >3s | | LCP | lighthouseResult.audits.largest-contentful-paint | ≤2.5s | 2.5-4s | >4s | | TBT | lighthouseResult.audits.total-blocking-time | ≤200ms | 200-600ms | >600ms | | CLS | lighthouseResult.audits.cumulative-layout-shift | ≤0.1 | 0.1-0.25 | >0.25 | | Speed Index | lighthouseResult.audits.speed-index | ≤3.4s | 3.4-5.8s | >5.8s |

Step 4：輸出報告

## PageSpeed 報告：{URL}

**策略：** Mobile
**Performance Score：** {score}/100

### Core Web Vitals

| 指標 | 數值 | 狀態 |
|------|------|------|
| LCP（最大內容繪製） | {value} | {好/待改善/差} |
| FCP（首次內容繪製） | {value} | {好/待改善/差} |
| TBT（總阻塞時間） | {value} | {好/待改善/差} |
| CLS（累積版面偏移） | {value} | {好/待改善/差} |
| Speed Index | {value} | {好/待改善/差} |

### 改善建議（前 5 項）

| 優先級 | 問題 | 預估節省 |
|--------|------|---------|
| {高/中/低} | {描述} | {時間} |

CrUX 分析流程（Tier 1 only）

呼叫 API

WebFetch: https://chromeuxreport.googleapis.com/v1/records:queryRecord?key={API_KEY}

POST body:

{
  "url": "{URL}",
  "formFactor": "PHONE"
}

解析結果

提取真實用戶的 Core Web Vitals 分佈（p75 值）：

• LCP、FID/INP、CLS
• 好/待改善/差的百分比分佈

輸出

附加到 PageSpeed 報告後方：

### CrUX 真實用戶數據（28 天）

| 指標 | p75 | 好 | 待改善 | 差 |
|------|-----|---|--------|---|
| LCP | {value} | {%} | {%} | {%} |
| INP | {value} | {%} | {%} | {%} |
| CLS | {value} | {%} | {%} | {%} |

與 analyze 整合

當使用者執行 /smart-blog-skills:analyze 且文章的 frontmatter 包含 url 或 canonical 欄位時：

1. 自動偵測是否有 config
2. 如果有 → 在技術元素評分中加入 PageSpeed 數據
3. 如果沒有 → 跳過，使用原有的純內容分析

這讓 analyze 的「技術元素」類別（15 分）可以基於真實數據評分，而非只檢查 HTML 結構。

錯誤處理

| 情境 | 行為 | |------|------| | 無 API Key + 被限流 | 提示使用者申請免費 API Key | | API Key 無效 | 提示檢查 key，退回 Tier 0 | | URL 無法存取 | 報告錯誤，跳過效能檢測 | | CrUX 無數據 | 說明該 URL 流量不足，CrUX 無法提供數據 |