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

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

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

معايير إضافة مدخل​

لا تضف مدخلًا إلا إذا تحققت كل الشروط التالية:

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

عند الشك، اسأل المطوّر قبل إضافة أي مدخل.

قالب المدخل​

### [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

المدخلات​

نطاقات الإنتاج لتطبيقات Vercel قد تعود إلى عمليات نشر Git master​

  • التاريخ: 2026-04-28
  • لاحظها: Tommaso + Codex
  • السياق: التحقق من مرايا تطبيقي Seedit و5chan في دليل التطبيقات على Bitsocial Web.
  • ما كان مفاجئًا: كان مشروعا Vercel المسمّيان seedit و5chan يحملان gitProviderOptions.createDeployments = "enabled"، ولذلك كانت عمليات الدفع إلى master على GitHub تُرقّى إلى نطاقات الإنتاج، رغم أن سياسة المستودع تتوقع أن تقدّم مرايا الإنتاج ملفات الإصدارات فقط.
  • الأثر: قد تصبح شارات المرايا الموثّقة في دليل التطبيقات غير صحيحة، لأن نطاقات الإنتاج تقدّم أحدث إيداع تطويري بدلًا من ملف ZIP الخاص بإصدار GitHub الذي سُجّلت بصمة index.html الخاصة به في about/src/lib/apps-data.ts.
  • إجراء التخفيف: قبل إضافة بيانات توثيق المرايا أو تحديثها، افحص مشروع Vercel عبر vercel api /v9/projects/<project-id> وتأكد من أن gitProviderOptions.createDeployments = "disabled". انشر محتويات ملف ZIP الخاص بالإصدار عبر vercel deploy --prebuilt --prod، واستخدم seedit-omega.vercel.app أو 5chan-omega.vercel.app لعمليات النشر التطويرية.
  • الحالة: مؤكدة

Portless 0.11 يعيد استخدام حالة الوكيل القديمة ما لم يفرض المُشغّل استخدام HTTPS​

  • التاريخ: 2026-04-28
  • لاحظها: Tommaso + Codex
  • السياق: ترقية مسار yarn start المعتاد من عنوان الوكيل القديم http://bitsocial.localhost:1355 إلى https://bitsocial.localhost.
  • ما كان مفاجئًا: حتى مع تثبيت portless@0.11.1، كان Portless يعيد استخدام وكيل HTTP القائم ~/.portless/proxy.port = 1355 ويطبع العنوان القديم :1355.
  • الأثر: لا يكفي تحديث إصدارات الحزم والتوثيق؛ إذ يظل بإمكان yarn start أن يعلن العنوان القديم ويستخدمه عندما تكون لدى المساهم حالة Portless قديمة قيد التشغيل.
  • إجراء التخفيف: أبقِ سكربتات التشغيل تبدأ وكيل HTTPS الخاص بـ Portless صراحةً على المنفذ 443 قبل تسجيل مسارات التطبيق، حتى ينتقل مسار التشغيل بعيدًا عن حالة 1355 المحفوظة بدلًا من أن يرثها.
  • الحالة: مؤكدة

Portless يغيّر عنوان التطبيق المحلي المعتمد​

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

خطافات Commitizen تعطّل الإيداعات غير التفاعلية​

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

Corepack ضروري لتفادي Yarn classic​

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

أسماء تطبيقات Portless الثابتة تتعارض بين أشجار عمل Bitsocial Web​

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

معاينة التوثيق كانت تثبّت المنفذ 3001 في الشيفرة​

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

اسم مضيف Portless الخاص بالتوثيق كان مثبّتًا في الشيفرة​

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

أصداف أشجار العمل قد تفوّت إصدار Node المحدّد في المستودع​

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

بقايا docs-site/ قد تخفي غياب مصدر التوثيق بعد إعادة الهيكلة​

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

معاينة التوثيق متعددة اللغات قد ترفع استهلاك الذاكرة أثناء التحقق​

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

