الإضافات

اختر سطح التمديد

@cadcamfun/plugin-sdk يحدد عقد البرنامج المساعد للعامل مع أ plugin.json البيان وإصدار API 1. يعرض مضيفه الخدمات التي يتم التحكم في قدراتها ويقوم بتشغيل وظائف المكونات الإضافية في عمال Bun. يقبل مُحمل مساعد الإنتاج حاليًا المكونات الإضافية التي تطلب فقط ai:tool.

ال /api/plugins تستخدم عائلة HTTP عقدًا مختلفًا للمكونات الإضافية للمتصفح: حزم ZIP مع manifest.json, a main الإدخال وأذونات المتصفح والتكوين وJavaScript bootstrap. إن تثبيت الحزمة من خلال واجهة برمجة التطبيقات هذه لا يجعلها مكونًا إضافيًا لـ SDK عاملاً. استخدم البيان ودورة الحياة المطابقين للتكامل المقصود.

بيان SDK للعامل

{
  "id": "com.example.shop-helper",
  "name": "Shop helper",
  "version": "1.0.0",
  "apiVersion": "1",
  "entry": "index.js",
  "capabilities": ["ai:tool"],
  "contributes": {
    "aiTools": [{
      "id": "lookup",
      "description": "Look up the shop's documented inspection checklist.",
      "kind": "read",
      "parameters": { "type": "object", "properties": {} },
      "entry": "lookup"
    }]
  }
}

تستخدم المعرفات نموذج DNS العكسي، والإصدار دلالي major.minor.patch مع الإصدار التجريبي الاختياري، و apiVersion يجب أن يكون "1". ترتبط مسارات الإدخال بدليل البرنامج المساعد. يمكن أن تعلن المساهمات عن الأوامر واللوحات والمعالجات اللاحقة والعمليات والأدوات المساعدة؛ إن الإعلان عن مساهمة لا يؤدي إلى توصيل هذه الميزة إلى كل مضيف.

يسمح المخطط اختياري signature و dev الحقول. يقوم مضيف العامل الحالي بتسجيل هذه القيم ولكنه لا يقوم بالتحقق من توقيع التشفير أثناء التثبيت. لا يعد حقل التوقيع وحده دليلاً على وجود ناشر معتمد.

إدخال الوحدة ووظائف الذكاء الاصطناعي

definePlugin هو مساعد هوية مكتوب لوحدة تحتوي على بيان و activate(ctx). قد يؤدي التنشيط إلى إرجاع وظيفة التنظيف، وقد يتم كشف الوحدة deactivate. يصف SDK خطافات دورة الحياة هذه؛ ويعتمد توفرها على العامل الأساسي للخرسانة، كما هو مفصل أدناه.

يتم تصدير وظائف المساعد من خلال aiTools سِجِلّ؛ المساهمة entry يسمي الوظيفة في هذا السجل. تشتمل مساهمة الأداة على وصفها ومخطط معلمة JSON و read أو write عطوف. يتم توجيه أداة الكتابة من خلال طلب موافقة بشرية في المساعد المضمن؛ يستقبل الجسر الخارجي أدوات القراءة الإضافية المسموح بها فقط.

قم بتجميع إدخال العامل كوحدة نمطية قائمة بذاتها. يقرأ المضيف العامل مصدر الإدخال ويستورده من خلال وحدة blob. تعامل مع عمليات استيراد الحزم أو الملفات النسبية باعتبارها مشكلة تكامل منفصلة بدلاً من افتراض محمل نظام الملفات على نمط العقدة.

واجهات برمجة التطبيقات التي يتم التحكم فيها بالقدرة

يتعرف SDK drawing:read, drawing:write, toolpath:read, storage, ui:panel، و ai:tool. رسم الكتابة يعني رسم القراءة. يستمد المضيف العام القدرات الفعالة من البيان المثبت ويتحقق منها على RPC؛ يقرر تطبيق التضمين البيانات والأسطح التي يرغب في تحميلها.

يمكن أن يعرض سياق SDK قراءات الرسم وتصحيحات إضافة/تحديث/إزالة Entity، وقراءات مسار الأدوات/البرنامج، وتخزين قيمة مفتاح السلسلة الخاصة، وتسجيل الأوامر/اللوحة التعريفية. الخدمات المفقودة غائبة عن السياق. استخدام مفاتيح التخزين plugin:<id>: مساحات الأسماء ورفض المفاتيح المطلقة أو مفاتيح الاجتياز الأصل.

