إنتقل إلى المحتوى الرئيسي

المفاجآت المعروفة

يتتبع هذا الملف نقاط الارتباك الخاصة بالمستودع والتي تسببت في أخطاء الوكيل.

معايير الدخول​

أضف إدخالاً فقط إذا كانت جميعها صحيحة:

  • إنها خاصة بهذا المستودع (وليست نصيحة عامة).
  • من المحتمل أن يتكرر بالنسبة للوكلاء المستقبليين.
  • لديها تخفيف ملموس يمكن اتباعه.

إذا كنت غير متأكد، اسأل المطور قبل إضافة إدخال.

قالب الإدخال​

### [Short title]

- **Date:** YYYY-MM-DD
- **Observed by:** agent name or contributor
- **Context:** where/when it happened
- **What was surprising:** concrete unexpected behavior
- **Impact:** what went wrong or could go wrong
- **Mitigation:** exact step future agents should take
- **Status:** confirmed | superseded

إدخالات​

يقوم Portless بتغيير عنوان URL للتطبيق المحلي الأساسي​

  • التاريخ: 18-03-2026
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • السياق: التحقق من المتصفح وتدفق الدخان
  • ما كان مفاجئًا: عنوان URL المحلي الافتراضي ليس هو منفذ Vite المعتاد. يتوقع الريبو https://bitsocial.localhost من خلال Portless، لذا فإن التحقق من localhost:3000 أو localhost:5173 يمكن أن يؤدي إلى التطبيق الخاطئ أو لا شيء على الإطلاق.
  • التأثير: يمكن أن تفشل عمليات فحص المتصفح أو تتحقق من صحة الهدف الخاطئ حتى عندما يكون خادم التطوير سليمًا.
  • التخفيف: استخدم https://bitsocial.localhost أولاً. يمكنك تجاوزه فقط باستخدام PORTLESS=0 corepack yarn start عندما تحتاج بشكل صريح إلى منفذ Vite مباشر.
  • الحالة: مؤكد

تعمل خطافات الالتزام على حظر الالتزامات غير التفاعلية​

  • التاريخ: 18-03-2026
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • السياق: سير عمل الالتزام الذي يحركه الوكيل
  • ما كان مفاجئًا: يقوم git commit بتشغيل Commitizen من خلال Husky وينتظر إدخال TTY التفاعلي، الذي يعلق أصداف الوكيل غير التفاعلية.
  • التأثير: يمكن للوكلاء المماطلة إلى أجل غير مسمى خلال ما ينبغي أن يكون التزامًا عاديًا.
  • التخفيف: استخدم git commit --no-verify -m "message" للالتزامات التي أنشأها الوكيل. لا يزال بإمكان البشر استخدام corepack yarn commit أو corepack yarn exec cz.
  • الحالة: مؤكد

مطلوب Corepack لتجنب الغزل الكلاسيكي​

  • التاريخ: 2026-03-19
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • السياق: ترحيل مدير الحزم إلى Yarn 4
  • ما كان مفاجئًا: لا يزال الجهاز يحتوي على تثبيت عالمي لـ Yarn Classic على PATH، لذلك يمكن أن يؤدي تشغيل yarn العادي إلى الإصدار v1 بدلاً من إصدار Yarn 4 المثبت.
  • التأثير: يمكن للمطورين تجاوز تثبيت مدير الحزم الخاص بمستودع الريبو عن طريق الخطأ والحصول على سلوك تثبيت مختلف أو إخراج ملف قفل.
  • التخفيف: استخدم corepack yarn ... لأوامر shell، أو قم بتشغيل corepack enable أولاً بحيث يتم حل yarn بشكل عادي مع إصدار Yarn 4 المثبت.
  • الحالة: مؤكد

