前言¶
在 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