يدعم محمل مساعد الإنتاج فقط ai:tool. يتم تخطي البيان الذي يطلب إمكانيات الرسم أو مسار الأدوات أو التخزين أو واجهة المستخدم مع ظهور تحذير. ولا يمنح هذه الأسطح بصمت أو يحمّل قدراتها الأوسع في المضيف المساعد.

التحميل ودورة حياة العامل

لتمكين ملحق مساعد، ضعه plugin.json والدخول المجمعة تحت <dataDir>/plugins/<id>/ وقم بإدراج المعرف في <dataDir>/plugins/enabled.json، مصفوفة JSON. يجب أن يتطابق معرف المجلد مع البيان. يحدث التحميل أثناء إنشاء خدمة البرنامج الإضافي المساعد؛ يقوم البرنامج الإضافي الفاشل بتسجيل تحذير دون إيقاف التطبيق.

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

يبدأ العمال ببيئة فارغة ويقوم التمهيد بإزالة واجهات برمجة التطبيقات العامة المحددة. يعد هذا تقييدًا على مستوى التطبيق، وليس وضع حماية لنظام التشغيل: تظل Bun globals قابلة للوصول. قم بتمكين كود الامتداد المناسب للتشغيل داخل حدود عملية التطبيق فقط.

حدود وقت التشغيل

يحدد المضيف إعداد ذاكرة عامل يبلغ 256 ميجابايت، وحد معدل 2،000-مكالمة في الدقيقة، و64 من المكالمات المعلقة على الأكثر لكل مكون إضافي. يتم توفير سلوك مهلة الأمر بواسطة مضيف التضمين؛ يستخدم المُحمل المساعد 10 ثانية. استدعاءات أدوات الذكاء الاصطناعي لها موعد نهائي منفصل يبلغ 30 ثانية. تؤدي المهلات، والأدوات الغائبة، وتعطل العمال، وفشل القدرة، واستنفاد قائمة الانتظار إلى إرجاع فشل المضيف المكتوب أو نتائج الأداة القابلة للقراءة.

يعطل تتبع الأعطال أحد المكونات الإضافية بعد ثلاثة حوادث في غضون عشر دقائق. ترتبط عناصر التحكم المضيفة هذه بـ RPC التعاوني وسلوك دورة الحياة؛ إعداد الذاكرة الذي تم تمريره إلى Bun ليس بديلاً عن ملف قابل للتنفيذ معزول بشكل منفصل.

يتم تعريف الحدود في apps/sidecar/src/plugins/host.ts: CALL_TIMEOUT_MS (5،000 مللي ثانية لكل مكالمة عادية)، AI_TOOL_TIMEOUT_MS (30،000 مللي ثانية لكل استدعاء أداة مساعد)، MEMORY_LIMIT_MB (256), CALL_RATE_LIMIT (2،000 مكالمات لكل مكون إضافي في الدقيقة)، MAX_PENDING_CALLS (64)، و CRASH_LIMIT (يتعطل 3 خلال 10-دقيقة CRASH_WINDOW_MS، وبعد ذلك يتم تعطيل المكون الإضافي تلقائيًا).

تثبيت ZIP وواجهة برمجة تطبيقات البرنامج المساعد للمتصفح

POST /api/plugins/install يقبل أرشيفًا متعدد الأجزاء. يقرأ المثبت manifest.json من جذر ZIP أو من دليل واحد عالي المستوى، يتحقق من صحة بيان المكون الإضافي للمتصفح، ويخزن ملفاته تحت <dataDir>/storage/plugins/<id>/. يظهر المتصفح الاستخدام main, engines.cadcamوقائمة أذونات المتصفح، بدلاً من SDK entry, apiVersion، والإمكانيات.

GET /api/plugins يسرد تلك الإدخالات المثبتة؛ تعمل نقاط النهاية التفصيلية والتمكين/التعطيل وإلغاء التثبيت والتحديث والتكوين على السجل الخاص بها. /api/plugins/bootstrap.js?id=… يخدم جافا سكريبت. /api/plugins/serve?id=…&file=… يقدم ملفات البرنامج المساعد. هذه هي عمليات نصية/ثنائية مع أنواع المحتوى المعلنة الخاصة بها.

