علِّم وكيل البرمجة لديك كتابة مخططات WordPress Playground

تُعلِّم مهارة وكيل المخططات الجديدة وكيلَ البرمجة لديك مخطط Playground Blueprint، الذي يحدد أسماء الخصائص وأنواع الموارد وتسلسل الخطوات الصالحة. لا مزيد من استخدام pluginZipFile بدلًا من pluginData. ولا مزيد من خطوات runPHP التي تفتقد require '/wordpress/wp-load.php'.

ثبّتها مرة واحدة، وسيُنشئ وكيلك ملفات Blueprint JSON صالحة بمعدل نجاح مرتفع، والأفضل من ذلك كله أنه سيفعل ذلك باستخدام اللغة الطبيعية. وهذا مثالي لاختبار الأفكار الجديدة، والعثور على الحالات الطرفية في إضافاتك وقوالبك، وإنشاء عروض توضيحية من مشاريعك.

ما الذي تفعله مهارة 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 واجهة سطر الأوامر. الطرفية (Bash) في نظام Mac، أو موجه الأوامر في Windows، أو WP-CLI في WordPress. لإضافة مهارة 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 مفهوم «طلب السحب» (pull request)، حيث يمكن مراجعة تغييرات التعليمات البرمجية التي يجريها المساهمون في الفروع ومناقشتها قبل دمجها من قِبل مالك المستودع. 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 بدلًا من خطوة تسجيل دخول منفصلة. وتعلّم المهارة الوكلاء اختيار الاختصارات للحالات البسيطة والخطوات الصريحة عندما يكون الترتيب مهمًا.

2. إضافةإضافة الإضافة هي قطعة برمجية تحتوي على مجموعة من الوظائف التي يمكن إضافتها إلى موقع WordPress. ويمكنها توسيع الوظائف أو إضافة ميزات جديدة إلى مواقع WordPress الخاصة بك. تُكتب إضافات WordPress بلغة PHP البرمجية وتتكامل بسلاسة مع WordPress. وقد تكون مجانية في دليل إضافات WordPress.org https://wordpress.org/plugins/ أو إضافات مدفوعة من جهة خارجية. من فرع GitHub

الطلب:

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 مع أسماء الفروع. ويشير جدول الأخطاء الشائعة في المهارة إلى ذلك صراحةً: «إغفال refType مع ref للفرع/الوسم — مطلوب؛ لا يعمل 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"
    }
  ]
}

تضمن المهارة أن يدرج الوكيل require '/wordpress/wp-load.php' في بداية كل خطوة runPHP. ومن دون هذا السطر، تفشل جميع وظائف WordPress بصمت — وهو خطأ ترتكبه الوكلاء كثيرًا عند غياب مرجع المهارة.

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، الذي يُحمَّل تلقائيًا من دون تفعيل. وتوثق المهارة هذا النمط صراحةً، وتحذر الوكلاء من إضافة require wp-load.php داخل كود mu-plugin (فهذا السطر مطلوب فقط في خطوات 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 إلى جانب أداتين أخريين من Playground لوكلاء الذكاء الاصطناعي:

الأداة	ما الذي تفعله	متى تُستخدم
مهارة Blueprint	تنشئ ملفات Blueprint JSON صالحة	عندما تحتاج إلى ملف Blueprint للمشاركة أو للتحكم في الإصدارات أو للتكامل المستمر
مهارة wp-playground	تشغّل أوامر CLI، وتدير الخوادم، وتصحح أخطاء المثيلات	عندما تحتاج إلى مثيلة Playground قيد التشغيل مع تفاعل مباشر
خادم MCP	يربط الوكلاء مباشرةً بـ Playground في المتصفح	عندما تحتاج إلى تنفيذ PHPPHP PHP (اختصار تكراري لـ PHP: Hypertext Preprocessor) هي لغة برمجة نصية عامة مفتوحة المصدر واسعة الاستخدام، وتناسب تطوير الويب خصوصًا، ويمكن تضمينها في HTML. https://www.php.net/manual/en/index.php ومعالجة الملفات في الوقت الفعلي

استخدم مهارة Blueprint عندما تريد إعدادًا قابلًا للنقل وإعادة الإنتاج. واستخدم مهارة wp-playground عندما تحتاج إلى خادم قيد التشغيل. ادمجهما معًا: أنشئ Blueprint باستخدام مهارة Blueprint، ثم شغّله باستخدام أوامر CLI الخاصة بمهارة wp-playground.

اختبر ملفات Blueprint الخاصة بك

رابط URLURL عنوان ويب محدد لموقع إلكتروني أو صفحة ويب على الإنترنت، مثل عنوان URL لموقع www.wordpress.org مضمّن (اختبار سريع)

صغّر ملف Blueprint JSON وألحقه بعنوان URL الخاص بـ Playground:

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