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

سورپرایزهای شناخته شده

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

معیارهای ورود​

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

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

اگر مطمئن نیستید، قبل از افزودن ورودی از توسعه‌دهنده سؤال کنید.

الگوی ورودی​

### [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 برنامه محلی متعارف را تغییر می دهد​

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

قلاب های Commitizen تعهدات غیر تعاملی را مسدود می کنند​

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

Corepack برای اجتناب از نخ کلاسیک مورد نیاز است​

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

نام‌های برنامه‌های Portless ثابت در میان درختان کاری وب Bitsocial با هم برخورد می‌کنند​

  • تاریخ: 30-03-2026
  • ** مشاهده شده توسط: ** Codex
  • زمینه: شروع yarn start در یک درخت کاری وب Bitsocial در حالی که درخت کاری دیگر قبلاً از طریق Portless ارائه می‌شد
  • چیزی که تعجب آور بود: استفاده از نام تحت اللفظی برنامه Portless bitsocial در هر درخت کاری باعث می شود که مسیر با یکدیگر برخورد کند، حتی زمانی که پورت های پشتیبان متفاوت هستند، بنابراین فرآیند دوم با شکست مواجه می شود زیرا bitsocial.localhost قبلاً ثبت شده است.
  • تأثیر: شاخه‌های وب Bitsocial موازی می‌توانند یکدیگر را مسدود کنند، حتی اگر Portless به آنها اجازه همزیستی ایمن را بدهد.
  • ** کاهش: ** راه‌اندازی Portless را پشت سر scripts/start-dev.mjs نگه دارید، که اکنون از یک مسیر شاخه‌دار *.bitsocial.localhost خارج از کیس متعارف استفاده می‌کند و زمانی که نام خالی bitsocial.localhost قبلاً اشغال شده است، به مسیر شاخه‌ای بازمی‌گردد.
  • وضعیت: تایید شد

پیش نمایش Docs برای پورت کد سخت 3001 استفاده می شود​

  • تاریخ: 30-03-2026
  • ** مشاهده شده توسط: ** Codex
  • زمینه: اجرای yarn start در کنار سایر مخازن و نمایندگان محلی
  • چیزی که تعجب آور بود: دستور root dev فضای کاری اسناد را با docusaurus start --port 3001 اجرا کرد، بنابراین هر زمان که فرآیند دیگری قبلاً مالک 3001 بود، کل جلسه برنامه‌نویس شکست خورد، حتی اگر برنامه اصلی قبلاً از Portless استفاده می‌کرد.
  • تأثیر: yarn start می‌تواند فرآیند وب را بلافاصله پس از راه‌اندازی از بین ببرد و کار محلی نامرتبط را به دلیل برخورد پورت اسناد قطع کند.
  • کاهش: راه اندازی اسناد را پشت سر yarn start:docs نگه دارید، که اکنون از Portless به علاوه scripts/start-docs.mjs برای احترام به پورت رایگان تزریق شده استفاده می کند یا با اجرای مستقیم به پورت موجود بعدی برمی گردد.
  • وضعیت: تایید شد

اسناد ثابت نام میزبان Portless سخت کد شده بود​

  • تاریخ: 2026-04-03
  • ** مشاهده شده توسط: ** Codex
  • زمینه: اجرای yarn start در یک درخت کاری وب Bitsocial ثانویه در حالی که درخت کاری دیگر از قبل اسناد را از طریق Portless ارائه می کرد.
  • چیزی که تعجب آور بود: start:docs هنوز نام میزبان تحت اللفظی docs.bitsocial.localhost را ثبت کرده است، بنابراین yarn start ممکن است از کار بیفتد حتی اگر برنامه about قبلاً می دانست چگونه از برخورد مسیر Portless برای نام میزبان خود جلوگیری کند.
  • تأثیر: درخت های کاری موازی نمی توانند به طور قابل اعتمادی از دستور root dev استفاده کنند زیرا ابتدا فرآیند docs خارج شد و concurrently سپس بقیه جلسه را از بین برد.
  • کاهش: راه اندازی اسناد را پشت سر scripts/start-docs.mjs نگه دارید، که اکنون همان نام میزبان Portless با محدوده شاخه ای را به عنوان برنامه about مشتق می کند و URL عمومی مشترک را به هدف پروکسی توسعه دهنده /docs تزریق می کند.
  • وضعیت: تایید شد