تتعارض أسماء التطبيقات التي لا تحتوي على منفذ والتي تم إصلاحها عبر أشجار عمل Bitsocial Web​

  • التاريخ: 2026-03-30
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • السياق: بدء yarn start في شجرة عمل Bitsocial Web بينما كانت شجرة عمل أخرى تخدم بالفعل من خلال Portless
  • ما كان مفاجئًا: استخدام اسم التطبيق الحرفي bitsocial في كل شجرة عمل يجعل المسار نفسه يتعارض، حتى عندما تكون منافذ الدعم مختلفة، لذلك تفشل العملية الثانية لأن bitsocial.localhost مسجل بالفعل.
  • التأثير: يمكن لفروع ويب Bitsocial المتوازية أن تحظر بعضها البعض على الرغم من أن Portless يهدف إلى السماح لها بالتعايش بأمان.
  • التخفيف: حافظ على بدء التشغيل بدون منفذ خلف scripts/start-dev.mjs، والذي يستخدم الآن مسار *.bitsocial.localhost على نطاق فرعي خارج الحالة الأساسية ويعود إلى مسار على نطاق فرعي عندما يكون اسم bitsocial.localhost المجرد مشغولًا بالفعل.
  • الحالة: مؤكد

يتم استخدام معاينة المستندات للمنفذ الثابت رقم 3001​

  • التاريخ: 2026-03-30
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • ** السياق: ** تشغيل yarn start جنبًا إلى جنب مع اتفاقيات إعادة الشراء والوكلاء المحليين الآخرين
  • ما كان مفاجئًا: قام أمر root dev بتشغيل مساحة عمل المستندات باستخدام docusaurus start --port 3001، لذلك فشلت جلسة التطوير بأكملها عندما كانت عملية أخرى مملوكة بالفعل لـ 3001، على الرغم من أن التطبيق الرئيسي يستخدم Portless بالفعل.
  • التأثير: قد يؤدي yarn start إلى إيقاف عملية الويب فورًا بعد تشغيلها، مما يؤدي إلى مقاطعة العمل المحلي غير ذي الصلة عبر تصادم منفذ المستندات.
  • التخفيف: حافظ على بدء تشغيل المستندات خلف yarn start:docs، والذي يستخدم الآن Portless بالإضافة إلى scripts/start-docs.mjs لاحترام منفذ مجاني تم حقنه أو الرجوع إلى المنفذ التالي المتاح عند التشغيل مباشرة.
  • الحالة: مؤكد

كان اسم المضيف الذي تم إصلاحه في المستندات غير المحمولة مشفرًا بشكل ثابت​

  • التاريخ: 2026-04-03
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • السياق: تشغيل yarn start في شجرة عمل Bitsocial Web الثانوية بينما كانت شجرة عمل أخرى تقدم المستندات بالفعل من خلال Portless
  • ما كان مفاجئًا: لا يزال start:docs يسجل اسم المضيف docs.bitsocial.localhost الحرفي، لذا قد يفشل yarn start على الرغم من أن التطبيق about يعرف بالفعل كيفية تجنب تصادمات المسار غير المنفذ لاسم المضيف الخاص به.
  • التأثير: لم تتمكن أشجار العمل المتوازية من استخدام أمر root dev بشكل موثوق لأن عملية المستندات خرجت أولاً ثم قام concurrently بإنهاء بقية الجلسة.
  • التخفيف: حافظ على بدء تشغيل المستندات خلف scripts/start-docs.mjs، والذي يستمد الآن نفس اسم المضيف Portless على نطاق الفرع مثل التطبيق about ويدخل عنوان URL العام المشترك هذا في هدف وكيل التطوير /docs.
  • الحالة: مؤكد

