教你的编程代理编写 WordPress Playground 蓝图 – DocsWP

新的 Blueprint 智能体技能 教会您的编码智能体 Playground Blueprint 架构，该架构定义了有效的属性名称、资源类型和步骤顺序。不再出现用 pluginZipFile 代替 pluginData 的情况。不再出现缺少 require '/wordpress/wp-load.php' 的 runPHP 步骤。

只需安装一次，您的智能体就能以很高的成功率生成有效的 Blueprint JSONJSON JSON（JavaScript 对象表示法）是一种简洁、可读的数据结构化格式。它主要用于在服务器和 Web 应用程序之间传输数据，是 XML 的替代方案。，而且最棒的是，整个过程可以使用自然语言。这非常适合测试新想法、发现插件和主题中的边界情况，以及从您的项目创建演示。

Blueprint 技能的功能

该技能是一份结构化的 Markdown 参考文档，您的编码智能体会将其加载到上下文中。它涵盖：

每个顶层属性：landingPage、preferredVersions、features、steps，以及简写形式（login、plugins、siteOptions、constants）
所有资源类型：wordpress.org/plugins、wordpress.org/themes、url、git:directory、literal:directory、bundled
步骤参考：installPlugin、writeFile、writeFiles、runPHP、wp-cli、runSql 等
常见错误：智能体在生成输出前会对照检查的错误列表
Blueprint 捆绑包：包含捆绑资源的自包含软件包

智能体会在编写 Blueprint 之前读取这份参考文档。它不再猜测属性名称，而是遵循文档化的架构。

如何安装该技能

如需快速安装，请使用 npx skills CLICLI 命令行界面。Mac 上的终端（Bash）、Windows 上的命令提示符，或用于 WordPress 的 WP-CLI。将 Blueprint 技能添加到您的项目中：

npx skills add wordpress/agent-skills --skill blueprint

或者，您也可以克隆 agent-skills 仓库并运行构建脚本来手动安装：

git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
node shared/scripts/skillpack-build.mjs --clean
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=claude,gemini,codex,cursor,vscode

该技能适用于 Claude Code、Gemini CLI、GitHubGitHub GitHub 是一个提供 Git 仓库在线实现的网站，其他开发者可以轻松共享、复制和修改这些仓库。公共仓库可免费托管，私有仓库则需要付费订阅。GitHub 引入了“拉取请求”概念，使贡献者在分支中完成的代码更改可以在合并到仓库所有者的代码库之前接受审查和讨论。 https://github.com/ Copilot、Cursor 和 Codex。

五个示例

下面的每个示例都展示了您提供给智能体的提示词以及它生成的 Blueprint。这些是真实场景，在这些场景中，Blueprint 技能可以避免常见错误。

1. 快速开发环境

提示词：

Create a Blueprint that sets up a development environment with
debug mode, the Developer plugin, and landing on the admin dashboard.

生成的 Blueprint：

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "features": { "networking": true },
  "constants": {
    "WP_DEBUG": true,
    "WP_DEBUG_LOG": true
  },
  "login": true,
  "plugins": ["developer"],
  "steps": []
}

请注意，智能体使用了 constants 简写，而不是 defineWpConfigConsts 步骤；同时使用 login: true，而不是单独的登录步骤。该技能教会智能体在简单情况下选择简写，在顺序很重要时使用明确的步骤。

WordPress Admin panel showing the Developer plugin enabled via blueprint

2. 来自 GitHub 分支的插件插件插件是一段包含一组函数的软件，可以添加到 WordPress 网站中。它们可以扩展功能或为您的 WordPress 网站添加新特性。WordPress 插件使用 PHP 编程语言编写，并能与 WordPress 无缝集成。其中一些插件可以在 WordPress.org 插件目录中免费获取 https://wordpress.org/plugins/，第三方插件则可能需要付费。

提示词：

Write a Blueprint that installs my plugin from the feature/checkout-v2
branch on GitHub and activates it.

生成的 Blueprint：

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/plugins.php",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [
    { "step": "login" },
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "git:directory",
        "url": "https://github.com/your-org/your-plugin",
        "ref": "feature/checkout-v2",
        "refType": "branch",
        "path": "/"
      },
      "options": { "activate": true }
    }
  ]
}

如果没有该技能，智能体通常会省略 refType，导致 git:directory 无法处理分支名称。技能中的常见错误表明确指出了这一点：“在使用分支或标签 ref 时省略 refType —— 该属性是必需的；只有 HEAD 可以在没有它的情况下工作。”

3. 包含示例产品的 WooCommerce 商店

提示词：

Create a Blueprint for a WooCommerce store with 5 sample products
across 2 categories, running on PHP 8.2.

