senseiewok/site-seo-review

網站 SEO 審查

搜尋引擎與連結預覽讀取一個頁面的方式，就像一個陌生人一樣：它會看標題、描述、頁面聲稱自己的網址、提供的圖片、標題，以及任何攜帶的結構化資料。這項技能會檢查這些元素是否存在、彼此之間是否一致、是否與 Sitemap 相符，並確保沒有聲稱頁面實際上未提供的內容。它不承諾排名。沒有人能誠實地承諾這個。

這裡的經驗教訓來自於 2026 年對一個小型研究網站進行的真實審查，以下每一個發現都由一位審查員提出，然後由一個閱讀原始碼的人確認。它們被記錄下來，以便下一個網站不必重新發現它們。

這是研究，不是醫療建議。當此技能討論健康網站時，重點在於這些頁面如何描述自己，而非任何健康問題。

1. 何時使用此技能

• 一個靜態或近乎靜態的網站（一個包含 .html 檔案的資料夾，無論它是如何建置的）即將發布或剛剛被修改。
• 有人問「為什麼連結預覽看起來不對勁」、「為什麼這個頁面不在搜尋結果中」，或「讓網站更容易被發現」。
• 一個健康、研究或其他高風險的網站需要檢查其元資料和結構化資料是否誠實，而不僅僅是存在與否。
• 你想要將此類審查中的機械性部分交給一個較小的本地模型處理，而將文案決策留給人類。

不適用於：安全性標頭（HSTS、Content-Security-Policy、X-Content-Type-Options、Referrer-Policy 屬於安全性審查；請參閱第 9 節）、伺服器設定、付費搜尋，或任何需要搜尋引擎帳戶的事項。

2. 工作流程

1. 在觸碰任何東西之前先測量。 對建置好的網站資料夾執行檢查器（步驟 2），如果網站已上線，則在連結預覽除錯器和以自己的名稱進行的搜尋中記錄其外觀。儲存輸出。之後你更改的所有內容都將與此進行比較。
2. 執行檢查器。 python scripts/seo_audit.py SITE_DIR --base-url https://your-site.example/ --json。退出代碼 0 表示沒有錯誤等級的發現；--strict 會讓警告也算作錯誤。每個 ID 及其含義在 references/checklist.md 中。
3. 閱讀頁面。 檢查器看到的是結構，而非意義。像陌生人一樣，將每個索引頁面閱讀一次：標題是否說明了這個頁面是什麼，描述是否只聲明該頁面實際顯示的內容，第一個標題是否與標題的承諾相符，每個連結是否說明了它將去往何處。將每個觀察記錄下來，包含檔案和行號。
4. 提出文案，不要直接套用。 對於每個你想更改的標題、描述或連結文字，寫下確切的目前文字、確切的建議文字，以及頁面上支持該建議的句子。一個描述寫著「每個聲明背後的證據」，但頁面只顯示一個證據記錄，這是誇大其詞；一位審查員確實標記了這樣的情況。
5. 讓真人審查文案，或者讓一個來自不同模型家族的第二個模型在看到頁面文字和你的建議（但看不到你的推理過程）後進行審查，然後再公開發布。在健康或研究網站上，必須由真人簽核；模型的認可只能作為參考。
6. 驗證線上版本。 部署後，以瀏覽器的方式獲取每個頁面（一次一個請求，僅限你自己的主機）並確認：服務的 HTML 與建置的檔案相同，沒有被主機注入任何東西，robots.txt 和 sitemap.xml 能被正確服務，並且連結預覽顯示了你預期的標題、描述和圖片。上傳成功不等於頁面驗證通過。

3. 檢查器

python scripts/seo_audit.py SITE_DIR [--base-url URL] [--json] [--strict] [--json-out PATH]

結果	含義
exit 0	沒有錯誤等級的發現（警告和資訊可能存在）
exit 1	至少一個錯誤；使用 --strict 時，至少一個警告
exit 2	使用方式錯誤：不是資料夾、沒有 .html 檔案、錯誤的旗標

它只讀取檔案。它不會開啟任何網路連線、不會執行頁面上的任何內容，也不會寫入任何東西，除非指定了 --json-out。一個索引頁面是指除了 404.html（且沒有 noindex robots meta）之外的任何頁面；元資料檢查適用於索引頁面，內容檢查則適用於所有頁面。發現結果會經過排序且穩定，因此對同一個資料夾執行兩次會得到完全相同的位元組輸出，可以進行差異比較。