پوسته‌های Worktree می‌توانند نسخه Node پین‌شده مخزن را از دست بدهند​

  • تاریخ: 2026-04-03
  • ** مشاهده شده توسط: ** Codex
  • زمینه: اجرای yarn start در درخت کاری Git مانند .claude/worktrees/* یا تسویه‌حساب‌های درخت کاری خواهر و برادر
  • چیزی که تعجب آور بود: برخی از پوسته های درخت کاری node و yarn node را به Homebrew Node 25.2.1 حل و فصل کردند، حتی اگر پین های repo در 22.12.0 در ZXQPLACEHOLDER4ZQPLACEH به صورت ZXQPLACEHOLDER4ZQPLACEH به صورت ZXQPLACEHOLDER4ZQPLACEH به خوبی اجرا شوند. لانچرها تحت زمان اجرا اشتباه
  • تأثیر: رفتار سرور برنامه‌نویس می‌تواند بین پرداخت اصلی و درخت‌های کاری جابه‌جا شود و تولید باگ‌ها را سخت کند و زنجیره ابزار Node 22 مورد انتظار مخزن را نقض کند.
  • ** کاهش: ** راه‌اندازهای توسعه‌دهنده را در پشت scripts/start-dev.mjs و scripts/start-docs.mjs نگه دارید، که اکنون تحت باینری گره .nvmrc زمانی که پوسته فعلی روی نسخه اشتباه است، دوباره اجرا می‌شوند. راه‌اندازی پوسته همچنان باید nvm use را ترجیح دهد.
  • وضعیت: تایید شد

باقیمانده‌های docs-site/ می‌توانند منبع اسناد گمشده را پس از Refactor پنهان کنند.​

  • تاریخ: 2026-04-01
  • ** مشاهده شده توسط: ** Codex
  • زمینه: پاکسازی monorepo پس از ادغام پس از انتقال پروژه Docusaurus از docs-site/ به docs/
  • چیزی که تعجب آور بود: پوشه قدیمی docs-site/ می تواند روی دیسک با فایل های قدیمی اما مهم مانند i18n/ باقی بماند، حتی پس از اینکه مخزن ردیابی شده به docs/ منتقل شد. این باعث می‌شود که Refactor به صورت محلی تکراری به نظر برسد و می‌تواند این واقعیت را پنهان کند که ترجمه‌های اسناد ردیابی شده واقعاً به docs/ منتقل نشده‌اند.
  • تأثیر: نمایندگان می‌توانند پوشه قدیمی را به‌عنوان «آشغال» حذف کنند و به‌طور تصادفی تنها نسخه محلی ترجمه‌های اسناد را از دست بدهند، یا به ویرایش اسکریپت‌هایی ادامه دهند که همچنان به مسیر مرده docs-site/ اشاره می‌کنند.
  • ** کاهش: ** با docs/ به عنوان تنها پروژه اسناد متعارف رفتار کنید. قبل از حذف هر گونه باقیمانده محلی docs-site/، منبع ردیابی شده مانند docs/i18n/ را بازیابی کنید و اسکریپت ها و قلاب ها را به روز کنید تا ارجاع به docs-site متوقف شود.
  • وضعیت: تایید شد

پیش‌نمایش اسناد Multilocale می‌تواند در حین تأیید، RAM را افزایش دهد​

  • تاریخ: 2026-04-01
  • ** مشاهده شده توسط: ** Codex
  • زمینه: رفع i18n اسناد، مسیریابی محلی، و رفتار Pagefind با yarn start:docs به علاوه نمایشنامه نویس
  • چیزی که شگفت‌آور بود: حالت پیش‌نمایش اسناد پیش‌فرض اکنون یک سند کامل چندمکانی به‌علاوه نمایه‌سازی Pagefind را قبل از ارائه انجام می‌دهد، و زنده نگه داشتن این فرآیند در کنار چندین جلسه Playwright یا Chrome می‌تواند رم بسیار بیشتری نسبت به حلقه توسعه‌دهنده Vite یا تک محلی Docusaurus مصرف کند.
  • تأثیر: دستگاه ممکن است محدود به حافظه شود، جلسات مرورگر ممکن است از کار بیفتد، و اجرای قطع شده می تواند سرورهای اسناد یا مرورگرهای بدون هد را پشت سر بگذارد که به مصرف حافظه ادامه می دهند.
  • ** کاهش:** برای کارهای اسنادی که نیازی به تأیید مسیر محلی یا Pagefind ندارند، DOCS_START_MODE=live yarn start:docs را ترجیح دهید. فقط زمانی از پیش‌نمایش چند محلی پیش‌فرض استفاده کنید که نیاز به اعتبارسنجی مسیرهای ترجمه شده یا Pagefind داشته باشید. یک جلسه نمایشنامه نویس را نگه دارید، جلسات مرورگر قدیمی را قبل از باز کردن موارد جدید ببندید و اگر دیگر به آن نیاز ندارید، پس از تأیید، سرور اسناد را متوقف کنید.
  • وضعیت: تایید شد