תיעוד 87

המלצה על תוספים עבור הארגון שלך

הוסף בלוק relevance לרשומות של תוספים במרקטפלייס כדי ש-Claude Code יציע אותם כאשר עבודת המשתמש מתאימה.

אם אתה מפעיל מרקטפלייס של תוספים עבור הארגון שלך, תוכל לגרום ל-Claude Code להציע תוספים ספציפיים למשתמשים על סמך מה שהם עובדים עליו. הוסף בלוק relevance לרשומה של תוסף ב-marketplace.json, ולאחר מכן הוסף את המרקטפלייס לרשימת ההיתרים (allowlist) בהגדרות המנוהלות (managed settings). כאשר הפעלת המשתמש (session) תואמת לאחד האותות (signals) שהוגדרו, Claude Code מציג הצעת התקנה עבור אותו תוסף.

הצעות שמוצהרות על ידי מרקטפלייס פועלות במתכונת opt-in לכל מרקטפלייס דרך הגדרות מנוהלות (managed settings). שום הצהרות relevance של מרקטפלייס אינן מייצרות הצעות עד שמנהל מערכת מוסיף אותו לרשימת ההיתרים, כולל המרקטפלייס הרשמי של Anthropic. בנוסף, Claude Code כולל הצעה מובנית אחת שאינה תלויה ברשימת היתרים זו. טיפ זה וכל הטיפים שמוצהרים על ידי מרקטפלייס מושבתים כאשר spinnerTipsEnabled מוגדר כ-false.

דף זה מיועד למפעילי מרקטפלייס ולמנהלי מערכת בארגונים. אם ברצונך להתקין תוספים, ראה גילוי והתקנה של תוספים (Discover and install plugins).

#איך זה עובד

כל רשומת תוסף ב-marketplace.json יכולה לכלול אובייקט relevance. האובייקט מציין נושא (topic) ואות אחד או יותר (signals). אות הוא תבנית ש-Claude Code בודק מול ההפעלה הנוכחית, כגון ספריית העבודה או קבצים ש-Claude קרא.

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

כאשר אות מתאים והתוסף אינו מותקן כבר, Claude Code מציג את התוסף בשלושה מקומות:

טיפ בספינר (Spinner tip): הודעה בנוסח "Working with topic? Install the plugin plugin" יחד עם הפקודה /plugin install מופיעה מתחת לספינר בזמן ש-Claude מגיב.
הצעה בתחילת הפעלה (Session-start suggestion): אם אות ה-cwd מתאים לספריית העבודה, הודעה של שורה אחת בנוסח plugin suggestion: <name>@<marketplace> · /plugin מופיעה לפני התור הראשון.
לשונית Discover ב-/plugin: התוסף מוצמד לראש רשימת ה-Discover עם הערה כגון "suggested for this directory" או "suggested for stripe commands".

הטיפ בספינר וההודעה בתחילת ההפעלה הם חלק ממערכת ה-spinner-tips. ‏Claude Code משבית את שניהם כאשר הערך של spinnerTipsEnabled נקבע כ-false בכל קובצי ההגדרות שלך, או כאשר הערך של excludeDefault נקבע כ-true במפתחות spinnerTipsOverride בהגדרות המשתמש, ב---settings ובהגדרות המנוהלות (managed settings), ומפתחות אלה מגדירים לפחות טיפ אחד או tipsFile.

ההצמדה בלשונית Discover אינה תלויה בהגדרות הטיפים.

‏Claude Code לעולם אינו מתקין תוסף באופן אוטומטי. המשתמש תמיד מאשר זאת.

#הוספת relevance לרשומת תוסף

הוסף אובייקט relevance לרשומה של התוסף ב-marketplace.json שלך. הדוגמה הבאה מצהירה שהתוסף terraform-helpers רלוונטי כאשר Claude קורא קובץ .tf או כאשר Claude מריץ terraform:

{
  "name": "acme-corp-plugins",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "terraform-helpers",
      "source": "./plugins/terraform-helpers",
      "description": "Acme conventions and helpers for Terraform",
      "relevance": {
        "topic": "Terraform",
        "signals": {
          "cli": ["terraform"],
          "filesRead": ["**/*.tf"]
        }
      }
    }
  ]
}

תוסף עם בלוק relevance ללא אות תואם מתנהג כמו כל רשומת מרקטפלייס אחרת. הוא מופיע ברשימת ה-Discover במיקומו הרגיל ולעולם אינו מופיע כטיפ בספינר.

#פירוט שדות (Field reference)

