📘 תיעוד 84

אירוח ותחזוקה של שוק תוספים

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

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

הדף הזה מיועד לאדם שמפעיל שוק תוספים.

[!NOTE]

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

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

התחילו באירוח השוק כדי לבחור מארח ואת הפקודה שהמשתמשים מריצים. קראו את שמירה על משתמשים מעודכנים לפני ההפצה הראשונה. קראו את שינוי שם או הסרה של תוסף לפני שאתם משנים את name של תוסף.

#אירוח השוק

אפשר לארח את שוק התוספים ב-GitHub, במארח git אחר, ככתובת URL מתארחת של marketplace.json, או בתיקייה במערכת קבצים משותפת. שלחו למשתמשים את פקודת ההוספה של המארח שלכם, ואמרו להם מה הם צריכים על המחשב:

כדי לנעוץ ענף או תג של שוק תוספים ב-GitHub או בכתובת git, אמרו למשתמשים להוסיף #<ref> בסוף, כמו ב-your-org/your-marketplace#stable. הפניה לפקודות התוספים מפרטת כל צורה שהפקודה מקבלת.

הוספה מוצלחת מדפיסה Successfully added marketplace: your-marketplace. Claude Code לוקח את השם הזה משדה name ב-marketplace.json שלכם, ולא משם המאגר.

אחר כך המשתמשים מתקינים תוסף לפי name של הרשומה ולפי name של שוק התוספים, כמו ב-/plugin install code-formatter@your-marketplace.

#רישום השוק עבור כולם במאגר

כדי לשתף את שוק התוספים עם כל מי שעובד במאגר אחד, הריצו שם פעם אחת מהמעטפת claude plugin marketplace add your-org/your-marketplace --scope project ובצעו commit לקובץ .claude/settings.json שהפקודה כותבת. Claude Code רושם אז את שוק התוספים עבור כל חבר צוות שסומך על התיקייה.

#הימנעות מרשומות עם נתיב יחסי בשוק שמתארח בכתובת URL

כשמשתמשים מוסיפים את שוק התוספים ככתובת URL חשופה של marketplace.json, Claude Code מוריד רק את הקובץ הזה. רשומה במערך plugins שה-source שלה הוא נתיב יחסי כמו ./plugins/formatter נכשלת אז בהתקנה עם its marketplace entry path does not stay inside the marketplace directory. תנו לכל רשומה מקור שאפשר להביא בפני עצמו, כמו מאגר github או כתובת URL של archive, או ארחו את שוק התוספים במאגר git כדי ש-Claude Code ישכפל את כל העץ.

#שמירה בתוך מגבלות ההורדה של קבצים מתארחים

כשמשתמשים מוסיפים את שוק התוספים ככתובת URL של marketplace.json, או מתקינים רשומה עם מקור archive, Claude Code מוריד את הקובץ מהשרת שלכם. ההורדה נכשלת מעבר למגבלות בטבלה הזו, ולכן התאימו את גודל הקבצים והגדירו את השרת כך שיישאר בתוכן.

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

אחרי הורדת archive, ההתקנה נכשלת כשה-zip חורג מאחת ממגבלות החילוץ האלה:

• רשומות: 100,000 קבצים ותיקיות
• גודל קובץ: 512 MiB לכל קובץ אחד, לא דחוס
• גודל כולל: 1 GiB לא דחוס
• יחס דחיסה: תוכן לא דחוס בגודל של פי 50 מגודל ה-zip

#עריכת תוספים במקום בתיקייה משותפת

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

#השארת קבצי תוספים מחוץ ל-Git LFS

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

#שיתוף קבצים בתוך שוק תוספים עם קישורים סימבוליים

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

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

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

הפקודה הבאה יוצרת קישור מתוך תוסף בשוק אל מיומנות משותפת שמוגדרת על ידי תוסף אח. ב-Windows, השתמשו ב-mklink /D מתוך שורת פקודה מוגבהת, או הפעילו את Developer Mode:

