پرش به مطلب اصلی

شگفتی‌های شناخته‌شده

این فایل نقاط سردرگمی مخصوص همین مخزن را ثبت می‌کند که به اشتباه ایجنت‌ها منجر شده‌اند.

شرایط افزودن ورودی​

تنها زمانی ورودی جدیدی اضافه کنید که هر سه شرط برقرار باشد:

  • مخصوص همین مخزن باشد، نه توصیه‌ای عمومی.
  • احتمال تکرار آن برای ایجنت‌های بعدی وجود داشته باشد.
  • راهکار مشخصی داشته باشد که بتوان دنبالش کرد.

اگر تردید دارید، پیش از افزودن ورودی از توسعه‌دهنده بپرسید.

الگوی ورودی​

### [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 می‌توانند دوباره به استقرارهای master در Git برگردند​

  • تاریخ: 2026-04-28
  • مشاهده‌شده توسط: Tommaso + Codex
  • زمینه: بررسی آینه‌های اپلیکیشن Seedit و 5chan در فهرست اپلیکیشن‌های Bitsocial Web.
  • چه چیزی غیرمنتظره بود: پروژه‌های seedit و 5chan در Vercel مقدار 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 وضعیت قدیمی پراکسی را دوباره به کار می‌گیرد مگر آنکه لانچر 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 را چاپ می‌کرد.
  • پیامد: به‌روزرسانی نسخه بسته‌ها و مستندات کافی نیست؛ اگر یک مشارکت‌کننده وضعیت قدیمی Portless را در حال اجرا داشته باشد، yarn start همچنان می‌تواند نشانی قدیمی را اعلام و استفاده کند.
  • راهکار: اسکریپت‌های راه‌اندازی را طوری نگه دارید که پیش از ثبت مسیرهای اپلیکیشن، صراحتاً پراکسی HTTPS پورت‌لس را روی پورت 443 بالا بیاورند تا جریان اجرا از وضعیت ماندگار 1355 مهاجرت کند و آن را به ارث نبرد.
  • وضعیت: تأییدشده

Portless نشانی متعارف محلی اپلیکیشن را تغییر می‌دهد​

  • تاریخ: 2026-03-18
  • مشاهده‌شده توسط: Codex
  • زمینه: بررسی‌های مرورگری و جریان‌های دودی
  • چه چیزی غیرمنتظره بود: نشانی محلی پیش‌فرض، پورت همیشگی Vite نیست. مخزن انتظار دارد از طریق Portless به https://bitsocial.localhost مراجعه شود، بنابراین بررسی localhost:3000 یا localhost:5173 می‌تواند به اپلیکیشن اشتباه یا اصلاً به هیچ چیز برسد.
  • پیامد: بررسی‌های مرورگری می‌توانند شکست بخورند یا هدف اشتباهی را تأیید کنند، حتی وقتی سرور توسعه سالم است.
  • راهکار: ابتدا از https://bitsocial.localhost استفاده کنید. تنها زمانی با PORTLESS=0 corepack yarn start آن را دور بزنید که به‌طور مشخص به یک پورت مستقیم Vite نیاز دارید.
  • وضعیت: تأییدشده

هوک‌های Commitizen جلوی کامیت‌های غیرتعاملی را می‌گیرند​

  • تاریخ: 2026-03-18
  • مشاهده‌شده توسط: Codex
  • زمینه: جریان‌های کامیت که ایجنت اجرا می‌کند
  • چه چیزی غیرمنتظره بود: git commit از طریق Husky، Commitizen را فعال می‌کند و منتظر ورودی تعاملی از ترمینال می‌ماند؛ همین باعث می‌شود شل‌های غیرتعاملی ایجنت معلق بمانند.
  • پیامد: ایجنت می‌تواند در چیزی که باید یک کامیت معمولی باشد، بی‌نهایت متوقف بماند.
  • راهکار: برای کامیت‌هایی که ایجنت می‌سازد از git commit --no-verify -m "message" استفاده کنید. انسان‌ها همچنان می‌توانند از corepack yarn commit یا corepack yarn exec cz استفاده کنند.
  • وضعیت: تأییدشده

برای پرهیز از Yarn کلاسیک، Corepack ضروری است​

  • تاریخ: 2026-03-19
  • مشاهده‌شده توسط: Codex
  • زمینه: مهاجرت مدیر بسته به Yarn 4
  • چه چیزی غیرمنتظره بود: روی این ماشین هنوز یک نصب سراسری Yarn کلاسیک در PATH وجود دارد، پس اجرای ساده yarn می‌تواند به نسخه ۱ برسد به جای نسخه ۴ که مخزن پین کرده است.
  • پیامد: توسعه‌دهنده‌ها می‌توانند ناخواسته پین‌شدن مدیر بسته در مخزن را دور بزنند و رفتار نصب یا خروجی فایل قفل متفاوتی بگیرند.
  • راهکار: برای فرمان‌های شل از corepack yarn ... استفاده کنید، یا ابتدا corepack enable را اجرا کنید تا yarn ساده هم به نسخه پین‌شده Yarn 4 برسد.
  • وضعیت: تأییدشده

