NeboAI
NeboAI
להתחלה

מדריך plugin.json

plugin.json הוא קובץ המניפסט ש-Nebo קורא כדי להתקין ולהריץ תוסף. המפתחות נכתבים ב-camelCase. בעמוד הזה מופיע כל שדה ש-Nebo קורא היום ומה כל אחד מהם עושה.

שדות ברמה העליונה

שדהסוגחובהמשמעות
idstringכןהמזהה של התוסף בחנות. השתמש ב-slug בזמן הפיתוח.
slugstringכןמזהה יציב. [a-z0-9-], עד 64 תווים, בלי מקף בהתחלה, בסוף או כפול. קובע את שם הכלי plugin__<slug> ואת המשתנה <SLUG>_BIN.
namestringכןשם התצוגה. ציין את השירות שהתוסף מתחבר אליו.
versionstringכןגרסה סמנטית, כמו 0.1.0.
platformsmapכןמפתח פלטפורמה לקובץ הבינארי. ראה פלטפורמות.
descriptionstringלאמשפט אחד לאנשים ולעובדים.
authorstringלאשם המפרסם.
categorystringלאעוזר לעובדים למצוא את התוסף.
triggersרשימת מחרוזותלאמילים שמתארות מתי התוסף רלוונטי. משמשות לרמזי חיפוש.
entrySkillsרשימת מחרוזותלאכישורים כלולים שיוזכרו ראשונים בתיאור הכלי של התוסף.
dependenciesרשימה של {name, version, optional}לאתוספים אחרים שהתוסף הזה מריץ. ברירת המחדל של version היא "*"; של optional היא false. הנתיבים <SLUG>_BIN שלהם מוגדרים בכל קריאה.
authobjectלאהתחברות וחשבונות. ראה אימות.
capabilitiesobjectלאconfigSchema, hooks, commands, routes, providers.
permissionsobjectלאסינון סביבה ותקרת הזמן הקצוב.
eventslistלאמשגיחים שמזינים את תהליכי העבודה של העובדים.
interfaceBindingsmapלאפעולות מוגדרות טיפוס שהתוסף מספק.
channelobjectלאגשר קבוע לשירות הודעות.
setupobjectלאאשף הגדרה צעד אחר צעד.

Nebo מאמת התקנות מהחנות: כללי ה-slug, גרסה סמנטית, לפחות פלטפורמה אחת, binaryName בלי מפרידי נתיב או .., פקודת login אלא אם auth.type הוא env, שמות אירועים ופקודות שאינם ריקים, ותבניות קישור שעוברות ניתוח. תוספים בתיקיית התוספים של המשתמש מדלגים על האימות.

פלטפורמות

המפתחות הם darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 ו-windows-amd64. בכל רשומה יש את כל חמשת השדות שלמטה. כשאתה מפרסם, החנות כותבת את הגיבוב, הגודל, החתימה וכתובת ההורדה האמיתיים, אז השאר אותם ריקים בקובץ שאתה מעלה.