ln -s ../../shared-plugin/skills/foo ./skills/foo

#הפצה דרך הגדרות הארגון

בתוכנית Team או Enterprise אפשר גם להפיץ את שוק התוספים דרך Organization settings > Plugins & skills ב-claude.ai, במקום לארח אותו במקום שהמשתמשים מוסיפים בעצמם. סנכרון הארגון קורא את המאגר דרך חיבור GitHub או GitLab של הארגון ב-claude.ai, ולכן אישורי git של המשתמשים אינם מעורבים.

סנכרון הארגון מחמיר יותר לגבי המאגר מאשר /plugin marketplace add:

• מאגר שוק התוספים: ב-github.com וב-gitlab.com הוא חייב להיות פרטי או פנימי
• מקורות תוספים: סנכרון הארגון מקבל רק חלק מסוגי המקור
• תיקיית bin/ ברמה העליונה: claude.ai דוחה תוסף שיש לו תיקייה כזו, ומסנכרן את שאר שוק התוספים. הודעת השגיאה מתחילה ב-Plugin contains a top-level bin/ directory. השאירו קבצי הפעלה בתיקייה אחרת, כמו scripts/, והפנו אליהם כ-${CLAUDE_PLUGIN_ROOT}/scripts/<name> מתוך ה-hooks או הגדרות שרת ה-MCP

סנכרון תוספי הארגון ממאגר ב-claude.com מפרט את המקורות המתקבלים, את הגדרת GitLab ואת שגיאת bin/, וניהול תוספים עבור הארגון מכסה את תהליך העבודה של המנהל.

#מתן גישה לשוק תוספים פרטי

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

אתם בוחרים אם השכפול רץ על SSH או על HTTPS לפי הצורה של פקודת ההוספה שאתם שולחים למשתמשים:

• GitHub owner/repo: Claude Code בודק ssh -T [email protected] ומשכפל על SSH כשהבדיקה מצליחה. אם הבדיקה נכשלת, או ששכפול ה-SSH עצמו נכשל, הוא משכפל על HTTPS. משתמשים במחשבים בלי מפתח SSH של GitHub יכולים להגדיר CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 כדי לדלג על הבדיקה ולשכפל על HTTPS.
• git@host:path.git: SSH.
• https://example.com/repo.git: HTTPS.

אמרו למשתמשים מה כל פרוטוקול צריך על המחשב שלהם:

• SSH: המפתח חייב לעבוד בלי בקשת ביטוי סיסמה, למשל כי הוא טעון ב-ssh-agent. המארח כבר חייב להיות ב-known_hosts.
• HTTPS: Claude Code משאיר את עוזר אישורי ה-git של המשתמש פעיל, אבל אוסר עליו לבקש קלט, ואינו מריץ תוכניות askpass כמו אחת שמוגדרת ב-GIT_ASKPASS. אישור שהעוזר כבר שומר עובד. אישור שהעוזר היה צריך לבקש נכשל. ב-GitHub, gh auth login ואחריו gh auth setup-git שומרים אישור כזה.

עבור מארח GitHub Enterprise Server, המשתמשים צריכים גישת git אל המארח הזה מהמחשב שלהם. ראו שוקי תוספים ב-GHES כדי לדעת מה כל משטח של Claude Code צריך כדי להגיע לשוק תוספים שמתארח ב-GHES.

אם אתם מפיצים דרך Organization settings > Plugins & skills ב-claude.ai, אישורי git של המשתמשים אינם מעורבים. ראו הפצה דרך הגדרות הארגון.

#שירות למשתמשים שאין להם חשבון במארח git

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

מקורות הרשומה האלה אינם צריכים חשבון git:

