轉換網站
協調器。它只會發送一次問題訊息，然後依序執行所有其他技能，不再停頓，最後以一個 Pull Request（由合併者處理）和一份操作手冊（啟動者使用）結束。
黃金法則
- 一次輸入訊息，之後不再停頓。 每個問題都附有預設值。若後續需要帳號、登入或您沒有的權杖，則會將其列入「need you」清單（
state.needsYou和docs/LAUNCH.md的 A 節），工作流程繼續進行。 - 原始站點僅供讀取。 只有以下腳本以節奏讀取它：擷取腳本、
shoot.mjs、原始站點上的styles.mjs、css-coverage.mjs、launch-audit --old-url和pre-launch --predecessor-url。原始頁面載入時會封鎖分析，因此不會產生訪問次數。切勿在原始站點上提交表單、登入或手動抓取網頁來填補資訊缺口。 - 預設建置等於原始站點，包括缺陷。 內容從擷取的標記中移動，絕不重新輸入或整理。每個異常都是一個決策行，表示「預設情況下重現原始站點」。強制性的差異是異常；改進是提案（僅在
PROPOSALS=on時使用）。 - 每個提交都需通過閘道，絕不寬鬆。 切勿編輯
baseline/以通過閘道（只能使用baseline/scripts.json中的keep標記）。跳過不等於通過；「未涵蓋」永遠不等於通過。 main分支只包含支架提交，別無其他。 在一個新的空儲存庫中，init-site會在main分支上建立一個提交，這與「絕不提交到 main」的規則例外：Pull Request 需要一個基礎。之後的所有工作都在astro-rebuild分支上，一個 Pull Request。絕不強制推送、絕不合併、絕不觸碰 DNS、舊主機或儀表板設定。- 聊天記錄或儲存庫中不應包含密碼。 切勿要求使用者貼上權杖。憑證來自環境變數或 CLI 自身的登入流程。
以下使用的名稱
KIT 是此工具包的絕對路徑（包含 skills/ 和 package.json 的資料夾）。
LIVE 是原始網站的源頭。
SITE 是新網站儲存庫的絕對路徑（預設為 <當前資料夾>/<Slug>）；擷取內容和執行狀態從一開始就寫入其中，而 init-site.mjs 則會圍繞它們建立支架。從 SITE 執行所有指令。每個腳本都會顯示 --help；請執行該指令，而非閱讀原始碼。每個在新 shell 中執行的 Node 指令都以 source ~/.nvm/nvm.sh && nvm use 22.23.4 開頭（或在讀取 .nvmrc 的 shell 中執行）。
步驟 0a：一個可以執行的工具包
這些腳本從工具包的 node_modules 匯入 parse5、playwright 等套件。如果 $KIT/package.json 或 $KIT/node_modules 遺失（表示安裝時只複製了技能資料夾，兩者皆無），請複製工具包並安裝它，然後將複製的版本用作 KIT：
git clone https://github.com/ethanplusai/astro-conversion-kit <資料夾>/astro-conversion-kit
npm install --prefix <資料夾>/astro-conversion-kit
步驟 0：預檢與指紋辨識（在輸入訊息之前）
node $KIT/skills/convert-site/scripts/preflight.mjs --json
node $KIT/skills/capture-site/scripts/fingerprint.mjs $LIVE
安裝缺失但您可以自行安裝的項目，無需詢問：當 playwright.chromium 為 false 時，執行 npx playwright install chromium；vercel 和 wrangler 透過 npx 執行。已安裝但未登入的 CLI 需要由使用者自行登入：在輸入訊息中指定指令名稱（gh auth login、npx vercel login、npx wrangler login），並在支架階段再次檢查。
experience 決定您說話的方式，而非您做什麼。new：每個階段用一句簡單的句子說明它做什麼和為什麼，每個術語解釋一次，安裝過程靜默進行。some：每個階段一行。experienced：僅顯示指令和結果。Shopify 的指紋是一個商店：停止並告知。
步驟 1：輸入（唯一的一次訊息）
發送 references/intake.md 的模板，填入預檢和指紋辨識找到的內容：每個問題及其預設值，以及「遺漏了什麼以及會發生什麼」的清單。如果使用者不回覆，則使用預設值。切勿發送第二次問題訊息。
各階段
順序如 docs/process.md 所示；references/phases.md 包含每個指令及其驗證方式。在每個邊界執行 node $KIT/skills/convert-site/scripts/state.mjs --dir $SITE phase <名稱>；在前一個階段的驗證成立之前，不要開始新階段。state.mjs 的呼叫應一次一個，切勿使用 && 鏈接：每個呼叫都會改寫 state.json，鏈接中途失敗會使其不同步。
| # | 階段 (<名稱>) | 發生什麼事 | 完成條件 |
|---|---|---|---|
| 1 | intake | 預檢、指紋辨識、唯一的一次訊息 | 已回覆，或使用預設值 |
| 2 | capture | capture-site 到 $SITE/capture/，CSS 涵蓋率 | 每個 URL 都已儲存或記錄其狀態；備註已寫入 |
| 3 | plan | 決定託管方式、URL 形式、媒體模式、模板；決策記錄在狀態中；草稿在 .conversion/ 下 | 每個模板、計數、異常和超出範圍的功能都有一個決策 |
| 4 | scaffold | 儲存庫，圍繞擷取內容的 init-site.mjs，然後是 docs/plan.md 和 docs/media-plan.json | 建置成功但頁面為空；main 分支包含唯一的支架提交 |
| 5 | baseline | npm run baseline（templates.json 已存在） | build-baseline.mjs --check 退出碼為 0 |
| 6 | build | 佈局和共享部分，每個模板一個頁面，鎖定模板設計，然後是每個頁面 | npm run build 通過；模板閘道逐一路徑通過 |
| 7 | gates | 完整閘道 | npm run verify 退出碼為 0 |
| 8 | visual | 每個模板在 390、768、1440 解析度下；每個頁面在 390 和 1440 解析度下 | 每一對都通過 |
| 9 | components | 可選，預設關閉（references/components-optional.md） | 閘道和差異仍然通過，一個獨立的提交 |
| 10 | prelaunch | pre-launch、暫存部署、verify-live、launch-audit、一次測試提交 | prelaunch-reconcile.mjs 退出碼為 0（references/phases.md §10）；稽核查阻擋項目已修正或列出 |
| 11 | suggestions | suggest-improvements 與 gates.json 和 review/ | docs/suggestions.md 及其「From the review」章節 |
| 12 | pr | 操作手冊、推送、PR、最終報告 | PR 引用閘道輸出和每個「未涵蓋」章節 |
| 13 | 啟動 | 由使用者從 docs/LAUNCH.md 執行 | post-launch 檢查切換並監控 30 天 |
各個階段使用的技能及其各自的規則：capture-site（2）、parity-gates（5 到 7）、visual-review（6、8）、pre-launch 和 launch-audit（10）、suggest-improvements（11）、post-launch（在操作手冊中）。在其階段開始前閱讀每個技能的 SKILL.md。
建置，用一段話說明
references/build-rules.md 具有約束力。佈局以及共享的頁首、導覽和頁尾始終是元件；內容區塊是擷取到的標記，由腳本移動。媒體保留其原始路徑，字型自行託管，CSS 透過涵蓋率修剪（css-coverage.mjs 後接 css-prune.mjs），絕不重寫。表單遵循 references/forms.md，第三方腳本遵循 references/third-party.md。redirects.csv 是唯一的重新導向來源：新的重新導向是一個行，其 source 為 decision 且 note 命名決策 id，然後執行 npm run redirects:build；絕不手動編輯生成的規則。每個模板一個提交（feat: <模板> template，在其路徑範圍的閘道通過後），絕不為整個建置做一個提交。在展開到每個頁面之前，模板的設計會被鎖定（視覺審查）。使用子代理時，每個模板或閘道修復有一個實作者，絕不兩個處理同一個檔案；每個任務簡報攜帶絕對路徑和 build-rules.md，您在下一個階段之前審查他們的提交。
決策、異常、提案
本節是規則；參考資料連結到此處。
- 決策。 任何原始站點表現異常的地方，以及您套用的每個預設值，都會得到
state.mjs decision '{"topic":…,"choice":…,"default":…,"reason":…,"costIfWrong":…}'，它會列印其 id（d1、d2……）。唯一的總帳是docs/plan.md中的決策表格：id、日期、主題、選擇、預設值、原因、錯誤成本。在支架之前，決策存在於.conversion/state.json中；在init-site之後，計劃表格會立即從它們寫入。預設始終是「重現原始站點」。 - 異常（
exceptions.json，{ path, field, from, to, reason, approvedBy, date }）：靜態建置無法避免的差異；對於該路徑上的該欄位，閘道會用to取代from。approvedBy是"default, <decision id>"，直到使用者在 PR 中簽核。表單和腳本不是異常欄位（它們有自己的標記）。routes是：擷取無法讀取的路由：from是其狀態字串，to是"skip"或建置後的取代路徑。 - 提案（
proposals.json，形狀相同加上id、決策 id 和approvedBy: "proposed"；多個記錄可能共享一個 id）：一種改進。程式碼使用proposalOn(id)切換它；它僅在PROPOSALS=on的建置中發布，由npm run verify:proposals進行閘控。沒有閘道衡量的變更（改寫的 href）是field: "markup"，從不比較。當使用者批准時，記錄會移動到exceptions.json（approvedBy）。
託管
預設為 Vercel，應要求使用 Cloudflare Pages：references/hosting-vercel.md 和 references/hosting-cloudflare.md。每個頁面都帶有 noindex，除非生產建置設定了 PUBLIC_INDEXABLE=true。媒體可以是 repo、store（media-upload.mjs）或 live-temporary（僅限暫存；在 DNS 切換前消失），由 media-plan.mjs 決定（references/phases.md §3）。
計劃後的一次訊息
在第 3 階段之後，發送一條簡短的狀態訊息（不是問題）：平台、頁面和模板計數、媒體決策、超出範圍的功能和選項、預設採取的決策，以及到目前為止的「need you」清單。在非互動式執行中也是必需的（有既定答案，無人回覆）：進度行不能取代它。然後繼續進行，無需等待。
Pull Request（第 12 階段）
推送 astro-rebuild 分支（main 分支已在支架階段推送），然後執行 gh pr create --base main --head astro-rebuild --title "Astro rebuild of <主機>" --body-file .conversion/pr-body.md。當 pre-launch 因 placeholders.form-id 失敗（尚無表單 id）時，加入 --draft，最終報告會將其列為阻擋項目。如果沒有 gh 登入，正文會留在該檔案中，而「推送並開啟 PR」則會加入「need you」清單。正文順序如下：
## What changed 一段話：平台、轉換了什麼、主機、媒體模式
## Counts 頁面、模板、重新導向、媒體檔案和大小、表單、保留/移除的供應商
## Exceptions applied 每個 exceptions.json 條目：路徑、欄位、原因、決策 id
## Proposals open 每個 proposals.json id：路徑、內容、原因（僅在 PROPOSALS=on 時發布）
## Decisions docs/plan.md 的決策表格，以及每個非預設的選擇
## Gate output `npm run verify` 的輸出，逐字，在程式碼區塊中，包含每個跳過行；
然後 prelaunch-reconcile 接受的每一行，標示為 "reproduced from live (dN)"
## Visual review `npm run review:check` 的輸出，每個 docs/visual-overrides.json 條目
（路由、id、閾值、原因），每個 bannerClosed 和 heightMismatch；聯絡表單是
review/index.html 和 review/all.html（本地；npm run review:sheet）
## Staging 暫存 URL、verify-live 結果、launch-audit 的阻擋項目及其狀態
## Suggestions 按類別統計的計數、中風險和高風險項目、可套用的 id
## Not covered pre-launch 和 launch-audit 的「未涵蓋」章節，逐字，每個
在其自己的標題下；然後是 capture-site、visual-review 和 suggestions 的
## Waiting on you 每個 state.needsYou 項目，按操作手冊順序
最終報告（給使用者）
以 PR 連結開頭（如果是草稿，則附上「draft: waiting on the form id」），然後是：轉換了什麼（計數）、閘道和視覺審查各一行、暫存 URL、「need you」清單，從 state.mjs --dir $SITE get needsYou 讀取（每個項目附上確切的指令或點擊，按操作手冊順序），然後是每個「未涵蓋」章節的逐字內容。說「PR open, waiting on your merge」，絕不說「done」或「live」。停止您啟動的任何審查伺服器（npm run review:serve -- --stop，如果您使用了預覽，則加上 npx astro preview stop），然後停止。
恢復執行
在新工作階段中，讀取 node $KIT/skills/convert-site/scripts/state.mjs --dir $SITE get 並從 phase 繼續：首先重新執行該階段的驗證；如果成立，則開始下一個階段。擷取使用 --resume 恢復。絕不重複輸入訊息。稍後套用建議是 convert-site --apply <id>（references/apply-suggestion.md），絕不是執行流程本身的一部分。
參考資料
| 檔案 | 涵蓋範圍 |
|---|---|
references/intake.md | 唯一的一次訊息：問題、預設值、遺漏了什麼以及會發生什麼 |
references/phases.md | 每個階段：確切的指令、完成的驗證、要記錄的內容 |
references/build-rules.md | 如何建置佈局、內容、CSS、媒體、字型、延遲載入圖片和重新導向 |
references/forms.md | Formspree 連線、欄位名稱、蜜罐、感謝頁面、表單 id、一次測試提交 |
references/third-party.md | baseline/scripts.json 和 docs/third-party.md 中的 keep 允許清單 |
references/hosting-vercel.md | 專案、公開的 noindex 暫存、索引、Blob 媒體、選擇性保護 |
references/hosting-cloudflare.md | Pages 專案、_redirects、_headers、R2 媒體函數、查詢重新導向 |
references/runbook.md | docs/LAUNCH.md：A 需要您，B 結案，C 啟動日，D 30 天監控 |
references/components-optional.md | 可選的元件傳遞 |
references/apply-suggestion.md | --apply <id>：提案記錄、分支提交、閘道、表單 |