AlexMaghen/wp-dev

wp-dev：在本機開發 WordPress 正式網站

將 wpsync 以 ${CLAUDE_PLUGIN_ROOT}/bin/wpsync 執行（以下簡稱 wpsync）。開發者通常不是建置此網站的人，因此請用白話解釋每個步驟，並在需要他們操作時說明。

請先閱讀 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/guiding.md。 它說明了如何顯示進度（該階段步驟的檢查清單）、如何提問（每個決策和每個等待都使用問題對話框），以及在應用程式不提供這些功能時該怎麼做。下方的 詢問 行標明要使用的對話框。

原則： 在變更任何東西之前先檢查，並立即回報每個問題及其修正方式。每個步驟都可以安全地重複執行，因此中斷後開發者只需說「繼續我的 wp-dev 專案」，你就會從中斷處繼續。

在開始之前：wpsync 可以執行嗎？

wpsync 在 Bun 上執行，所以在尚未安裝 Bun 的 Mac 上，每個 wpsync 指令（包括 status、init 和 doctor）都會失敗並顯示「wpsync needs Bun」（退出碼 127）。請在任何 wpsync 指令之前先檢查：

1. 執行 ${CLAUDE_PLUGIN_ROOT}/bin/wpsync --version。如果它印出版本號，請繼續到「我們在哪裡？」。
2. 如果它說 wpsync 需要 Bun，請尋找 Homebrew：command -v brew || ls /opt/homebrew/bin/brew /usr/local/bin/brew。
   • 找到 Homebrew → brew install oven-sh/bun/bun（如果 brew 不在 PATH 中，請使用完整路徑），然後再次執行 wpsync --version。
   • 沒有 Homebrew → 需要開發者操作（會要求他們的 Mac 密碼）。說明 wpsync 和其他工具會透過 Homebrew 安裝，開啟一個已準備好來自 https://brew.sh 安裝指令的終端機分頁（請見 guiding.md），然後使用「完成，檢查它」對話框等待。接著讓 Homebrew 可用（請見步驟 2 中的「剛安裝完 Homebrew 之後」），並如上安裝 Bun。

如果 wpsync 可以執行，請不要提及它，直接繼續。只有在需要安裝 Bun 時，才用一句話告訴開發者這是第一個必要條件，並說明 wpsync doctor --local 會在步驟 2 中檢查其餘項目。

我們在哪裡？

在當前資料夾中執行 wpsync status --json，並根據其 phase 進行：

phase	執行
no-project	從步驟 1 開始階段 1（起始閘門）
start-gate（在較早的對話中建立的資料夾）	從步驟 2 開始階段 1
connect、pull	從步驟 2 開始階段 1（會跳過已完成的步驟）
work	階段 2：進行變更使用 wp-work 技能，重新整理使用 wp-pull，發佈上線使用 wp-publish
publish-pending	上一次發佈正在等待完成或復原：請見 wp-publish

無論處於哪個階段：如果 status 中有 wordfence 欄位，則此網站的 Wordfence 必須在 wpsync 處理期間關閉，並在之後重新開啟。請遵循 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md。

在階段 1 中，開始（或恢復時再次顯示）來自 guiding.md 的 設定檢查清單，並標記已完成的步驟，然後開始一個「設定」章節。

階段 1：設定本機副本

1. 起始閘門：正確的資料夾，然後是網址

對話的資料夾在開始時就固定了，所以開發者 應該在要放置本機副本的資料夾中開始對話。然後所有事情都只在這個對話中進行。

這個對話是在可用的資料夾中嗎？ 查看當前資料夾（ls -A）：

• 空的（或只有 .DS_Store 或 .claude）：這是網站的新資料夾。繼續下面的步驟。

• 其他任何東西（桌面、家目錄、另一個專案）：不要在此處設定。請傳送以下訊息並停止：

  要設定網站，請在您想要放置本機副本的資料夾中開始一個新的 Claude Code 對話：一個新的空資料夾，例如 ~/wp-sites/example.com。

  開始一個新對話，選擇（或建立）該資料夾，並將權限模式設為 繞過權限，如果您不希望批准每個步驟的話。（發佈到正式網站時仍會等待您在對話框中輸入其網域。）然後在該處說 「新 wp-dev 專案」。

