📘 תיעוד 85

הגבלת גרסאות של תלויות תוספים

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

תוסף יכול להיות תלוי בתוספים אחרים על ידי רישומם ב-plugin.json או ברשומת ה-marketplace שלו. כברירת מחדל, תלות עוקבת אחר הגרסה הזמינה העדכנית ביותר, כך שגרסה חדשה של ה-upstream יכולה לשנות את התלות שתחת התוסף שלך ללא אזהרה. אילוצי גרסה מאפשרים לך להחזיק תלות בטווח גרסאות שנבדק עד שתבחר להתקדם.

כאשר מתקינים תוסף שמצהיר על תלויות, Claude Code פותר ומתקין אותן באופן אוטומטי, מלבד תלות שברשומת ה-marketplace שלה יש מקור מסוג command או headersHelper, שאותה עליך להתקין בעצמך תחילה. בהמשך, /reload-plugins, עדכון אוטומטי של ה-marketplace של התוסף התלוי, הרצה חוזרת של claude plugin install על התוסף התלוי, ו-claude plugin marketplace add מתקינים כל אחד תלות מוצהרת שעדיין אינה מותקנת, תחת אותם כללים. אם תלות נותרת לא פתורה, ראה פתרון שגיאות תלות.

מדריך זה מיועד למחברי תוספים שמצהירים על תלויות ב-plugin.json ולמתחזקי marketplace שמתייגים גרסאות (releases). תלויות כאן הן תוספים אחרים. עבור חבילות npm ו-Bun שתוסף עצמו משתמש בהן, ראה תלויות של חבילות Node.js. כדי להתקין תוספים שיש להם תלויות, ראה גילוי והתקנה של תוספים. עבור סכמת ה-manifest המלאה, ראה מדריך הפניה לתוספים.

#למה להגביל גרסאות של תלויות

חשוב על marketplace פנימי שבו שני צוותים מפרסמים תוספים. צוות הפלטפורמה מתחזק את secrets-vault, שרת MCP שעוטף backend של סודות. צוות ה-deploy מתחזק את deploy-kit, שקורא ל-secrets-vault כדי להביא פרטי אימות במהלך פריסות (deploys).

deploy-kit נבדק מול secrets-vault בגרסה v2.1.0. ללא אילוץ גרסה, בפעם הבאה שצוות הפלטפורמה יתייג גרסה שמשנה שם של כלי MCP, עדכון אוטומטי יעביר את ה-secrets-vault של כל מהנדס לגרסה החדשה, ו-deploy-kit יישבר.

באמצעות אילוץ גרסה, deploy-kit מצהיר שהוא זקוק ל-secrets-vault בטווח ~2.1.0. מהנדסים ש-deploy-kit מותקן אצלם נשארים בטלאי (patch) ה-2.1.x התואם הגבוה ביותר. צוות ה-deploy משדרג לפי לוח הזמנים שלו על ידי פרסום גרסה חדשה של deploy-kit עם אילוץ רחב יותר.

#הצהרה על תלות עם אילוץ גרסה

רשום תלויות במערך dependencies של קובץ ה-.claude-plugin/plugin.json של התוסף שלך.

ה-manifest הבא מצהיר על תלות אחת ללא גרסה ותלות אחת עם אילוץ גרסה:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

רשומה יכולה להיות מחרוזת פשוטה שמכילה רק את שם התוסף, כמו "audit-logger" בדוגמה לעיל, שתלויה בכל גרסה שה-marketplace של אותו תוסף מספק. לשליטה רבה יותר, השתמש באובייקט עם השדות הבאים:

גרסאות pre-release כגון 2.0.0-beta.1 אינן נכללות, אלא אם הטווח שלך כולל במפורש סיומת pre-release כמו ^2.0.0-0.

#אריזת תוספים כערכה עבור צוות

מלבד השדה הנדרש name, ה-manifest של תוסף יכול לכלול רק מערך dependencies. התקנתו מושכת את כל התלויות, מה שהופך אותו לדרך לארוז ערכת תוספים נבחרת מאחורי התקנה אחת.

לדוגמה, צוות פלטפורמה יכול לפרסם חבילות ייעודיות לתפקיד ב-marketplace פנימי, כך שמהנדסים יריצו פקודת claude plugin install אחת במקום להתקין כל כלי בנפרד:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

