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, auth.type이 env가 아닌 경우의 login 명령, 비어 있지 않은 이벤트 이름과 명령, 그리고 파싱 가능한 바인딩 템플릿을 확인합니다. 사용자 플러그인 디렉터리에 있는 플러그인은 검증을 건너뜁니다.

플랫폼

키는 darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64, windows-amd64입니다. 각 항목에는 아래 다섯 필드가 모두 있습니다. 게시하면 마켓플레이스가 실제 해시, 크기, 서명, 다운로드 URL을 기록하므로, 업로드하는 파일에서는 비워 두세요.

"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실행 파일의 파일 이름입니다. Windows에서는 .exe를 붙이세요.
sha256바이너리의 해시입니다. 설치할 때 확인합니다.
signature바이너리의 서명입니다. 서명 키가 있으면 설치할 때 확인합니다.
size바이트 단위 크기입니다.
downloadUrlNebo가 패키지를 다운로드하는 위치입니다.

인증

필드의미
typeoauth_cli는 플러그인이 실행하는 브라우저 로그인, env는 값으로 입력하는 자격 증명, neboai는 _TOKEN으로 끝나는 모든 auth.env 키로 소유자의 NeboAI 토큰을 받는 방식입니다.
env변수 이름과 기본값의 대응입니다. Nebo가 login에 전달하는 자격 증명 이름은 이것뿐입니다.
commands.login로그인합니다. type이 env가 아니면 필수입니다. 계정 폴더가 설정된 상태로 실행됩니다.
commands.status계정이 로그인되어 있는지 알려주는 JSON을 출력합니다.
commands.refresh사용자 개입 없이 토큰을 갱신합니다.
commands.logout로그아웃합니다. 소유자만 실행할 수 있습니다.
profileDirEnv직원과 계정마다 별도의 자격 증명 폴더를 받는 변수입니다. 이 값이 없으면 플러그인은 공유 계정 하나만 사용합니다.
label, description연결 카드에 표시되는 텍스트입니다.
help연결하는 동안 표시되는 {url, urlLabel, text}입니다.
publicRedirect제공업체가 http://localhost 리디렉션을 거부할 때 true로 설정하세요. 그러면 로그인이 NeboAI의 공개 리디렉션을 거쳐 진행됩니다.

Nebo는 상태 출력에서 authenticated, isAuthenticated, logged_in, loggedIn, token_valid 중 처음 나오는 값을 읽습니다. 비어 있지 않은 token_error가 있거나 credential_source, auth_method, storage, status의 값이 none이면 로그아웃 상태로 봅니다. 상태 명령에는 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"
  }
]
필드의미
nameslug를 제외한 이벤트 이름입니다. 필수입니다.
command감시자를 시작하는 인수입니다. 필수입니다. {{key}}는 직원의 입력값으로 대체됩니다.
description이벤트를 일으키는 원인입니다.
multiplexedtrue이면 감시자 하나가 여러 이벤트 타입을 내보내며, 각 줄에 "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>로 같은 명령을 호출해도 실행할 수 없습니다.

훅, 슬래시 명령, 라우트

"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

훅은 직원의 턴 중 특정 시점에 명령을 실행합니다. Nebo는 JSON 페이로드를 stdin에 씁니다. action 훅의 출력은 무시됩니다. filter 훅은 {"payload": ..., "handled": false}를 반환하며, "handled": true이면 이후 훅이 실행되지 않습니다. 오류나 시간 초과가 발생하면 이전 페이로드가 유지되며 턴을 막지 않습니다. 세 번 연속 실패한 훅은 5분 동안 일시 중지됩니다.

필드기본값의미
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

라우트는 봇의 /api/v1/plugins/<slug>/api/<path>에서 HTTP 요청에 응답하며, path와 method로 일치 여부를 판단합니다. 요청 본문은 stdin으로 전달되고 stdout이 응답이 됩니다. 시간 제한은 30초입니다.

providers

제공업체는 채팅 모델 소스를 추가합니다. id, displayName, providerType, modelsCommand, chatCommand를 선언하세요. Nebo는 채팅 요청을 JSON으로 chatCommand의 stdin에 보내고, 스트리밍되는 이벤트를 stdout에서 줄 단위 JSON으로 최대 300초 동안 읽습니다. 현재는 채팅 스트리밍만 사용합니다.

channel

채널은 메시징 서비스를 연결합니다. Nebo는 command를 계속 실행해 두고, stdout에서 수신 메시지를 읽고 stdin에 답장을 씁니다. 둘 다 줄 단위 JSON입니다.

필드기본값의미
command필수브리지를 시작하는 인수입니다.
name, description""설정에 표시됩니다.
restartDelaySecs5충돌 후 다시 시작하기 전에 기다리는 시간입니다.
sharedfalse모든 직원이 브리지 하나를 사용합니다. 메시지는 직원 이름으로 라우팅되고, 답장에는 각 직원의 신원이 담깁니다.
needsLocalApifalse브리지에 봇의 로컬 API 주소, 토큰, 직원 ID를 전달합니다. 필요한 경우가 아니면 꺼져 있습니다.

setup

설정 마법사는 하나의 양식으로는 다룰 수 없는 단계를 소유자에게 차례로 안내합니다. form 단계의 값은 이후 generate 인수의 {{key}}를 채웁니다. 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가 있습니다.