דלג לתוכן הראשי

הפתעות ידועות

קובץ זה עוקב אחר נקודות בלבול ספציפיות למאגר שגרמו לטעויות של סוכן.

קריטריוני כניסה​

הוסף ערך רק אם כולם נכונים:

  • זה ספציפי למאגר הזה (לא עצה כללית).
  • זה צפוי לחזור על עצמו עבור סוכנים עתידיים.
  • יש לו הקלה קונקרטית שניתן לעקוב אחריה.

אם אינך בטוח, שאל את המפתח לפני הוספת ערך.

תבנית כניסה​

### [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 משנה את כתובת האתר הקנונית של האפליקציה המקומית​

  • תאריך: 2026-03-18
  • נצפה על ידי: קודקס
  • הקשר: אימות דפדפן וזרימת עשן
  • מה היה מפתיע: ברירת המחדל של כתובת האתר המקומית אינה יציאת Vite הרגילה. ה-repo מצפה ל-https://bitsocial.localhost דרך Portless, כך שבדיקת localhost:3000 או localhost:5173 יכולה לפגוע באפליקציה הלא נכונה או בכלום.
  • השפעה: בדיקות דפדפן יכולות להיכשל או לאמת את היעד השגוי גם כאשר שרת הפיתוח תקין.
  • הקלה: השתמש תחילה ב-https://bitsocial.localhost. עוקף אותו רק עם PORTLESS=0 corepack yarn start כאשר אתה זקוק במפורש ליציאת Vite ישירה.
  • סטטוס: אושר

הוקס של Commitizen חוסמים התחייבויות לא אינטראקטיביות​

  • תאריך: 2026-03-18
  • נצפה על ידי: קודקס
  • הקשר: זרימות עבודה של מחויבות מונעות על ידי סוכן
  • מה היה מפתיע: git commit מפעיל את Commitizen דרך האסקי ומחכה לקלט TTY אינטראקטיבי, שתולה קליפות של סוכן לא אינטראקטיבי.
  • השפעה: סוכנים יכולים להיעצר ללא הגבלת זמן במהלך מה שאמור להיות התחייבות רגילה.
  • הקלה: השתמש ב-git commit --no-verify -m "message" עבור התחייבויות שנוצרו על ידי סוכן. בני אדם עדיין יכולים להשתמש ב-corepack yarn commit או corepack yarn exec cz.
  • סטטוס: אושר

נדרשת Corepack כדי להימנע מ-Yarn classic​

  • תאריך: 2026-03-19
  • נצפה על ידי: קודקס
  • הקשר: הגירה של מנהל החבילות אל Yarn 4
  • מה היה מפתיע: למכונה עדיין יש התקנה עולמית של Yarn קלאסי ב-PATH, כך שהפעלת yarn רגילה יכולה לפתור ל-v1 במקום לגרסת Yarn 4 המוצמדת.
  • השפעה: מפתחים יכולים לעקוף בטעות את ההצמדה של מנהל החבילות של ה-repo ולקבל התנהגות התקנה שונה או פלט של קבצי נעילה.
  • הקלה: השתמש ב-corepack yarn ... עבור פקודות מעטפת, או הפעל תחילה את corepack enable, כך שה-yarn פשוט יפתור לגרסת Yarn 4 המוצמדת.
  • סטטוס: אושר

שמות אפליקציות ללא Portless קבועים מתנגשים בין עצי עבודה של Bitsocial Web​

  • תאריך: 30-03-2026
  • נצפה על ידי: קודקס
  • הקשר: הפעלת yarn start בעץ עבודה Bitsocial Web אחד בזמן שעץ עבודה אחר כבר שירת דרך Portless
  • מה היה מפתיע: שימוש בשם המילולי של האפליקציה Portless bitsocial בכל עץ עבודה גורם למסלול עצמו להתנגש, גם כאשר יציאות הגיבוי שונות, כך שהתהליך השני נכשל כי bitsocial.localhost כבר רשום.
  • השפעה: סניפים מקבילים של Bitsocial Web יכולים לחסום אחד את השני למרות ש-Portless נועד לתת להם להתקיים בבטחה.
  • הקלה: שמור את ההפעלה Portless מאחורי scripts/start-dev.mjs, שמשתמש כעת במסלול *.bitsocial.localhost בהיקף סניף מחוץ למקרה הקנוני ונופל בחזרה למסלול בהיקף ענף כאשר השם החשוף bitsocial.localhost כבר תפוס.
  • סטטוס: אושר

תצוגה מקדימה של Docs משמשת לקידוד קשיח של יציאה 3001​

  • תאריך: 30-03-2026
  • נצפה על ידי: קודקס
  • הקשר: הפעלת yarn start לצד נציגויות וסוכנים מקומיים אחרים
  • מה היה מפתיע: פקודת ה-root dev הריצה את סביבת העבודה של docs עם docusaurus start --port 3001, כך שכל הפעלת ה-dev נכשלה בכל פעם שתהליך אחר כבר החזיק ב-3001, למרות שהאפליקציה הראשית כבר השתמשה ב-Portless.
  • השפעה: yarn start עלול להרוג את תהליך האינטרנט מיד לאחר אתחולו, ולהפריע לעבודה מקומית שאינה קשורה בהתנגשות מסמכים-פורטים.
  • הקלה: שמור את ההפעלה של מסמכים מאחורי yarn start:docs, המשתמשת כעת ב-Portless בתוספת scripts/start-docs.mjs כדי לכבד יציאה פנויה שהוזרקה או לחזור ליציאה הזמינה הבאה כאשר היא פועלת ישירות.
  • סטטוס: אושר

