前言¶
在 WordPress 插件、主題或 Blueprint 相關任務裏，你常常需要「先起一個能跑的站點」再驗證改動。本地可以裝完整棧，也可以走 WordPress Playground：瀏覽器裏或 CLI 裏用 WebAssembly 跑 WordPress，底層是 SQLite，實例可隨時丟棄。Playground 能力多——本地 @wp-playground/cli、playground.wordpress.net 分享鏈接、快照、掛載本地代碼、切換版本、Xdebug 等——若讓 AI 助手憑印象選路徑，容易混用 Blueprint 編寫與運行時、或把「僅瀏覽器」和「要讀本地磁盤」的需求搞錯。
下面介紹 WordPress 官方 Agent Skills 倉庫中的 wp-playground：它不是 Playground 的百科全書，而是一層路由封裝，先判斷你要哪種工作流，再只加載對應的 reference 或姊妹 skill，避免重複和誤路由。
這是什麼¶
wp-playground 出自 WordPress/agent-skills，維護方與 WordPress 生態一致。Skill 自述爲 thin routing wrapper：在用戶意圖模糊、或任務橫跨多種 Playground 能力時，按固定流程分流，而不是在一份文檔裏堆滿 Blueprint schema 與 CLI 細節。
與 blueprint skill 的分工很明確：Blueprint JSON 的編寫、審閱、schema、steps、resources、bundles 等，應直接使用 blueprint skill；wp-playground 負責運行時、CLI、調試、分享鏈接等 Playground 工作流的路由與指引。
官方目錄地址：skills/wp-playground。
兼容性（Skill 元數據）：
- WordPress 7.0+，PHP 7.4.0+
- Playground CLI 需要 Node.js 20.18+；WordPress 在 WebAssembly 中運行，數據庫爲 SQLite
核心功能¶
以下能力均來自 Skill 說明與路由表，按工作流歸類。
意圖識別與路由¶
Agent 按用戶意圖選擇後續文檔，原則上一次只加載與當前任務相關的 reference；若請求包含多個獨立部分，可加載多於一份。
- 判斷屬於哪類：Blueprint 編寫/審閱、本地 CLI、僅瀏覽器/分享鏈接、Xdebug 或卡住的 CLI、或混合請求。
- 路由到下方對應來源；混合任務時，Blueprint 部分交給
blueprint，再回到 wp-playground 處理運行時、CLI、調試或分享。 - 勿在 wp-playground 內重複 Blueprint schema 細節。
| 意圖 | 去向 |
|---|---|
| Blueprint JSON、schema、steps、resources、bundles 或 Blueprint 審閱 | 使用 blueprint skill |
本地 CLI：@wp-playground/cli 服務、run-blueprint、build-snapshot、掛載、版本切換、本地校驗 |
references/cli.md |
| Xdebug 或卡住的 CLI | references/debugging.md |
| 僅瀏覽器：Query API、Blueprint URL、分享鏈接、瀏覽器限制；現有站點操作可經 WebMCP、Playground MCP、Sites API | references/website.md（按所選連接方式只加載對應 reference；未指定連接方式時，對支持的瀏覽器操作優先可用 WebMCP 工具） |
Skill 描述中還提到：WebMCP site tools、snapshots、mounts、version switching、Xdebug，以及 playground.wordpress.net 分享鏈接與瀏覽器預覽，均落在上述路由所指向的 reference 中展開。
Agent 需要事先弄清的信息¶
- 工作流類型：Blueprint 編寫、本地 CLI、網站/分享鏈接、快照或調試。
- 若需掛載或打包本地代碼：項目或 bundle 路徑。
- 若版本敏感：目標 WordPress / PHP 版本。
- 本地服務：端口偏好。
- 是否必須瀏覽器分享，還是必須訪問本地文件系統。
校驗與常見失敗模式¶
校驗：
- Blueprint 內容：對照已發佈 schema，並遵循
blueprintskill 的 verification。 - 本地 CLI：在 Playground 實例中確認掛載的插件/主題或 Blueprint 副作用。
- 分享鏈接：打開生成的 URL，確認落地頁與預期資源加載。
失敗模式（Skill 明確要求糾正路由）：
- Blueprint 相關工作誤進 wp-playground → 改用 blueprint skill。
- 僅瀏覽器流程卻需要本地文件系統 → 改走 CLI（
references/cli.md）；playground.wordpress.net不能讀本地路徑。 - 從本地 CLI 流程卻要可分享的瀏覽器鏈接 → 改看
references/website.md；本地 server URL 不是可移植的分享鏈接。 - 調試被當作「二級跳轉」含糊處理 → 直接讀
references/debugging.md。
升級路徑： 若任務需要 PHP 擴展、原生數據庫、持久化或接近生產的設施，Playground 無法滿足時，Skill 建議改用完整 WordPress 棧，例如 wp-env、Docker 或項目自帶環境。
安裝與啓用¶
最快方式使用官方倉庫推薦的 npx skills（與 agent-skills README 一致）。
僅安裝 wp-playground：
npx skills add WordPress/agent-skills --skill wp-playground
查看倉庫內全部 skill：
npx skills add WordPress/agent-skills --list
一次安裝多個 skill（示例含 wp-playground）：
npx skills add WordPress/agent-skills --skill wp-plugin-development wp-abilities-api wp-playground
作用域： 默認會詢問安裝到項目（如 .cursor/skills/、.claude/skills/），可納入版本庫供團隊共用。全局安裝加 -g / --global，例如：
npx skills add WordPress/agent-skills --skill wp-playground --global
Cursor 全局： 在 clone 並 build agent-skills 後，可用官方腳本安裝到 ~/.cursor/skills/：
node shared/scripts/skillpack-install.mjs --targets=cursor-global
（完整 clone、build、按 target 安裝到 Codex / VS Code / Claude / Cursor 等路徑的步驟見 WordPress/agent-skills 的 Quick Start。）
本地 CLI 相關操作前，Skill 要求確認 Node.js 20.18+ 以及 npm / npx 可用。
典型用法（Agent 側流程）¶
wp-playground 不替代你手寫 Playground 命令，而是規定 Agent 先路由、再讀深文。可復現的協作方式如下。
- 向助手描述目標（例如「用 Blueprint 起本地站並掛載當前插件」「生成 playground.wordpress.net 分享鏈接」「CLI 卡住要查 Xdebug」）。
- 助手加載 wp-playground，按 Procedure 歸類意圖。
- 若涉及 Blueprint JSON → 切換或並行使用 blueprint skill。
- 若爲本地執行 → 按
references/cli.md使用@wp-playground/cli（如 server、run-blueprint、build-snapshot等，以 reference 爲準）。 - 若爲純瀏覽器 → 按
references/website.md配置 Query API / Blueprint URL；需要分享時驗證 URL 可打開且資源正確。 - 若爲調試 → 直接遵循
references/debugging.md（Xdebug、運行時日誌、worker 標誌等）。
混合請求示例：先讓 blueprint 完成 JSON 編寫與 schema 校驗，再回到 wp-playground 指引本地 run-blueprint 或瀏覽器分享，避免在同一輪對話裏混用兩套權威說明。
適用場景與注意¶
適合誰
- 使用 Cursor、Claude Code、Codex、Copilot 等支持 Agent Skills 的開發者，經常在 WordPress 任務裏臨時起 Playground 環境。
- 團隊已安裝 WordPress/agent-skills，希望 Playground 相關提問不被 AI 猜錯工作流。
約束（Guardrails）
- Playground 實例可丟棄，基於 SQLite；不要指向生產數據。
- 僅瀏覽器 Playground 無法讀取本地文件系統路徑；需用公開 URL、託管 ZIP bundle 或內聯 Blueprint JSON，或改用本地 CLI 掛載。
- Blueprint 的單一事實來源保持在 blueprint skill，不要在 wp-playground 裏複製 schema 示例。
WordPress 官方說明：這些 skill 由文檔與 Gutenberg/WordPress 資料生成後經貢獻者審閱，屬 v1，會持續迭代；詳見倉庫 docs/ai-authorship.md。
結尾¶
wp-playground 的價值在於把 Playground 的多條入口收成可執行的路由：Blueprint 歸 blueprint，CLI / 瀏覽器 / 調試各讀對應 reference，並寫明校驗與失敗時的糾正方式。若你已在用 Agent 做 WordPress 開發，把它與 blueprint、wp-env 等 skill 一起裝上，可以減少「起環境」這一步的來回試錯。
官方 Skill 目錄：https://github.com/WordPress/agent-skills/tree/trunk/skills/wp-playground