התקנת backend-standard פותרת ומתקינה את כל ארבע התלויות.

כדי להוסיף כלי לערכה הסטנדרטית מאוחר יותר, פרסם גרסה חדשה של backend-standard עם התלות הנוספת. עדכון אוטומטי כבוי כברירת מחדל עבור marketplaces שאינם של Anthropic, כך שמהנדסים מקבלים את הגרסה החדשה באחת משתי דרכים:

• הפעלת עדכון אוטומטי עבור ה-marketplace ב-/plugin. העדכון האוטומטי הבא יעביר את החבילה לגרסה החדשה ויתקין את כל התלויות שהיא מוסיפה.
• הרצת claude plugin update backend-standard, ולאחר מכן /reload-plugins כדי להתקין את התלויות שנוספו.

כדי לפרוס חבילות ברחבי הארגון, הוסף את תוסף החבילה ל-enabledPlugins ב-הגדרות מנוהלות.

#תלות בתוסף מ-marketplace אחר

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

כדי לאפשר זאת, המתחזק של ה-root marketplace מוסיף את שם ה-marketplace המיועד ל-allowCrossMarketplaceDependenciesOn ב-marketplace.json. ה-root marketplace הוא זה שמארח את התוסף שהמשתמש מתקין; רק רשימת המורשים (allowlist) שלו נבדקת, כך שאמון אינו משורשר דרך marketplaces מתווכים.

קובץ ה-marketplace.json הבא מאפשר ל-deploy-kit להיות תלוי בתוסף מ-acme-shared:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

אם השדה חסר או אינו כולל את ה-marketplace המיועד, ההתקנה נכשלת עם שגיאת cross-marketplace שמציינת את השדה שיש להגדיר. משתמשים עדיין יכולים להתקין את התלות ידנית תחילה, מה שמקיים את האילוץ מבלי לשנות את רשימת המורשים.

#בדיקת תוסף והתלות שלו באופן מקומי

אם אתה מפתח במקביל תוסף ואת התוסף שבו הוא תלוי, טען את שניהם באמצעות --plugin-dir:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

העותק המקומי של התלות מקיים את רשומת התלות של התוסף שלך, גם כאשר הרשומה מציינת marketplace, כך שאין צורך להתקין את התלות מה-marketplace שלה. Claude Code אינו בודק אילוץ גרסה מול עותק מקומי, ולכן קובץ ה-plugin.json המקומי אינו זקוק ל-version. לפני גרסה v2.1.242, רשומת תלות שציינה marketplace מעולם לא התאימה לעותק המקומי, ו-Claude Code השבית את התוסף שלך בעת הטעינה.

אם לא התקנת את התלות מה-marketplace שלה, התוסף שלך יפסיק להיטען כאשר העותק המקומי ייעלם:

• השבתת את העותק המקומי: Claude Code משבית את התוסף שלך בטעינת התוספים הבאה. עבור רשומת תלות שמציינת marketplace, Claude Code מדווח Dependency "<name>@inline" is disabled: enable it or remove the dependency. עבור רשומה של שם בלבד, הוא מדווח על התלות לפי שמה בלבד. <name>@inline היא הדרך שבה Claude Code מזהה כל תוסף של --plugin-dir ו---plugin-url.
• התחלת session ללא הדגל --plugin-dir של התלות: Claude Code מדווח שהתלות אינה מותקנת. העבר את הדגל שוב, או התקן את התלות מה-marketplace שלה.

#תיוג גרסאות תוסף עבור פתרון גרסאות

Claude Code פותר אילוצי גרסה מול תגיות git במאגר שמארח את התלות: המאגר של התוסף עצמו עבור מקורות תוסף מסוג github, url, ו-git-subdir, או מאגר ה-marketplace עבור תוסף שה-marketplace מתייחס אליו באמצעות נתיב יחסי. כדי ש-Claude Code ימצא את הגרסאות הזמינות של תלות, יש לתייג את הגרסאות של תוסף ה-upstream באמצעות מוסכמת שמות ספציפית.

תייג כל גרסה בתבנית {plugin-name}--v{version}, כאשר {version} תואם לשדה version ב-plugin.json של אותו commit. מתוך ספריית התוסף, הרץ:

claude plugin tag --push

