審查靜態網站
目標
在使用者進一步編輯、發佈或將靜態網站視為完成之前,對其輸出進行驗證。
此技能是針對所生成 HTML/CSS/JS 網站的品質把關。它不選擇主題、重現參考、遷移內容或部署網站。它驗證生成的資料夾是否表現得像一個真正的靜態網站。
核心檢查項目:
- 原始檔案為有效的 UTF-8 且人類可讀。
- 本地連結、腳本、樣式表、圖片及其他資源皆可解析。
- 網站本地連結和資源預設使用相對於頁面的路徑,而非根絕對路徑(如
/assets/style.css)。 - 除非使用者明確接受僅限伺服器的行為,否則輸出應可透過
index.html直接開啟進行手動預覽。 - 生成的頁面涵蓋預期的頁面類型。
- 網站能在真實瀏覽器中透過本地 HTTP 渲染。
- 桌面和行動裝置佈局皆可使用。
- 回報或修復主控台錯誤、中斷的互動、殘留的佔位符以及複製來的來源特定文字。
合約
輸入:
- 靜態網站根目錄,例如
site/、dist/、out/、public/、docs/或儲存庫根目錄。 - 可選的預期頁面範圍、本地預覽 URL、
EDITING.md、參考 URL/截圖以及禁止的來源特定字串。
輸出:
- 按嚴重性排序的發現結果,或當驗證是建置/修復任務的一部分時的修復內容。
- 靜態審計結果、檢查過的瀏覽器頁面/視口以及任何已更改的檔案。
- 針對發佈或移交就緒狀態的明確通過/失敗狀態。
邊界:
- 不要選擇主題、重建網站、遷移內容、個人化身份或進行部署。
- 不要在驗證期間重新設計網站,除非視覺問題阻礙了可用性且使用者要求修復。
- 除非有意使用
--allow-root-absolute且已說明限制,否則不要認可根絕對路徑的本地網站路徑。
成功閘道:
- 無剩餘的封鎖性問題:主要導覽中斷、缺少必需的頁面類型、無法讀取的原始編碼、本地資源失敗、主控台當機、行動裝置無法使用或意外的根絕對路徑問題。
- 警告已被修復、記錄或由使用者接受。
若閘道失敗:
- 當驗證是建置的一部分時,修復簡單的本地問題。
- 將較大的失敗導向
make-personal-site、copy-website-style、personalize-site、add-blog-posts或edit-site-part,取決於失敗的表面。 - 重新執行確定性審計和受影響的瀏覽器檢查。
使用時機
在下列情況後使用此技能:
make-personal-site建立或重新設計了原創的靜態個人網站。copy-website-style將目標網站的風格重現為靜態檔案。- 使用者指向一個現有的靜態輸出資料夾,詢問它是否足夠好。
- 使用者在發佈前要求檢查、驗證、QA、審查、審計或測試靜態網站。
如果使用者提供了一個框架原始碼專案,請盡可能驗證已建置的靜態輸出資料夾。除非使用者明確要求,否則不要在此引入框架建置工作流程。
輸入
使用任何可用的輸入:
- 靜態網站根目錄,例如
site/、dist/、out/或public/。 - 本地預覽 URL(若伺服器已在執行中)。
- 預期頁面範圍:僅首頁、完整個人網站、部落格、作品集、筆記、連結、風格重現等。
EDITING.md、頁面地圖或由其他技能產生的任何移交備註。- 參考 URL 或截圖(當驗證風格重現時)。
- 已知不得殘留的字串,例如原作者姓名、網域、電子郵件、分析 ID 或舊的佔位文字。
若網站根目錄不明確,檢查附近的資料夾,並選擇包含 index.html 和靜態資源的資料夾。
工作流程
- 識別靜態網站根目錄和預期頁面範圍。
- 讀取
EDITING.md或從 HTML 檔案和導覽連結推斷頁面地圖。 - 執行確定性檔案審計腳本。
- 啟動或重複使用靜態根目錄的本地 HTTP 伺服器。
- 在真實瀏覽器中以桌面和行動裝置寬度驗證網站。
- 為每種生成的頁面類型開啟至少一個代表性頁面。
- 測試核心互動,例如導覽、主題切換、搜尋/篩選、複製按鈕、行動選單和分頁。
- 檢查瀏覽器主控台錯誤和遺失的網路資源。
- 審計相對路徑相容性、佔位符、UTF-8 可讀性以及來源特定的殘留文字。
- 當使用者要求驗證作為建置的一部分時,修復直接的缺陷;否則先報告發現結果。
確定性檔案審計
在瀏覽器驗證之前使用捆綁腳本:
python scripts/static_site_check.py <site-root>
對於風格重現或複製網站的清理,傳遞禁止的來源特定字串:
python scripts/static_site_check.py <site-root> --forbid "original-author" --forbid "original-domain.com"
腳本檢查:
- HTML、CSS、JS、JSON、Markdown、SVG、XML 和文字檔案的 UTF-8 解碼。
- 可疑的亂碼和替換字元。
- HTML 檔案中缺少
<meta charset="utf-8">。 - 中斷的本地
href、src、srcset、poster、action和data-src引用。 - 根絕對路徑的網站本地引用,例如
/assets/...、/posts/...、/data/...或/images/...,除非明確允許。 - CSS
url(...)資源引用,包括遺失或根絕對路徑的本地 URL。 - HTML、JavaScript 和 JSON 資料中常見的根絕對路徑網站本地字串。
- 逃逸網站根目錄的連結。
- 常見的佔位字串。
- 使用
--forbid提供的禁止字串。 - 隱私敏感的部署根目錄檔案,例如
.env、私鑰、憑證檔案、本地服務帳戶工件。 - 原始碼中類似秘密的賦值、已知令牌模式、私鑰區塊和本地絕對檔案系統路徑。
- 不應發佈的臨時、日誌、備份和作業系統工件。
- HTML 頁面計數和推斷的頁面類型。
- 是否存在
EDITING.md。
檔案審計仍應驗證供應商檔案的 UTF-8 可讀性,但不應將第三方縮小供應商套件中類似佔位符的單詞視為網站佔位內容。
將腳本錯誤視為封鎖性問題,除非使用者只想要快速探索性審查。將警告視為需要手動檢查的項目。
如果網站是特意設計為在自訂網域根目錄下需要根相對路徑,請使用 --allow-root-absolute 執行腳本,並說明不保證直接 file:// 開啟和 GitHub 專案子路徑部署。除非使用者明確接受該權衡,否則不要對生成的純靜態個人網站使用此例外。
路徑相容性
生成的純靜態網站應能在三種常見情境中運作:
- 直接從檔案系統開啟
index.html以進行快速手動預覽。 - 透過本地 HTTP 提供資料夾服務,以進行瀏覽器自動化和主控台/網路檢查。
- 部署到可能從網域根目錄或子路徑提供服務的靜態主機。
預設規則:
- 對網站本地連結和資源使用相對於頁面的路徑。
- 從根頁面,使用
assets/style.css、posts/example.html和about.html。 - 從巢狀頁面,根據情況使用
../assets/style.css、../blog.html和同層級的相對連結。 - 預設不要為內部導覽使用
/assets/style.css、/posts/example.html、/data/posts.json、/images/foo.png或/。
同時檢查 JavaScript 生成的連結、搜尋結果、標籤篩選器、複製按鈕、動態卡片、RSS/sitemap 引用、圖片封面、CSS url(...) 值、favicon、字型和 KaTeX/數學供應商資源。僅靜態 HTML 屬性為相對路徑是不夠的,如果 JavaScript 後來插入了根絕對路徑的話。
根絕對路徑僅在使用者明確希望進行僅限伺服器根目錄的部署時才可接受,例如自訂網域根目錄,並且了解直接檔案開啟和 GitHub 專案 Pages 子路徑可能會中斷。
瀏覽器驗證
在最終交付前使用真實瀏覽器。透過 HTTP 而非 file:// 提供本地檔案服務:
python -m http.server 8000
然後開啟:
http://127.0.0.1:8000/
使用實際可用的互動式瀏覽器工具作為本地 HTTP 目標的首選驗證路徑。「可用」意味著該工具在當前回合的可呼叫工具清單中公開,而不僅僅在技能、外掛程式清單或系統描述中提到。在 Codex 中,這可能是瀏覽器/應用程式內瀏覽器外掛程式(當使用者或用戶端已將其路由到該回合時);在其他代理程式中,它可能是等效的可見瀏覽器、瀏覽器使用工具或 devtools 支援的瀏覽器。它應開啟本地 URL、檢查桌面/行動裝置視口、執行互動並檢查可見的主控台/網路問題。
如果在當前回合中沒有公開的互動式瀏覽器工具,請不要假裝瀏覽器階段已執行。如果驗證依賴於它,請要求使用者使用其用戶端的路由方法啟用或叫用瀏覽器工具;對於 Codex,這可能意味著發送一個明確提及 @browser 的請求。如果使用者未重新路由或用戶端沒有此類工具,則回退到 Playwright、截圖、靜態審計或 shell 檢查,並說明這是回退方案,而非完整的互動式瀏覽器驗證。
當互動式瀏覽器工具實際可呼叫時,不要預設使用 Playwright、僅無頭模式的截圖腳本、shell 開啟的瀏覽器視窗或靜態截圖生成。截圖是有用的證據,但不能取代互動式瀏覽器階段。僅在沒有互動式瀏覽器工具可呼叫、使用者明確要求 Playwright,或特別需要可重複的腳本回歸測試時,才使用 Playwright 作為回退方案。
僅在任務需要使用者的 Chrome 設定檔、現有分頁、擴充功能、已驗證的遠端頁面或 Chrome 特定行為時,才使用 Chrome 自動化。不要依賴 Chrome 擴充功能自動化來處理 file:// 頁面;請改用本地 HTTP。
即使自動化應使用本地 HTTP,生成的原始碼仍應透過使用相對路徑並避免僅限伺服器的核心內容假設,來維持直接開啟的相容性。如果應用程式/瀏覽器允許快速的 file:// 基本檢查,請直接開啟根 index.html 並驗證 CSS、圖片、導覽和代表性子頁面是否未中斷。如果檔案自動化不可用,請依賴確定性根絕對路徑審計,並說明直接開啟是手動還是自動檢查的。
瀏覽器檢查:
- 桌面首屏:構圖、間距、排版、可見導覽和明顯的溢位。
- 行動裝置首屏:導覽行為、文字換行、內容優先級和水平溢位。
- 內部導覽:所有主要導覽連結皆能渲染。
- 頁面類型覆蓋率:每種生成的頁面類型至少進行一次瀏覽器階段或截圖。
- 互動覆蓋率:主題切換、選單、篩選器、搜尋、複製按鈕、分頁、手風琴、標籤頁、懸停/點擊狀態或其他可見控制項。
- 主控台狀態:無明顯的 JavaScript 錯誤。
- 網路狀態:無遺失的本地 CSS、JS、圖片或字型資源。
- 可存取性基礎:互動控制項的焦點可見性、可讀的對比度、有意義的頁面標題以及實務上非空的圖片替代文字。
對於小型網站,點選每個生成的頁面。對於較大的網站,抽樣檢查每種頁面類型以及 EDITING.md 中提到的任何路由。
頁面類型覆蓋率
從檔案名稱、路由、可見導覽和 EDITING.md 推斷頁面類型。
典型的頁面類型:
- 首頁。
- 關於或個人檔案。
- 部落格、歸檔、分類、標籤、筆記或列表頁面。
- 文章或詳細頁面。
- 專案、作品集、出版物或工作頁面。
- 連結、朋友、資源、現在、用途、花園、搜尋、主題/設定或其他特殊頁面。
如果生成的網站聲稱是部落格但沒有文章/詳細頁面,請回報。如果導覽指向不存在的子頁面,請將其回報為封鎖性問題。
編碼與原始碼可讀性
瀏覽器截圖是不夠的。原始檔案必須能被未來的模型和人讀取。
要求:
- HTML 檔案包含
<meta charset="utf-8">。 - 非 ASCII 文字以 UTF-8 儲存。
- HTML、CSS 註解、JavaScript 字串、JSON/資料檔案、SVG 文字和
EDITING.md在原始碼形式下可讀。 - 無亂碼、替換字元或意外的瀏覽器編碼恢復。
如果終端機顯示亂碼但瀏覽器看起來正確,請在使用 UTF-8 感知的讀取確認後再判定為損壞。如果檔案內容本身包含亂碼,請從乾淨文字重寫受影響的字串,而不是疊加另一層編碼轉換。
佔位符與殘留物審計
檢查生成的網站是否仍包含:
TODO、FIXME、lorem ipsum、placeholder、replace me、your name、example.com或範例/演示文字。- 假電子郵件、虛假的社交連結、空按鈕或無效的行動呼籲。
- 在風格重現中原網站的作者姓名、網域、文章標題、電子郵件、分析 ID、社交連結、朋友連結或私人 URL。
如果使用者仍然需要它們作為有意的可編輯標記,請不要盲目移除佔位符。清楚回報它們,或僅在使用者提供真實內容時才替換它們。
隱私與本地殘留物
在發佈前將以下內容視為封鎖性問題:
- 可部署根目錄內的
.env、.npmrc、.pypirc、私鑰檔案、憑證 JSON 檔案、服務帳戶檔案或密碼儲存庫/匯出檔案。 - HTML、CSS、JavaScript、JSON、Markdown、SVG 或文字檔案中的類似秘密賦值、存取令牌、私鑰區塊或 API 金鑰。
- 生成原始碼中的本地絕對檔案系統路徑,例如 Windows 磁碟機路徑、
file:///...、/Users/...、/home/...或/mnt/...。
將日誌、備份、臨時檔案和作業系統元資料視為警告,除非它們暴露了私人內容。在打包或發佈前,將其從可部署輸出中移除。
修復政策
當使用者要求「檢查」、「審查」或「告訴我什麼有問題」時,首先報告發現結果,並避免大規模編輯。
當驗證是建置或修復任務的一部分時,可以修復簡單的本地問題:修復遺失的 <meta charset>、修正明顯的斷裂資源路徑、移除明顯的佔位符文字(如果使用者已提供替代內容)、移除部署根目錄中的隱私敏感工件以及更正簡單的編碼問題。
在修復之前,對於不確定的更改應與使用者溝通意見,特別是關於佔位符內容、可能故意使用的路徑以及邊際編碼情況。
不要在驗證期間重新設計或重組網站。如果發現無法透過簡單的本地修復解決的主要設計問題,請告知使用者,建議適當的技能(make-personal-site、copy-website-style 等),並在沒有這些技能或使用者另有指示時用可用工具進行補救。