מסמכים מתוקנים שם מארח Portless היה מקודד קשה​

  • תאריך: 2026-04-03
  • נצפה על ידי: קודקס
  • הקשר: הפעלת yarn start בעץ עבודה משני של Bitsocial Web בזמן שעץ עבודה אחר כבר הגיש מסמכים דרך Portless
  • מה היה מפתיע: start:docs עדיין רשמה את שם המארח המילולי docs.bitsocial.localhost, כך ש-yarn start עלול להיכשל למרות שאפליקציית האודות כבר ידעה להימנע מהתנגשויות של נתיב Portless עבור שם המארח שלה.
  • השפעה: עצי עבודה מקבילים לא יכלו להשתמש באופן אמין בפקודת root dev מכיוון שתהליך המסמכים יצא ראשון ו-concurrently לאחר מכן הרג את שאר ההפעלה.
  • הקלה: שמור את ההפעלה של מסמכים מאחורי scripts/start-docs.mjs, שמגיע כעת לאותו שם מארח Portless בהיקף ענף כמו אפליקציית About ומחדיר את כתובת ה-URL הציבורית המשותפת אל יעד ה-proxy dev /docs.
  • סטטוס: אושר

קונכיות Worktree יכולות לפספס את גרסת ה-Node המוצמדת של ה-repo​

  • תאריך: 2026-04-03
  • נצפה על ידי: קודקס
  • הקשר: הפעלת yarn start בעצי עבודה של Git כגון .claude/worktrees/* או תשלומים של עצי עבודה אחים
  • מה היה מפתיע: כמה מעטפות של עץ העבודה פתרו את node ו-yarn node ל-Homebrew Node 25.2.1 למרות שהריפו מצמידים את 22.12.0 ב-.nvmrc, כך ש-ZXQXPLACEHOLDER יכול להפעיל את ההשקה הלא נכון. זמן ריצה.
  • השפעה: התנהגות שרת Dev יכולה להיסחף בין התשלום הראשי לעצי העבודה, מה שקשה לשחזר באגים ולהפר את שרשרת הכלים הצפוי Node 22 של ה-Repo.
  • הקלה: שמור את משגרי הפיתוח מאחורי scripts/start-dev.mjs ו-scripts/start-docs.mjs, אשר כעת פועלים מחדש תחת ה-.nvmrc Node הבינארי כאשר המעטפת הנוכחית נמצאת בגרסה הלא נכונה. הגדרת מעטפת עדיין צריכה להעדיף nvm use.
  • סטטוס: אושר

שאריות docs-site/ יכולות להסתיר מקור מסמכים חסר לאחר ה-refactor​

  • תאריך: 2026-04-01
  • נצפה על ידי: קודקס
  • הקשר: ניקוי מונורפואי לאחר מיזוג לאחר העברת פרויקט הדוקוסאורוס מ-docs-site/ ל-docs/
  • מה היה מפתיע: התיקיה הישנה docs-site/ יכולה להישאר בדיסק עם קבצים מיושנים אך חשובים כמו i18n/, גם לאחר שהריפו במעקב עבר ל-docs/. זה גורם לרפקטור להיראות משוכפל מקומית ויכול להסתיר את העובדה שתרגומי מסמכים במעקב לא הועברו למעשה אל docs/.
  • השפעה: סוכנים יכולים למחוק את התיקיה הישנה כ"זבל" ולאבד בטעות את העותק המקומי היחיד של תרגומי מסמכים, או להמשיך לערוך סקריפטים שעדיין מצביעים על הנתיב המת של docs-site/.
  • הקלה: התייחסו ל-docs/ כפרויקט המסמכים הקנוני היחיד. לפני מחיקת שאריות מקומיות של docs-site/, שחזר מקור במעקב כמו docs/i18n/ ועדכן סקריפטים ו-hooks כדי להפסיק להתייחס ל-docs-site.
  • סטטוס: אושר

תצוגה מקדימה של מסמכים מרובים מקומיים יכולה להגדיל את זיכרון ה-RAM במהלך האימות​

  • תאריך: 2026-04-01
  • נצפה על ידי: קודקס
  • הקשר: תיקון מסמכים i18n, ניתוב מקומי והתנהגות חיפוש דף עם yarn start:docs פלוס מחזאית
  • מה היה מפתיע: מצב התצוגה המקדימה של מסמכים המוגדרת כברירת מחדל מבצעת כעת בניית מסמכים מרובת מקומית מלאה בתוספת אינדקס של Pagefind לפני ההגשה, ושמירה על תהליך זה בחיים לצד מספר הפעלות של מחזאית או Chrome יכולה לצרוך הרבה יותר זיכרון RAM מאשר לולאת פיתוח רגילה של Vite או Docusaurus יחידה.
  • השפעה: המכונה עלולה להיות מוגבלת בזיכרון, הפעלות דפדפן יכולות לקרוס, וריצות מופרעות יכולות להשאיר שרתי מסמכים מיושנים או דפדפנים חסרי ראש שממשיכים לצרוך זיכרון.
  • הקלה: עבור עבודת מסמכים שאינה זקוקה לאימות מסלול מקומי או חיפוש דף, העדיפו DOCS_START_MODE=live yarn start:docs. השתמש בתצוגה המקדימה של ריבוי מקומות המוגדרים כברירת מחדל רק כאשר אתה צריך לאמת מסלולים מתורגמים או חיפוש עמודים. שמור הפעלה יחידה של Playwright, סגור הפעלות דפדפן ישנות לפני פתיחת חדשות, והפסק את שרת המסמכים לאחר אימות אם אינך זקוק לו יותר.
  • סטטוס: אושר