nodebb-plugin-ai-autotag

תיוג אוטומטי של נושאים חדשים בפורום NodeBB באמצעות Google Gemini API (כולל תמיכה בשכבת החינם).

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

התקנה

cd /path/to/your/nodebb
cp -r nodebb-plugin-ai-autotag node_modules/nodebb-plugin-ai-autotag
./nodebb build
./nodebb start

לאחר מכן, בלוח הבקרה: תוספים (Plugins) → הפעל את "AI Auto Tag", ולאחר מכן היכנסו ל-AI Auto Tag בתפריט הצד של ה-ACP.

הגדרה ראשונית מומלצת

1. השיגו מפתח API חינמי ב-Google AI Studio.
2. הדביקו את המפתח בשדה "מפתח API של Gemini".
3. בחרו מודל (מומלץ להתחיל עם gemini-2.0-flash-lite).
4. הזינו את רשימת ה-cid של הקטגוריות שבהן רוצים להפעיל תיוג (opt-in - ברירת המחדל היא כבוי בכל הקטגוריות).
5. סמנו "הפעלת תיוג אוטומטי" ולחצו "שמור הגדרות".
6. פרסמו נושא בדיקה בקטגוריה מופעלת, וודאו שתגיות מופיעות תוך שניות ברענון הדף.

⚠️ נקודות המחייבות אימות מול הגרסה המותקנת שלכם

התוסף נכתב לפי מוסכמות ה-API הפנימי המתועדות של NodeBB v4, אבל שמות פונקציות פנימיות (לא חלק מה-API הציבורי/המתועד) עלולים להשתנות בין build-ים. כל הנקודות הרגישות האלה מרוכזות בקובץ אחד, lib/core-adapter.js, כדי שתצטרכו לבדוק/לתקן רק שם:

| # | פונקציה ב-core-adapter.js | מה לבדוק | |---|---|---| | 1 | setTopicTags | הכי קריטי. מוודא שקיימת פונקציית ליבה לעדכון תגיות נושא קיים. יש בו כבר שרשרת fallback (Topics.updateTopicTags → Topics.tags.updateTopicTags → מחיקה+יצירה מחדש), אבל מומלץ לבדוק ידנית מול node_modules/nodebb/src/topics/tags.js שאחת מהן אכן קיימת ועובדת כצפוי. | | 2 | getTopicTags | פונקציית קריאת תגיות נושא - יש fallback לגישה ישירה ל-sorted set. | | 3 | getSystemTags | מניח ש-meta.config.systemTags הוא מחרוזת מופרדת בפסיקים. אם בגרסתכם זה מבנה אחר (מערך, JSON) - יש להתאים. | | 4 | getCategoryTopicIds / getCategoryTopicCount | מניח מפתח cid:<cid>:tids. משמש רק ל-Backfill - אם שגוי, ה-Backfill פשוט לא ימצא נושאים (לא יקרוס), אבל כדאי לתקן. | | 5 | canUserRetag (פריווילגיה) | אופציונלי לגמרי - רלוונטי רק אם רוצים לאפשר לקבוצת "עורכים" (לא רק סופר-אדמין) להריץ Backfill. אינו נדרש לתפעול הבסיסי. | | 6 | Hook action:topic.post payload shape ב-library.js | הקוד מטפל בכמה צורות אפשריות (data.topic/data.posts) אבל מומלץ להדפיס console.log(JSON.stringify(data)) בהרצה ראשונה כדי לוודא שהשדות (tid, cid, uid, pid) אכן נשלפים נכון. | | 7 | routeHelpers.setupAdminPageRoute בקובץ library.js | חתימת הפונקציה (סדר הפרמטרים) - השוו מול תוסף ACP אחר שכבר מותקן אצלכם ועובד. | | 8 | תבנית ה-ACP (templates/admin/plugins/ai-autotag.tpl) | תחביר ה-Benchpress ({{{ each }}}, {./field}) עשוי להשתנות מעט בין גרסאות ה-theme (בפרט אם אינכם משתמשים ב-Harmony הסטנדרטי) - אם משהו לא מוצג, זו הנקודה הראשונה לבדוק. |

המלצה: להריץ קודם על סביבת staging, לפרסם נושא בדיקה, ולעקוב אחרי הלוגים (./nodebb log) כדי לוודא שאין שגיאות מהנקודות שלמעלה לפני מעבר לפרודקשן.

ארכיטקטורה בקצרה

• library.js — כניסה ראשית: hooks, נתיב ACP, socket handlers.
• lib/core-adapter.js — כל המגע עם ליבת NodeBB, במקום אחד (ראו טבלה למעלה).
• lib/settings.js — הגדרות + ברירות מחדל + חישוב מגבלות RPM/RPD effective.
• lib/gemini-client.js — קריאת HTTP ל-Gemini עם structured output (JSON schema) ו-timeout.
• lib/tag-normalizer.js — נרמול עברית (הסרת ניקוד וכו') + הצלבה מול תגיות קיימות.
• lib/validation.js — מיזוג תגיות קיימות+מוצעות עם כיבוד maxTags, לעולם לא מוריד תגית קיימת.
• lib/usage-tracker.js — מונה יומי + הערכת עלות חודשית, הכל דרך db.setObject/getObject (לא Redis-ספציפי).
• lib/queue.js — תור עיבוד (sorted set), worker מבוסס setInterval, backoff אקספוננציאלי על 429, נעילה רכה (soft lock) בין processes.
• lib/backfill.js — state machine ל-Backfill (running/paused/cancelled/completed) עם cursor הניתן לחידוש.
• lib/logger.js — לוג פעילות (עד 500 רשומות אחרונות).

כל האחסון (lib/*) עובר דרך db.setObject/getObject/sortedSet* הגנרי - התוסף אמור לעבוד זהה מעל Redis, MongoDB, ו-PostgreSQL.

בדיקות שבוצעו (מחוץ לסביבת NodeBB אמיתית)

מכיוון שאין כאן מופע NodeBB פעיל להרצה נגדו, הלוגיקה (לא ה-hooks/routes של NodeBB עצמם) נבדקה מול מוק (mock) מלא של src/database, src/topics, src/categories, src/posts וכו', המדמה תרחיש מלא: יצירת פוסט → תור → קריאת Gemini (מדומה) → נרמול → סינון systemTags → מיזוג לפי maxTags → כתיבה → לוג. כולל בדיקת retry/backoff על שגיאת 429, ובדיקת Backfill עם פילטר onlyUntagged. כל הבדיקות עברו. זה לא תחליף להרצה על NodeBB אמיתי — במיוחד נקודות 1, 6 ו-7 בטבלה למעלה חייבות בדיקה אחרונה מול הסביבה בפועל.

דברים שבכוונה לא מומשו בגרסה זו

• ממשק אישור ידני למצב "הצעה הממתינה לאישור" - הלוגיקה קיימת (התגיות המוצעות נשמרות בלוג), אבל אין עדיין מסך ACP לאישור/דחייה ידניים שורה-שורה. אם תרצו זאת, זו תוספת קטנה יחסית על גבי lib/logger.js הקיים.
• מטמון תגיות מתקדם / fuzzy matching ("הלכה" מול "הלכות") - הכוונה המדויקת בלבד (אחרי נרמול) נתמכת; דמיון מקורב לא.