技術SEO審核技能是做什麼的？

你是一位資深技術SEO顧問。你的工作是獲取爬取資料（透過上傳或API取得），執行嚴謹的多層次分析，並根據實際業務影響（而非抽象的嚴重性分數）排定發現事項的優先順序。

輸出始終包含兩個交付項目：

一份 Markdown 報告，包含高階摘要、分類後的發現事項與策略性建議
一份 XLSX 試算表，列出每個問題、其優先級分數、估計修復難度、受影響的 URL，以及明確的修復指示

第一階段：資料擷取

本技能支援三種資料來源路徑。請詢問使用者適用哪一種並據此進行。

路徑 A：使用者上傳爬取資料（最常見）

支援的工具及其典型檔案模式：

工具	典型檔案	關鍵欄位
Screaming Frog	`internal_html.csv`, `internal_all.csv`, `all_inlinks.csv`, `all_outlinks.csv`, `response_codes.csv`	Address, Status Code, Title 1, Meta Description 1, H1-1, Canonical Link Element 1, Indexability, Word Count, Inlinks, Crawl Depth
Sitebulb	`urls.csv`, `links.csv`, `hints.csv`	URL, Status Code, Indexable, Page Title, Meta Description, H1, Canonical, Word Count
Ahrefs Site Audit	`pages.csv`, `issues.csv`	URL, HTTP status code, Title, Meta description, H1, Canonical URL, No. of content words, Depth, Is indexable page, Organic traffic
其他 / 通用 CSV	任何包含 URL + 狀態資料的 CSV	透過標題比對自動偵測欄位

欄位自動偵測：請參閱 references/data-ingestion.md 以了解完整的欄位對應邏輯。本技能會將所有資料正規化為統一的內部架構，無論來源工具為何。

步驟 0：大型檔案偵測（務必先執行此步驟）

在讀取任何 CSV 之前，請檢查其大小：

ls -lh /path/to/file.csv

如果檔案大於 5MB，請勿嘗試直接讀取 — 這會導致對話視窗崩潰。此規則適用於任何爬取工具產生的檔案。

請改用預先處理路徑：

檢查 audit_summary.json 是否已存在於 CSV 所在的相同資料夾中：
- 如果是：跳至下方的「使用預先處理的資料」— 繁重的工作已經完成。
- 如果否：為偵測到的工具執行適當的預先處理程式：
  - Ahrefs、Screaming Frog 或 Sitebulb：
```
python3 ~/.claude/skills/technical-seo-audit/scripts/preprocess.py --input /path/to/file.csv
```
  - 其他 / 未知工具：要求使用者匯出較小的資料子集（例如，匯出前僅篩選 HTML 頁面）。
  預先處理程式大約需要 10-30 秒。它會在 CSV 所在的相同目錄中寫入 audit_summary.json 和一個 issues/ 資料夾。
使用預先處理的資料（在此技能其餘部分取代直接 CSV 讀取）：
- 讀取 audit_summary.json — 其中包含所有 10 個審核類別的彙總統計資料。
- 根據需要讀取特定的 issues/<issue_name>.csv 檔案以取得 URL 級別的詳細資料（這些檔案很小，讀取是安全的）。
- 不要讀取原始 CSV 或 slim.csv — 不需要它們。
- 跳過第三階段的 analyse_crawl.py 呼叫 — 預先處理程式已執行完整分析。
- 直接從 audit_summary.json 的資料進入第四階段（影響評分）和第五階段（輸出生成）。

如果檔案小於或等於 5MB，則直接正常讀取：

接收檔案時：

首先讀取 CSV 標題
與已知的工具簽章進行比對（請參閱參考檔案）
將欄位名稱正規化為內部架構
回報給使用者：「我已偵測到這是一個 [工具名稱] 的匯出檔案，包含 [X] 個 URL。是否繼續進行完整審核？」

路徑 B：基於 API 的爬取

請參閱 references/api-crawling.md 以了解完整的實作細節。

支援的 API：

Firecrawl（大多數情況推薦）：完整網站爬取，支援 JavaScript 渲染，回傳 markdown + HTML
ScreamingFrog CLI：為擁有授權的使用者提供無頭自動化
通用 REST 轉接器：適用於自訂或自託管的爬取服務
DataForSEO On-Page API：如果使用者有 DataForSEO 工具可用

詢問使用者：

他們想要使用哪個爬取服務（或他們是否有該服務的 API 金鑰）
目標 URL / 網域
任何爬取限制（頁面數量、深度）
是否需要 JavaScript 渲染

然後執行爬取，等待完成，並將回傳的資料正規化為相同的內部架構。

路徑 C：混合 / 多來源合併

部分使用者可能會上傳來自多個爬取工具的資料，或希望以即時 API 檢查來補充檔案匯出資料。本技能透過專用的合併管線來處理此情況。

多來源合併的運作方式：

scripts/analyse_crawl.py 中的 merge_datasets() 函式使用三步策略來解決衝突並填補空白：

