عقدة مجتمع موثقة: ثلاثة أسئلة الأهلية قبل إعادة كتابة بدون تبعيات

أسئلة
1

مرحباً بفريق n8n،

أنا أصون n8n-nodes-duckduckgo-search، وهي عقدة بحث DuckDuckGo خالية من بيانات الاعتماد بحوالي 21000 تثبيت. أود تقديمها للتحقق وقد اطلعت على المتطلبات، خاصة قاعدة عدم الاعتماد على مكتبات في وقت التشغيل. يعني الالتزام بها إزالة أربع تبعيات — axios وduck-duck-scrape و@mozilla/readability وlinkedom. يقوم الاثنان الأخيران بتشغيل استخراج نص المقالات في العقدة، واستبدالهما يتطلب إعادة كتابة كبيرة مع خطر حقيقي لتراجع الجودة.

قبل الالتزام بهذا العمل، هناك ثلاثة أشياء لم أتمكن من حسمها من التوثيق:
1. “يجب ألا تكون عقدة موجودة.” لا توجد عقدة DuckDuckGo في n8n اليوم، وهذه الحزمة لديها بالفعل ~21 ألف تثبيت، لذلك أفسر القاعدة بأنها لا تنطبق هنا. هل هذا صحيح، أم أنها تغطي أيضاً عقدة المجتمع الموجودة بالفعل؟

2. نقاط النهاية غير الرسمية. لا تنشر DuckDuckGo أي API للبحث. تستخدم العقدة نفس نقاط نهاية HTML/lite و API Instant Answer العام الذي تستخدمه جميع مكتبات DuckDuckGo. لا تتناول الإرشادات نقاط النهاية غير الرسمية بطريقة أو بأخرى. هل تكون عقدة مبنية عليها مؤهلة للتحقق أصلاً؟ إن لم تكن كذلك، فأفضل أن أعرف قبل البدء.

3. المراجعة من عنوان IP لمركز بيانات. تطبق DuckDuckGo حدود معدل لكل عنوان IP وتجيب على الانفجار برسالة حالة شاذة — HTTP 202 يحمل CAPTCHA، وليس حالة خطأ. سيصطدم المراجع الذي يختبر من البنية التحتية للسحابة بها بكل احتمال. تكتشف العقدة تلك الصفحة وتبلغ عنها بشكل صريح بدلاً من إرجاع قائمة فارغة، لذلك ما سيراه المراجع هو رسالة خطأ بدلاً من نتائج البحث. هل هناك طريقة لتوضيح هذا قبل المراجعة، أو طريقة مفضلة لإثبات أن العقدة تعمل؟

معلومات حول الحزمة

شكراً،
Sam Nodehi

2

مرحباً @Sam_Nodehi، بينما تنتظر الرد، إليك بعض الأشياء التي قد تساعدك:

الموارد المقترحة

تم مطابقتها تلقائياً مع سؤالك.

الوثائق:

المنتدى:

@Misha، @Baseman - لقد ساعدتما في حل مشاكل مماثلة من قبل، هل يمكنكما إلقاء نظرة؟

مقترح تلقائياً من قِبل روبوت مجتمع n8n. إنه تجربة توجيهية - يرجى مشاركة تعليقاتك هنا.

3

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

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

شخصياً، أزلنا جميع التبعيات الخارجية للتحقق واجعلناها تستخدم خوادمنا على الجانب الخادم. أحد العيوب هو أنه بالنسبة لحزمتنا الشهيرة https://github.com/turbodocx/html-to-docx، سنحتاج إلى حرق دورات الحوسبة على هذا وربما وضعها في خطتنا المحسوبة.

بخصوص السؤال 3، مشكلة عنوان IP لمركز البيانات: حقيقة أن عقدتك تكتشف صفحة الشذوذ وتبلغ عنها بوضوح بدلاً من إرجاع مصفوفة فارغة هي السلوك الصحيح، وسأضع هذا بالقرب من أعلى ملف readme بدلاً من ترك المراجع ليكتشفه. المراجع الذي يواجه حد المعدل ويرى رسالة واضحة “أرجعت DuckDuckGo صفحة شذوذ” يراقب معالجة الأخطاء الخاصة بك، وهو انطباع مختلف تماماً عن عقدة تبدو أنها لا ترجع شيئاً. قيل مقدماً، يبدو وكأنه قوة. قيل بعد ذلك، يبدو وكأنه عذر.