在新的資料夾中， 用一句簡短的句子詢問正式網站的網址：

正式網站的網址是什麼？例如 https://example.com。

如果資料夾名稱包含網域（例如 example.com-local），請改為提供建議：「正式網站的網址是什麼？從資料夾名稱我猜是 https://example.com。」

然後在此處建立專案：wpsync init <site-url> --dir .。它會寫入該資料夾的 CLAUDE.md、.claude/settings.json（預先核准 ddev、git、brew 和唯讀的 wpsync 指令；發佈仍會詢問）和標記為待處理的 .wpsync.json。它不會聯絡任何外部服務。請直接繼續步驟 2。這些設定會從此資料夾的下一個對話開始生效；如果您不在繞過權限模式，這個對話在此期間可能會稍微頻繁地詢問。您無法偵測權限模式，也不需要。

2. 檢查這台 Mac

wpsync doctor --local 會一次列出所有項目。以 guiding.md 中的結果表格顯示。按以下順序安裝缺少的項目：

• 您可以執行： brew install ddev/ddev/ddev、brew install oven-sh/bun/bun，以及 Docker。 如果兩個 Docker 應用程式都沒有安裝，請詢問「我應該在這台 Mac 上安裝哪個 Docker 應用程式？」：OrbStack（推薦：在 Mac 上更輕量、更快，個人使用免費）或 Docker Desktop（標準版；個人和小型公司免費）。然後執行 brew install --cask orbstack 或 brew install --cask docker。 Docker 已安裝但「未執行」： 自行啟動（open -a OrbStack 或 open -a Docker），並等待最多一分鐘讓 docker info 成功。只有首次啟動（條款、密碼）需要開發者操作；如果一分鐘後 docker info 仍然失敗，則表示有首次啟動的對話框正在等待他們。
• 需要開發者操作（密碼或點擊，您從不替他們執行）：Xcode 命令列工具（xcode-select --install）、Homebrew（來自 https://brew.sh）、OrbStack 或 Docker Desktop 的首次啟動，以及 mkcert -install。開啟一個已準備好指令的終端機分頁（請見 guiding.md），並使用「完成，檢查它」對話框等待。當缺少多個項目時，請在一次訊息中全部列出，並只等待一次，而不是每個項目等待一次。

mkcert 是必需的（doctor 會將其回報為 FIX，直到設置完成）。本機副本的網址是 https://…ddev.site。如果沒有 mkcert -install，Chrome 會拒絕該網址，而透過純 http 載入頁面時，樣式和圖片會遺失（WordPress 會透過 https 連結它們）。這在步驟 7 中看起來會像一個損壞的副本。因此請在這裡、第一次下載之前，執行此操作：說明它會要求 Mac 的密碼，在終端機分頁中執行 mkcert -install，然後等待。如果是在 DDEV 啟動後才安裝（恢復較舊的設定），DDEV 仍在使用其不受信任的憑證：在網站資料夾中執行 ddev poweroff && ddev start，然後請他們重新載入頁面。

再次執行 wpsync doctor --local，直到沒有任何項目顯示 FIX。注意事項可以等等，但請說明它們的意義。

剛安裝完 Homebrew 之後： 在 Apple Silicon Mac 上，Homebrew 會安裝在 /opt/homebrew，安裝程式的「Next steps」中的幾行指令執行之前，它不會在 PATH 中。doctor 會回報為「已安裝在 /opt/homebrew/bin/brew，但尚未在 PATH 中」，並附上要加入到 ~/.zprofile 的那一行；永遠不要叫他們重新安裝。您自己的 shell 不會載入 ~/.zprofile，所以在這個對話中，請在指令前加上 eval "$(/opt/homebrew/bin/brew shellenv)" &&。

3. 檢查網站

wpsync doctor <site-url>（唯讀）。在連線之前，它會檢查網站是否為 WordPress、REST API 是否啟用，以及應用程式密碼是否開啟。（主機是否傳遞 Authorization 標頭只能用真實金鑰測試，所以這會在 wpsync 連線時檢查。）以結果表格顯示。在繼續之前修正或解釋每個 FIX；大多數是主機或安全外掛的設定，開發者必須詢問其他人：使用 guiding.md 中的「當檢查需要其他人協助時」對話框。