• archive: zip שמורד על HTTPS. המשתמשים לא צריכים git ולא חשבון, רק גישת רשת לכתובת. נדרש Claude Code v2.1.224 או חדש יותר. נעצו כל archive עם sha256 כדי ש-Claude Code יסרב להורדה שהשתנתה. כדי לשלוח אישורים עם ההורדה, ראו אימות הורדות archive.
• מאגר git ציבורי: Claude Code משכפל מקור url או git-subdir ציבורי על HTTPS בלי אישורים, כשהרשומה נותנת כתובת https://. עבור מקור github, או מקור git-subdir שנכתב כ-owner/repo, אמרו למשתמשים בלי מפתח SSH של GitHub להגדיר CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

השאירו את CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 בהוראות שלכם גם אם claude plugin install מצליח בלעדיו מהמעטפת במחשב בלי מפתח SSH. עבור מקור github, הפקודה הזו יכולה ליפול בעצמה אל HTTPS, ולהדפיס SSH not configured, cloning via HTTPS. התקנות מתוך /plugin בתוך סשן ועדכוני תוספים אינם נופלים כך, ולכן בלי המשתנה הם נכשלים אצל משתמשים שאין להם מפתח SSH של GitHub.

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

#מה עדכון אוטומטי ברקע עושה עם אישורים

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

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

• מקורות מרוחקים ב-SSH: מפתח שטעון ב-ssh-agent מאמת את הבדיקה.
• מקורות מרוחקים ב-HTTPS עם אישור שמור: עוזר שיכול לספק אישור שמור בלי לבקש קלט מאמת את הבדיקה. Git Credential Manager, עוזר ה-Keychain של macOS, ו-git-credential-store עובדים כך אחרי שהם מחזיקים אישור עבור המארח.
• מקורות מרוחקים ב-HTTPS עם עוזר שצריך לבקש קלט: העוזר אינו יכול לענות ברקע. העדכון נכשל בשקט וה-checkout הקיים נשאר במקומו, ולכן התוספים של המשתמש ממשיכים לעבוד מהמצב שסונכרן לאחרונה.

אחרי הבדיקה, Claude Code עושה אחד מהדברים הבאים:

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

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

• שמירת אישור: להתחבר קודם לעוזר האישורים כדי שהוא יחזיק אישור עבור המארח. עבור GitHub, להריץ gh auth login, ואחר כך gh auth setup-git.
• שמירת ה-checkout בכשל: אם המשתמש מגדיר CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, Claude Code שומר את ה-checkout הקיים בלי לנסות שכפול מחדש כשהבדיקה ברקע אינה יכולה להגיע אל המקור המרוחק או להזדהות מולו. התוספים ממשיכים לעבוד מהמצב שסונכרן לאחרונה.

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

#הפצה לכל החברה

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

עבור אנשים שאין להם חשבון במארח git, כל אחד מהסעיפים האלה מכסה דרך אחת להגיע אליהם:

• מקורות רשומה שאינם צריכים חשבון git: שירות למשתמשים שאין להם חשבון במארח git
• תיקיית תוספים שמולאה מראש: זריעת קונטיינרים ו-CI, שגם משרתת משתמשים שאין להם חשבון במארח git
• הגדרות ארגון ב-claude.ai: הפצה דרך הגדרות הארגון, שבה אישורי git של המשתמשים אינם מעורבים

#עדכון המשתמשים

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

#הפעלת עדכון אוטומטי

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

• בקשה מהמשתמשים להפעיל: כל משתמש נכנס אל Marketplaces ב-/plugin, בוחר את השוק שלך, ובוחר Enable auto-update.
• בקשה ממנהל להגדיר: אם מנהל מגדיר "autoUpdate": true על רשומת extraKnownMarketplaces של השוק שלך בהגדרות מנוהלות, זה מופעל לכל מי שמקבל את ההגדרות האלה. ראה הגדרת מדיניות עדכון.

בלי עדכון אוטומטי, המשתמשים מקבלים את השינויים כשהם מריצים /plugin marketplace update <name> בסשן או claude plugin update <plugin>@<name> במעטפת.