הפקודה claude plugin tag גוזרת את שם התגית מה-manifest של התוסף ומרשומת ה-marketplace שמכילה אותו. לפני יצירת התגית, היא מאמתת את תוכן התוסף, מוודאת ש-plugin.json ורשומת ה-marketplace מסכימים על הגרסה, דורשת עץ עבודה (working tree) נקי תחת ספריית התוסף, ומסרבת אם התגית כבר קיימת.

• הדגל --push דוחף את התגית ל-remote בשם origin, ולכן המאגר זקוק ל-remote מוגדר בשם origin. העבר את --remote כדי לדחוף ל-remote אחר.
• אם הדחיפה נכשלת, התגית עדיין נוצרת מקומית והפקודה מסתיימת עם שגיאה.
• עם --push, ריצה מוצלחת מסתיימת עם Created tag secrets-vault--v2.1.0 ו-Pushed to origin, כאשר השורה האחרונה מציינת את ה-remote שאליו בוצעה הדחיפה. ללא --push, הפקודה מדפיסה את פקודת ה-git push שיש להריץ במקום.
• הדגל --dry-run מדפיס מה היה מתוייג מבלי ליצור זאת.

הרצה ישירה של git tag secrets-vault--v2.1.0 היא שוות ערך אם אתה שומר בעצמך על סנכרון בין plugin.json לרשומת ה-marketplace.

קידומת שם התוסף מאפשרת למאגר marketplace אחד לארח מספר תוספים עם קווי גרסאות עצמאיים. המפריד --v מפוענח כהתאמת קידומת על שם התוסף המלא, כך ששמות תוספים המכילים מקפים מטופלים כהלכה.