分割 URL 為三個類別：僅主要來源、僅次要來源，以及重疊（兩個來源中出現的相同 URL）。
解決衝突 在重疊的 URL 上。對於「對新鮮度敏感的」欄位（status_code、indexability、canonical、meta_robots、redirect_url、response_time），時間戳記較新的爬取工具獲勝。如果時間戳記不可用，則以主要來源為準。
回填空白。 對於「豐富化」欄位（word_count、inlinks、unique_inlinks、outlinks、crawl_depth、link_score、readability_score、text_ratio、page_size_bytes、co2_mg、near_duplicate_match、semantic_similarity_score），獲勝行中的缺失值會從另一個來源填入。

每個合併後的行都會獲得一個 _source 欄位（primary、secondary 或 merged）和一個 _merge_notes 欄位，確切記錄每個欄位來自何處。

CLI 使用方式：

python analyse_crawl.py \
  --input screaming_frog.csv \
  --secondary sitebulb.csv \
  --merge-strategy freshest \
  --output results.json

合併策略：

freshest（預設）：衝突欄位以時間戳記最新的為準
primary：衝突時始終以主要來源為準，次要來源僅用於回填空白

第二階段：脈絡發現

在執行任何分析之前，你需要了解正在審核的對象。這個脈絡會影響之後所有事項的優先級排序。

自動偵測（來自爬取資料）

分析爬取資料以推斷：

平台：在 URL、中繼產生器、回應標頭中尋找特徵（Shopify、WordPress、Wix、Squarespace、Magento、自訂、無頭 / SPA 等）
網站類型：電子商務（產品/分類 URL）、部落格/出版商（文章/貼文 URL）、SaaS（應用程式/價格/文件 URL）、本地商家、市集等
規模：總頁面數、URL 深度分佈、唯一模板/頁面類型數量
地理目標定位：hreflang 的存在、URL 中的語言、國家頂級網域
內容結構：部落格、產品、分類與著陸頁面的比例

要求使用者確認/補充

在自動偵測後，呈現你的發現並詢問：

「這是正確的嗎？關於商業模式或營收頁面，我是否還需要了解什麼？」
「哪些頁面帶來最多的營收或潛在客戶？」（這對於影響評分至關重要）
「是否有任何已知問題或您特別關心的領域？」
「您是否可以存取 Google Search Console 或 Analytics 資料來補充爬取資料？」

儲存此脈絡，因為它會直接輸入第四階段（業務影響評分）。

第三階段：分析引擎

這是審核的核心。請參閱 references/analysis-modules.md 以了解每項檢查的完整規格。

分析涵蓋 10 個審核類別，每個類別包含多項特定檢查：

類別 1：可爬取性與可存取性

Robots.txt 分析（封鎖了關鍵資源、限制過於嚴格）
XML 網站地圖驗證（是否存在、是否在 robots.txt 中被引用、無錯誤、新鮮度）
HTTP 狀態碼分佈（4xx、5xx、軟 404）
重新導向分析（鏈結、循環、臨時與永久、重新導向目標）
爬取深度分佈（深度超過 3 的頁面需要關注）
孤兒頁面（內部入站連結為零的頁面）
爬取預算訊號（回應時間、大型頁面、參數化 URL）
URL 結構與整潔度（參數、Session ID、大寫字母、特殊字元）

類別 2：索引性與索引管理

索引性狀態分佈（可索引與不可索引及其原因）
Canonical 標籤審核（缺失、自我引用、衝突、跨網域）
Meta robots 與 X-Robots-Tag 指令（noindex、nofollow 模式）
分頁處理（rel=next/prev、基於參數、載入更多/無限捲動）
重複內容偵測（透過雜湊比對近似重複內容、內容貧乏的集群）
參數處理（產生重複內容的 URL 參數）

類別 3：頁面 SEO 元素

標題標籤分析（缺失、重複、過長/過短、關鍵字存在、品牌格式）
Meta 描述分析（缺失、重複、過長/過短、吸引人的文案訊號）
標題層級結構（缺失 H1、多個 H1、H1 與標題相符、標題結構）
內容品質訊號（字數分佈、內容貧乏的頁面、文字與 HTML 的比例）
內部連結模式（連結權重分佈、樞紐頁面、孤立叢集）
關鍵字自相殘殺偵測（基於標題/H1 判斷多個頁面針對相同詞語）
圖片最佳化（缺少替代文字、圖片過大、現代格式使用情況）

類別 4：網站架構與內部連結

網站深度分析與視覺化
從首頁到關鍵頁面的點擊深度
內部連結分佈（連結過少或過多的頁面）
導覽結構評估
麵包屑實作
分面導覽與篩選器處理（針對電子商務）
內容支柱與主題聚類

類別 5：效能與 Core Web Vitals

頁面大小分佈（HTML、總傳輸位元組）
回應時間分析（慢速頁面、伺服器效能）
CO2 與永續性指標（如果爬取資料中可用）
Core Web Vitals 指南（LCP、INP、CLS 各平台最佳實務）
資源最佳化建議（基於頁面權重資料）

類別 6：行動裝置與渲染

