تكامل الذكاء الاصطناعي
يوفّر Blockstudio ملفي سياق لمساعدي البرمجة. الملف الأساسي فهرس موجز للوثائق. أما الثاني فيضم النص الكامل لكل مستند ومخطط، للأدوات التي تحتاج إلى المجموعة كاملة في طلب واحد.
يقرأ الوكيل الفهرس، ويعثر على المستند الذي يحتاج إليه، ثم يفتحه. والبديل هو تزويده بنصف ميغابايت من النصوص غير المصنفة، بحيث لا يمكن الوصول إلى أي جزء بعينه، ويُحمّل كل شيء سواء أكان ذا صلة أم لا.
الفهرس
يسرد blockstudio-llm.txt كل مستند منشور مرة واحدة، مصنفًا حسب القسم والقسم الفرعي الذي ينتمي إليه، ومرتبًا وفق ترتيب التنقل. ويتضمن كل إدخال:
route: URL الخاص بالوثائق.file: مسار المصدر Markdown في مستودع Blockstudio.purpose: سطر يصف الغرض من المستند.settings: مساراتblockstudio.jsonالتي يتولى المستند إدارتها.hooks: أسماء عوامل التصفية والإجراءات PHP وJavaScript التي يتولاها.php: الدوال والفئات والأساليب التي يتولاها.cli: الأوامر التي يتولاها.
## 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()
لا يُكتب سطر المعرّف إلا عندما يتولى المستند فعليًا شيئًا من ذلك النوع؛ لذا لا يتضمن الإدخال أعلاه سطر cli، بينما تتولى صفحة العرض المسبق الثابت عائلة أوامر العرض المسبق كاملة.
أسطر المعرّفات هي ما يجعل الفهرس قابلاً للاستعلام. يبحث الوكيل عن الخطاف الذي يعمل قبل عرض كتلة، فيفحص أسطر الخطافات ويصل إلى PHP الخطافات، التي تضم المفردات الكاملة للمرشحات والإجراءات. ويبحث الوكيل عن العرض المسبق الثابت، فيفحص الكلمة نفسها ويصل إلى العرض المسبق الثابت والإعدادات، اللذين يضمان العدادات والإعدادات على التوالي. وتُدرج المخططات العامة الخمسة JSON بالطريقة نفسها، مع المسار والملف الخاص بكل منها.
تُستخرج المعرّفات من النصوص والأكواد المضمنة وأمثلة الأكواد. أما الكتل المحددة بـtext فتحتوي على مخرجات حرفية وقوائم أدلة، لذا يتم تجاوزها: فالمستند الذي يعرض مخرجات أمر لا يتولى ذلك الأمر لمجرد عرضه.
النص الكامل
يضم blockstudio-llm-full.txt الوثائق كاملةً وكل مخطط في ملف واحد. وما يزال يُنشأ آليًا ويُنشر ويمكن الوصول إليه، لكنه لم يعد أول ما يُقدَّم للوكيل، وهذا موضح في ترويسته.
كيفية إنشائهما
يُجمّع الملفان وقت الإنشاء بواسطة npm run build:llm، الذي يشغّل scripts/build-llm.ts. وينفّذ البرنامج النصي ما يلي:
- يقرأ البيانات التمهيدية لكل مستند منشور في مجموعات
docsوguidesوregistry، لاستخراج العنوان والمسار والغرض. - يستخرج المعرّفات التي يتولاها كل مستند من متنه: أسماء الخطافات من استدعاءات عوامل التصفية والإجراءات، ومسارات الإعدادات التي يتحقق منها مخطط الإعدادات، ودوال وفئات PHP، وأوامر CLI.
- يكتب الفهرس إلى
includes/llm/blockstudio-llm.txt. - يتصفح شجرة الوثائق بترتيب التنقل، ويحذف عناصر Markdown المخصصة للتنقل فقط مع الحفاظ على العناوين وأمثلة الأكواد، ثم يضيف مخططات JSON ويكتب النص الكامل إلى
includes/llm/blockstudio-llm-full.txt.
يفشل npm run docs:check إذا غاب مستند منشور عن الفهرس، أو إذا أشار الفهرس إلى ملف لم يعد موجودًا.
كيفية استخدامهما
- فعّل إعداد
ai/enableContextGenerationفيblockstudio.json:
{
"ai": {
"enableContextGeneration": true
}
}
-
أصبح الملفان متاحين الآن في
your-site.com/blockstudio-llm.txtوyour-site.com/blockstudio-llm-full.txt. -
وجّه أداة الذكاء الاصطناعي إلى الفهرس:
- Cursor: أضف URL كمستند في إعدادات مشروعك.
- Claude Code: أشر إلى URL أو نزّل الملف وأضفه إلى سياق مشروعك.
- GitHub Copilot: أدرج الملف في مستودعك أو أشر إليه في تعليماتك.
ستعمل أي أداة تقبل URL أو ملفًا نصيًا كسياق. الملفان ثابتان ولا يتضمنان بيانات خاصة بالموقع، مثل الكتل المسجّلة أو الإعدادات الحالية.
العقد الخاص بمشروعك
يصف الفهرس Blockstudio. لكنه لا يصف مشروعك، وهو النصف الآخر مما يحتاج إليه الوكيل: أماكن وجود الكتل والصفحات، والميزات المفعّلة، وما سيرفضه التحليل. ينشئ vendor/bin/blockstudio-agents ذلك انطلاقًا من blockstudio.json وملفاتك الخاصة. راجع عقد المشروع.