📘 תיעוד 69

תלויות תוספים

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

תלות בתוסף היא תוסף אחר שהתוסף שלכם נשען עליו, למשל תוסף שאת שרת ה-MCP או את ה-skill שלו הוא קורא. כל תלות עוקבת אחרי הגרסה האחרונה שהמרקטפלייס שלה מספק, אלא אם מצהירים על אילוץ גרסה, טווח גרסאות סמנטי כמו ^2.0 או ~2.1.0 שנבדק מולו.

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

הערה

המקרים האלה מכוסים בדפים אחרים:

• התקנת תוסף שיש לו תלויות: ראו ניהול תוספים מותקנים
• קריאת שגיאת תלות: ראו שגיאות תלות
• הצהרה על חבילות npm ו-Bun שהקוד של התוסף עצמו צריך: ראו תלויות חבילות Node.js

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

#הצהרה על תלויות

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

עם אילוץ כמו ~2.1.0 על תלות ממקור שמגובה ב-git, משתמשים שהתוסף שלכם מותקן אצלם ממשיכים לקבל תיקוני 2.1.x של התלות ולא עוברים ל-2.2. כדי לשדרג לפי לוח הזמנים שלכם, בדקו מול מהדורה חדשה יותר ואז פרסמו גרסה חדשה של התוסף עם אילוץ רחב יותר.

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

רשמו תלויות במערך dependencies של .claude-plugin/plugin.json של התוסף. המניפסט הבא מצהיר על תלות אחת בלי גרסה ועל תלות אחת עם אילוץ:

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

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

כדי לקבוע אילוץ גרסה, השתמשו באובייקט עם השדות האלה, כל אחד מחרוזת:

טווח לא תואם גרסאות טרום מהדורה כמו 2.0.0-beta.1, אלא אם מצטרפים במפורש עם סיומת טרום מהדורה כמו ^2.0.0-0.

#חבילת תוספים לצוות

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

לדוגמה, צוות פלטפורמה יכול לפרסם חבילות לפי תפקיד במרקטפלייס פנימי, כך שמהנדסים מריצים 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 עם התלות הנוספת. כשהמרקטפלייס לא מתעדכן אוטומטית כברירת מחדל, המהנדסים מפעילים עדכון אוטומטי למרקטפלייס או מעדכנים ידנית:

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

לשלבים בצד המהנדס, ראו שמירה על תוספים מעודכנים.

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

#תלות בתוסף ממרקטפלייס אחר

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

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

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

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "allowCrossMarketplaceDependenciesOn": ["your-shared-marketplace"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "your-shared-marketplace" }
      ]
    }
  ]
}

אם allowCrossMarketplaceDependenciesOn חסר או לא כולל את מרקטפלייס היעד, Claude Code לא מתקין את התלות. כשהתלות מוצהרת ברשומת המרקטפלייס, ההתקנה עצמה נדחית עם הודעה שמתחילה ב-Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist ומציינת את השדה שצריך להגדיר. כשהיא מוצהרת ב-plugin.json, ההתקנה מסתיימת בלי התלות והתוסף שלכם נכשל בטעינה.

בדיקת רשימת ההיתר לא חלה על תלות שכבר מופעלת. אם משתמש מתקין את audit-logger מ-your-shared-marketplace בעצמו קודם, באותו היקף, deploy-kit מותקן אחר כך בלי שינוי ברשימת ההיתר.

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

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

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

העותק המקומי של התלות מספק את רשומת התלות של התוסף, ולכן אין צורך להתקין את התלות מהמרקטפלייס שלה.

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

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

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

כששני התוספים נמצאים בתיקיית אב אחת, אפשר להעביר את התיקייה הזו ל---plugin-dir פעם אחת. אם התיקייה עצמה אינה תוסף, Claude Code טוען כל תיקיית בת שיש בה .claude-plugin/plugin.json. נדרש Claude Code v2.1.265 ואילך.

#פרסום תוסף שאחרים תלויים בו

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

• מקור github, url, או git-subdir: המאגר של התוסף עצמו, ולכן מחבר התוסף יוצר את התגים
• נתיב יחסי כמו ./plugins/secrets-vault: מאגר המרקטפלייס, ולכן מתחזק המרקטפלייס יוצר את התגים

#יצירת תג מהדורה

תייגו כל מהדורה כ-<plugin-name>--v<version>, כאשר <version> תואם את שדה version ב-plugin.json של אותו commit. קידומת שם התוסף מאפשרת למאגר מרקטפלייס אחד לארח כמה תוספים עם היסטוריות גרסאות נפרדות.