نام‌های ثابت اپلیکیشن در Portless میان worktreeهای Bitsocial Web تداخل می‌کنند​

  • تاریخ: 2026-03-30
  • مشاهده‌شده توسط: Codex
  • زمینه: اجرای yarn start در یک worktree از Bitsocial Web در حالی که worktree دیگری از قبل از طریق Portless سرو می‌کرد
  • چه چیزی غیرمنتظره بود: استفاده از نام تحت‌اللفظی bitsocial به عنوان نام اپلیکیشن Portless در همه worktreeها باعث می‌شود خودِ مسیر تداخل کند، حتی وقتی پورت‌های پشتیبان متفاوت‌اند؛ در نتیجه فرایند دوم شکست می‌خورد چون 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 در یک worktree ثانویه از Bitsocial Web در حالی که worktree دیگری از قبل مستندات را از طریق Portless سرو می‌کرد
  • چه چیزی غیرمنتظره بود: start:docs همچنان نام میزبان تحت‌اللفظی docs.bitsocial.localhost را ثبت می‌کرد، پس yarn start می‌توانست شکست بخورد، هرچند اپلیکیشن about از قبل بلد بود چطور از تداخل مسیرهای Portless برای نام میزبان خودش پرهیز کند.
  • پیامد: worktreeهای موازی نمی‌توانستند با اطمینان از فرمان توسعه ریشه استفاده کنند، چون فرایند مستندات زودتر خارج می‌شد و آنگاه concurrently بقیه نشست را از بین می‌برد.
  • راهکار: راه‌اندازی مستندات را پشت scripts/start-docs.mjs نگه دارید؛ این اسکریپت اکنون همان نام میزبان Portless مختص شاخه را مانند اپلیکیشن about استخراج می‌کند و آن نشانی عمومی مشترک را به مقصد پراکسی توسعه /docs تزریق می‌کند.
  • وضعیت: تأییدشده

