Dennis · 27 يوليو 2026
Blockstudio 7.6
Blockstudio يجعل الإصدار 7.6 المشروع قابلًا للقراءة والعرض من PHP، وينقل الإعدادات الافتراضية لواجهة الإنتاج الأمامية إلى blockstudio.json: مخزون API، وعرض مستقل، ومساعدات قوالب للوسائط وTailwind، وملفات تعريف الأداء، ومجلد تخزين مؤقت واحد، وإعادة عرض ثابتة مع تقديم مبكر، وإعدادات تحليل أكثر صرامة، وأدوات مشروع مُنشأة لوكلاء البرمجة.
يتولى استدعاءان معظم مهام الإصدار. يعيد Canvas::inventory() كل صفحة وكتلة ونمط وقالب لمحرر الموقع وجزء قالب ومثال UI مجمّع يسجله المشروع. ويعيد Render::document() محتوى HTML جاهزًا لأي منها، مع الأصول المستخدمة في عرضه فقط.
تحديث 7.6.2: لم تعد الصفحات المعتمدة على الملفات تُطابق أثناء طلبات WordPress العادية. شغّل
wp bs pages syncأو استدعِBlockstudio\Pages::reconcile()عند تطبيق تغييرات المصدر. تستخدم توجيهات المجموعات وإعداداتtemplateForالافتراضية إعدادات بيئة التشغيل المحفوظة، وتتجنب المطابقة الصريحة استعلام OR-meta الكبير متعدد اللغات السابق. أُزيل الخيار قصير الأمدthemeDefaults.syncPagesInDevelopmentلأن مزامنة الصفحات لم تعد تعمل من خطافات الطلب. أصبحتPages::init()مخصصة للإعداد الأولي فقط؛ وعلى عمليات التكامل التي مررتforceاستخدامPages::reconcile()أو CLI. وما زال فتح Canvas يجري مطابقة صريحة واحدة ومصادقًا عليها لمخزون التأليف.
تحديث 7.6.12: تُسبق أوراق أنماط المحرر الآن بتمرير إعادة كتابة واحد بدلًا من تجميع SASS لكل أصل، لذا لم يعد إنشاء المحرر البارد على موقع يضم كتلًا كثيرة معرضًا لاستنفاد حدّ ذاكرة متواضع. تُعاد معالجة الصفحة المعاد إنشاؤها مسبقًا والمخزنة مؤقتًا إذا أُزيلت ورقة أنماط Tailwind ذات تجزئة المحتوى، بدلًا من عرضها بلا أنماط، وذلك عبر ذاكرة التخزين المؤقت PHP والإضافة المبسطة Early Serve. وتُقرأ سمات الكتل المكتوبة في المستوى الأعلى عند العرض بدلًا من إسقاطها، لذا يُحترم المخطط Blockstudio المسجل على
WP_Block_Typeبواسطة أدوات الكتابة البرمجية.
تحديث 7.6.11: يستبدل تثبيت عناصر الرسم البياني الآن مستند المسار ذريًا عندما تتغير نسخة المتجر تحت المفتاح نفسه، ويُبقي المستندات المتطابقة كما هي، ويُبلغ عن المسارات التي رُقّيت واستُبدلت وتُخطيت وأُبقيت عبر
Static_Prerender_Early_Serve::last_promotion().
تحديث 7.6.10: تكشف إصابات ذاكرة التخزين المؤقت لوقت التشغيل الآن الأصول المجمّعة المحذوفة حتى أثناء مهلة إزالة الارتداد للمراقبة، وتُعزل ذاكرات التخزين المؤقت المسطحة السابقة للإصدار 7.6 ذريًا وتحذف على دفعات محدودة عبر cron. تُصدر العناصر العامة المضمّنة UI مرة واحدة لكل صفحة. ويمكن لـ Early Serve في وضع الرسم البياني تقديم المسارات المعروضة مباشرة خارج خريطة المسارات المنشورة من ذاكرة الهوية. ويمكن لـ Tailwind اختياريًا إصدار ملف ذاكرة التخزين المؤقت ذي تجزئة المحتوى باستخدام
tailwind.output: "link"؛ ويظل الإخراج المضمّن هو الافتراضي.
باختصار:
- جرد المشروع: يعرض
Canvas::inventory()كل سجل مسجل مع مصادره وترتيب عرض ثابت. - التحديد المستهدف: يؤدي تحديد الكتل والصفحات إلى حصر الاستكشاف والمزامنة والعرض والتجميع في تلك السجلات.
- العرض المستقل: يعرض
Blockstudio\Renderناتج HTML مكتملًا لكتلة أو تركيب أو مستند كامل. - عائلات مكونات UI: يجمع
Blockstudio\Uiالمكتبة المضمّنة في عائلة عامة واحدة لكل مكوّن، مع مثال لكل منها. - أبعاد صور ثابتة: يعرض
bs_media_image()أصول القالب بأبعاد حقيقية منassets/media.jsonمُنشأ. - مساعدات أصناف Tailwind: يركّب
bs_tw_merge()وbs_tw_variants()الأصناف في PHP مع دمج يراعي التعارضات. - ملفات تعريف الأداء: يفعّل
performance.profileإعدادات الواجهة الأمامية للإنتاج دفعة واحدة؛ وتتجاوز القيم الفرعية إعدادات الملف. - الوصول إلى الإعدادات ذات الأنواع: يقرأ
Settings::get_bool()وما يماثلهblockstudio.jsonبأنواع فعلية ويُظهر أخطاء التحليل. - مجلد واحد لذاكرة التخزين المؤقت: يوجد كل ملف مُنشأ تحت
cache.path، مع ربطه بهوية وقت التشغيل. - العرض المسبق الثابت: يمكن تخزين HTML المجهول مؤقتًا وإبطاله عبر رسم بياني للتبعيات وتقديمه قبل إقلاع WordPress.
- إعدادات التحليل المسبقة: توسّع
themeوextreme-themeوwordpress-renderنطاقblockstudio/phpstanليتجاوز قوالب الكتل. - خطاف الالتزام المُدار: ينشئ
blockstudio-githooks syncخطاف ما قبل الالتزام ويملكه، ويشغّل الإعداد المسبق المُهيأ. - عقد المشروع: ينشئ
blockstudio-agentsملفAGENTS.mdيصف ما يؤلفه المشروع، والميزات التي يفعّلها، وما يفرضه إعداده المسبق. - فهرس الوثائق: أصبح ملف سياق الذكاء الاصطناعي فهرسًا لكل مستند وغرضه والمعرّفات التي يملكها.
- وسوم الكتل المعتمدة: يعيد أمر مستقل كتابة اختصارات البادئات والبدائل إلى
<bs:namespace-slug>، مع تشغيل تجريبي. - التوافق افتراضيًا: لا يغيّر أي مما سبق موقعًا حتى يُذكر في
blockstudio.json.
قراءة المشروع وعرضه
جرد المشروع
يعرض Canvas::inventory() كل ما يسجله المشروع في مصفوفة عادية واحدة، دون عرض أي شيء.
use Blockstudio\Canvas;
$result = Canvas::inventory();
foreach ($result['inventory']['blocks'] as $block) {
echo $block['name'] . "\n";
}
تُجمع السجلات حسب النوع: pages وblocks وpatterns وtemplates وparts وui. يحدد order ترتيب العرض الثابت عبر جميع الأنواع، ويربط sources كل سجل بمسارات مصدره، بينما يجمع warnings وerrors المشكلات في إدخالات منظمة.
تحمل سجلات الكتل id وname وtitle وsource وpath وprovenance وdeclaration جاهزًا للعرض. تحتفظ سجلات الصفحات بـ source بوصفه الهوية الثابتة، وبـ path بوصفه القالب الذي يعرضها.
التحديد المستهدف
يؤدي تحديد السجلات إلى حصر العمل بدلًا من تصفيته لاحقًا.
$changed = Canvas::inventory([
'blocks' => ['mytheme/hero'],
'pages' => ['about'],
]);
يعرض ذلك كتلة واحدة وصفحة واحدة. وتعود patterns وtemplates وparts وui فارغة، ولا تُقرأ مصادرها أو تُزامن أو تُعرض أو تُجمّع مطلقًا.
القواعد دقيقة:
- عدم وجود مفاتيح للأنواع يحمّل كل الأنواع.
- يحمّل
trueأوnullأو"*"كل سجل من ذلك النوع. - تطابق السلسلة أو القائمة تمامًا مع المعرّف أو الاسم أو الاسم المختصر أو المسار أو مسار المصدر.
- لا يحمّل السلسلة الفارغة أو القائمة الفارغة أو
falseأي سجل من ذلك النوع. - بمجرد وجود مفتاح لأي نوع، تظل الأنواع غير المحددة كما هي.
تُعاد المعرّفات التي لم تعد موجودة ضمن deleted بدلًا من التسبب في فشل، ويطبّق مسار تحديث Canvas REST القاعدة نفسها على المعاملين blocks وpages.
يأخذ Canvas::documents() التحديد نفسه ويضيف مستندًا معروضًا لكل سجل. وتُعرض الصفحات المحددة ضمن سياق واجهة أمامية مستعاد، بحيث ترى الشروط الخاصة بالاستعلام وأصناف body والرموز القصيرة والتخطيطات وإعادة التوجيه وعمليات الاستدعاء عند الإدراج تلك الصفحة، لا الطلب الذي طلب عرضها.
العرض المستقل
يعرض Blockstudio\Render HTML معروضًا كسلسلة نصية، عبر المسار نفسه الذي تستخدمه الواجهة الأمامية.
use Blockstudio\Render;
$html = Render::composition([
'root' => 'mytheme/card',
'data' => ['heading' => 'Example card'],
'layers' => [
['name' => 'mytheme/button', 'data' => ['label' => 'Continue']],
],
]);
يوجد شكل تصريح واحد في الأساس، وله أربعة مفاتيح: name وattributes وcontent وchildren. أما root وdata وinner وinnerBlocks وlayers وexample فهي تسهيلات إدخال يدمجها Render::normalize() فيه. تُعرض العناصر الفرعية بشكل متكرر، ويؤدي الإدخال غير السليم إلى استثناء يذكر اسم الكتلة المعنية.
يغلّف Render::document() الناتج في مستند HTML مستقل ومكتمل.
$document = Render::document('mytheme/hero', [
'title' => 'Hero preview',
]);
echo $document['html'];
يمثل body ناتج الكتلة وحده، وhtml المستند المُجمّع، وblocks أسماء الكتل التي أسهمت فيه، بينما يقسم assets الترميز إلى head وfooter وstyles وscripts وmodules وinteractivity وui وtailwind. يقتصر نطاق الأصول على ما عُرض، لذا لا تظهر أصول المحرر مطلقًا.
Render::document_from_html() يغلّف HTML المُعرَض في موضع آخر، بينما يعرض Render::content() محتوى الكتلة المتسلسل دون مستند. استدعِ Blockstudio\Batch_Render::reset() بين المستندات ضمن عملية PHP واحدة؛ فـCanvas::documents() يتولى ذلك بالفعل.
عائلات مكونات UI
يكشف Blockstudio\Ui مكتبة UI المضمّنة في مدخل واحد لكل مكوّن عام بدلًا من قائمة بالأجزاء الداخلية.
يعرض Ui::inventory() مدخلًا واحدًا لكل عائلة، يتضمن كتلة الجذر والعنوان وكتل التنفيذ التي تحتاج إليها. ويضيف Ui::examples() تصريحًا حتميًا لكل عائلة: مع الاحتفاظ بالقيم الافتراضية، وتضمين طبقات العناصر الفرعية المطلوبة تحت آبائها، وتوفير نص توضيحي ثابت عندما يكون الحقل فارغًا. هذا التصريح معتمد، لذا يمكن إدخاله مباشرة في Render::document().
يجمع Canvas المكونات بالطريقة نفسها. تظهر UI المضمّنة ضمن النوع ui كمثال واحد لكل عائلة، ولا تظهر تسجيلات التنفيذ ضمن blocks.
صُممت العائلات لتُركّب معًا: تفتح قائمة الاختيار داخل مربع حوار، وتظهر القائمة المنسدلة فوق المشغّل؛ وترتكز القوائم ومربعات الاختيار المركبة على إحداثيات ثابتة ضمن نافذة العرض تصمد أمام التمرير؛ وتتراكم النوافذ المنبثقة وتُغلق واحدة تلو الأخرى بضغطة Escape؛ وتستخدم كل تذييلة عنصر التحكم نفسه للإغلاق مع اختلاف الشكل. يشرح فصل التركيب؛ ويعرض /ui/examples هذه التركيبات أثناء عملها.
مساعدات القوالب
أبعاد صور ثابتة
يعرض bs_media_image() أصول القالب بعرض وارتفاع حقيقيين ونسبة أبعاد محجوزة، كي لا تعود الصور خارج مكتبة الوسائط تتسبب في تحريك التخطيط.
<?php
echo bs_media_image([
'src' => 'assets/images/hero.webp',
'alt' => 'Hero',
]);
الناتج هو figure.blockstudio-media مع aspect-ratio مضمّن حول img يحمل قيم width وheight وloading وdecoding حقيقية. تأتي الأبعاد من assets/media.json مُنشأ، يكتبه Blockstudio\Media_Metadata_Builder في خطوة الإنشاء أو يدويًا.
يقبل src مسارًا نسبيًا إلى القالب أو مسارًا مطلقًا أو URL كاملًا، ويغطي attachmentId صور مكتبة الوسائط. يعطّل eager التحميل الكسول للصور أعلى الصفحة، ويصدر sources عنصر <picture>.
عند تفعيل performance.media.lazy، ينتقل URL الحقيقي إلى data-src خلف عنصر نائب ذي حجم صحيح.
مساعدات أصناف Tailwind
يركّب bs_tw_merge() وbs_tw_variants() أصناف Tailwind في قوالب PHP باستخدام المحرك الذي يضمّنه Blockstudio بالفعل.
يعرض bs_tw_merge('px-2 text-sm', 'px-4') قيمة text-sm px-4: يُسقط px-2 المتعارض وتفوز القيمة اللاحقة. وتُقبل المصفوفات المتداخلة من قيم الأصناف.
يعرض bs_tw_variants() دالة قابلة للاستدعاء صغيرة لبدائل المكونات:
$button = bs_tw_variants([
'base' => 'inline-flex items-center',
'variants' => [
'size' => ['sm' => 'h-8 px-3', 'lg' => 'h-12 px-6'],
],
'defaultVariants' => ['size' => 'sm'],
]);
echo $button(['size' => 'lg', 'class' => 'rounded']);
يطبع ذلك inline-flex items-center h-12 px-6 rounded. وتُدعم الأصناف الأساسية والبدائل والبدائل الافتراضية والبدائل المركبة، بالإضافة إلى class أو className لكل استدعاء.
إعداد الإنتاج
ملفات تعريف الأداء
يفعّل performance.profile إعدادات الواجهة الأمامية للإنتاج في مكان واحد.
{
"performance": {
"profile": "speed",
"preload": {
"links": "off"
}
}
}
الإعداد الافتراضي هو compat ولا يغيّر شيئًا. يفعّل speed وstrict المجموعة نفسها: إزالة مخرجات المولّد والرموز التعبيرية والخلاصات والاكتشاف والمنشورات المجاورة من الرأس؛ وإسقاط اكتشاف oEmbed والبرامج النصية للمضيف؛ وتعطيل XML-RPC والردود على الإشارات واكتشاف المحرر عن بُعد؛ وإزالة أصول الواجهة الأمامية العامة للنواة؛ وتطبيق الإعدادات الافتراضية لمخرجات الصور؛ وخفض معدل Heartbeat خارج المحررات؛ وجلب المستندات من المصدر نفسه عند التحويم أو التركيز؛ واستخدام محمّل الصور في Blockstudio.
تتجاوز كل قيمة فرعية إعدادات الملف، كما يفعل preload.links أعلاه. ويُنصح باختبار إزالة أصول الواجهة الأمامية للنواة أولًا، لأن الصفحة التي تعتمد عليها ستتعطل بوضوح. يكشف Runtime_Settings::current() ملف التعريف المحسوم.
يغطي themeDefaults أمرين تنفذهما القوالب يدويًا عادةً: titleTag وsuppressDirectoryUpdates لإخفاء القالب الفرعي النشط والقالب الأب من نتائج التحديث.
الوصول إلى الإعدادات ذات الأنواع
يقرأ Blockstudio\Settings الإعدادات بأنواع فعلية بدلًا من إعادة ما يحتويه JSON كما هو.
use Blockstudio\Settings;
$lazy = Settings::get_bool('performance/media/lazy');
$margin = Settings::get_string('performance/media/rootMargin', '300px');
$ttl = Settings::get_int('performance/staticPrerender/ttl', 86400);
$roles = Settings::get_array('users/roles');
foreach (Settings::errors() as $error) {
error_log($error);
}
يُبلّغ عن JSON غير السليم عبر Settings::errors() بدلًا من إرجاع القيم الافتراضية. ويعرض Settings::get_raw() ما صرّح به المصدر النشط فقط، ما يميّز بين قيمة ضُبطت على false وقيمة لم تُضبط قط.
يعرض Settings::fingerprint() هوية ثابتة للإعدادات الفعلية، ويعيد الوصول تحميلها عند تغيّر blockstudio.json.
مجلد واحد لذاكرة التخزين المؤقت
يوجد كل ملف مُنشأ الآن تحت cache.path، الذي يكون افتراضيًا wp-content/blockstudio/cache.
{
"cache": {
"enabled": true,
"path": "cache/blockstudio"
}
}
تقع حمولات الإنشاء وبيانات تسجيل الكتل وأصول المحرر وTailwind CSS المجمّع ومستندات العرض ومقاطع الجزر وHTML الثابتة وفهارس الرسوم البيانية وقوائم الانتظار الدافئة وبيانات التشخيص كلها تحت هذا الجذر. يُحل المسار النسبي انطلاقًا من WP_CONTENT_DIR، أما المسار المطلق فيوجهه إلى وحدة تخزين مخصصة.
تُخزّن العناصر تحت الشبكة والموقع الحاليين، ثم تحت هوية وقت تشغيل: بصمة لإصدارات Blockstudio وWordPress وPHP والإعدادات الفعلية والقالب والإضافات النشطة ومصادر الاستكشاف والملفات المصدرية ذات الصلة. عند تغيير أحد المدخلات، تصبح العناصر المتأثرة جديدة وتُحذف القديمة.
تُنفذ عمليات الإنشاء الباردة مرة واحدة: يتولى طلب واحد الإنشاء ونشر النتيجة ذريًا بينما تنتظر الطلبات الأخرى. ويواصل النظام تقديم آخر عنصر سليم عند فشل التحديث، مع إبقاء الفشل ظاهرًا، كما يمسح Blockstudio\Runtime_Cache::purge('tailwind') نطاقًا واحدًا.
العرض المسبق الثابت
يخزّن العرض المسبق الثابت مستندات HTML المجهولة والمكتملة مؤقتًا، ويمكنه تقديمها قبل إقلاع WordPress. وهو معطّل افتراضيًا.
{
"performance": {
"staticPrerender": {
"enabled": true,
"ttl": 3600,
"earlyServe": true,
"dynamicPaths": ["/account", "/checkout"]
}
}
}
شروط الأهلية
تقتصر الأهلية على مستندات HTML المجهولة والمكتملة. يتم تجاوز الطلبات التي لا تستخدم GET، وسلاسل الاستعلام، ولوحة الإدارة، وREST، وAjax، وcron، والخلاصات، والبحث، والمعاينات، والطلبات الحاملة لـ nonce، وملفات تعريف الارتباط المخصصة، وأي مسار تحت dynamicPaths. ويمكن للرد إلغاء أهليته بالكامل بعلامة <!-- blockstudio:no-cache -->.
يراعي تطابق المسارات الحدود، لذا يغطي /account المسار /account/orders لكنه لا يغطي /accounting.
نمطا التوقيع والرسم البياني
يحدد invalidate كيفية انتهاء صلاحية الإدخالات. يملأ نمط signature الافتراضي استجابة مرتبطة بالهوية عند غياب نسخة مجهولة، ويبدّلها بعد تغييرات على مستوى الموقع، وهو مناسب للمواقع العادية.
نمط graph مخصص لأدوات الإنشاء والنشر الصريحة. يسجل تبعيات المصدر الخاصة بكل صفحة، بحيث لا تعيد الخطة إنشاء سوى عناوين URL المتأثرة.
use Blockstudio\Static_Prerender_Runtime;
$plan = Static_Prerender_Runtime::build_plan($sourceUrls);
foreach ($plan['affectedUrls'] as $url) {
$result = render_with_dependencies($url);
Static_Prerender_Runtime::persist_built_response(
$url,
$result['html'],
$result['files'],
$result['virtualHashes']
);
}
Static_Prerender_Runtime::garbage_collect(array_keys($plan['live']));
التقديم المبكر
عند تفعيل earlyServe، يتولى Blockstudio خريطة مسارات صغيرة خاصة بكل موقع وإضافة advanced-cache.php مبسطة تبث الاستجابة المؤهلة من ذاكرة التخزين المؤقت قبل إقلاع WordPress أو الإضافات أو القالب.
لا يستبدل مطلقًا خريطة أو إضافة مبسطة أو تصريح WP_CACHE تابعًا لجهة أخرى. يتحقق عنصر الرسم البياني من كل ملف HTML مشار إليه قبل تبديل الخريطة، لذا يبقي النشر غير المكتمل الرسم البياني السابق نشطًا. وتظل إدخالات المواقع المتعددة معزولة حسب المضيف ومسار الصفحة الرئيسية ومعرّف الموقع.
التسخين والحالة
تغطي ثلاثة أوامر WP-CLI الاستخدام اليومي:
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
يعرض status الهوية النشطة وأعداد الملفات والبايتات وسجلات الرسم البياني وحالة قائمة الانتظار، إضافة إلى عدادات الإصابات والإخفاقات وعمليات الإنشاء لكل نطاق.
التحليل وأدوات الوكلاء
إعدادات التحليل المسبقة
يضيف blockstudio/phpstan ثلاث طبقات فوق تحليل الكتل، بالإضافة إلى أمر واحد يشغّل الطبقة التي اختارها المشروع.
| الإعداد المسبق | ما يضيفه |
|---|---|
base |
تحليلات المخطط والقوالب والخطافات والإعدادات وAPI الحالية. |
theme |
جذور القوالب وعناوين الأنماط والأصول وتحديد نطاق المحددات والقيم الافتراضية للحقول وحدود المكررات. |
extreme-theme |
max لـ PHPStan، وPHP غير الآمن، والتحقق من الهروب وTailwind وJavaScript والتفاعلية. |
wordpress-render |
اختبار عرض مباشر يقدمه المستدعي، إضافة إلى extreme-theme. |
تأتي القيم الافتراضية من blockstudio.json، كي تشترك عمليات التشغيل التفاعلية وCI وخطافات الالتزام في إعداد واحد:
{
"phpstan": {
"preset": "theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
vendor/bin/blockstudio-phpstan --root . -- --no-progress
رموز الخروج هي 0 عند النجاح، و1 للتشخيصات، و2 للاستخدام غير الصالح. يركّب الغلاف إعداده في المجلد المؤقت للنظام، فلا تُحفظ ملفات إعداد أو خط أساس أو ذاكرة تخزين مؤقت مُنشأة في المشروع، كما يرفع حد ذاكرة PHPStan إلى 1G.
ويضم أيضًا موفر BC Math، لذا لم تعد فحوصات JavaScript بحاجة إلى ext-bcmath.
خطاف الالتزام المُدار
يحوّل إعداد واحد وأمر واحد الإعداد المسبق المُهيأ إلى بوابة للالتزام.
{
"githooks": {
"commit": true
}
}
vendor/bin/blockstudio-githooks sync
تكتب المزامنة الخطاف وسجل الملكية داخل المجلد المشترك لـ Git، وتوجه core.hooksPath إلى المجلد المُدار، وتربط أي خطاف ما قبل الالتزام سبق ضبطه. ويحدد الخطاف المستودع وجذر المشروع وقت الالتزام، لذا تعمل عمليات الدفع المرتبطة والمسارات التي تحتوي على مسافات.
يشغّل الخطاف vendor/bin/blockstudio-phpstan فقط؛ ولا ينسّق الملفات أو يعيد كتابتها مطلقًا. يؤدي ضبط commit على false ثم المزامنة مجددًا، أو تشغيل blockstudio-githooks remove، إلى استعادة مسار الخطاف المسجل وحذف الملفات التي يملكها Blockstudio فقط.
عقد المشروع
ينشئ blockstudio-agents ملف AGENTS.md يحدد مكان وجود الكتل، وتعريف الصفحة في هذا المشروع، والميزات المفعّلة، وما سيرفضه المحلّل.
vendor/bin/blockstudio-agents
يُشتق المستند من المشروع ولا يُنشأ من قالب جاهز. يحصل قالب يتضمن ترويسة style.css وكتلًا وصفحات قائمة على الملفات على عقد مختلف عن إضافة لا تسجل إلا الكتل، مع تضمين الأعداد والمجلدات ونطاقات الأسماء ولغات القوالب التي عثر عليها الماسح. يحدد blockstudio.json الميزات الظاهرة، لذا لا يظهر ذكر العرض المسبق الثابت في مشروع لا يستخدمه.
يُقرأ قسم الصحة من ملفات القواعد الخاصة بالإعداد المسبق المحدد، طبقةً تلو الأخرى، لذا فإن اكتساب إعداد مسبق لقاعدة جديدة يغيّر كل عقد مُنشأ معه.
تعمل الملكية مثل خطاف الالتزام. يُرفض استبدال أي ملف لا يحمل علامة الإنشاء ما لم ينص --force على خلاف ذلك، وتبقى منطقة الملاحظات في النهاية بعد إعادة الإنشاء، ويُصدر --check رمز الخروج 1 عندما يكون العقد غير محدث، ويطبع --stdout الملف دون لمس نظام الملفات.
فهرس الوثائق
أصبح blockstudio-llm.txt فهرسًا بدلًا من تجميع للنصوص. يظهر كل مستند منشور مرة واحدة ضمن قسمه وقسمه الفرعي، مع مساره وملف مصدره وغرضه في سطر واحد والمعرّفات التي يملكها: مسارات الإعدادات وأسماء الخطافات ودوال وفئات PHP والأوامر.
## Docs / Dev / Inspection Tools
### Canvas
route: /docs/dev/canvas
file: docs/docs/dev/canvas.md
purpose: A visual workspace and public inventory API for Blockstudio content.
settings: dev/canvas/enabled, ui
hooks: blockstudio/settings/dev/canvas/admin_bar, blockstudio/settings/dev/canvas/enabled
php: Blockstudio\Canvas, Canvas::documents(), Canvas::inventory()
يقرأ الوكيل الفهرس، ويعثر على المستند الوحيد الذي يحتوي على المعرّف الذي يحتاج إليه، ثم يفتح ذلك المستند. لا يزال الملف الموحّد السابق، بحجم نصف ميغابايت، يُنشأ ويُنشر في /blockstudio-llm-full.txt؛ لكنه لم يعد أول ما يُقدَّم لأي شخص.
وسوم الكتل المعتمدة
يعيد أمر مستقل كتابة الاختصارات ذات البادئات والأسماء المستعارة بالصيغة المعتمدة لـ <bs:namespace-slug>، التي تسجل اسم الكتلة الحقيقي ويُحلّ مرجعها دون تحميل مرشح للمشروع.
باستخدام بادئة brand مع theme-components وبادئة ui مع bsui، يكون لهذا الاختصار:
<brand-card>
<ui-input />
</brand-card>
المعنى نفسه لـ:
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
تظل البادئات والأسماء المستعارة المطابقة تمامًا مدعومة، ولم تعد مهملة. لا يحمّل الأمر WordPress ولا يكتب شيئًا دون --apply:
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
--root="$PWD" \
--prefix-map=/tmp/prefixes.json \
--known-blocks=/tmp/blocks.json \
--report=/tmp/tag-migration.json \
--dry-run
يربط --prefix-map كل بادئة بمساحاتها الاسمية، ويسرد --known-blocks أسماء الكتل المسجلة. يسجل التقرير عمليات الربط من الصيغ القديمة إلى المعتمدة مع عدد مرات الظهور وبصمات الملفات، ويسرد بشكل منفصل الوسوم غير المعروفة والأسماء المستعارة الملتبسة والوسوم الديناميكية. يرفض --apply الكتابة ما دام أي منها موجودًا، إلا عند تمرير --allow-unresolved.
تُعالَج العلامات المقترنة والمتداخلة وذاتية الإغلاق، بما في ذلك العلامات الحرفية ضمن سلاسل PHP. لا تتغير سوى أسماء العلامات، ولا يُحدث التشغيل الثاني أي تغييرات، وتُدرج الأمثلة داخل التعليقات أو كتل الأكواد أو <pre> أو <code> في التقرير فقط.
السلوك الافتراضي
لا يؤدي تثبيت 7.6 بحد ذاته إلى أي تغيير.
يكون إعداد الأداء الافتراضي هو compat. يظل إخراج الرأس وoEmbed وRPC الخاص بـ XML وHeartbeat والإعدادات الافتراضية للصور والتحميل المسبق للروابط والتحميل الكسول و<title> للواجهة الأمامية كما تركها WordPress والقالب.
تظل هذه الميزات معطّلة ما لم تُفعّل: كل مفتاح من performance.staticPrerender وperformance.measurement وperformance.media وthemeDefaults، بالإضافة إلى githooks.commit وdev.canvas.enabled وui.enabled وtailwind.enabled وblockTags.enabled. لا ينشئ العرض المسبق الثابت ملفات ولا يثبت إضافةً مدمجةً عند تعطيله.
Canvas وRender سلبيان. يقرآن السجلات الحالية ولا يعرضان إلا ما يطلبه المستدعي؛ ولا يتصل أي منهما بإخراج الواجهة الأمامية أو يسجل مسارات. لا تزال شاشة إدارة Canvas تتطلب dev.canvas.enabled وedit_posts.
يتطلب التحليل الأكثر صرامة تحديده بالاسم. لا يؤدي تثبيت blockstudio/phpstan إلا إلى تفعيل الامتداد الأساسي، ويشغّل الأمر المعتمد base ما لم يحدد المشروع إعدادًا مسبقًا.
تتطلب الملفات المُنشأة تشغيل الأمر الخاص بها. لا يفعل githooks.commit شيئًا حتى يُشغّل blockstudio-githooks sync، ولا يفعل AGENTS.md شيئًا حتى ينفذ blockstudio-agents ذلك.
الترقية من 7.5
لم تتغير المتطلبات: PHP 8.2 أو أحدث، وWordPress 6.7 أو أحدث.
composer require blockstudio/blockstudio
تُعاد بناء ذاكرات التخزين المؤقت مرة واحدة. تتضمن هوية بيئة التشغيل إصدار Blockstudio، لذا يكون الطلب الأول بعد الترقية باردًا وتُحذف الكائنات القديمة. يمكن حذف ذاكرة Tailwind المؤقتة القديمة من wp-content/uploads/blockstudio/tailwind/cache؛ وعلى المقتطف البرمجي الذي استخدم glob للعثور عليها استدعاء Blockstudio\Runtime_Cache::purge('tailwind') بدلًا من ذلك.
يُعاد تسمية مجلد wp-content/blockstudio/cache/runtime المسطح السابق للإصدار 7.6 تلقائيًا لإخراجه من المسار النشط، ثم يُحذف عبر دفعات WP-Cron محدودة. لذلك لا حاجة إلى حذف أشجار ملفات القفل القديمة الكبيرة أثناء طلب النشر.
للملفات المُنشأة مواضعها. يجب وضع assets/media.json في نظام التحكم بالإصدارات أو ضمن خطوة بناء. لا توجد خريطة المسارات وإضافة advanced-cache.php المدمجة وإعلان WP_CACHE إلا عند تفعيل earlyServe، ولا يوجد خطاف ما قبل الإيداع إلا عند المزامنة. توجد كل الملفات الأخرى المُنشأة ضمن cache.path، ويمكن حذفها بأمان.
لم يُحذف أي شيء أو يُعَد تسميته. تظل bs_render_block() وbs_block() وBlockstudio\Pages وBlockstudio\Patterns الواجهات المعتمدة للمحتوى المدعومة بالملفات.
يمكن التراجع عن كل ميزة على حدة. يعيد performance.profile إلى compat، وstaticPrerender.enabled إلى false، وgithooks.commit إلى false مع sync، وcache.enabled إلى false، وكل منها يتراجع عن طبقة واحدة.
ترتيب مناسب للتبني:
- عيّن
performance.profileإلىspeed، ثم تحقق من إخراج الرأس والخلاصات وأي إضافة تعتمد على oEmbed أو RPC الخاص بـ XML. - أنشئ
assets/media.json، وانقل القوالب إلىbs_media_image()، ثم فعّلperformance.media.lazy. - فعّل
performance.staticPrerenderمع إبقاءearlyServeمعطّلًا، وتحقق من الزيارات باستخدامwp bs prerender status، ثم فعّلearlyServe. - شغّل
blockstudio-phpstan --preset themeحتى يخلو من المشكلات، قبل وضع أي إعداد مسبق خلفgithooks.commit.