يمكن أن تفوت قذائف Worktree إصدار العقدة المثبتة في الريبو​

  • التاريخ: 2026-04-03
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • السياق: تشغيل yarn start في أشجار عمل Git مثل .claude/worktrees/* أو عمليات سحب شجرة العمل الشقيقة
  • ما كان مفاجئًا: قامت بعض أغلفة شجرة العمل بحل node وyarn node إلى Homebrew Node 25.2.1 على الرغم من أن دبابيس الريبو 22.12.0 في .nvmrc، لذلك يمكن لـ yarn start تشغيل مشغلات التطوير بصمت في وقت التشغيل الخاطئ.
  • التأثير: يمكن أن ينجرف سلوك خادم المطورين بين منطقة الدفع الرئيسية وأشجار العمل، مما يجعل من الصعب إعادة إنتاج الأخطاء وانتهاك سلسلة أدوات Node 22 المتوقعة من الريبو.
  • التخفيف: احتفظ بمشغلات التطوير خلف scripts/start-dev.mjs وscripts/start-docs.mjs، والتي يتم الآن إعادة تنفيذها ضمن العقدة الثنائية .nvmrc عندما يكون Shell الحالي على الإصدار الخاطئ. يجب أن يظل إعداد Shell يفضل nvm use.
  • الحالة: مؤكد

يمكن لبقايا docs-site/ إخفاء مصدر المستندات المفقود بعد إعادة البناء​

  • التاريخ: 2026-04-01
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • السياق: تنظيف monorepo بعد الدمج بعد نقل مشروع Docusaurus من docs-site/ إلى docs/
  • ما كان مفاجئًا: يمكن أن يظل مجلد docs-site/ القديم على القرص بملفات قديمة ولكن مهمة مثل i18n/، حتى بعد نقل الريبو المتعقب إلى docs/. وهذا يجعل عملية إعادة البناء تبدو مكررة محليًا ويمكن أن تخفي حقيقة أن ترجمات المستندات المتعقبة لم يتم نقلها فعليًا إلى docs/.
  • التأثير: يمكن للوكلاء حذف المجلد القديم باعتباره "غير هام" وفقدان النسخة المحلية الوحيدة من ترجمات المستندات عن طريق الخطأ، أو الاستمرار في تحرير البرامج النصية التي لا تزال تشير إلى مسار docs-site/ الميت.
  • التخفيف: تعامل مع docs/ باعتباره مشروع المستندات الأساسي الوحيد. قبل حذف أي بقايا docs-site/ المحلية، قم باستعادة المصدر المتعقب مثل docs/i18n/ وقم بتحديث البرامج النصية والخطافات لإيقاف الإشارة إلى docs-site.
  • الحالة: مؤكد

يمكن أن تؤدي معاينة المستندات متعددة اللغات إلى زيادة ذاكرة الوصول العشوائي (RAM) أثناء التحقق​

  • التاريخ: 2026-04-01
  • ** تمت مراقبته بواسطة: ** الدستور الغذائي
  • السياق: إصلاح المستندات i18n والتوجيه المحلي وسلوك البحث عن الصفحات باستخدام yarn start:docs بالإضافة إلى Playwright
  • ما كان مفاجئًا: يعمل وضع معاينة المستندات الافتراضي الآن على إنشاء مستندات كاملة متعددة اللغات بالإضافة إلى فهرسة Pagefind قبل العرض، ويمكن أن يستهلك الحفاظ على هذه العملية إلى جانب جلسات Playwright أو Chrome المتعددة ذاكرة الوصول العشوائي (RAM) أكثر بكثير من حلقة Vite العادية أو حلقة تطوير Docusaurus ذات لغة واحدة.
  • التأثير: يمكن أن يصبح الجهاز مقيدًا بالذاكرة، ويمكن أن تتعطل جلسات المتصفح، ويمكن أن تؤدي عمليات التشغيل المتقطعة إلى ترك خوادم مستندات قديمة أو متصفحات مقطوعة الرأس مما يؤدي إلى استهلاك الذاكرة.
  • التخفيف: بالنسبة إلى عمل المستندات الذي لا يحتاج إلى التحقق من المسار المحلي أو البحث عن صفحة، يفضل DOCS_START_MODE=live yarn start:docs. استخدم المعاينة الافتراضية متعددة اللغات فقط عندما تحتاج إلى التحقق من صحة المسارات المترجمة أو Pagefind. احتفظ بجلسة Playwright واحدة، وأغلق جلسات المتصفح القديمة قبل فتح جلسات جديدة، وأوقف خادم المستندات بعد التحقق إذا لم تعد بحاجة إليها.
  • الحالة: مؤكد