生成的 Blueprint：

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/shop/",
  "preferredVersions": { "php": "8.2", "wp": "latest" },
  "features": { "networking": true },
  "steps": [
    { "step": "login" },
    {
      "step": "installPlugin",
      "pluginData": { "resource": "wordpress.org/plugins", "slug": "woocommerce" },
      "options": { "activate": true }
    },
    {
      "step": "runPHP",
      "code": "<?php\nrequire '/wordpress/wp-load.php';\n\n// Create categories\n$cat_clothing = wp_insert_term('Clothing', 'product_cat');\n$cat_accessories = wp_insert_term('Accessories', 'product_cat');\n\n$products = [\n  ['T-Shirt', 29.99, $cat_clothing['term_id']],\n  ['Hoodie', 59.99, $cat_clothing['term_id']],\n  ['Jeans', 49.99, $cat_clothing['term_id']],\n  ['Watch', 89.99, $cat_accessories['term_id']],\n  ['Backpack', 39.99, $cat_accessories['term_id']]\n];\n\nforeach ($products as [$title, $price, $cat_id]) {\n  $post_id = wp_insert_post([\n    'post_title' => $title,\n    'post_type' => 'product',\n    'post_status' => 'publish'\n  ]);\n  update_post_meta($post_id, '_regular_price', $price);\n  update_post_meta($post_id, '_price', $price);\n  wp_set_object_terms($post_id, [$cat_id], 'product_cat');\n}\n"
    }
  ]
}

该技能确保智能体在每个 runPHP 步骤的顶部加入 require '/wordpress/wp-load.php'。没有这一行，所有 WordPress 函数都会静默失败——如果没有技能参考，这是智能体经常犯的错误。

WordPress Playground Loading a store with 5 products in a woo store.

4. 用于自定义行为的内联 mu-plugin

提示词：

Write a Blueprint that disables the admin bar and adds a custom
dashboard widget showing the server's PHP version.

生成的 Blueprint：

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [
    { "step": "login" },
    {
      "step": "writeFile",
      "path": "/wordpress/wp-content/mu-plugins/custom-dashboard.php",
      "data": "<?php\nadd_filter('show_admin_bar', '__return_false');\n\nadd_action('wp_dashboard_setup', function() {\n  wp_add_dashboard_widget(\n    'php_version_widget',\n    'PHP Version',\n    function() {\n      echo '<p>Running PHP ' . phpversion() . '</p>';\n    }\n  );\n});"
    }
  ]
}

智能体使用 writeFile 创建 mu-plugin，它无需激活即可自动加载。该技能明确记录了这种模式，并警告智能体不要在 mu-plugin 代码中添加 require wp-load.php（该行仅在 runPHP 步骤中需要）。

5. 包含自定义插件的 Blueprint 捆绑包

提示词：

Create a Blueprint bundle that installs a custom analytics plugin
from a local zip file.

生成的捆绑包结构：

analytics-bundle/
├── blueprint.json
└── analytics-plugin.zip

blueprint.json：

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/plugins.php",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [
    { "step": "login" },
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "bundled",
        "path": "/analytics-plugin.zip"
      },
      "options": { "activate": true }
    }
  ]
}

在本地运行：

npx @wp-playground/cli server --blueprint=./analytics-bundle/ --blueprint-may-read-adjacent-files

目录捆绑包需要使用 --blueprint-may-read-adjacent-files 标志。没有该标志，任何 bundled 资源引用都会失败，并显示“找不到文件”错误。技能记录了这一注意事项，因此智能体会自动包含该标志。

Blueprint 技能如何与其他工具配合使用

Blueprint 技能可以与另外两个面向 AI 智能体的 Playground 工具配合使用：

工具	功能	使用场景
Blueprint 技能	生成有效的 Blueprint JSON	需要用于共享、版本控制或 CI 的 Blueprint 文件时
wp-playground 技能	运行 CLI 命令、管理服务器、调试实例	需要可实时交互的运行中 Playground 实例时
MCP 服务器	将智能体直接连接到浏览器中的 Playground	需要实时执行 PHPPHP PHP（PHP：超文本预处理器的递归缩写）是一种广泛使用的开源通用脚本语言，尤其适合 Web 开发，并且可以嵌入 HTML 中。 https://www.php.net/manual/en/index.php 和文件操作时

当您需要可移植、可复现的配置时，使用 Blueprint 技能。当您需要运行中的服务器时，使用 wp-playground 技能。将两者结合起来：使用 Blueprint 技能生成 Blueprint，然后使用 wp-playground 技能的 CLI 命令启动它。

测试您的 Blueprint

内联 URLURL Internet 上某个网站或网页的特定网址，例如网站的 URL www.wordpress.org（快速测试）

压缩 Blueprint JSON，并将其附加到 Playground URL 后：

https://playground.wordpress.net/#{"preferredVersions":{"php":"8.3","wp":"latest"},"steps":[{"step":"login"}]}

本地 CLI（完整测试）

# Start a server with your Blueprint
npx @wp-playground/cli server --blueprint=./blueprint.json

# Headless validation (runs and exits)
npx @wp-playground/cli run-blueprint --blueprint=./blueprint.json

开始使用

在您的项目中安装 Blueprint 技能：

npx skills add wordpress/agent-skills --skill blueprint

然后让您的智能体编写 Blueprint。描述您的需求：插件、主题、内容和配置，智能体就会生成首次运行即可成功的有效 JSON。

在 #playground 频道的 Making WordPress Slack 中分享您构建的内容，或在 GitHub 上提交问题。

#agent-skills、#ai