צרו את התג מתיקיית התוסף, עם remote בשם origin שמוגדר לקבל את התג שנדחף, באמצעות claude plugin tag:

claude plugin tag --push

הפקודה בונה את שם התג מהמניפסט של התוסף. לפני יצירת התג היא מריצה את הבדיקות האלה:

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

ריצה מוצלחת מדפיסה Created tag secrets-vault--v2.1.0. עם --push היא גם מדפיסה Pushed to origin. בלי --push היא מדפיסה את פקודת git push להרצה בעצמכם.

העבירו --dry-run כדי לראות את התוכנית בלי ליצור דבר.

ההפניה של claude plugin tag מפרטת את שאר הדגלים.

אפשר גם להריץ git tag secrets-vault--v2.1.0 ישירות, כל עוד שומרים בעצמכם על סנכרון של version ב-plugin.json וברשומת המרקטפלייס.

#אילוץ תלות עם מקור שאינו git

פתרון לפי תגים חל רק על מקורות שמגובים ב-git. לתלות עם מקור תוסף מסוג npm, archive, או command, האילוץ לא שולט באיזו גרסה נמשכת. הוא עדיין נבדק כשהתוסף נטען, והתוסף התלוי מושבת אם הגרסה המותקנת לא מקיימת אותו.

עבור מקורות npm, archive, ו-command, הגרסה שנבדקת היא version ב-plugin.json של התלות. הגדירו אחת שם לפני שמאולצים את התלות, כי plugin.json שלא קובע גרסה לא מקיים שום אילוץ.

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

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

• /reload-plugins
• עדכון אוטומטי של מרקטפלייס התוסף התלוי
• הרצה חוזרת של claude plugin install על התוסף התלוי
• claude plugin marketplace add

#איך תלויות מתנהגות אצל המשתמשים שלכם

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

#איך אילוץ נפתר מול תגים

כשמשתמש מתקין תוסף שמצהיר על { "name": "secrets-vault", "version": "~2.1.0" }, התלות מותקנת מהתג secrets-vault--v הגבוה ביותר שמקיים את ~2.1.0 במאגר שמארח את secrets-vault. כשאין תג שמקיים את הטווח, ההתקנה נכשלת או משתמשת בעותק הנוכחי של המרקטפלייס:

• תוסף עם מאגר משלו: ההתקנה נכשלת עם הודעה שמכילה Dependency "secrets-vault@your-marketplace" has no git tag satisfying.
• תוסף שמופנה אליו בנתיב יחסי: ההתקנה משתמשת בעותק הנוכחי של המרקטפלייס, והאילוץ נבדק כשהתוסף נטען. אם העותק הזה מחוץ לטווח, התוסף התלוי נשאר מושבת ו-claude plugin list מציג Requires "secrets-vault@your-marketplace" ~2.1.0, installed 3.0.0.

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

#אישור הגרסה שנפתרה

כדי לאשר לאיזו גרסה אילוץ נפתר, הריצו claude plugin list במעטפת. תלות שנפתרה לפי תג מציגה את הגרסה שלה עם סיומת commit של 12 תווים, כמו 2.1.0-8713c5b11005.

בדיקות אילוץ משתמשות בגרסה של התג ולא ב-version שב-plugin.json, גם אם plugin.json באותו commit מפגר מאחור.

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

#שילוב אילוצים מכמה תוספים

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

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

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

#תלויות כשהתוסף שלכם נטען מ-claude.ai

כשמשתמש מפעיל את התוסף שלכם לחשבון claude.ai שלו, Claude Code טוען אותו כ-<name>@synced, בלי מרקטפלייס. עבור העותק הזה של התוסף, Claude Code רואה רשומת תלות שמציינת מרקטפלייס כממומשת כשיש למשתמש אחד מאלה:

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

אם אומרים למשתמשים להפעיל את התוסף מ-claude.ai, אמרו להם להפעיל שם גם את התלות, או להתקין אותה מהמרקטפלייס שלה.

תוסף claude.ai ממלא את הרשומה רק כשהתוסף שלכם גם נטען מ-claude.ai.

#ראו גם

• claude plugin prune: הסרת תלויות שהותקנו אוטומטית ואף תוסף כבר לא צריך
• אירוח מרקטפלייס: ערוצי מהדורה והמלצה על תוספים אחרים