باختصار
- dll2llm أداة سطر أوامر تفحص تجميعات .NET ويمكنها إنشاء مجلد Agent Skill.
- يمكن تزويد الأداة بملف RevitAPI.dll، كما يمكن إضافة RevitAPIUI.dll عند الحاجة إلى طبقة واجهة المستخدم.
- يحتوي المجلد الناتج على SKILL.md وINDEX.md وملفات موضوعية مرتبة بحسب مساحات الأسماء.
- تتطلب التغييرات في Revit استخدام Transaction؛ ويمكن استخدام SubTransaction داخل Transaction مفتوحة.
ما الذي ستتعلمه في هذا الدليل؟
قد لا يتمكن وكيل الذكاء الاصطناعي الذي يعمل مع Revit API من اختيار الأصناف والطرق الصحيحة دائمًا بالاعتماد على المعرفة العامة بالبرمجة وحدها. ويعزو دليل Autodesk Platform Services (APS) ذلك إلى نقص سياق API: فقد يتعرف الوكيل على بعض الأنواع الشائعة، لكنه قد يخمّن على نحو خاطئ طرقًا أقل استخدامًا. ولأن Revit API يضم عددًا كبيرًا من الأصناف ومساحات الأسماء، فإن توفير جميع المعلومات في ملف نصي واحد قد لا يكون حلًا عمليًا أيضًا.
في هذا الدليل، سنتناول طريقة إنشاء مجلد Agent Skill من تجميعات Revit API وكيفية استخدام هذا المجلد في تطوير الوكلاء. الهدف هنا ليس إعداد الأتمتة في Revit من البداية إلى النهاية، بل تزويد الوكيل بسياق أكثر تنظيمًا وقابلية للبحث حول API. ويعرض دليل Autodesk أداة سطر الأوامر dll2llm مثالًا لتنفيذ ذلك.
المتطلبات والقيود
يتطلب سير العمل الوصول إلى تجميعة Revit API. ويوضح دليل APS كيفية توجيه الأداة إلى ملف RevitAPI.dll، وإضافة ملف RevitAPIUI.dll عند الحاجة إلى طبقة واجهة المستخدم أيضًا. ويتضمن الدليل عرضًا توضيحيًا تُؤخذ فيه الملفات المصدرية من دليل تثبيت Revit قبل إنشاء مجلد المهارات.
تُعرّف الأداة بأنها مشروع GitHub باسم dll2llm، وهي تفحص تجميعة .NET وتحولها إلى ملفات Agent Skill. ولا يحدد المصدر نظام التشغيل المدعوم أو إصدار .NET المطلوب أو مصفوفة التوافق مع إصدارات Revit أو أوامر التثبيت أو منتج وكيل بعينه. لذلك، لن يكون من المناسب افتراض أمر أو مسار قائمة أو إصدار هنا. قبل البدء، تحقّق من أحدث وصف لمشروع dll2llm ومن ملفات DLL الموجودة في تثبيت Revit الذي تستخدمه.
تسرد الإرشادات الرسمية SKILL.md وINDEX.md وملفات Markdown للموضوعات ضمن الملفات الأساسية للمجلد الناتج. وتُنظّم ملفات الموضوعات بحسب مساحات الأسماء؛ ويمكن تقسيم مساحات الأسماء الكبيرة إلى أجزاء أبجدية لتجنب تحميل نافذة السياق بمحتوى مفرط. ولأن المصدر لا يذكر الحاجة إلى حساب، فإن هذا الدليل لا يفترض وجود مثل هذا الشرط.
إنشاء Agent Skill خطوة بخطوة
حدّد الهدف. ابدأ بتحديد مهام Revit API التي تتوقع أن يساعد فيها الوكيل. فعلى سبيل المثال، قد تتطلب قراءة بيانات النموذج أو تصفية العناصر أو إجراء تغييرات على النموذج ضمن إضافة، معرفة مختلفة بـ API. وتقدّم Autodesk Agent Skill بوصفه وسيلة لتزويد الوكيل بسياق API؛ أما الأداة نفسها فلا تحدد متطلبات المشروع.
اختر التجميعات المطلوبة. ملف RevitAPI.dll هو المُدخل الأساسي الذي يتضمن طبقة قاعدة بيانات Revit API. وإذا احتاج الوكيل إلى معلومات عن طبقة الواجهة، ففكّر في إضافة RevitAPIUI.dll. ويشير مقال APS إلى إمكانية استخدام الملف الثاني اختياريًا. لا تفترض أن استخدام التجميعين معًا إلزامي لكل مهمة؛ فاحتياجات المشروع هي التي تحدد النطاق.
اطّلع على مشروع dll2llm. تُعرض الأداة بوصفها مشروع dll2llm على GitHub. وبما أن تفاصيل التثبيت والتشغيل غير واردة في النص المصدر، فلن نورد أمرًا محددًا للطرفية هنا. اتبع إرشادات المشروع وتأكد من مسار التجميعة الذي تتوقع الأداة استخدامه مُدخلًا.
زوّد الأداة بالتجميعة. في سير العمل الوارد بدليل APS، تُشغّل dll2llm مع تحديد التجميعات الموجودة في دليل تثبيت Revit. اختر RevitAPI.dll، وأضف RevitAPIUI.dll عند الحاجة، ثم اجعل الأداة تجمع المخرجات في مجلد مهارات منفصل. ويذكر الدليل أن الملفات الناتجة موزعة بحسب مساحات الأسماء؛ لذلك قد لا يقتصر الناتج على مستند API طويل واحد.
تحقّق من الملفات الناتجة. تأكد من إنشاء SKILL.md وINDEX.md إلى جانب ملفات Markdown للموضوعات. وتتضمن هذه الملفات معلومات API المصنفة بحسب مساحات الأسماء. ويساعد احتمال تقسيم مساحات الأسماء الكبيرة أبجديًا على منع تحول سياق الوكيل إلى كتلة ضخمة واحدة من المحتوى. لا تتعامل مع الملفات على أنها أمثلة برمجية موثّقة لمجرد أنها أُنشئت؛ فالأداة تولّد سياق API، لكنها لا تختبر منطق مشروعك نيابة عنك.
أضف المهارة إلى سير عمل الوكيل. وفق نهج Autodesk، يستطيع الوكيل استخدام مرجع Revit API أثناء تنفيذ المهمة بعد إعداد المهارة. والهدف هو تقليل الحاجة إلى نسخ مقتطفات الشيفرة ولصقها واحدًا تلو الآخر في نافذة المحادثة، وإتاحة سياق أوسع لـ API أمام الوكيل. ولا يوضح هذا المصدر الوكلاء الذين يدعمون تنسيق المهارات أو طريقة تثبيتها؛ لذا راجع إرشادات البيئة التي تستخدمها.
اختبر اقتراحات الشيفرة بمهام صغيرة. لا تتعامل مع الشيفرة التي ينشئها الوكيل على أنها موثوقة مباشرة. تحقّق أولًا من تطابق أسماء الأصناف والطرق مع المرجع المُنشأ، ثم افحص ما إذا كانت العملية تحقق النتيجة المتوقعة في النموذج المستهدف. وراجع إدارة المعاملات بعناية خاصة في الشيفرة التي تغيّر النموذج: يتطلب إجراء تغييرات على النموذج في Revit استخدام Transaction، ولا يمكن أن تكون هناك سوى Transaction واحدة مفتوحة في الوقت نفسه. عند إتمام المعاملة بنجاح، تُحفظ التغييرات باستخدام Commit؛ أما RollBack فيتراجع عنها. كما توضح وثائق Revit API إمكانية التحقق من حالات هذه العمليات.
أخطاء شائعة
الخلط بين سياق API والتحقق من المشروع: توفّر المهارة للوكيل مرجعًا حول أنواع API ومساحات الأسماء، لكنها لا تثبت أن الشيفرة الناتجة ستعمل على نحو صحيح في مشروع ما. اختبر بنفسك ما تفعله الشيفرة بالنموذج.
تجاهل تنظيم Transaction: يجب تنفيذ العمليات التي تغيّر النموذج ضمن سياق Transaction. ويمكن استخدام SubTransaction لتقسيم مهمة أكبر إلى أجزاء منطقية، لكن يجب إنشاؤها داخل Transaction مفتوحة وإغلاقها قبل إغلاق المعاملة الأساسية. ويمكن استخدام TransactionGroup للتعامل مع عدة عمليات مستقلة معًا؛ ولا يمكن بدء مجموعة جديدة بينما توجد Transaction مفتوحة.
إضافة ملفات غير ضرورية: يعرّف الدليل RevitAPIUI.dll على أنه مُدخل إضافي يمكن استخدامه عند الحاجة إلى طبقة واجهة المستخدم أيضًا. وبدلًا من إضافة محتوى لا تحتاج إليه، طابق نطاق المهارة مع المهمة.
افتراض تفاصيل الإصدار والتثبيت: لا يتضمن مقال APS جدول توافق مفصلًا أو أمر تثبيت. لذا دوّن مصدر تجميعة Revit المستخدمة، واتبع إرشادات dll2llm، ولا تفترض أن الإصدارات الأخرى ستنتج المخرجات نفسها.
الخطوات التالية: سير عمل العمارة والتصور المعماري
يمكن لفرق BIM التي تنفذ مهامًا متكررة لاستخراج البيانات أو تحرير النماذج في Revit، ومطوري الإضافات، والطلاب الذين يتعلمون API الاستفادة من هذه الطريقة. وقد يساعد تمكّن الوكيل من العثور على أصناف API على تقليل التخمينات الخاطئة للطرق أثناء إعداد النماذج الأولية. لكن ذلك لا يلغي مراجعة النموذج أو مراجعة الشيفرة أو اختبار سير العمل في ظروف المشروع الفعلية. وقد تظهر الفائدة في مكاتب العمارة والتصميم الداخلي، خصوصًا عند تطوير الأتمتة الداخلية ومساعدة أعضاء الفريق الجدد على استخدام API في البحث عن المراجع.
لا تُعد Revit API Agent Skill ميزة تحسّن جودة التصيير مباشرة؛ فهي موجّهة إلى عمليات البرمجيات والأتمتة التي تعمل مع بيانات النموذج. وبالنسبة إلى فريق التصور المعماري، قد يشمل مجال استخدامها تطوير أدوات تستخرج المعلومات من Revit أو تؤتمت التغييرات على النموذج. ولا توضح المصادر تكاليف الأجهزة أو التراخيص أو الاشتراكات الخاصة بالوكلاء. قبل بدء التطبيق، قيّم شروط البرامج الحالية ودعم بيئة الوكيل التي تستخدمها للمهارات على نحو مستقل.
المصدر والترخيص
أُعد هذا الدليل استنادًا إلى شروح dll2llm وAgent Skill الواردة في دليل “Let AI Write Your Revit Code” الصادر عن Autodesk Platform Services، وإلى تعريفات Transaction وSubTransaction وTransactionGroup في وثائق Revit API لدى Autodesk. وتُدرج المصادر الترخيص على أنه حر؛ وقد أُعيد شرح النص والخطوات بصياغة أصلية. كما استُخدم وصف دورة Autodesk University للمبتدئين في Revit API لدعم نطاق التعلم المتعلق بـ API والتصفية وTransaction.
المصادر
3 مصادرلا نعيد نشر نصوص المصادر؛ الاقتباسات القصيرة مشار إليها، وما تبقى ملخص وتعليق من إعدادنا.
بالنسبة إلى المكاتب والطلاب الذين يستخدمون Revit في تركيا، تكمن القيمة العملية لنهج Agent Skill في إتاحة مرجع أكثر تنظيمًا حول API ضمن سير عمل الوكيل. ويمكن للفرق التي تعمل خصوصًا على مهام متكررة لبيانات النموذج أو النماذج الأولية للإضافات مراجعة اقتراحات الشيفرة بسرعة أكبر.
مع ذلك، فإن مجلد المهارات ليس أتمتة مستقلة ولا إضافة تم التحقق من صحتها. ينبغي التحقق مسبقًا من إمكانية الوصول إلى ملفات DLL، ودعم بيئة الوكيل للمهارات، وشروط البرامج المستخدمة. ولأن المصادر لا توضح تكاليف الأجهزة أو التراخيص، يجب تحديد هذه البنود على نحو مستقل عند حساب الاستثمار.
الأسئلة الشائعة
ما الملفات المطلوبة لإنشاء Revit API Agent Skill؟
يوضح دليل Autodesk تزويد أداة dll2llm بملف RevitAPI.dll. ويمكن إضافة RevitAPIUI.dll أيضًا عند الحاجة إلى طبقة واجهة المستخدم.
ما المخرجات التي ينشئها dll2llm؟
وفقًا لدليل APS، تنشئ الأداة مجلد مهارات يحتوي على SKILL.md وINDEX.md وملفات Markdown للموضوعات مرتبة بحسب مساحات الأسماء.
هل يلزم استخدام Transaction في الشيفرة التي تغيّر النموذج في Revit؟
نعم. توضح وثائق Revit API أن إجراء تغييرات على النموذج يتطلب Transaction، وأنه لا يمكن أن تكون هناك سوى Transaction واحدة مفتوحة في الوقت نفسه.