"platforms": {
  "darwin-arm64":  { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "linux-amd64":   { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
}
שדהמשמעות
binaryNameשם הקובץ של קובץ ההפעלה. הוסף .exe ב-Windows.
sha256הגיבוב של הקובץ הבינארי. נבדק בהתקנה.
signatureהחתימה של הקובץ הבינארי. נבדקת בהתקנה כשיש מפתח חתימה זמין.
sizeגודל בבתים.
downloadUrlהמקום שממנו Nebo מוריד את החבילה.

אימות

שדהמשמעות
typeoauth_cli להתחברות בדפדפן שהתוסף מריץ; env לפרטי גישה שמוזנים כערכים; neboai כדי לקבל את אסימון ה-NeboAI של הבעלים בכל מפתח של auth.env שמסתיים ב-_TOKEN.
envמיפוי של שם משתנה לערך ברירת מחדל. אלה גם שמות פרטי הגישה היחידים ש-Nebo מעביר ל-login.
commands.loginמתחבר. חובה אלא אם type הוא env. רץ כשתיקיית החשבון מוגדרת.
commands.statusמדפיס JSON שאומר אם החשבון מחובר.
commands.refreshמחדש אסימון בלי אינטראקציה.
commands.logoutמתנתק. רק הבעלים יכול להריץ אותה.
profileDirEnvמשתנה שמקבל תיקיית פרטי גישה נפרדת לכל עובד ולכל חשבון. בלעדיו התוסף מחזיק חשבון משותף אחד.
label, descriptionהטקסט בכרטיס החיבור.
help{url, urlLabel, text} שמוצג בזמן החיבור.
publicRedirectהגדר true כשהספק מסרב להפניות אל http://localhost; ההתחברות עוברת אז דרך ההפניה הציבורית של NeboAI.

Nebo קורא את הראשון מבין authenticated, isAuthenticated, logged_in, loggedIn או token_valid בפלט הסטטוס. token_error שאינו ריק, או הערך none ב-credential_source, auth_method, storage או status, פירושו שהחשבון מנותק. לפקודת הסטטוס יש 45 שניות.

{"authenticated": true, "account": "finance@example.com"}

configSchema

capabilities.configSchema מתאר את הערכים שהבעלים מגדיר לתוסף. כל ערך מגיע לקובץ הבינארי כמשתנה סביבה ששמו נקבע לפי key. עבור מפתחות של פרטי גישה שמופיעים גם ב-auth.env, הסכמה נותנת תוויות לשדות של טופס החיבור לכל עובד.

שדהסוגברירת מחדלמשמעות
keystringחובהשם משתנה הסביבה.
labelstringחובהתווית השדה.
descriptionstring""טקסט עזרה.
fieldTypestring"string"סוג הקלט, כמו string, number, boolean, select או password.
defaultstringאיןערך שממולא מראש.
requiredbooleanfalseהתוסף לא מוכן עד שהערך מוגדר.
secretbooleanfalseהערך מוסתר כשקוראים אותו בחזרה.
optionsרשימת מחרוזותאיןאפשרויות הבחירה עבור select.

permissions

שדהברירת מחדלמשמעות
envAllow[]משתנים בירושה שהתוסף רשאי לראות. ריק מתיר את כולם.
envDeny[]משתנים בירושה שתמיד מוסרים.
maxTimeoutSeconds300הגבול העליון לזמן הקצוב של כל קריאה.
networkfalseמצהיר על שימוש ברשת. למידע בלבד; לא נאכף.

events

אירוע הוא משגיח שרץ לאורך זמן. Nebo מפעיל אותו כשתהליך עבודה של עובד משגיח עליו, ומפעיל אותו מחדש אם הוא יוצא. כל שורה שהמשגיח כותב ל-stdout היא אירוע אחד. בזמן הריצה מתווסף ה-slug לפני שם האירוע, כך ש-note.created הופך ל-notes-sync.note.created.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]
שדהמשמעות
nameשם האירוע, בלי ה-slug. חובה.
commandארגומנטים שמפעילים את המשגיח. חובה. {{key}} מוחלף בערכי הקלט של העובד.
descriptionמה גורם לאירוע.
multiplexedכשהערך הוא true, משגיח אחד פולט כמה סוגי אירועים וכל שורה נושאת שדה "event".

תהליכי עבודה נרשמים לאירועים באמצעות טריגר watch. ראה טריגרים.

interfaceBindings

קישור ממפה פעולת ממשק לאחת הפקודות שלך. כל קישור הופך לכלי מוגדר טיפוס עבור העובדים, שנקרא על שם הפעולה באותיות קטנות, עם קווים תחתונים במקום נקודות ומקפים: notes.search הופך ל-notes_search. באמצעות קישורים תוסף ממלא את היכולות שעובד דורש; ראה יכולות.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}
מציין מיקוםמתרחב ל
{field}ערך השדה כמילה אחת. השדה לא מועבר בנוסף כדגל.
{field[]:--flag}זוג --flag <item> אחד לכל פריט בשדה מסוג רשימה.
{field?:--flag}--flag <value> כשהשדה קיים; כלום כשהוא חסר.
{field:cents->dollars}סכום שלם בסנטים, שנכתב כדולרים.