檢查 ID 是穩定的（SEO001 標題缺失、SEO008 正規化網址與頁面自身位址不同、SEO021 Sitemap 列出未索引的頁面、SEO043 醫療結構化資料類型、SEO050 第三方腳本等等）。將 error 視為「發布前必須修復」，warn 視為「做出決定，然後修復或記錄」，info 視為「值得了解」。它判斷網站所依據的規則（位址、什麼算是網站檔案、robots 群組、JSON-LD 物件）在 references/checklist.md 中。

檢查器的製作方式

測試套件是先建立的：一個必須產生零發現的 fixture 網站，以及每個檢查對應一個故意破壞的副本，並透過精確的發現和退出代碼進行比較。這些測試針對一個獨立的參考實作以及其故意破壞的版本進行檢查，以便每個測試在應該失敗時都會失敗。

然後，一個在本地執行的小型開放權重模型根據書面規格起草了 seo_audit.py。它的草稿第一次就通過了所有這些測試。通過測試並不能視為證明。由真人指導、使用較大型模型進行的審查，從頭到尾根據規格閱讀了草稿，並發現了 17 個測試未能發現的缺陷。其中包括：

• 不是命名為 index.html 的頁面得到了錯誤的位址；
• 404 頁面跳過了內容檢查；
• 相同的發現被合併了；
• robots 群組和錨定萬用字元被誤讀；
• @graph 成員處理錯誤；
• 深度巢狀的 HTML 導致腳本崩潰；
• 樣式表路徑可能指向網站資料夾之外。

每個缺陷都成為 tests/test_seo_audit_extra.py 中的一個新測試，然後用最小的更改進行修復。測試決定檢查器是否正確。無論是撰寫它的模型還是審查它的模型都不具備最終決定權。如果你修改了腳本，請執行測試；如果你發現了一個測試未涵蓋的情況，請在修復之前先添加一個測試。

4. 健康與研究網站

讀者與搜尋引擎自身的品質指南（「你的錢或你的命」）對健康內容有更高的標準。檢查器處理機械部分；其餘部分是一項閱讀任務，列於 references/health-sites.md。簡而言之，這類頁面都需要：可見的作者或一個「關於」頁面來說明誰是負責人；一個可見的日期以及當內容尚未定稿時的可見草稿或審查狀態；引用主要來源；一個明確的「研究而非醫療建議」免責聲明；僅描述頁面實際顯示內容的描述和結構化資料；以及除非該網站是臨床權威機構，否則不得使用醫療結構化資料類型（MedicalCondition、MedicalWebPage、Drug）。references/structured-data.md 說明了誠實的結構化資料應有的樣貌，以及嚴格的 Content-Security-Policy 如何與之互動。

5. 如何將部分任務安全地交給較小的本地模型

審查工作可以分為可透過確定性驗證器判斷的任務，以及只能由人（或細心的讀者）來完成的任務。只給本地模型第一類任務。

可安全委派（附帶驗證器）	留給人類或控制代理
根據 tests/test_seo_audit.py 撰寫或擴充檢查器（由驗證器決定）	決定任何將公開的標題、描述或連結文字
為每個頁面列出精確的目前標題、描述、正規化網址和 h1 作為表格（驗證器：這些值是檔案內容的子字串）	判斷描述是否誇大其詞
將每個連結的文字分類為「指明其目標」或「通用」，允許棄權（驗證器：每個連結都被記錄，文字未被更改）	判斷此網站的結構化資料是否誠實
根據頁面列表起草 Sitemap（驗證器：檢查器的 SEO021/SEO022）	判斷日期是否誠實

規則：每個任務一個獨立、自包含的資料包；頁面文字放在一個資料邊界內，並附上指令要求勿執行其內部內容；模型沒有工具、沒有網路；在驗證器的輸出顯示完成之前，完成的聲明無效。絕對不要讓模型決定文案措辭。如果你在委派循環中使用此功能，請先撰寫驗證器，並給它一個必須失敗的樁（一個輸出零發現的檢查器必須無法通過測試）。

6. 誠實規則