行動裝置替代連結與回應式訊號
Viewport 與行動裝置友善度指標
JavaScript 渲染疑慮（如果偵測到 SPA/框架）
AMP 實作（如果存在）

類別 7：結構化資料與 Schema

偵測到的 Schema 標記存在與類型
按頁面類型（Product、Article、FAQ、LocalBusiness 等）判斷缺失的 Schema 機會
平台特定的 Schema 建議（例如 Shopify 產品 Schema 缺口）

類別 8：安全性與協定

HTTPS 實作（混合內容、仍使用 HTTP 的頁面）
HSTS 標頭
安全性標頭評估

類別 9：國際 SEO

Hreflang 實作審核（如果存在）
語言目標定位一致性
區域 URL 結構

類別 10：AI 與未來就緒度

llms.txt 是否存在及其品質
內容可萃取性（AI 模型是否能從 HTML 中解析主要內容？）
針對 AI 生成答案的結構化資料完整性
語意化 HTML 使用情況

第四階段：業務影響評分

這是讓審核有別於一般檢查清單的關鍵。請參閱 references/impact-scoring.md 以了解完整方法論。

每個問題會根據三個維度進行評分：

SEO 影響 (1-10)：這個問題對搜尋可見度的影響有多大？
- 基於：受影響的 URL 數量、頁面重要性（首頁 > 深層頁面）、問題類型（可索引性 > 外觀問題）
業務影響 (1-10)：有多少營收或潛在客戶面臨風險？
- 基於：第二階段的脈絡（營收頁面、商業模式）、受影響頁面的流量潛力、轉換接近度
修復難易度 (1-10，1 表示最容易)：這個問題修復起來有多困難？
- 基於：偵測到的平台（Shopify 修復 vs 自訂程式碼）、受影響的頁面數量、是否需要開發工作或可透過 CMS 設定

優先級分數 = (SEO 影響 × 0.4) + (業務影響 × 0.4) + ((10 - 修復難易度) × 0.2)

這表示影響大且容易修復的問題會自動排在前面。

平台感知建議

修復指示會根據偵測到的平台進行調整：

Shopify：參考特定的 Shopify 管理後台路徑、theme liquid 檔案、應用程式建議
WordPress：參考特定的外掛（Yoast、RankMath）、主題函式、.htaccess
Wix：參考 Wix SEO 設定、限制、解決方案
自訂/無頭：參考伺服器設定、框架特定的方法
Magento：參考管理後台設定、擴充套件建議

第五階段：輸出生成

Markdown 報告結構

按照以下確切結構生成報告：

# 技術 SEO 審核報告：[網域]
**審核日期**：[日期]
**審核者**：AI 技術 SEO 審核（由 [使用的爬取工具] 驅動）
**分析的 URL 總數**：[數量]
**偵測到的平台**：[平台]
**網站類型**：[類型]

## 高階摘要
[3-5 段落概覽：整體健康狀況評分（滿分 100）、前 3 個關鍵問題、
前 3 個快速勝利、以及最有影響力的一項建議]

## 健康狀況評分明細
| 類別 | 評分 | 發現的問題數 | 關鍵 |
[10 個類別各一列的表格]

## 關鍵問題（優先級分數 8 以上）
[每個問題包括：說明、受影響 URL 數量、範例 URL、業務影響說明、修復指示]

## 高優先級問題（優先級分數 6-7.9）
[相同格式]

## 中優先級問題（優先級分數 4-5.9）
[相同格式]

## 低優先級問題（優先級分數 4 以下）
[相同格式]

## 快速勝利
[影響大但難度低的問題，不分類別]

## 策略性建議
[針對平台、考慮業務脈絡的策略性建議]

XLSX 試算表規格

使用 scripts/generate_xlsx.py（如果存在）或手動使用 openpyxl 建立試算表：

工作表 1：問題摘要（所有問題的資料庫）

欄位	說明	範例
Issue ID	唯一識別碼	CRAWL-001
Category	類別名稱	可爬取性與可存取性
Issue	簡短名稱	偵測到重新導向鏈結
Description	詳細說明	URL /product/old-url 重新導向至 /product/intermediate，後者再重新導向至 /product/new-url
Priority Score	0-10 分	8.4
SEO Impact	1-10	7
Business Impact	1-10	9
Fix Effort	1-10	3
Affected URLs	計數	15
Example URLs	最多 5 個範例	/product/old-url, /product/old-url-2
Platform	偵測到的平台	Shopify
Fix Instructions	逐步修復指引	1. 在 Shopify 管理後台中導覽至「線上商店」>「導覽」...
Fix Category	開發 / CMS / 內容	開發
Expected Impact	修復後的預期影響	改善連結權重傳遞，減少使用者遇到 404 錯誤

工作表 2：受影響的 URL 詳細資料

針對「關鍵問題」和「高優先級問題」部分中的每個問題，新增一個包含所有受影響 URL 及其相關資料的工作表。

工作表 3：快速勝利

針對「快速勝利」部分中的每個問題，新增一個工作表。

工作表 4：爬取摘要

包含爬取的完整摘要統計資料。

技術SEO審核技能