#`relevance`

שדה	סוג	תיאור
`topic`	string	אופציונלי. הביטוי שמשלים את "Working with topic?" בטיפ הספינר. לעיתים קרובות זהו שם המוצר, למשל `Stripe`. השתמש בתחום כגון `design` כאשר שם התוסף אינו נקרא באופן טבעי כנושא. ברירת המחדל היא שם התוסף כאשר כל מקטע שמופרד במקף מתחיל באות גדולה. ההודעה בתחילת ההפעלה אינה משתמשת בערך זה. מקסימום 64 תווים.
`signals`	object	תואמים (matchers) שקובעים מתי התוסף רלוונטי. נדרש לפחות אות אחד כדי שניתן יהיה להציע את התוסף. ראה את הטבלה להלן.

#`relevance.signals`

שדה	סוג	תיאור
`cwd`	array of strings	תבניות גלוב (glob) המותאמות מול ספריית העבודה של ההפעלה. נבדק כנתיב מוחלט, וכאשר נמצאים בתוך מאגר git, כנתיב יחסי לשורש המאגר. מנורמל ללוכסנים ימניים ואינו רגיש לאותיות גדולות או קטנות. כל תבנית תואמת לספרייה עצמה ולכל מה שתחתיה, כך ש-`infra`, `infra/` ו-`infra/**` מתנהגים באופן זהה. זהו האות היחיד שיכול להתאים בתחילת ההפעלה, לפני התור הראשון. מקסימום 10 תבניות של 256 תווים כל אחת.
`cli`	array of strings	שמות פקודות מתוך פקודות מעטפת (shell) ש-Claude הריץ בהפעלה זו, למשל `["stripe"]`. חל בכל הפלטפורמות: פקודות שרצות ב-Windows דרך PowerShell או Git Bash נרשמות באותו אופן. `Claude Code` רושם שם פקודה אחד לכל הפעלה של כלי מעטפת: האסימון (token) הראשון לאחר השמות של משתני סביבה מובילים ו-`sudo`. פקודות מורכבות תורמות רק את הפקודה המובילה שלהן, כך ש-`cd infra && terraform plan` רושמת `cd`, ולא `terraform`. התאמה מדויקת. מקסימום 10 רשומות של 64 תווים כל אחת.
`hosts`	array of strings	שמות מארחים (hostnames) שנראו בכתובות URL של `http://` או `https://` בפקודות Bash בהפעלה זו, למשל `["api.stripe.com"]`. שם מארח בלבד באותיות קטנות: ללא סכמה, פורט או נתיב. התאמה מדויקת שאינה רגישה לאותיות גדולות או קטנות. מקסימום 20 רשומות של 128 תווים כל אחת.
`filesRead`	array of strings	תבניות גלוב המותאמות מול הנתיבים של קבצים ש-Claude קרא בהפעלה זו, למשל `["*/.tf"]`. מנורמל ללוכסנים ימניים ואינו רגיש לאותיות גדולות או קטנות. מקסימום 10 תבניות של 256 תווים כל אחת.
`manifestDeps`	array of objects	תלויות שמוצהרות במניפסטים של חבילות (package manifests) ש-Claude קרא בהפעלה זו. כל רשומה היא `{ "file": "...", "pattern": "..." }`, כאשר `file` הוא ביטוי רגולרי שמותאם מול נתיב קובץ המניפסט כפי שנרשם במצב ההפעלה, בדרך כלל נתיב מוחלט, ו-`pattern` הוא ביטוי רגולרי שמותאם מול תוכן הקובץ. עגן את `file` בסוף, למשל `[/\\\\]package\\.json$` בצורה עם מילוט ב-JSON, מכיוון שתבנית המעוגנת בהתחלה לעולם לא תתאים לנתיב מוחלט. נתיבים אינם מנורמלים מבחינת מפרידים עבור אות זה, לכן נתיבי Windows משתמשים בלוכסנים אחוריים (backslashes). קובצי מניפסט הגדולים מ-512 KB מדולגים. שני הערכים הם מחרוזות מקור של JavaScript `RegExp` באורך של 256 תווים לכל היותר. `file` מותאם ללא רגישות לאותיות גדולות או קטנות. `pattern` רגיש לאותיות גדולות או קטנות. מקסימום 10 רשומות.

האותות cli, hosts, filesRead ו-manifestDeps זקוקים להיסטוריית הפעלה, ולכן הם יכולים להתאים רק בטיפ בספינר ובלשונית Discover. האותות filesRead ו-manifestDeps בודקים את מצב הקבצים המתועד של ההפעלה, שכולל גם קבצים ש-Claude כתב או ערך וקובצי זיכרון CLAUDE.md שנטענו אוטומטית.

