الاختبار والتحزيم
الحالة: مُخطَّط (لم يُبنَ بعد، المرحلة 1). حزمة تطوير البرمجيات (SDK)، وأداة
mkp، والقوالب، وبيئة الاختبار، والتثبيت من ملف، كلها لم تُبنَ بعد. تصف هذه الصفحة التصميم الوارد في القصة 54.12 و القصة 54.10، وهو قابل للتغيير.
اللغات
| المستوى | اللغة | سلسلة الأدوات | ملاحظات |
|---|---|---|---|
| 1 | Rust | cargo component، wit-bindgen |
أصغر المكوّنات وأسرعها |
| 1 | TypeScript / JavaScript | jco componentize |
|
| 1 | Python | componentize-py |
Python الخالصة فقط: لا NumPy ولا torch؛ استخدم خدمات المضيف |
| 2 | Go | TinyGo -target=wasip2 |
مجموعة فرعية من Go؛ بأفضل جهد ممكن |
تحصل لغات المستوى 1 على قوالب وأدوات مساعدة في حزمة التطوير واختبارات شاملة من البداية إلى النهاية مع كل تغيير في حزمة التطوير. ويحصل المستوى 2 على قالب واختبار دخاني. يمكن أن تعمل لغات أخرى تُنتج مكوّنات، لكن دون قالب.
العمل الثقيل (الإطارات المفكوكة الترميز، والصوت، والنصوص المفرّغة، والتضمينات، والنموذج اللغوي) تتولاه مكتبة ويُوصَل إليه عبر الواجهة البرمجية للإضافات، ولا يُضمَّن في إضافتك.
أداة mkp
أداة سطر أوامر واحدة لكل اللغات:
| الأمر | ما يفعله |
|---|---|
mkp new <template> <id> |
مشروع يضم manifest.toml وi18n/en.json وi18n/ar.json وعنصرًا نائبًا للأيقونة ومرحلة نموذجية وبيانات اختبار ثابتة واختبارًا |
mkp build |
يشغّل سلسلة أدواتك، ثم التحقق نفسه من البيان وتدقيق الواردات اللذين يجريهما الخادم المنزلي والمتجر |
mkp test |
يشغّل إضافتك في بيئة الاختبار المحلية على بيانات الاختبار الثابتة الخاصة بها |
mkp keys new، list، export-public |
مفتاح التوقيع Ed25519 الخاص بك |
mkp pack --sign |
يكتب files.json ويوقّعه ويصنع ملف .mkplugin |
mkp run --home <url> |
يثبّت على خادم منزلي في وضع المطوّر عبر الواجهة البرمجية للمشرف |
mkp submit |
يرفع إلى المتجر (المرحلة 2) |
يطابق إصدار حزمة التطوير إصدار الواجهة البرمجية للإضافات التي يستهدفها: mkp 1.2.x يبني لـ
maktaba:plugin@1.2.
تُولَّد الروابط البرمجية من WIT لكل لغة، مع أدوات مساعدة للأحداث ذات الأنواع، والمواضيع، ومُنشئ
للفصول، وكاتب WebVTT، وdata بوصفها خريطة مفتاح وقيمة، والتسجيل مع رموز.
البدء
mkp new rust dev.example.silence-chapters
cd silence-chapters
mkp build
mkp test
ثم عدّل manifest.toml (راجع البيان والحزمة)، وصرّح فقط عن القدرات التي
تستخدمها، وأضف النصوص بالإنجليزية والعربية معًا.
بيئة الاختبار
يضمّن mkp test شيفرة مضيف Wasmtime نفسها التي تشغّل الإضافات في الخادم المنزلي، إضافةً إلى
واجهة برمجية وهمية للإضافات في العملية نفسها.
- تخدم الواجهة الوهمية كل استدعاء من بيانات الاختبار الثابتة الخاصة بك:
fixtures/library.json(فيديوهات ومسلسلات)، وfixtures/media/(ملفات نموذجية صغيرة)، وfixtures/transcripts/. - تفرض القدرات والنطاق والحصص بجداول القواعد نفسها التي تستخدمها الواجهة البرمجية الحقيقية، فلا تتفاجأ في الخادم المنزلي إضافةٌ نجحت محليًا.
- تسجّل كل استدعاء في
trace.jsonمع مخرجاتك. يقارنهاmkp test --goldenبالنسخ المرجعية المخزّنة. - تستخدم حدود البيان الخاص بك. يستخدم
--limits strictحدود المراجعة في المتجر؛ شغّل الاختبار به قبل الإرسال.
تشغّل الفحوص الآلية في المتجر بيانات الاختبار الثابتة الخاصة بك عبر بيئة الاختبار نفسها، فاحرص على أن تكون ممثِّلة.
النماذج
| النموذج | اللغة | يوضّح |
|---|---|---|
silence-chapters |
Rust | media.audio، chapters.write |
tag-from-filename |
TypeScript | library.read، tags.write، الإعدادات |
arabic-title-normaliser |
Python | suggest، معالجة النص العربي |
weekly-report |
Go (TinyGo) | جدول زمني، data، notify.admin |
البناء والتحزيم
- يُنتج
mkp buildالملفplugin.wasm، ويفشل عند أي خطأ في البيان أو أي استيراد محظور. - يكتب
mkp pack --signالملفfiles.json(المسار وبصمة sha256 والحجم لكل ملف)، ويوقّعه بمفتاح المطوّر الخاص بك فيsignatures/developer.sig، ويصنع ملف.mkpluginبصيغةtar+ zstd. - تحقق من الحجم: 50 MB على الأكثر. يستهدف قالب «مرحبًا بالعالم» للغة Python حجمًا لا يتجاوز 25 MB.
التثبيت من ملف
يثبّت الخادم المنزلي حزمة من ملف، دون اتصال، من الإعدادات، ثم الإضافات، ثم التثبيت من ملف، أو بأداة سطر الأوامر:
maktaba-server plugins install silence-chapters-1.4.0.mkplugin
| يحمل الملف | يُثبَّت | الشارة |
|---|---|---|
| توقيع المتجر وتوقيع المطوّر (المرحلة 2) | دائمًا، كما من المتجر | لا شيء، أو «مُراجَعة» |
| توقيع المطوّر الخاص بك فقط | فقط عند تفعيل السماح بالإضافات غير المُراجَعة | غير مُراجَعة |
| بلا توقيع | فقط عند تفعيل السماح بالإضافات غير المُراجَعة | غير مُراجَعة |
| مجلد غير محزوم في وضع المطوّر | فقط عند تفعيل السماح بالإضافات غير المُراجَعة | قيد التطوير |
إلى أن يوجد المتجر، يُعدّ كل ملف غير مُراجَع. خيار السماح بالإضافات غير المُراجَعة معطّل افتراضيًا؛ ويطلب تفعيله كلمة مرور المشرف مجددًا ويُسجَّل في سجل التدقيق. ثم يراجع المشرف نافذة الأذونات ويكتب اسم الإضافة للتأكيد. العزل والصلاحيات الممنوحة والحصص متطابقة تمامًا بين الإضافات المُراجَعة وغير المُراجَعة.
وضع المطوّر
maktaba-server plugins dev ./silence-chapters
يثبّت وضع المطوّر من مجلد غير محزوم، ويراقبه، وعند أي تغيير يعيد التحقق ويعيد التحميل خلال نحو 5
ثوانٍ. يتطلب تفعيل السماح بالإضافات غير المُراجَعة، ويَسِم الإضافة بشارة «قيد التطوير»، ويزيلها
عند توقف الأمر إلا إذا مرّرت --keep. يعمل في المضيف نفسه وبيئة العزل نفسها كأي إضافة.
تضم أداة سطر الأوامر أيضًا list وshow وenable وdisable وstart وstop وupdate
وrollback وremove وgrants وpolicy، للخوادم المنزلية التي لا متصفح فيها.
تحديث إضافتك على خادم منزلي
- يُثبَّت الإصدار الجديد بجانب القديم. يُصرَّف الإصدار القديم، ثم يتولى الجديد العمل. ويُحتفظ بالإصدار السابق للتراجع إليه.
- إذا طلب الإصدار الجديد قدرات أكثر، فإنه ينتظر موافقة المشرف.
- ارفع قيمة
data_versionحين يتغير شكل بياناتك المخزّنة. يُرفض التراجع إلى إصدار ذيdata_versionأدنى إلا إذا مسح المشرف بيانات إضافتك أيضًا. - حين يعطّل المشرف إضافتك، تبقى معطّلة عبر التحديثات والاستعادات وإعادة التثبيت حتى يفعّلها مشرف.