📘 תיעוד 86

המלצה על התוסף שלך מתוך ה-CLI שלך

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

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

הפרוטוקול אינו דורש פקודות נוספות ואינו משנה את מה שה-CLI שלך מדפיס עבור משתמשים מחוץ ל-Claude Code.

דף זה מיועד למתחזקי CLI ו-SDK. אם ברצונך להתקין תוספים, ראה גלה והתקן תוספים.

#איך זה עובד

Claude Code מגדיר את משתנה הסביבה CLAUDECODE ל-1 עבור כל פקודה שהוא מריץ דרך הכלים Bash ו-PowerShell, ועבור פקודות hook. החל מגרסה v2.1.172 הוא מגדיר גם את CLAUDE_CODE_CHILD_SESSION ל-1 באותם תהליכי משנה. כאשר ה-CLI שלך מזהה את אחד המשתנים האלה, הוא כותב תג סגירה עצמית <claude-code-hint /> ל-stderr. בפקודות hook תג הרמז מוסר ומתעלמים ממנו. רק פלט של הכלים Bash ו-PowerShell מפעיל את הנחיית ההתקנה.

כאשר Claude Code מקבל את פלט הפקודה, הוא:

1. סורק לאיתור שורות רמז ומסיר אותן לפני שהפלט מגיע למודל
2. בודק שהרמז מכוון לתוסף בחנות רשמית של Anthropic
3. בודק שהתוסף אינו מותקן כבר ושלא הוצגה עבורו הנחיה בעבר
4. מציג למשתמש הנחיית התקנה שמציינת את הפקודה שפלטה את הרמז

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

#פליטת הרמז

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

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

• CLAUDECODE: מוגדר בכל גרסה של Claude Code, ולכן מגיע למספר המפגשים הגדול ביותר. הוא מוגדר גם במפגשי tmux ובתהליכי משנה של שרתי stdio של MCP ש-Claude Code מפעיל. הרחבות IDE מגדירות אותו גם בטרמינלים המשולבים שלהן, שבהם אדם עשוי להריץ את ה-CLI שלך ישירות.
• CLAUDE_CODE_CHILD_SESSION: מוגדר רק בתהליכי משנה ש-Claude Code עצמו מפעיל, כגון קריאות לכלי, פקודות hook, ופקודות שורת סטטוס, כך שהתג אינו מגיע בדרך כלל לטרמינל אנושי. תהליך ארוך חיים שהופעל בתוך מפגש, כגון שרת tmux, לוכד את המשתנה, ולכן מעטפות שיופעלו מאוחר יותר מאותו תהליך עדיין יציגו את התג הגולמי. דורש את Claude Code בגרסה v2.1.172 ומעלה, ולכן מפגשים בגרסאות ישנות יותר מפספסים את הרמז.

הדוגמאות הבאות מתנות את הפליטה ב-CLAUDECODE לתפוצה מרבית ופולטות רמז עבור תוסף בשם example-cli בחנות הרשמית:

Node.js:

if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}

Python:

import os, sys

if os.environ.get("CLAUDECODE"):
    print(
        '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
        file=sys.stderr,
    )

Go:

if os.Getenv("CLAUDECODE") != "" {
    fmt.Fprintln(os.Stderr,
        `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
}

Shell:

if [ -n "$CLAUDECODE" ]; then
  printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
fi

החלף את example-cli בשם התוסף שלך בחנות הרשמית.

#בחירת מיקום הפליטה

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

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

כאשר הרמז עובר את כל הבדיקות, Claude Code מציג הנחיה כמו הבאה:

─────────────────────────────────────────────────────────────
  Plugin recommendation

    The example-cli command suggests installing a plugin.

    Plugin: example-cli
    Marketplace: claude-plugins-official
    Official integration for example-cli deployments

    Would you like to install it?
    ❯ 1. Yes, install example-cli
      2. No
      3. No, and don't show plugin installation hints again

─────────────────────────────────────────────────────────────

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

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

• פעם אחת לתוסף: לאחר שההנחיה מוצגת, Claude Code רושם את התוסף ולעולם אינו מציג עבורו הנחיה שוב, ללא קשר לתשובת המשתמש.
• פעם אחת למפגש: בכל ה-CLIs במכונה, לכל היותר הנחיית רמז אחת מופיעה בכל מפגש של Claude Code.
• מפגש אינטראקטיבי ראשי בלבד: Claude Code מציג את ההנחיה רק במפגש הטרמינל שבו המשתמש מקליד. Claude Code לעולם אינו מציג הנחיה עבור פקודה שמופעלת על ידי תת-סוכן, ולעולם אינו מציג הנחיה כאשר המשתמש מריץ את Claude Code במצב לא אינטראקטיבי עם הדגל -p או דרך Agent SDK. Claude Code עדיין מסיר את שורת הרמז מפלט הפקודה בכל המקרים האלה.
• ביטול הסכמה לטלמטריה: מפגשים שבהם כלי אנליטיקה מושבתים לעולם אינם מציגים הנחיות רמז. זה כולל מפגשים שבהם DISABLE_TELEMETRY או CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC מוגדרים, ומפגשים אצל ספקים צד שלישי כגון Amazon Bedrock או Agent Platform של Google Cloud שבהם חל ביטול הסכמה אוטומטי לטלמטריה.

בחירה ב-Yes מתקינה את התוסף לרמת המשתמש (user scope). בחירה ב-No, and don't show plugin installation hints again משביתה את כל הנחיות הרמז העתידיות עבור המשתמש.

#מבנה הרמז

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

<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />

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

#דרישות

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

• שורה משל עצמו: התג חייב לתפוס שורה משל עצמו. תג המוטמע באמצע שורה, למשל בתוך פקודת יומן (log), זוכה להתעלמות. רווחים מקדימים ועוקבים בשורה מותרים.
• חנות רשמית: הערך של value חייב להפנות לתוסף בחנות שבשליטת Anthropic כגון claude-plugins-official. רמזים שמצביעים על חנויות אחרות מושמטים בשקט.

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

יתר ההנחיות מומלצות אך אינן נאכפות. ל-Claude Code אין אפשרות לבדוק אם ה-CLI שלך פועל לפיהן:

• כתיבה ל-stderr: שימוש ב-stderr שומר את התג מחוץ לצינורות מעטפת כגון example-cli deploy | jq. מערכת Claude Code סורקת את שני הערוצים, כך שגם stdout עובד.
• התניה במשתנה סביבה: פלוט רק כאשר CLAUDECODE או CLAUDE_CODE_CHILD_SESSION מוגדרים. ראה פליטת הרמז לגבי האופן שבו שני המשתנים נבדלים.

#הכנס את התוסף שלך לחנות הרשמית

פרוטוקול הרמזים נכנס לתוקף רק עבור תוספים שמופיעים בחנות הרשמית של Anthropic, שהיא claude-plugins-official. חברת Anthropic אוצרת את החנות הזו לפי שיקול דעתה, וטופסי ההגשה בתוך האפליקציה מוסיפים תוספים לחנות הקהילתית במקום זאת, שאותה פרוטוקול הרמזים אינו בודק. אם אתה עובד מול איש קשר לשותפים ב-Anthropic, פנה אליו כדי לתאם הוספה לחנות הרשמית.

#ראה גם

• יצירת תוספים: בנה את התוסף שה-CLI שלך ממליץ עליו
• יצירה והפצה של חנות תוספים: ארח תוספים מחוץ לחנות הרשמית
• משתני סביבה: הפניה מלאה עבור CLAUDECODE ומשתנים קשורים