הדוגמה הבאה משתמשת ב-manifestDeps כדי להציע תוסף Stripe ברגע ש-Claude קרא package.json שתלוי ב-stripe. תבנית ה-file משתמשת ב-[/\\\\] כדי שתתאים גם ללוכסן ימני וגם ללוכסן אחורי כמפרידי נתיב, וב-\\. כדי שהנקודה תהיה ליטרלית. ב-JSON, כל לוכסן אחורי בביטוי הרגולרי נכתב פעמיים.

{
  "name": "stripe-helpers",
  "source": "./plugins/stripe-helpers",
  "relevance": {
    "topic": "Stripe",
    "signals": {
      "manifestDeps": [
        {
          "file": "[/\\\\]package\\.json$",
          "pattern": "\"stripe\"\\s*:"
        }
      ]
    }
  }
}

הערה: Claude Code מתעלם משדות לא מוכרים תחת relevance ותחת relevance.signals בזמן הטעינה, כך שלקוחות ישנים יותר ממשיכים לטעון את המרקטפלייס שלך.

#הפעלת הצעות בהגדרות מנוהלות (managed settings)

הצהרה על relevance ב-marketplace.json אינה מספיקה כשלעצמה. מנהל מערכת חייב להוסיף את המרקטפלייס לרשימת ההיתרים (allowlist) ב-הגדרות מנוהלות (managed settings) לפני שההצעות שלו יופיעו למשתמשים.

הוסף את שם המרקטפלייס אל pluginSuggestionMarketplaces. עבור כל מרקטפלייס שאינו המרקטפלייס הרשמי של Anthropic, הצהר גם על מקור המרקטפלייס באותן הגדרות מנוהלות, כרשומה של אותו שם ב-extraKnownMarketplaces או כרשומה ב-strictKnownMarketplaces. המערכת מתעלמת מהשם שברשימת ההיתרים אם המרקטפלייס שנרשם במחשב הגיע ממקור שונה. הדבר מונע ממקור לא קשור להירשם תחת שם שברשימת ההיתרים כדי שהתוספים שלו יוצעו ברחבי הארגון שלך.

קובץ ה-managed-settings.json הבא רושם מרקטפלייס ארגוני ממאגר GitHub ומפעיל את ההצעות שלו:

{
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  },
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}

המרקטפלייס הרשמי פטור מדרישת הצהרת המקור מכיוון ששמו יכול להירשם רק מהמקור הרשמי של Anthropic. הוספת השם בלבד לרשימת ההיתרים מספיקה:

{
  "pluginSuggestionMarketplaces": ["claude-plugins-official"]
}

#מה המשתמש רואה

כאשר אות מתאים במהלך הפעלה, הטיפ בספינר מציג:

Working with Terraform? Install the terraform-helpers plugin:
/plugin install terraform-helpers@acme-corp-plugins

בתחילת הפעלה, אות cwd תואם מציג את ההודעה הבאה בשורה אחת:

plugin suggestion: terraform-helpers@acme-corp-plugins · /plugin

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

בלשונית Discover ב-/plugin, התוסף מוצמד מעל שאר התוצאות עם הערה המציינת את האות שהתאים, כגון suggested for this directory או suggested for terraform commands. לשונית Discover מצמידה תוסף נתון פעם אחת. ביקורים מאוחרים יותר מציגים אותו בסדר הרגיל.

#אימות המרקטפלייס שלך

הרץ את claude plugin validate מול ספריית המרקטפלייס שלך כדי לבדוק את בלוק ה-relevance לפני הפרסום:

claude plugin validate ./my-marketplace

כלי האימות מדווח על מפתחות לא מוכרים תחת relevance ותחת relevance.signals כאזהרות, מסמן ערך relevance שאינו אובייקט, ודוחה רשומת signals.hosts הכוללת סכמה, פורט או נתיב.

#ראה גם

יצירה והפצה של מרקטפלייס לתוספים (Create and distribute a plugin marketplace): בנה את המרקטפלייס שמארח את התוספים שלך
המלצה על התוסף שלך מתוך ה-CLI שלך (Recommend your plugin from your CLI): הצג פניות למשתמשים מתוך ה-CLI שלך במקום מתוך אותות ההפעלה של Claude Code
מדריך הגדרות (Settings reference): pluginSuggestionMarketplaces ו-extraKnownMarketplaces