بخصوص السؤال 1، أقرأه بالطريقة التي تفعلها. “يجب ألا تكون عقدة موجودة” بدت لي دائماً وكأنها تعني عقدة طرف أول موجودة، لأن مسار التحقق بالكامل موجود للحزم المجتمعية. أيضاً - لست متأكداً إذا كان بإمكانك الحصول على عقدة فيها لا تعمل للشركة؟ لكن هذه قراءة وليست تأكيداً، وهي بالضبط نوع الشيء الذي يستحق الحصول عليه كتابة قبل أن تقضي الوقت والجهد.

4

شكراً، كان يستحق البحث عنه، لأنه إذا تم احتساب التجميع، فقد يغير القرار برمته. ذهبت وقمت بقياسه بدلاً من التفكير فيه، والإجابة تبين أنها «نعم، لكن ليس لهذه المكتبات».

أنت محق بشأن حقل dependencies. توثيق قواعد n8n الخاصة تقول ذلك بشكل صريح، no-runtime-dependencies.md:

يجب التصريح عن المكتبات المشتركة في peerDependencies (بحيث توفرها بيئة التشغيل المضيفة) أو تجميعها وقت البناء في القطعة المنشورة.

وno-restricted-imports.md يستثني أي شيء في devDependencies، على أساس أنه لن يتم تثبيته أثناء التشغيل. لذا فإن نقل المكتبات إلى devDependencies وتجميعها في dist يؤدي بالفعل إلى الامتثال لكلا القاعدتين.

الجزء الذي يقرر الأمر هو أن المسح له مرحلتان. من التعليق في scanner/scanner.mjs في @n8n/scan-community-package@0.35.0:

أنماط .ts تطابق فقط عملية الفحص المصادقة على الأصول، ومرحلة tarball تفحص .js المترجم وpackage.json المنشور فقط.

لذا تتم مراجعة الحزمة نفسها، وno-restricted-globals وno-dangerous-functions وno-console تنطبق على أي شيء أصدره المجمِّع.

مقاس، وليس مفترض. قمت بتجميع تماماً ثلاث مكتبات مشكلة لدي، axios و@mozilla/readability وlinkedom، باستخدام esbuild (مخرجات 1.1 ميجابايت)، ثم قمت بتشغيل إعدادات المسح الخاصة بـ n8n عليها عبر analyzePackage للماسح:

passed: false
✖ 125 problems (125 errors, 0 warnings)

التفصيل: process ×46، globalThis ×8، setTimeout ×15، clearTimeout ×9، setImmediate ×5، console. ×11. لا eval أو new Function، لما يستحق الذكر. وفئة واحدة لم أكن أتوقعها، يتم حظر البيئات المدمجة في Node أيضاً:

error  Require of 'stream' is not allowed. n8n Cloud does not allow community nodes with dependencies
error  Require of 'util' is not allowed.
error  Require of 'path' is not allowed.

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

هذا يتطابق أيضاً مع ما أخبرت به الفريق صاحب مشروع آخر في خيط سابق: أزل جميع الاعتمادات الخارجية، بما فيها الاعتمادات التي تستخدمها عقد n8n الخاصة بها.

شيئان آخران، في حالة أنهما مفيدان لأي شخص يقرأ:

متطلب الأصل واضح مباشرة بمجرد إعداده، ناشر موثوق على npm بالإضافة إلى id-token: write، لا توجد حزمة في أي مكان. فخ واحد: الناشرون الموثوقون لديهم إعداد السماح بالإجراءات الذي يمكن تسجيله كـ npm stage publish فقط، مما يفشل مع E403 OIDC permission denied for this action بعد أن تم بالفعل توقيع الأصل. وهو يتطلب npm ≥ 11.5.1، بينما actions/setup-node مع Node 22 لا يزال يرسل npm 10.

هناك أيضاً خطأ يستحق الإشارة إليه: على Windows، تموت مرحلة جلب المصدر للماسح مع مسار temp مشوه (tar: C\:\\Users\\...: Cannot open)، لذا تكتمل فقط فحص الأصل. لا يمكن لصاحب مشروع Windows تشغيل المسح الكامل محلياً.

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

حول السؤال 1، هذا هو فهمي أيضاً. نقطتك الثانية هي تلك التي لم أكن قد اعتبرتها، ما إذا كان n8n يقبل عقدة لخدمة ليس لديك انتماء لها. إضافة ذلك إلى ما كنت أود تأكيده.

5