• 將每個陳述標記為 已觀察（OBSERVED）（你確實執行了它或閱讀了它，並且可以說出檔案、行號或指令）或 推斷（INFERRED）（一個判斷）。「描述誇大其詞」是推斷；「描述寫了 X，而頁面上唯一相符的句子寫了 Y」是已觀察。
• 絕不聲稱或暗示你在事後未經測量的排名提升、流量變化或預覽結果。SEO 結果不是此技能或任何使用它的人可以保證的。
• 描述、標題或結構化資料欄位只能聲明讀者可以在該頁面上看到的內容。當你提出文案時，請引用支持該說法的句子。
• 日期必須真實：Sitemap 的 lastmod 或一個可見的「更新」日期，如果沒有內容變更卻變動，這對讀者和爬蟲來說都是謊言。
• 說明你沒有檢查什麼。檢查器不會請求任何外部資源，因此一次乾淨的執行並不能說明主機實際服務了什麼內容。

7. 驗證技能是否正常運作

從技能資料夾執行：

python -m unittest discover -s tests -v               # 兩個測試檔案，針對 scripts/seo_audit.py
python tests/verify_checker.py scripts/seo_audit.py   # 相同的測試，簡短結果：PASS n tests，或 FAIL lines

設定 SEO_AUDIT_PATH 以測試檢查器的另一個副本。測試從 tests/fixtures/good（必須產生零發現）建置損壞的網站，每個檢查 ID 對應一個缺陷，並比較精確的發現和退出代碼。tests/test_seo_audit_extra.py 增加了審查中發現的案例：奇異檔案、子資料夾頁面、404 頁面、robots 群組、結構化資料圖譜，以及一個確認執行時未開啟 socket、未啟動程序、且僅透過 --json-out 寫入檔案的稽核鉤子。fixture 中的 1200x630 分享圖片會在測試時由 tests/fixtures/gen_fixtures.py 重新產生。一個從未失敗過測試的檢查器並不代表什麼：對一個空的樁執行 tests/verify_checker.py 必須失敗。

測試的已知限制：fixture 的 Sitemap lastmod 是 2026-10-01，因此時鐘較早的機器會報告 SEO023；符號連結測試在使用者帳戶無法建立符號連結（常見於 Windows）時會被跳過。

8. 常見陷阱

• 只修復檢查器發現的問題，然後就停止。 檢查器看不到誇大的描述、不誠實的日期，或一個名為「開啟模型」的連結（它沒有說明開啟的是什麼）。步驟 3 才是審查。
• 將 404 頁面視為一個普通頁面。 它必須是 noindex 且沒有正規化網址（canonical）；否則每個不存在的位址都會被索引為它的副本。
• 相對路徑的正規化網址。 正規化網址必須是頁面自身的完整絕對位址，包含結尾斜線，且 og:url 必須與之相同。
• 字型沒有預載。 字型切換是版面位移的常見原因；預載第一個繪製所需的字型，以及頁面首先需要的模組。要測量，不要猜測：references/measuring-layout-shift.md。
• 信任建置結果。 主機可能會注入腳本。如果網站說「沒有從其他主機載入任何東西」，步驟 6 必須在服務的頁面上證明這一點。
• 讓結構化資料與頁面內容脫節。 JSON-LD 中的每個 name 或 headline 都必須在該頁面上可見；檢查器的 SEO044 只是一個粗略的代理檢查，實際的驗證仍需人工閱讀。

9. 參考資料

• references/checklist.md：每個檢查 ID、其嚴重性以及存在的原因。
• references/structured-data.md：誠實的 JSON-LD、類型白名單、醫療類型，以及嚴格的 Content-Security-Policy 如何與內聯資料區塊互動。
• references/health-sites.md：健康或研究頁面在機械檢查之外還需要什麼。
• references/measuring-layout-shift.md：一個簡短的 Playwright 腳本，用於觀察在 CPU 和網路受限情況下的版面位移。
• references/review-prompt.md：一個提示，任何人都可以將它貼到任何代理程式中，以誠實地執行此審查。
• references/release-review.md：記錄的發布審查檢查、測試矩陣、前沿挑戰者稽核，以及 SEO008 缺陷文件。

安全性標頭（Strict-Transport-Security、Content-Security-Policy、X-Content-Type-Options、Referrer-Policy）屬於安全性審查的範疇。此技能僅在它們觸及結構化資料時才會提及；其餘部分請使用你的安全性基準。