يقرأ متصفح التسجيل المحلي بيانات تعريف الحزمة ضمن <dataDir>/plugins-registry. إنه كتالوج البيان المحلي. يعد تثبيت الأرشيف وقائمة التسجيل وتحميل ملحق المساعد العامل عمليات منفصلة.

مساعدين SDK

effectiveCapabilities, hasCapability، و missingCapabilities فحص قدرة الدعم. requireCapability يثير خطأ في القدرة عند غياب سطح السياق المطلوب. storageNamespace و storageKey بناء مفاتيح مساحة الاسم؛ parseManifest التحقق من صحة JSON؛ manifestKey تنسيقات زوج معرف/الإصدار.

مداخل التنفيذ

packages/plugin-sdk/src يمتلك البيان العام، والقدرة، والسياق، والمكونات الإضافية، وواجهات برمجة تطبيقات المضيف الاختباري. apps/sidecar/src/plugins/host.ts يمتلك دورة حياة العامل وRPC؛ services/ai-plugins.ts يمتلك تحميل ملف الموافقة وتسجيل المساعد. يتم تنفيذ تثبيت المتصفح في http/plugins.ts و repos/plugin-registry-repo.ts.

مراجعة الامتداد

حافظ على دقة مخططات المساهمة، وقم بإرجاع نتائج منظمة صغيرة، وأعلن عن سلوك القراءة/الكتابة بأمانة. الاختبار مقابل مضيف التضمين الفعلي: لا يؤدي توفر SDK إلى إنشاء وصول الإنتاج إلى الرسم أو التخزين أو واجهة المستخدم أو سجلات النشر. ال البرنامج المساعد nikcli مستقل هو عميل إجراء HTTP وله غرض مختلف عن التعليمات البرمجية المحملة في العامل.

أكمل نموذج الوحدة النمطية للمساعد

ال plugin.json المثال أعلاه الأسماء aiTools.lookup. هذا هو المقابل بذاته index.js. يتم تشغيل رمز الوحدة النمطية ذات المستوى الأعلى عند استيرادها؛ تعمل وظيفة البحث المعلنة عند استدعائها.

export const aiTools = {
  lookup: async () => ({
    ok: true,
    checklist: [
      "Compare the drawing revision with the job traveller.",
      "Record the measuring instrument and its calibration status.",
      "Record each inspected dimension and the measured value."
    ]
  })
}

هذه هي نماذج لتعليمات المتجر، وليست معيار فحص مدمج. استبدلها بالمحتوى الذي تمتلكه الإضافة بالفعل. للسماح بهذه الوحدة عند تهيئة الخدمة التالية، الملف الممكّن هو:

["com.example.shop-helper"]

يعرض الكتالوج قيد التشغيل معرفًا مشتقًا من معرفات المكونات الإضافية والأدوات. اكتشفها من خلال GET /api/ai/actions; لا تفترض أن سجل ZIP للمتصفح هو القائمة الممكّنة للمساعد. إعادة تحميل التطبيق/الخدمة هي الطريقة الموثوقة لإعادة قراءة ملف الموافقة على الإنتاج؛ لم يتم تكوين أي مراقب لنظام الملفات بواسطة هذا المُحمل.

مصدر: apps/sidecar/src/services/ai-plugins.ts, packages/ai/src/tools/plugin-tool.ts، و apps/sidecar/test/ai-plugin-tools.test.ts.

مخططات الوسيطة وحدود دورة الحياة

يجب أن يبدأ المعرف المحلي للأداة بحرف صغير وأن يحتوي على أحرف صغيرة أو أرقام أو شرطات سفلية، بحد أقصى 40 حرف. تحتوي الأوصاف على 10–2،000 حرفًا. يجب أن تسمي المساهمة وظيفة إدخال غير فارغة ومخطط معلمة JSON. يقوم محول التطبيق بالتحقق من صحة الوسائط قبل استدعاء العامل؛ يمكن أن يؤدي الرفض إلى إرجاع منظم ok: false النتيجة دون إنهاء البرنامج المساعد.

يصف SDK العام activate، تنظيف، و deactivate نقاط الدخول. تعترف معالجات تنشيط/إلغاء تنشيط RPC الخاصة بعامل Bun bootstrap الحالي برسائل دورة الحياة ولكنها لا تستدعي وظائف الوحدة النمطية المصدرة. لذلك يجب أن تضع ملحقات المساعد سلوكها القابل للاستدعاء aiTools وتجنب الاعتماد على عمليات الاسترجاعات لتنشيط SDK للإعداد أو التنظيف.