Wordfence： 如果它回報應用程式密碼「已關閉，極有可能是被 Wordfence 關閉」，請遵循 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md（「之前」）：開發者在 wp-admin 中關閉一個設定，然後您使用「完成，檢查它」對話框等待，直到 doctor 確認。您會在步驟 8 中提醒他們重新開啟。

4. 連線

wp-connect 技能。之後再次執行 wpsync doctor <site-url>：它現在還會檢查 Authorization 標頭、多站點、檔案權限、版本，以及這台 Mac 和伺服器上的磁碟空間。

（wpsync new <site-url> 會一次執行步驟 2 到 7，並在遇到第一個需要開發者操作的事項時停止；這對於恢復很方便。逐步執行（如這裡所示）則會在過程中提供更多說明。）

5. 下載

wp-pull 技能（第一次下載：wpsync pull <site-url> --dir .）。它會在 https://<project>.ddev.site 建立 DDEV 專案，這不需要修改 hosts 檔案。大型網站需要一些時間：請以長時間工作執行（guiding.md）。

6. 讓副本安全地執行

副本包含正式網站的資料庫：真實客戶的電子郵件、可能還有正式的金流或 API 金鑰、排程工作。DDEV 會攔截所有外寄郵件（可使用 ddev mailpit 查看），而 wpsync 會設定 WP_ENVIRONMENT_TYPE=local。檢視 CLAUDE.md 中的啟用中外掛。如果有任何外掛是金流、物流、CRM、電子報或 Webhook 外掛，請列出它們並 詢問「<網域> 本機副本上的這些外掛可能仍會與真實服務通訊。我們該怎麼做？」：帶我了解測試模式（推薦：您引導他們到本機 wp-admin 中每個外掛的測試或沙箱設定），或 維持原狀（他們接受本機副本可以連線到這些服務）。

如果啟用中的外掛沒有這類型的，請不要詢問：用一句話說明（指出任何只會寄送郵件的外掛，DDEV 會攔截它們），然後繼續。

7. 驗證

wpsync verify 會檢查頁面、wp-admin、永久連結、遺留的正式網址、圖片，以及外掛和佈景主題是否與正式網站相符。以結果表格顯示。

在調查失敗的頁面檢查之前，先用 curl 親自詢問該頁面一次：curl -s -o /dev/null -w '%{http_code}' <localUrl>/。如果它回應 200，則檢查很可能是在 DDEV 還在啟動時執行（它在 ddev start 後會短暫回應 502）：在深入檢查日誌之前，再執行一次 wpsync verify。

然後親自查看：在 Chrome（Claude 中的 Chrome）中並排開啟正式網站和本機副本，首頁和幾個內頁，並進行比較。不要在應用程式內建的瀏覽器面板中判斷副本：它會封鎖 *.ddev.site 頁面的樣式、腳本和圖片（ERR_BLOCKED_BY_CLIENT），因此即使完美的副本在那裡看起來也是壞的。如果 Chrome 不可用，請用 curl 檢查頁面，並請開發者查看。如果有您無法解釋的差異，請描述它並 詢問：現在修正它（推薦），或 沒關係，繼續。

本機登入：副本包含正式網站的使用者，因此開發者使用他們的正式密碼登入本機 wp-admin。

8. 交接

現在閱讀網站的 CLAUDE.md，以便從這裡開始套用其規則。

首先，如果此網站使用 Wordfence（wpsync status --json 顯示 "wordfence": "switched-off"）：設定不再需要正式網站，因此請遵循 ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md（「當 wpsync 完成時」），讓開發者重新開啟 Wordfence 的防護，等待，並用 wpsync status 確認。請在交接訊息之前執行此操作，這樣開發者的最後一步是開始工作，而不是另一個雜務。

然後在 Chrome 中開啟本機網站，並完成檢查清單。用粗體、獨佔一行，作為您訊息中的最後一件事（其後不要有任何內容；任何其他備註，例如登入說明，請放在前面）來結束設定：

網站的本地副本已準備就緒，網址為 https://{local site domain}。請檢查它，然後告訴我想開始進行哪些修改。

並將 https://{local site domain} 替換為 .wpsync.json 中的 localUrl。就在它之前，用一行說明登入：本機 wp-admin 接受他們的正式使用者名稱和密碼。