قد يترك translate-docs.py لغات التوثيق مترجمة جزئيًا أو بأهداف روابط معطّلة​

  • التاريخ: 2026-04-06
  • لاحظها: Codex
  • السياق: إصلاح مسارات التوثيق المترجمة ومحتواها بعد أن قدّم yarn start:docs صفحات تفصيلية بالإنجليزية أو أخفق في بناء مخرجات اللغات
  • ما كان مفاجئًا: كان في خط ترجمة التوثيق نمطا إخفاق خاصان بالمستودع في آن واحد: فـ scripts/translate-docs.py لم يكن يستخرج سوى مجموعة صغيرة من رسائل DocsHome عندما تستخدم استدعاءات tr(...) صيغًا لا يحللها، كما أن ملفات ماركداون المترجمة تحت docs/i18n/** كان يمكن أن تحتوي على معرّفات مسارات مترجمة آليًا أو على بقايا ZXQPLACEHOLDER داخل أهداف الروابط.
  • الأثر: قد تتراجع الصفحات الرئيسية المترجمة بصمت إلى الإنجليزية، وقد تظهر الصفحات التفصيلية المترجمة بلا ترجمة، وقد يفشل yarn docs:build الكامل بسبب روابط لغوية معطّلة رغم أن مصادر التوثيق سليمة.
  • إجراء التخفيف: بعد تغيير ترجمات التوثيق أو إعادة توليد ملفات اللغات، شغّل دائمًا yarn docs:build من جذر المستودع، وافحص ملفات ماركداون في docs/i18n/** بحثًا عن ZXQPLACEHOLDER، وتأكد من أن الروابط المترجمة ما زالت تشير إلى معرّفات المستندات المعتمدة مثل /apps/5chan/ بدلًا من مسارات عناوين مترجمة. وإذا تغيّرت نصوص DocsHome، فتأكد من أن scripts/translate-docs.py لا يزال يستخرج جميع رسائل docs.home.*.
  • الحالة: مؤكدة

فحوص العمل بلا جافاسكربت لموقع about يجب أن تستخدم مسار Portless لا معاينة SSR مستقلة​

  • التاريخ: 2026-04-12
  • لاحظها: Codex
  • السياق: التحقق من دعم العمل بلا جافاسكربت لموقع about/ من شجرة عمل تابعة لفرع
  • ما كان مفاجئًا: قد تبدو معاينة SSR المستقلة سليمة بينما يظل مسار Portless المرتبط بالفرع يقدّم غلاف تطبيق خاطئًا أو عملية أقدم. وفي هذا المستودع، العقد المحلي الحقيقي هو اسم مضيف Portless الناتج عن yarn start، لا خادم معاينة مؤقت.
  • الأثر: قد يزعم الوكلاء خطأً أن الدعم بلا جافاسكربت يعمل، أو يفوّتون انحدارات لا تظهر إلا على *.bitsocial.localhost.
  • إجراء التخفيف: للتحقق من about/ عبر المتصفح، شغّل دائمًا الخادم المحلي الحقيقي بـ yarn start أو yarn start:about واختبر أولًا عنوان Portless المرتبط بالفرع. وإذا بدا اسم مضيف Portless قديمًا، افحص العملية القديمة وأوقفها قبل إعادة الاختبار.
  • الحالة: مؤكدة

chain/ كان غير مرئي لـ yarn build:verify وyarn doctor​

  • التاريخ: 2026-07-05
  • لاحظها: Codex
  • السياق: التحقق من فرق تغييرات يقتصر على chain/ بعد إضافة مساحة العمل chain/ (تطبيق Vite مستقل لـ chain.bitsocial.net) إلى المستودع الموحّد.
  • ما كان مفاجئًا: كان scripts/verify-build.mjs يتعرّف فقط على بادئات المسارات about/ وdocs/ وstats/، ولذلك كان فرق التغييرات المقتصر على chain/ يطبع "No targeted build checks matched the current diff" ولا ينفّذ أي بناء إطلاقًا، رغم أن build:chain كان موجودًا بالفعل في package.json الجذري. وبشكل منفصل، كان yarn doctor مثبَّتًا في الشيفرة على react-doctor about -y، فلم تحصل تغييرات React تحت chain/src على أي تغطية من React Doctor.
  • الأثر: كان على الوكلاء الذين يتحققون من تغييرات chain أن يعرفوا وجوب استدعاء yarn build:chain مباشرةً بدلًا من الاعتماد على yarn build:verify، كما كانت مشكلات React في chain/src (التأثيرات والخطافات والشيفرة الميتة) تمر دون أن يكتشفها yarn doctor.
  • إجراء التخفيف: صار في scripts/verify-build.mjs فرع خاص بـ chain/ يماثل فرع about/، كما صار doctor وdoctor:verbose يشغّلان react-doctor --project about,chain -y في استدعاء واحد. ويبقى doctor:score مقتصرًا على about لأن --score لا يطبع شيئًا بصمت عند دمجه مع --project لأكثر من مشروع واحد؛ استخدم yarn react-doctor --project about,chain --verbose -y (أو --json) إذا احتجت إلى درجة لمشروع chain.
  • الحالة: مؤكدة

P2P في المتصفح يعمل عبر WebSockets آمنة؛ وpkc-js يرفض WebRTC وWebTransport افتراضيًا​

  • التاريخ: 2026-08-02
  • لاحظها: Claude
  • السياق: كتابة نصوص صفحة الهبوط والتوثيق حول كيفية عمل P2P عبر المتصفح في Bitsocial
  • ما كان مفاجئًا: تأتي @pkcprotocol/pkc-js ببوّابة اتصال افتراضية ترفض محاولات الاتصال عبر WebRTC وWebTransport في المتصفح — إذ يصدّر dist/browser/helia/dial-transport-filter.js القيمة DENIED_DIAL_TRANSPORTS_BY_DEFAULT = ["webrtc", "webrtc-direct", "webtransport"]. ويوضّح التعليق في شيفرتها السبب: في المتصفح تضيف تلك النواقل مسارات طويلة لإنشاء الاتصال كثيرًا ما تفشل (STUN/ICE، وتدوير بصمة الشهادة) فتُبطئ التحميل، بينما WebSocket مباشر وموثوق. وكل نظير حيّ في لوحة حالة P2P على المدونة يظهر بوصف "Secure WebSocket". وتوجد هذه البوّابة داخل node_modules، ولذلك لا يوجد في المستودع ما يلمّح إليها.
  • الأثر: من السهل جدًا كتابة نص عام يبدو معقولًا تقنيًا لكنه خاطئ — مثل نسب الفضل في إتاحة P2P عبر متصفح Bitsocial إلى وصول WebTransport إلى خط الأساس في المتصفحات في مارس 2026. وقد وصل هذا الزعم إلى صفحة الهبوط وجدول المقارنة وصفحتَي توثيق قبل أن ينتبه إليه المطوّر. والادعاءات المعمارية الخاطئة على الصفحات العامة يتحقق منها بالضبط جمهورُ المطوّرين الذي يستهدفه الموقع.
  • إجراء التخفيف: لا تستنتج أبدًا النواقل التي يستخدمها Bitsocial مما يدعمه libp2p أو منصة المتصفح من حيث المبدأ. راجع node_modules/@pkcprotocol/pkc-js/dist/browser/helia/dial-transport-filter.js للاطلاع على قائمة الرفض الحالية، وتأكد من عدم وجود تجاوز لـ connectionGater تحت about/src/، واقرأ تسميات النواقل الحيّة في لوحة "P2P status" على المدونة قبل إطلاق أي ادعاء عام. أما التغيير الوارد من المنبع الذي أزاح فعليًا العائق أمام النشر من المتصفح فهو إصلاح seqno المتزايد في gossipsub ضمن @libp2p/gossipsub 15.0.21 (مايو 2026)؛ وتشحن pkc-js حاليًا الإصدار 16.0.4.
  • الحالة: مؤكدة

الروابط النسبية بصيغة ./page.md من صفحة توثيق غير مترجمة تعطّل كل بناء لغوي​

  • التاريخ: 2026-08-02
  • لاحظها: Claude
  • السياق: إضافة صفحة جديدة بالإنجليزية فقط، docs/browser-p2p.md، تربط إلى مستندات قائمة عبر ./peer-to-peer-protocol.md و./apps/5chan.md
  • ما كان مفاجئًا: تعكس كل لغة تحت docs/i18n/<lang>/docusaurus-plugin-content-docs/current/ شجرة التوثيق. والصفحة الجديدة الغائبة عن تلك المرايا تظل تُعرض في كل لغة عبر التراجع إلى الإنجليزية، لكن روابط ماركداون النسبية فيها تتوقف عن العمل — إذ يولّد Docusaurus /ar/browser-p2p/peer-to-peer-protocol.md/ ويفشل البناء برسالة "Docusaurus found broken links!". والأهم أن yarn build:verify وyarn docs:build:verify يبنيان en فقط ويمرّان بنجاح؛ ولا يكشف المشكلة إلا yarn docs:build الكامل، الذي يتوقف عند أول لغة أبجديًا (ar).
  • الأثر: قد يجتاز تغيير في التوثيق كل الفحوص المحلية السريعة ومع ذلك يعطّل بناء الإنتاج متعدد اللغات. كما يبدو الإخفاق غير ذي صلة بالتغيير، لأن رسالة الخطأ تذكر مسار لغة لم يمسّه المؤلف إطلاقًا.
  • إجراء التخفيف: في أي صفحة توثيق غير منعكسة في docs/i18n/**، استخدم روابط نسبية إلى الجذر (/peer-to-peer-protocol/ و/apps/5chan/) بدلًا من روابط .md النسبية؛ فـ Docusaurus يضيف بادئة اللغة إليها تلقائيًا. والمثال القائم على ذلك هو docs/build-your-own-client.md. وشغّل yarn docs:build كاملًا — لا build:verify وحده — قبل تسليم أي تغيير يضيف صفحة توثيق أو يربط بها.
  • الحالة: مؤكدة

يجب تشغيل update-translations.js من داخل about/، والتشغيل المتزامن يفقد المفاتيح بصمت​

  • التاريخ: 2026-08-02
  • لاحظها: Claude
  • السياق: تطبيق 26 مفتاح i18next مترجمًا على اللغات الست والثلاثين جميعها عبر مهارة translate
  • ما كان مفاجئًا: فخّان منفصلان في السكربت نفسه. الأول أن scripts/update-translations.js يحدّد هدفه بالصيغة path.join(process.cwd(), "public", "translations")، بينما يحتفظ هذا المستودع بالترجمات في about/public/translations. لذا فإن تشغيل الأمر الموثَّق من جذر المستودع يفشل في كل مرة برسالة "Translations directory not found" — إذ يعرض docs/agent-playbooks/translations.md الأمر node scripts/update-translations.js ...، وهو ما يُقرأ باعتباره أمرًا يُنفَّذ من جذر المستودع. والثاني أن كل استدعاء هو عملية قراءة وتعديل وكتابة تشمل ملفات اللغات الست والثلاثين كلها، ولذلك يطمس استدعاءان متزامنان أحدهما الآخر فيختفي أحد المفاتيح دون أي خطأ. ومهارة translate توجّه صراحةً بإطلاق ما يصل إلى 4 وكلاء فرعيين في وقت واحد، وكل واحد منهم سيستدعي السكربت.
  • الأثر: الصيغة المنفَّذة من جذر المستودع تفشل بصوت عالٍ وتهدر جولة كاملة. أما مشكلة التزامن فتفشل بصمت: تختفي مفاتيح من لغات عشوائية، ويظل فرق التغييرات يبدو معقولًا.
  • إجراء التخفيف: شغّله بالصيغة cd about && node ../scripts/update-translations.js --key <key> --map <abs-path> --write. ولا تدع الوكلاء الفرعيين المترجمين يكتبون ملفات اللغات في وقت واحد أبدًا — بل اجعلهم يُخرجون ملفات JSON للقواميس فقط، ثم طبّق كل مفتاح على التوالي من الوكيل الأب. وبعد التطبيق، تحقق برمجيًا من وجود كل مفتاح في اللغات الخمس والثلاثين غير الإنجليزية، ومن أن أي قيمة ليست مطابقة بايت ببايت للمصدر الإنجليزي.
  • الحالة: مؤكدة