למה שהמשתמשים רואים כשעדכון מגיע אליהם, ראה מתי עדכון אוטומטי רץ.

#שחרור גרסה חדשה

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

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

לכל התקנה שאינה טעינה במקום או התקנה ממקור command, או העלה את version בכל שחרור או השמט אותו:

• העלאת version בכל שחרור: המשתמשים נשארים על העותק השמור במטמון עד שהמחרוזת משתנה. אם הגדרת "version": "1.0.0" ודחפת קומיטים חדשים בלי לשנות אותו, המשתמשים לא מקבלים אותם.
• השמטת version: המשתמשים עוקבים אחרי הקומיטים שלך. השאר את version מחוץ גם ל-plugin.json וגם לרשומת השוק.

אל תגדיר version גם ב-plugin.json וגם ברשומת השוק. אם תעשה זאת, Claude Code משתמש בערך מ-plugin.json בלי אזהרה, ו-claude plugin validate מדווח על אי ההתאמה כ-Entry declares version "<a>" but <path>/plugin.json says "<b>".

#החזקת המשתמשים על גרסה אחת

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

• ref ו-sha ברשומת התוסף: ref מציין ענף או תג ו-sha מציין קומיט עבור מקור github, url או git-subdir. ראה מקורות תוספים.
• #<ref> בפקודת ההוספה: משתמשים שמוסיפים your-org/your-marketplace#stable מקבלים את הענף או התג הזה של הקטלוג. לשני קווי שחרור בו זמנית, ראה הרצת ערוצי שחרור.
• תגי <plugin>--v<version>: טווח גרסאות של תלות נפתר מול התגים האלה. ראה שחרור תוסף שאחרים תלויים בו.

שחרור גרסה חדשה אומר מתי רשומה שהשתנתה מגיעה למשתמשים.

#שינוי הפקודה של מקור command

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

אחרי שהעותק של השוק אצל המשתמש קולט את השינוי, המשתמש רואה את הדברים הבאים:

• אין יותר הרצות ברקע: ההרצה פעם בסשן של הפקודה נעצרת עבור המשתמש, ולכן הפלט החדש של הכלי לא מגיע אליו.
• רשומה בלשונית Errors של /plugin: הרשומה מציגה את הפקודה החדשה ואת פקודת claude plugin update שיש להריץ.

בקש מהמשתמשים להריץ את פקודת claude plugin update שהרשומה מציגה, במסוף. Claude Code מציג להם את הפקודה החדשה ומבקש מהם לאשר אותה.

#הרצת ערוצי שחרור

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

תן לשני קובצי marketplace.json ערכי name שונים. Claude Code מזהה שוק לפי name שלו, ולכן משתמש לא יכול לרשום שני שווקים עם אותו שם בו זמנית.

עם שני הקטלוגים האלה, משתמשים שמוסיפים stable-tools מתקינים את code-formatter מענף stable, ומשתמשים שמוסיפים latest-tools מתקינים אותו מ-latest:

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

תן לשני ה-refs גרסאות plugin.json שונות, או השמט את version כדי ש-SHA של הקומיט יבדיל ביניהם. עדכונים מזוהים על ידי השוואת גרסאות, ולכן ref שזז בלי שינוי גרסה משאיר את המשתמשים על העותק השמור במטמון.

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

#שינוי שם או הסרה של תוסף

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

כדי לשנות את התווית שהמשתמשים רואים ב-/plugin בלי לשבור דבר, הגדר displayName ב-plugin.json והשאר את name ללא שינוי.

#העברת משתמשים עם מפת renames

כשחייבים לשנות name, הוסף מפת renames ברמה העליונה ל-marketplace.json כדי ש-Claude Code יעביר משתמשים קיימים במקום לדווח Plugin "<name>" not found in marketplace. עשה אותו דבר כשמסירים רשומה מ-plugins.