כאשר מתקינים תוסף שמצהיר על { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code מציג את התגיות במאגר שמארח את secrets-vault, מסנן לאלו שמתחילות ב-secrets-vault--v, ומביא את הגרסה הגבוהה ביותר שמקיימת את ~2.1.0. אם אף תגית במאגר של התוסף עצמו אינה מקיימת את הטווח, ההתקנה נכשלת עם Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0, שמציין את התלות יחד עם ה-marketplace שלה. עבור תוסף בעל נתיב יחסי ללא תגית תואמת, Claude Code מתקין במקום זאת את העותק הנוכחי של ה-marketplace ובודק את האילוץ כאשר התוסף נטען.

עבור תוסף שה-marketplace מתייחס אליו באמצעות נתיב יחסי, marketplace שנוסף כנתיב של תיקייה מקומית פותר תגיות באותו אופן כאשר התיקייה היא מאגר git. הדבר דורש את Claude Code בגרסה v2.1.196 ומעלה. בשני מקרים Claude Code מתקין במקום זאת את התלות מתוך התוכן הנוכחי של התיקייה:

• גרסאות מוקדמות יותר אינן קוראות תגיות מ-marketplace של תיקייה מקומית, ולכן תלות עם אילוץ נטענת רק אם אותו עותק מקיים את הטווח.
• תיקייה מקומית שאינה מאגר git אינה מכילה תגיות, ללא קשר לגרסה.

ה-semver של התגית שנפתרה נרשם בנפרד מה-version של plugin.json, כך שבדיקות אילוצים משתמשות בתגית שלמעשה הובאה גם אם ל-plugin.json באותו commit יש ערך מיושן. שם ספריית ה-cache עבור התקנה שנפתרה לפי תגית כולל סיומת commit-SHA באורך 12 תווים, כך שאם מתחזק מעביר תגית בכוח (force-moves) ל-commit אחר, ההתקנה הבאה מקבלת ספריית cache רעננה במקום לעשות שימוש חוזר בתוכן מיושן.

הערה: עבור תלויות עם מקור תוסף מסוג npm, archive, או command, האילוץ אינו שולט באיזו גרסה מיובאת, מכיוון שפתרון מבוסס תגיות חל רק על מקורות המגובים ב-git. האילוץ עדיין נבדק בזמן הטעינה, והתוסף התלוי מושבת עם dependency-version-unsatisfied אם הגרסה המותקנת אינה מקיימת אותו. עבור מקור מסוג command, Claude Code בודק את הגרסה ב-plugin.json של התלות ומתעלם מסיומת ה-content-hash; תלות שב-plugin.json שלה לא הוגדרה גרסה אינה מקיימת שום אילוץ, לכן הגדר גרסה לפני שאתה מגביל אותה.

Claude Code לעולם אינו מתקין בעצמו תלות עם מקור מסוג command, ולכן משתמשים מתקינים אותה תחילה. Claude Code גם לעולם אינו מריץ את headersHelper ברשומת ה-marketplace של תלות, ולכן משתמשים מתקינים תוסף זה תחילה.

#כיצד אילוצים משפיעים זה על זה

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

עדכון אוטומטי מייבא תלות בעלת אילוץ בתגית ה-git הגבוהה ביותר שמקיימת את הטווח של כל תוסף מותקן, במקום בגרסה העדכנית ביותר של ה-marketplace, כך שהתלות ממשיכה לקבל עדכונים בתוך הטווח המורשה שלה. אם אף תגית אינה מקיימת את כל הטווחים, העדכון האוטומטי מדלג על תלות זו ומציג את הדילוג בלשונית Errors ב-/plugin, תוך ציון התוסף המגביל.

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

#הפעלה או השבתה של תוסף עם תלויות

סעיף זה עוסק בתוספים שהותקנו מ-marketplace. עבור עותק שנטען באמצעות --plugin-dir, ראה בדיקת תוסף והתלות שלו באופן מקומי.

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

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

כלל זה תקף גם כאשר תלות מגדירה defaultEnabled: false ב-manifest שלה, מכיוון ש-Claude Code כותב עבורה true מפורש. אותו הדבר חל בעת התקנה: תלות שנמשכה כדי לספק תוסף פעיל מותקנת עם true ללא קשר לברירת המחדל שלה עצמה.

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

לדוגמה, אם deploy-kit תלוי ב-secrets-vault, השבתה של secrets-vault לבדו נכשלת עם פלט הדומה להלן:

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

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

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

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

claude plugin prune

אם שום דבר אינו עומד בתנאים להסרה, הפקודה מדפיסה Nothing to prune עם הסיבה ומסתיימת. זהו הפלט הצפוי בהתקנה נקייה (fresh install), ולא שגיאה.

כברירת מחדל, פעולת prune פועלת ב-user scope ומבקשת אישור לפני הסרת דבר כלשהו:

• --scope project או --scope local מכוונים ל-scope אחר.
• --dry-run מציג מה היה מוסר מבלי לשנות דבר.
• -y מדלג על בקשת האישור. כאשר stdin או stdout אינם terminal, פעולת prune מציגה את התלויות היתומות ומסתיימת מבלי להסיר אותן אלא אם תעביר -y.

כדי לבצע prune כחלק מהסרה, העבר את --prune אל claude plugin uninstall. לאחר הסרת התוסף שצוין, Claude Code סורק ומסיר תלויות שהותקנו אוטומטית וכעת הן יתומות. תוספים שהתקנת בעצמך לעולם אינם מוסרים באמצעות prune, אלא רק כאלה שהותקנו אוטומטית דרך מערך ה-dependencies של תוסף אחר.

אותה התנהגות אישור חלה כאן. כאשר stdin או stdout אינם terminal, ההסרה עדיין מושלמת, אך שלב ה-prune מציג את התלויות היתומות ואינו מסיר דבר אלא אם תעביר -y.

לדוגמה, כדי להסיר את deploy-kit ולנקות את התלויות שהוא משאיר אחריו:

claude plugin uninstall deploy-kit --prune

#פתרון שגיאות תלות

בעיות תלות מופיעות ב-claude plugin list ובממשק /plugin, כהודעות שגיאה תיאוריות ולא כקודים המילוליים שבטבלה זו. Claude Code משבית את התוסף המושפע עד שתפתור את השגיאה. הטבלה להלן מפרטת את השגיאות הנפוצות ביותר וכיצד לפתור אותן.

כדי לבדוק שגיאות אלו באופן תכנותי, הרץ claude plugin list --json. תוספים עם בעיות כוללים שדה errors שמפרט אותן. תוספים שנטענו באופן תקין משמיטים שדה זה.

#ראה גם

• יצירת תוספים: בניית תוספים עם skills, agents, ו-hooks
• יצירה והפצה של marketplace לתוספים: אירוח תוספים עבור הצוות שלך
• מדריך הפניה לתוספים: סכמת ה-plugin.json המלאה