HTML SEO 審查
概覽
針對一或多個靜態 HTML 檔案，產出具可操作性的、按嚴重性排序的發現清單。此技能整合了一個僅使用標準函式庫的 HTML 解析器，將所有 SEO 相關訊號萃取成單一 JSON 文件，再加上一份完整的評分表與發現報告範本——共同確保每次稽核都能產出可預測的輸出。
使用時機
當輸入是一或多個靜態 .html 檔案（或包含這些檔案的目錄），且使用者希望獲得可執行的頁面 SEO 發現時使用。觸發詞包括「SEO 審查」、「SEO 稽核」、「檢查這個 HTML 的 SEO」、「審查此頁面的 meta 標籤」、「稽核頁面 SEO」。
請勿在以下情況使用：
- 內容是靜態網站產生器（Jekyll/Hugo/Astro/Eleventy/Next.js）的原始碼。這需要能感知原始碼的審查；請留待未來的
ssg-seo-review技能處理。 - 使用者想要即時效能指標（LCP、CLS、INP）。僅憑 HTML 無法產生這些數據；建議使用 Lighthouse 或 PageSpeed Insights。
- 使用者想要反向連結、網域權威或其他外部 SEO 分析。這需要第三方工具（Ahrefs、SEMrush 等）。
工作流程
1. 萃取訊號
對目標檔案執行解析器。它接受單一檔案或目錄（遞迴搜尋 *.html）：
python3 scripts/extract_seo_signals.py <路徑> --pretty
輸出為 JSON 文件，包含以下頂層鍵值：lang、title、meta、links、scripts、headings、images、links_audit、body_word_count。每個元素都附有 line 編號，用於在發現中引用。
若為目錄，輸出為 {"files": [<每檔案的物件>]}。
該腳本僅使用 Python 標準函式庫——不需要 pip install。如果特定檔案解析失敗，該檔案的結果會包含 error 欄位，稽核會繼續處理其餘檔案。
2. 將訊號對應到評分表
載入 references/seo-checklist.md。依序瀏覽每個章節，檢查對應的 JSON 路徑。評分表中明確列出了每個檢查項要檢視的路徑（例如 images.missing_alt、meta.description.length、scripts.render_blocking_candidates）。
對於每個失敗的檢查，記錄：
- 嚴重性（來自評分表的 P0/P1/P2/P3）。
- 從 JSON 輸出取得的行號。
- 檔案中確切的引用標記或屬性值（使用行號重新讀取檔案，逐字引用——切勿改寫）。
- 修復方式，當變更是機械性操作時，應寫出具體的 before/after 差異。
3. 在報告前驗證每個發現
在撰寫發現之前，以機械化方式確認問題：
- 聲稱某屬性「缺失」，必須來自解析器的結構化輸出，而不是掃視 HTML 後的猜測。
- 聲稱某值「太短/太長」，必須引用 JSON 中的實際字元數。
- 引用的標記必須完全精確；如果無法從檔案中逐字重現某個引用，就捨棄它。
這能防範最常見的審查失敗：編造實際上不存在的問題。
4. 產出發現報告
使用 assets/findings-template.md 作為結構。填入以下內容：
- 摘要段落，包含整體評語與嚴重性計數。
- 每個發現一個區塊，按嚴重性（P0 → P3）排序，再按檔案順序排列。
- 當發現數量超過約 10 個時，可選擇加入「快速修復」章節——挑選 3-5 個影響最大的修復。
- 「超出範圍的項目」章節，列出使用者應透過外部工具（例如 Lighthouse 取得真實 CWV，curl 確認 canonical 解析等）追蹤的事項。
如果稽核涵蓋多個檔案，請產出一份涵蓋所有檔案的報告，將發現按檔案分組並歸入每個嚴重性層級——而不是每個檔案一份報告。
5. 優雅地跳過
如果某個檢查需要解析器無法提供的資訊（例如「這個 canonical URL 是否回應 200 狀態碼？」），請勿猜測。在報告的「超出範圍的項目」章節中註明，然後繼續。
參考資料
scripts/extract_seo_signals.py— HTML 解析器。僅使用標準函式庫。輸出包含行號的結構化 JSON。references/seo-checklist.md— 完整評分表，按類別組織，包含每個檢查項的嚴重性層級與 JSON 路徑。assets/findings-template.md— 稽核報告的輸出格式。