מפה כל שם קודם לשם הנוכחי שלו, או ל-null כשהתוסף נעלם. השוק הזה משנה את formatter ל-code-formatter ורושם ש-legacy-linter הוסר:

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

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

• רשומה ששמה שונה: התוסף נטען תחת השם החדש. claude plugin list ופרטי התוסף תחת /plugin מציגים פעם אחת Renamed to "code-formatter" in the "your-marketplace" marketplace, ו-Claude Code כותב מחדש את המפתח הישן לחדש ב-enabledPlugins וב-pluginConfigs בהיקפי ההגדרות של המשתמש, הפרויקט והמקומי.
• רשומת null: המפתח הישן מוסר מההיקפים האלה והמשתמש רואה Removed from the "your-marketplace" marketplace.
• מופעל בהגדרות מנוהלות: התוסף עדיין נטען תחת השם החדש, אבל Claude Code לא יכול לכתוב מחדש הגדרות מנוהלות, ולכן ההודעה חוזרת עד שמנהל מעדכן שם את enabledPlugins.

עבור שוק שמשתמשים הוסיפו ממאגר git או מ-URL, תוסף ששמו שונה מדווח Plugin "<name>" not cached at <path> עד שהמשתמש מריץ /plugin install code-formatter@your-marketplace פעם אחת בסשן.

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

במעטפת, הרץ claude plugin validate . אחרי עריכת המפה. הוא דוחה שרשרת שמעגלית או שמסתיימת במקום שאינו null או שם ב-plugins, עם renames.<name>: chain does not resolve.

#הסרת תוספים שהוסרו מהמכונות של המשתמשים

כדי להסיר תוסף שהוסר מהמכונות של המשתמשים במקום להשאיר עותק מאחור, הגדר "forceRemoveDeletedPlugins": true ברמה העליונה של marketplace.json. בלי השדה, תוסף שהוסר נשאר מותקן ומדווח Plugin "<name>" not found in marketplace כשסשן טוען אותו. איתו, Claude Code עושה את הדברים הבאים בכל תחילת סשן:

1. משווה את מה שהמשתמשים התקינו מהשוק שלך מול הרשומות ומפת renames, ומתייחס לכל תוסף שאינו רשום ואינו בעל שם חדש כאל תוסף שהוסר.
2. מסיר כל תוסף שהוסר מהיקפי המשתמש, הפרויקט והמקומי. תוספים שרק הגדרות מנוהלות התקינו נשארים במקום.
3. מציג כל תוסף שהוסר תחת כותרת Flagged ב-/plugin עם הסטטוס Removed from marketplace.

#אימות הורדות archive

כדי לאמת הורדת archive, למשל הורדה מרישום פרטי, הגדירו את כותרות ה-HTTP ש-Claude Code שולח איתה. אפשר להגדיר את headers באחד משני המקומות האלה:

• מקור url של השוק: מקור ה-url שממנו רשמתם את השוק, למשל רשומת extraKnownMarketplaces.
• רשומת התוסף: ב-Claude Code מגרסה 2.1.238 ואילך אפשר להגדיר זאת ברשומת marketplace.json של התוסף, לצד source.

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

הפניה לשוק מפרטת את שדות הרשומה headers ו-headersHelper.

המקום שתבחרו קובע אילו הורדות מקבלות את הכותרות ומתי Claude Code מריץ את הפקודה:

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

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

הרשומה הזו מגדירה headersHelper לצד source. היא גם מגדירה "strict": false, ש-Claude Code דורש מרשומת marketplace.json שמגדירה headersHelper:

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

כדי לבדוק את הרשומה, הריצו claude plugin install my-plugin@your-marketplace במעטפת. Claude Code מציג את הפקודה ואת כתובת ה-archive, ומוריד את ה-zip אחרי שאתם מקבלים.

#כתיבת פקודת headersHelper

בין אם מגדירים headersHelper על מקור url של שוק ובין אם על רשומת תוסף, כתבו את הפקודה כך שתעמוד בדרישות האלה:

• טקסט הפקודה: לכל היותר 500 תווים של ASCII להדפסה, בלי רצף של ארבעה רווחים או יותר.
• פלט: הדפיסו אובייקט JSON אחד של שמות כותרות וערכי מחרוזת ל-stdout, ואז צאו עם קוד 0 בתוך 10 שניות.
• מעטפת וספריית עבודה: Claude Code מריץ את הפקודה דרך sh, או דרך cmd.exe ב-Windows. ספריית העבודה היא ספריית התצורה, שהיא ~/.claude או CLAUDE_CONFIG_DIR. תנו נתיב מוחלט או פקודה שנמצאת ב-PATH, כי נתיב יחסי נפתר מול הספרייה הזו, לא מול הפרויקט של המשתמש.
• משתנים ש-Claude Code מסיר: כשהפקודה מוגדרת ברשומת marketplace.json, או ב-.claude/settings.json או .claude/settings.local.json של פרויקט, Claude Code מסיר מהסביבה כל משתנה ששמו נראה כמו פרטי הזדהות, לפי אותו כלל שהוא מחיל על headersHelper של MCP. ANTHROPIC_API_KEY ו-MY_REGISTRY_TOKEN מוסרים שניהם, לכן הפקודה צריכה לקרוא את פרטי ההזדהות מקובץ או ממחסן פרטי הזדהות. ההסרה הזו לא חלה על פקודה שמוגדרת בהגדרות משתמש, בקובץ --settings, או בהגדרות מנוהלות.
• משתנים ש-Claude Code מגדיר: CLAUDE_CODE_MARKETPLACE_URL ו-CLAUDE_CODE_MARKETPLACE_NAME לפקודה של מקור url, ו-CLAUDE_CODE_PLUGIN_NAME ו-CLAUDE_CODE_PLUGIN_ARCHIVE_URL לפקודה של רשומה. CLAUDE_CODE_MARKETPLACE_NAME לא מוגדר בשליפה הראשונה אחרי שמשתמש מוסיף שוק לפי כתובת, כי השליפה הזו היא מה שמספק את השם.

פקודה שמנפיקה אסימון bearer מדפיסה אובייקט כמו זה:

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

#מתי Claude Code מדלג על פקודת headersHelper או משמיט את הפלט שלה

פקודת headersHelper לא רצה, או שכותרות מ-headers או מפלט הפקודה מושמטות, כשאחד מהבאים חל:

• הפקודה נכשלת: אם הפקודה יוצאת עם קוד שונה מאפס, רצה מעבר ל-10 שניות, או מדפיסה משהו שאינו אובייקט JSON של ערכי מחרוזת, השליפה או ההורדה שלשמה הורצה הפקודה לא מתבצעת.
• כתובת השוק לא מתחילה ב-https://: הפקודה של מקור ה-url הזה לא רצה, והבקשות נושאות רק את הכותרות שרשומות בשדה headers שלו.
• הפניה יוצאת מה-origin: כשהורדה מופנית אל מחוץ ל-origin של כתובת ה-archive, הבקשה המופנית לא נושאת ערכי headers או פלט פקודה, לא ממקור url של השוק ולא מרשומת התוסף.
• הרשומה מגדירה כותרת ניתוב או זהות: Claude Code משמיט שמות של ניתוב בקשות וזהות לקוח כמו Host, Cookie ו-X-Forwarded-* מ-headers של רשומה ומפלט הפקודה, ושומר שמות אימות כמו Authorization. כל רשומת marketplace.json מסוננת כך. לרשומת תוסף מוטבעת בהגדרות, ראו extraKnownMarketplaces.
• פקודה שמוגדרת בהגדרות של ספריית --add-dir: הפקודה מתעלמת, גם במקור url וגם ברשומת תוסף מוטבעת, ונשלחות רק כותרות headers של הקובץ הזה.
• הגדרות מנוהלות חוסמות את הפקודה: הגדרת disableCommandPluginSources ל-true חוסמת פקודות headersHelper, ו-allowManagedHooksOnly חוסם אותן גם כן אלא אם disableCommandPluginSources הוא במפורש false. תחת כל אחד מהחסימות, Claude Code עדיין מריץ את הפקודה לשוק שההגדרות המנוהלות עצמן מצהירות עליו.