يحتوي التمهيد العام للعامل أيضًا على معالجات الرسم/مسار الأدوات/واجهة المستخدم النائبة. أنها لا تشكل رسم الإنتاج أو تكامل واجهة المستخدم. تقييد مساعد المحمل على ai:tool يمنع الإعلان عن هذه الأسطح غير المدعومة على أنها وصول لتطبيقات العمل.

مصدر: packages/plugin-sdk/src/manifest.ts, plugin.ts, apps/sidecar/src/plugins/host.ts (PLUGIN_BOOTSTRAP)، و services/ai-plugins.ts.

تشخيص الامتداد المفقود أو الفاشل

• لا توجد أدوات في الكتالوج: تحقق من JSON الممكّن الصالح، والمطابقة الدقيقة لمعرف المجلد/البيان، وفك تشفير البيان، و ai:tool القدرة. اقرأ تحذير بدء التشغيل الخاص بالمكون الإضافي الذي تم تخطيه.
• الطلبات الواضحة للأسطح غير المدعومة: قم بإزالة الإمكانات غير المدعومة فقط إذا كانت التعليمات البرمجية لا تحتاج إليها حقًا. لا يمكن للمكون الإضافي المساعد الحصول على حق الوصول للرسم والكتابة بمجرد الإعلان عنه.
• لا يوجد أداة: يصنع contributes.aiTools[].entry تطابق دالة تم تصديرها ضمن aiTools. يخدم معرف المساهمة واسم الإدخال أغراضًا مختلفة.
• فشل التحقق من صحة الوسيطة: فحص مخطط JSON والحقول المطلوبة. يتم رفض القيم الخاطئة قبل التنفيذ، كما يتضح من اختبارات العامل الحقيقي وتكامل التطبيقات.
• المهلة أو الحالة الخاطئة: التحقيق في حظر العمل، أو الوعود التي لم يتم حلها، أو الأعطال؛ الأعطال المتكررة تتسبب في خطأ البرنامج المساعد. إعادة التمكين فقط بعد تصحيح السبب.
• يرفض مثبت ZIP البيان: استخدم البرنامج المساعد للمتصفح manifest.json العقد لنقطة النهاية تلك. إعادة تسمية العامل plugin.json لا يترجم مجالاته.

مصدر: apps/sidecar/test/plugins-ai-tools.test.ts, ai-plugin-tools.test.ts, plugins-http.test.ts، و src/plugins/host.ts.

مرجع واضح

يشحن كل مكون إضافي أ plugin.json. parseManifest(json) يوزعه ويتحقق من صحته في خطوة واحدة، مما يحول خطأ بناء جملة JSON إلى نفس قناة الخطأ كخطأ في المخطط، لذلك تحتاج شاشة التثبيت فقط إلى معالجة نوع فشل واحد.

المساعدون: manifestKey(m) يعود id@version; requestedCapabilities(m) إرجاع قائمة القدرات التي تم فرزها للعرض؛ isDevPlugin(m) و isSigned(m) أجب عن أسئلة سياسة التثبيت.

القدرات وسياق البرنامج المساعد

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

اختبر مكونًا إضافيًا باستخدام مضيف اختبار SDK

import { cad } from "@cadcamfun/core"
import { createTestHost, definePlugin, requireCapability, testManifest } from "@cadcamfun/plugin-sdk"

const manifest = testManifest({
  id: "com.example.frame",
  capabilities: ["drawing:write", "storage", "ui:panel"],
})

const plugin = definePlugin({
  manifest,
  activate(ctx) {
    const drawing = requireCapability(ctx, "drawing:write", "drawing")
    ctx.ui?.registerCommand({ id: "frame.add", title: "Add frame line" })
    ctx.storage?.set("runs", "1")
    drawing.patch({
      _tag: "AddEntity",
      entity: { ...cad.baseEntity("frame-1"), _tag: "Line",
                start: { x: 0, y: 0 }, end: { x: 100, y: 0 } },
    })                                   // returns revision 1
    return () => ctx.log.info("teardown") // runs on deactivation
  },
})

const host = createTestHost({ manifest, drawing: cad.emptyDrawing("d1", "Demo") })
const stop = await host.activate(plugin)
host.drawing()?.entities.length     // 1
host.context.storage?.get("runs")   // "1"
host.ui.commands                    // [{ id: "frame.add", title: "Add frame line" }]
await stop()