شل‌های worktree ممکن است نسخه پین‌شده Node مخزن را نبینند​

  • تاریخ: 2026-04-03
  • مشاهده‌شده توسط: Codex
  • زمینه: اجرای yarn start در worktreeهای Git مانند .claude/worktrees/* یا چک‌اوت‌های worktree همتراز
  • چه چیزی غیرمنتظره بود: برخی شل‌های worktree، node و yarn node را به Node نسخه 25.2.1 از Homebrew نگاشت می‌کردند، در حالی که مخزن نسخه 22.12.0 را در .nvmrc پین کرده است؛ پس yarn start می‌توانست بی‌سروصدا لانچرهای توسعه را روی رانتایم اشتباه اجرا کند.
  • پیامد: رفتار سرور توسعه می‌تواند بین چک‌اوت اصلی و worktreeها فرق کند، بازتولید باگ‌ها را سخت کند و زنجیره ابزار مورد انتظار 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 ارجاع ندهند.
  • وضعیت: تأییدشده

پیش‌نمایش چندزبانه مستندات می‌تواند در حین بررسی، مصرف RAM را به‌شدت بالا ببرد​

  • تاریخ: 2026-04-01
  • مشاهده‌شده توسط: Codex
  • زمینه: اصلاح i18n مستندات، مسیریابی زبان‌ها و رفتار 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 وقتی فراخوانی‌های tr(...) به شکلی نوشته شده بودند که اسکریپت آن را پارس نمی‌کرد، فقط زیرمجموعه کوچکی از پیام‌های DocsHome را استخراج می‌کرد، و مارک‌داون ترجمه‌شده زیر docs/i18n/** می‌توانست درون مقصد لینک‌ها اسلاگ‌های ماشین‌ترجمه‌شده یا آثار ZXQPLACEHOLDER داشته باشد.
  • پیامد: صفحه‌های خانه بومی‌سازی‌شده می‌توانند بی‌سروصدا به انگلیسی برگردند، صفحات جزئیات بومی‌سازی‌شده می‌توانند ترجمه‌نشده به نظر برسند، و yarn docs:build کامل می‌تواند روی لینک‌های خراب زبان‌ها شکست بخورد، حتی وقتی مستندات منبع معتبرند.
  • راهکار: پس از تغییر ترجمه‌های مستندات یا بازتولید فایل‌های زبان، همیشه yarn docs:build را از ریشه مخزن اجرا کنید، مارک‌داون‌های docs/i18n/** را برای ZXQPLACEHOLDER جست‌وجو کنید، و مطمئن شوید لینک‌های ترجمه‌شده هنوز به اسلاگ‌های متعارف مستندات مانند /apps/5chan/ اشاره می‌کنند و نه به مسیرهای ترجمه‌شده. اگر متن DocsHome تغییر کرد، مطمئن شوید scripts/translate-docs.py هنوز همه پیام‌های docs.home.* را استخراج می‌کند.
  • وضعیت: تأییدشده

بررسی‌های بدون JS سایت about باید از مسیر Portless انجام شود، نه از یک پیش‌نمایش SSR مستقل​

  • تاریخ: 2026-04-12
  • مشاهده‌شده توسط: Codex
  • زمینه: بررسی پشتیبانی بدون JS برای سایت about/ از یک worktree شاخه‌ای
  • چه چیزی غیرمنتظره بود: یک پیش‌نمایش SSR مستقل می‌تواند سالم به نظر برسد در حالی که مسیر واقعی Portless مختص شاخه هنوز پوسته اپلیکیشن اشتباه یا فرایندی قدیمی را سرو می‌کند. در این مخزن، قرارداد واقعی محلی همان نام میزبان Portless حاصل از yarn start است، نه یک سرور پیش‌نمایش موقتی.
  • پیامد: ایجنت‌ها می‌توانند به‌اشتباه ادعا کنند پشتیبانی بدون JS کار می‌کند، یا رگرسیون‌هایی را از دست بدهند که فقط روی *.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:verify مستقیماً yarn build:chain را صدا بزنند، و مشکلات 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 برای بیش از یک پروژه بی‌سروصدا هیچ خروجی چاپ نمی‌کند؛ اگر به امتیاز chain نیاز داشتید از yarn react-doctor --project about,chain --verbose -y (یا --json) استفاده کنید.
  • وضعیت: تأییدشده

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، چرخش certhash) که بارگذاری را کند می‌کند، در حالی که WebSocket مستقیم و قابل‌اتکاست. همه همتاهای زنده در پنل وضعیت P2P وبلاگ برچسب "Secure WebSocket" را نشان می‌دهند. این دروازه‌بان داخل node_modules قرار دارد، پس هیچ چیزی در خود مخزن به آن اشاره نمی‌کند.
  • پیامد: خیلی آسان است که متنی عمومی نوشته شود که از نظر فنی محتمل ولی نادرست است — مثلاً اینکه رسیدن WebTransport به Baseline مرورگرها در مارس ۲۰۲۶ را عامل ممکن شدن P2P مرورگری Bitsocial بدانیم. همین ادعا پیش از آنکه توسعه‌دهنده متوجه شود، به صفحه فرود، جدول مقایسه و دو صفحه مستندات راه یافت. ادعاهای نادرست معماری در صفحات عمومی را دقیقاً همان مخاطب توسعه‌دهنده‌ای بررسی می‌کند که سایت هدف گرفته است.
  • راهکار: هرگز از روی آنچه libp2p یا بستر مرورگر در اصل پشتیبانی می‌کنند نتیجه نگیرید Bitsocial از کدام ترابری‌ها استفاده می‌کند. برای فهرست رد فعلی، node_modules/@pkcprotocol/pkc-js/dist/browser/helia/dial-transport-filter.js را بررسی کنید، مطمئن شوید هیچ بازنویسی connectionGater زیر about/src/ وجود ندارد، و پیش از هر ادعای عمومی برچسب‌های زنده ترابری را در پنل "P2P status" وبلاگ بخوانید. تغییری در بالادست که واقعاً انتشار از مرورگر را ممکن کرد، اصلاح seqno یکنواخت gossipsub در @libp2p/gossipsub نسخه 15.0.21 (مه ۲۰۲۶) بود؛ 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/** آینه نشده است، به جای لینک‌های نسبی .md از لینک‌های نسبت به ریشه (/peer-to-peer-protocol/، /apps/5chan/) استفاده کنید؛ Docusaurus خودش پیشوند زبان را به آن‌ها اضافه می‌کند. docs/build-your-own-client.md نمونه موجود این کار است. پیش از تحویل هر تغییری که صفحه‌ای به مستندات اضافه می‌کند یا به آن لینک می‌دهد، یک yarn docs:build کامل اجرا کنید، نه فقط build:verify.
  • وضعیت: تأییدشده

update-translations.js باید از about/ اجرا شود، و اجراهای همزمان بی‌سروصدا کلیدها را از بین می‌برند​

  • تاریخ: 2026-08-02
  • مشاهده‌شده توسط: Claude
  • زمینه: اعمال ۲۶ کلید ترجمه‌شده 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 صراحتاً می‌گوید تا ۴ زیرایجنت همزمان اجرا شوند که هرکدام همین اسکریپت را صدا می‌زنند.
  • پیامد: شکل ریشه‌مخزنی با صدای بلند شکست می‌خورد و یک پاس کامل را هدر می‌دهد. اما مشکل همزمانی بی‌صدا شکست می‌خورد: کلیدها از زبان‌های دلخواهی حذف می‌شوند و دیف همچنان قابل‌قبول به نظر می‌رسد.
  • راهکار: آن را به شکل cd about && node ../scripts/update-translations.js --key <key> --map <abs-path> --write اجرا کنید. هرگز اجازه ندهید زیرایجنت‌های مترجم همزمان روی فایل‌های زبان بنویسند؛ آن‌ها فقط باید فایل‌های JSON دیکشنری تولید کنند و سپس ایجنت والد هر کلید را به‌ترتیب اعمال کند. پس از اعمال، به‌صورت برنامه‌ای بررسی کنید که هر کلید در هر ۳۵ زبان غیرانگلیسی وجود دارد و هیچ مقداری بایت‌به‌بایت با منبع انگلیسی یکسان نیست.
  • وضعیت: تأییدشده