#איך משתמשים מקבלים פקודת headersHelper

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

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

• הפעלה במסוף: מתצוגת התוסף עצמו ב-/plugin.
• מעטפת: עם claude plugin install או claude plugin update.
• תוסף VS Code: מתיבת הדו-שיח Manage plugins, עם גרסה 2.1.290 ואילך של התוסף.

במעטפת לא אינטראקטיבית, העבירו --yes כדי לקבל את הפקודה. כדי לקבל רק את הפקודה שהרצת --json קודמת הציגה, העבירו --accept-command עם ה-sha256 שההרצה דיווחה.

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

#התקנות ועדכונים שמסרבים לפקודה במקום לשאול

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

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

#מתי רצה פקודה של מקור url של שוק

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

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

#תלות בתוספים אחרים והמלצה עליהם

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

• טווחי גרסאות: תלות יכולה לשאת טווח semver.
• תלויות בין שווקים: תלות משוק אחר מותקנת רק כשהשוק שלכם מציין את השוק הזה ב-allowCrossMarketplaceDependenciesOn.

לטווחי גרסאות, למוסכמת תג ה-git <plugin>--v<version> שלפיה הם נפתרים, ולאמון בין שווקים, ראו תלויות תוספים.

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

#דרכים לעקוף את מה ששוק לא יכול לעשות

יש דברים שבעלים מבקשים ואין להם שדה ב-marketplace.json. זו האפשרות הקרובה ביותר לכל אחד:

• הגבלת מה עוד משתמשים מתקינים: רשימת ההיתר של שווקים היא הגדרה מנוהלת, strictKnownMarketplaces. ראו הגבלת מה משתמשים יכולים להתקין.
• התקנה או הפעלה של תוסף בלי שהמשתמש מבקש: אין שדה רשומה שמתקין תוסף. enabledPlugins מנוהל עושה זאת לצי. ראו התקנה מראש ודרישת תוספים.
• הצגת רשומות שונות למשתמשים שונים: לרשומות אין שדה קהל, וכל משתמש שמוסיף את השוק רואה את כל הקטלוג. אחסנו שווקים נפרדים לקהלים נפרדים.
• סימון תוסף כמיושן: אין מצב deprecation. האפשרות היא להסיר את הרשומה, למפות את שמה ל-null ב-renames, ובאופן אופציונלי להגדיר forceRemoveDeletedPlugins.
• הפעלת עדכון אוטומטי למשתמשים: כל משתמש מפעיל זאת תחת Marketplaces ב-/plugin, או שמנהל מגדיר autoUpdate בהגדרות מנוהלות. ראו הפעלת עדכון אוטומטי.
• נשיאת אישורי git: אין שדה שוק שמחזיק אסימון git. גישה לשוק או לתוסף שמתארחים ב-git הולכת לפי הגדרת ה-git של המשתמש, לפי מתן גישה לשוק פרטי. למקורות archive, רשומה יכולה להגדיר headers או headersHelper במקום זאת.

#השלבים הבאים

• הפניה לשוק: שדות marketplace.json, סוגי מקור, והודעות אימות
• ניהול תוספים לארגון: דרישה, הגבלה, או זריעת השוק שלכם במכונות הארגון
• תלויות תוספים: תייגו מהדורות כדי שתוספים שתלויים בשלכם יוכלו לפתור גרסאות
• פתרון בעיות בתוספים: השגיאות שהמשתמשים רואים כשמוסיפים או מעדכנים מהשוק שלכם