שדות קלט שתבנית לא מציינת מתווספים בסוף כ---field value. מצייני מיקום של רשימה ושל ערך אופציונלי חייבים להיות מילים שלמות. אי אפשר להגיע לפעולה שדורשת אישור על ידי קריאה לאותה פקודה דרך plugin__<slug>.

Hooks, פקודות סלאש ונתיבים

"capabilities": {
  "hooks": [
    { "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
  ],
  "commands": [
    { "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
  ],
  "routes": [
    { "path": "/callback", "method": "GET", "command": "http callback" }
  ]
}

hooks

Hook מריץ את הפקודה שלך בנקודה מסוימת בתור של עובד. Nebo כותב מטען JSON ל-stdin. הפלט של hook מסוג action לא נלקח בחשבון. hook מסוג filter מחזיר {"payload": ..., "handled": false}; ‏"handled": true עוצר את ה-hooks שאחריו. שגיאות וחריגות זמן משאירות את המטען הקודם ואף פעם לא חוסמות את התור. אחרי שלושה כשלים ברצף, ה-hook מושהה לחמש דקות.

שדהברירת מחדלמשמעות
hookחובהאחד מבין tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue.
hookType"action"action או filter.
commandחובהארגומנטים לקובץ הבינארי שלך.
priority100נמוך יותר רץ ראשון.
timeoutMs500מגבלת זמן באלפיות שנייה.

commands

עם "slash": true, הקלדה של /name args בצ׳אט מריצה את command args ישירות, בלי העובד. הפלט הוא התשובה. מגבלת הזמן היא 30 שניות.

routes

נתיב עונה לבקשות HTTP בכתובת /api/v1/plugins/<slug>/api/<path> בבוט, לפי התאמה של path ו-method. גוף הבקשה עובר ל-stdin, וה-stdout שלך הוא התגובה. מגבלת הזמן היא 30 שניות.

providers

ספק מוסיף מקור למודל צ׳אט. הצהר על id, displayName, providerType, modelsCommand ו-chatCommand. Nebo שולח בקשת צ׳אט כ-JSON ב-stdin אל chatCommand וקורא אירועים בהזרמה כ-JSON מופרד בשורות חדשות ב-stdout, עד 300 שניות. כרגע נעשה שימוש רק בהזרמת צ׳אט.

channel

ערוץ מגשר אל שירות הודעות. Nebo משאיר את command פועל, קורא הודעות נכנסות מה-stdout שלו וכותב תשובות ל-stdin שלו, בשני המקרים כ-JSON מופרד בשורות חדשות.

שדהברירת מחדלמשמעות
commandחובהארגומנטים שמפעילים את הגשר.
name, description""מוצג בהגדרות.
restartDelaySecs5זמן המתנה לפני הפעלה מחדש אחרי קריסה.
sharedfalseגשר אחד לכל העובדים; ההודעות מנותבות לפי שם העובד, והתשובות נושאות את הזהות של כל עובד.
needsLocalApifalseמעביר לגשר את כתובת ה-API המקומית של הבוט, אסימון ואת מזהה העובד. כבוי, אלא אם אתה צריך אותו.

setup

אשף הגדרה מוביל את הבעלים דרך שלבים שטופס יחיד לא יכול לכסות. ערכים משלבי form ממלאים את {{key}} בארגומנטים של generate בהמשך. ערכים משלבי credentials נשמרים כמשתני הסביבה של התוסף.

"setup": {
  "title": "Connect Example Chat",
  "steps": [
    { "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
    { "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
    { "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
    { "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
  ]
}
סוג השלבשדות
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. מציג את הפלט של הפקודה להעתקה.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. השלב מסתיים כש-verifyCommand מצליחה.

לשדות יש key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) ו-required.