// Without the grant, requireCapability throws:
const denied = createTestHost({ manifest, granted: ["storage"] })
await denied.activate(plugin)
// CapabilityError: Plugin com.example.frame may not use "drawing:write":
// it was not granted at install time

• testManifest(overrides) يبدأ من بيان صالح الحد الأدنى (com.example.test-plugin، الإصدار 1.0.0، واجهة برمجة التطبيقات 1، الإدخال index.js، لا توجد إمكانيات).
• granted الإعدادات الافتراضية لكل ما يطلبه البيان. قم بتمرير قائمة أصغر لاختبار المسارات المرفوضة.
• host.storage هي لقطة تم التقاطها عند إنشاء المضيف. قراءة القيم الحية من خلال host.context.storage.
• host.on(commandId, handler) و host.invoke(commandId, args) ممارسة الأوامر المسجلة.
• runPostProcessor يدير منشورًا ساهم به ضد أحد البرامج، و keyOf(pluginId, key) يعرض مفتاح التخزين بمساحة الاسم حتى تتمكن الاختبارات من تأكيد العزل.

كيفية تحميل التطبيق للمكونات الإضافية المساعدة

1. عند بدء التشغيل يقرأ السايدكار <data dir>/plugins/enabled.json، مجموعة JSON من معرفات المكونات الإضافية. لا يتم تحميل أي شيء إلا إذا كان مدرجًا هناك.
2. لكل معرف يقرأ <data dir>/plugins/<id>/plugin.json ويقوم بتوزيعها. يجب أن يكون اسم المجلد مساويًا للبيان id.
3. فقط ai:tool السلكية في هذا المضيف. يتم تخطي البيان الذي يطلب الرسم أو مسار الأدوات أو التخزين أو الوصول إلى واجهة المستخدم مع تحذير بدلاً من تحميله بأسطح لا تفعل شيئًا بصمت.
4. تم تثبيت البرنامج المساعد في مضيف عامل وتمكينه. مكون إضافي يفشل في تحميل السجلات Plugin <id> was not loaded: ... ولا يتوقف التطبيق عن البدء أبدًا.
5. يتم تقديم كل أداة ساهم بها إلى المساعد plugin_<slug of plugin id>_<tool id>، على الأكثر 80 حرفًا، حيث يقوم الرمز الثابت بتصغير المعرف واستبدال الأحرف الأخرى بشرطات سفلية. com.example.bolt-circle مع الأداة bolt_circle يصبح plugin_com_example_bolt_circle_bolt_circle.
6. يتم التحقق من صحة الوسائط مقابل مخطط JSON الخاص بالأداة قبل أن يراها العامل. إذا تجاوز المخطط 20،000 من الأحرف، أو لم يكن مخطط كائن، أو لا يمكن تحويله، يقبل المضيف أي كائن ويجب التحقق من صحة المكون الإضافي.
7. تعود المكالمة التي تنتهي مهلتها أو تعثر على المكون الإضافي { ok: false, error } (نص خطأ يصل إلى 500 حرفًا) للمساعد بدلاً من إيقاف المنعطف. أ write يتم التأكد من الأداة مع الشخص قبل كل مكالمة مهما كانت حججها.

تم اختبار المعرف وقواعد الإصدار

أنواع المساهمة

حقول البيان الأخرى: signature (Ed25519 فوق تجزئة الأرشيف، وهو مطلوب لعمليات التثبيت المجمعة) و dev (المكون الإضافي للتطوير المحلي: يتخطى عمليات التحقق من التوقيع ويظهر شارة).

تم اختبار دقة القدرة

import { effectiveCapabilities, missingCapabilities, storageKey, requireCapability } from "@cadcamfun/plugin-sdk"

effectiveCapabilities(["drawing:write", "storage"])
// ["drawing:read", "drawing:write", "storage"]   (write implies read; sorted)

missingCapabilities(["drawing:read", "toolpath:read", "ai:tool"], ["drawing:write"])
// ["toolpath:read", "ai:tool"]

storageKey("com.example.gear", "presets/m2")   // "plugin:com.example.gear:presets/m2"
storageKey("com.example.gear", "../x")
// RangeError: storage key "../x" may not escape the plugin namespace   (same for "/abs")

requireCapability(ctxWithoutDrawing, "drawing:read", "drawing")
// CapabilityError (_tag "CapabilityDenied"):
// Plugin com.example.gear may not use "drawing:read": it was not granted at install time

في 3د