@Sam_Nodehi
@Nicolas_Fry عمل رائع!.. كنت سأوضح أيضًا سؤال نقطة النهاية قبل إجراء إعادة الكتابة. نظرًا لأن DuckDuckGo لا توفر واجهة برمجية رسمية للبحث، فقد تكون بيئة اختبار المراجع مهمة تمامًا مثل العقدة نفسها. بخصوص مشكلة مركز البيانات/عنوان IP، أتفق على أن التوثيق الصريح لاستجابة 202 ومعالجة الشذوذ في ملف README خطوة جيدة. فهو يوفر للمراجع السياق بدلاً من جعل الاختبار الفاشل يبدو وكأنه عقدة معطلة. وبخصوص متطلبات التبعية، كنت بالتأكيد سأطلب تأكيدًا من n8n حول ما إذا كان التجميع/البيع بالتجزئة مقبولاً قبل إزالة readability وlinkedom - قد يوفر الكثير من عمل إعادة الكتابة غير الضروري.

6

شكراً لك @daniel_Samuel، وأنت محق في الإصرار على سؤال التجميع حتى بعد نشري القياس، لأن القياس يجيب على سؤال أضيق مما يبدو عليه.

ما أثبته هو ما يفعله الماسح الضوئي: تجميع axios و@mozilla/readability وlinkedom باستخدام esbuild، وتشغيل الإعدادات الخاصة بـ @n8n/scan-community-package على الناتج، فتحصل على 125 خطأ. جميعها تأتي من كود المكتبات نفسها، process ×46، globalThis ×8، setTimeout ×15، بالإضافة إلى require('stream') وrequire('util') وrequire('path').

ما لم يثبته هو ما إذا كان هذا الحكم هو السياسة المتبعة. process داخل تبعية مجمعة ليس “استخدام عام مقيد” بأي شكل قد يعترف به أي شخص، لم يكتبه أحد، لا يمكن الوصول إليه من السطح الخاص بالعقدة، والقاعدة التي ينتهكها موجودة لمنع العقد من فعل أشياء على n8n Cloud بدلاً من منع وجود تبعية. يمكن لمراجع أن يقرأها بطريقتين معقولتين، وفقط n8n يمكنها أن تقول أيهما.

لذا أعتقد أن السؤال الذي يجب طرحه عليهم أحد من “هل التجميع مقبول”، والذي توثيق قواعدهم الخاصة يجيب عليه بالفعل: no-runtime-dependencies تقول المكتبات المشتركة “يجب أن تُعلن في peerDependencies … أو تُجمّع وقت البناء في الأثر المنشور”، وno-restricted-imports تستثني أي شيء في devDependencies. بينهما، نقل المكتبات إلى devDependencies والتجميع يوضح كلا القاعدتين بنظافة. السؤال المفتوح هو الجزء بعد ذلك:

هل حكم الماسح الضوئي على كود الطرف الثالث المبيع ملزم، أم يمكن لمراجع أن يلغي النتائج التي تأتي من تبعية مجمعة بدلاً من مصدر العقدة نفسها؟

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

على الاثنين الآخرين، موافق وبالفعل تم. معالجة 202 والشذوذ أصبحت الآن أول شيء في README، فوق قائمة الميزات، توضح ما تعنيه مجموعة النتائج الفارغة ولا تعنيه، إطارك “السياق للمراجع بدلاً من اختبار فاشل يبدو وكأنه عقدة مكسورة” هو بالضبط لماذا. كتابة هذا أيضاً كشفت عن خطأ حقيقي: بحث الصور تحقق من صفحة الشذوذ على الطلب الذي يجلب الرمز لكن ليس على الذي يعيد النتائج، لذا كتلة هناك جاءت أيضاً كقائمة فارغة. تم إصلاحه، جنباً إلى جنب مع الفجوة نفسها على مسار 403.

لا توجد كلمة من أي شخص في n8n على الموضوع بعد. إذا لم يصل شيء هذا الأسبوع سأأخذ نفس الأسئلة الثلاثة إلى nodes@n8n.io وسأبلغ عودتي هنا بكلا الحالتين، لأن الإجابة ليست حقاً خاصة بـ DuckDuckGo، أي شخص عقدته يحتاج محلل HTML أو عميل HTTP يقف أمام نفس الجدار.

7

تحديث: تم إصدار الإصدار 32.17.0. يقرأ Extract Page Content و Fetch Page Content الآن أول 2 ميجابايت من الصفحات الكبيرة بدلاً من الفشل. يغطي انتهاء المهلة الزمنية للصفحة الآن التنزيل بأكمله. يتم تشغيل الاستخراج في خيط عامل، لذا لا يمكن لصفحة بطيئة جداً في التحليل أن تجمد n8n بعد الآن.

هناك قالبان مدمجان في العقدة الآن في المكتبة: