NeboAI
NeboAI
시작하기

플러그인

플러그인은 직원이 작업할 대상을 제공합니다. 온라인 서비스, 비즈니스 시스템, 컴퓨터의 프로그램 등이 그 대상입니다. 플러그인은 명령줄 바이너리로 만들고 plugin.json 매니페스트로 설명합니다. 직원은 플러그인의 명령을 호출하고, 설치, 직원별 계정, 업데이트는 Nebo가 처리합니다.

플러그인 작동 방식

플러그인은 실행 파일과 매니페스트로 이루어집니다. Nebo는 호출과 호출 사이에 플러그인 프로세스를 계속 실행해 두지 않습니다. 직원이 플러그인을 사용할 때마다 Nebo는 명령과 인수로 바이너리를 시작하고, 종료될 때까지 기다린 다음, 출력을 직원에게 돌려줍니다.

  • 명령은 인수입니다. 직원은 notes search 같은 명령과 이름이 있는 인수를 선택합니다. Nebo는 각 인수를 --name value로 전달합니다. 셸이 없으므로 파이프와 리디렉션은 적용되지 않습니다.
  • 출력은 stdout입니다. 결과를 stdout에 쓰세요. JSON이 잘 맞습니다.
  • 일반 호출에서는 표준 입력이 닫혀 있습니다. 훅, 라우트, 채팅 제공업체는 stdin을 사용합니다. plugin.json 참조를 확인하세요.

설치되고 활성화된 모든 플러그인은 직원에게 plugin__<slug>라는 도구 하나로 보입니다. 직원은 다음과 같이 호출합니다.

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

Nebo는 다음을 실행합니다.

notes-sync notes search --query "quarterly plan" --limit 5
매개변수타입의미
command문자열, 필수플러그인 명령과 위치 인수 단어입니다.
args문자열 객체이름이 있는 인수입니다. 각각 --key value가 됩니다.
timeoutinteger대기할 시간(초)입니다. 기본값은 120이며, 매니페스트의 permissions.maxTimeoutSeconds를 넘을 수 없습니다.
displaystring호출에 승인이 필요할 때 소유자에게 보이는 문장입니다.

첫 플러그인 만들기

인수에서 명령을 읽고 결과를 출력하는 바이너리를 아무 언어로나 작성하세요. 그런 다음 봇의 사용자 플러그인 디렉터리에 plugin.json과 함께 넣으세요.

<data>/user/plugins/notes-sync/
├── plugin.json      # runtime manifest
├── notes-sync       # your binary, named after the slug
└── skills/          # optional: skills that teach employees to use it
    └── notes-sync/
        └── SKILL.md
{
  "id": "notes-sync",
  "slug": "notes-sync",
  "name": "Notes Sync",
  "version": "0.1.0",
  "description": "Search, read and create notes in Example Notes.",
  "platforms": {}
}

id, slug, name, version, platforms는 필수입니다. 사용자 플러그인 디렉터리에서는 platforms 맵을 비워 둘 수 있습니다. 이 경우 Nebo는 plugin.json 옆에서 slug 이름의 바이너리를 찾고, 이어서 target/release/와 target/debug/에서 찾습니다. 게시하면 마켓플레이스가 업로드한 모든 바이너리에 대해 platforms를 채웁니다.

<data>는 macOS에서는 ~/Library/Application Support/Nebo, Windows에서는 %APPDATA%\Nebo, Linux에서는 ~/.local/share/nebo이며, 설정한 경우 NEBO_HOME의 값입니다. 사용자 디렉터리의 플러그인은 같은 slug의 마켓플레이스 플러그인보다 우선하므로, 새 빌드를 테스트하기에 알맞은 곳입니다.

직원에게 사용법 알려주기

plugin.json 옆에 skills/ 폴더를 두세요. 그 안의 각 스킬은 플러그인이 설치되어 있는 동안 모든 직원이 사용할 수 있으며, 플러그인을 의존성으로 자동으로 등록합니다. 스킬에서 어떤 명령이 있는지, 무엇을 반환하는지, 언제 사용해야 하는지 알려주세요. 가장 유용한 스킬을 entrySkills에 넣으면 플러그인의 도구 설명이 그 스킬을 가장 먼저 안내합니다.

마켓플레이스 목록 페이지는 별도의 파일인 PLUGIN.md입니다. Nebo는 실행 중에 이 파일을 읽지 않으며, 사람들이 설치하기 전에 보는 페이지입니다. 플러그인 출시하기를 참고하세요.

환경

각 호출은 로더와 셸 주입 변수를 제거한 봇의 환경을 상속한 다음, 다음 값을 추가합니다. 나중 항목이 우선합니다.

변수값
auth.env 키매니페스트의 기본값입니다.
<SLUG>_BIN이 플러그인과 이 플러그인이 의존하는 각 플러그인의 바이너리 경로입니다. slug는 대문자로 바뀌고 하이픈은 밑줄로 바뀝니다.
NEBO_DATA_DIR플러그인 자체의 데이터 폴더인 <data>/appdata/plugins/<slug>/입니다. 작업 디렉터리이기도 하며, 제거 후에도 유지됩니다.
PATH플러그인 폴더가 먼저 오고, 이어서 상속된 경로가 옵니다.
설정소유자가 configSchema 필드에 저장한 값입니다.
NEBO_AGENT_ID호출하는 직원입니다.
profileDirEnv플러그인이 계정을 지원하는 경우, 이 직원과 계정의 계정 폴더입니다.

permissions.envAllow와 permissions.envDeny는 플러그인이 봇에서 상속하는 항목을 좁힙니다. 플러그인 자체의 인증 변수는 절대 제거하지 않습니다.

계정과 자격 증명

서비스에 로그인하는 플러그인은 직원마다 계정을 하나씩 가져야 합니다. 경리 담당 직원은 재무 로그인으로, 비서는 자기 로그인으로 로그인하며, 서로의 토큰을 보지 못합니다. 매니페스트에 이를 선언하기만 하면 나머지는 Nebo가 처리합니다.

"auth": {
  "type": "env",
  "label": "Example Notes account",
  "env": { "EXAMPLE_NOTES_TOKEN": "" },
  "commands": { "login": "auth login", "status": "auth status", "logout": "auth logout" },
  "profileDirEnv": "EXAMPLE_NOTES_CONFIG_DIR"
},
"capabilities": {
  "configSchema": [
    { "key": "EXAMPLE_NOTES_TOKEN", "label": "API token", "fieldType": "password", "secret": true, "required": true }
  ]
}
  1. auth.env는 자격 증명의 이름을 정합니다. capabilities.configSchema는 자격 증명에 레이블을 붙이고 연결 양식에서의 순서를 정합니다.
  2. auth.profileDirEnv는 플러그인이 자격 증명 폴더를 찾기 위해 읽는 변수의 이름을 정합니다. Nebo는 직원과 계정마다 폴더를 하나씩 만들고 호출할 때마다 그 변수를 설정합니다.
  3. 소유자가 계정을 연결하면 Nebo는 소유자가 입력한 값과 계정 폴더를 설정한 상태로 login 명령을 실행합니다. 플러그인은 필요한 것을 그 폴더에 저장합니다. Nebo는 값을 보관하지 않습니다.
  4. status 명령은 {"authenticated": true} 같은 JSON을 출력합니다. 토큰이 만료되면, refresh를 선언한 경우 Nebo가 이를 실행합니다.

브라우저 로그인을 사용하려면 type을 oauth_cli로 설정하고 login이 제공업체의 로그인 URL을 출력하거나 열도록 하세요. 직원이 혼자 로그인하는 일은 없습니다. 호출에 로그인이 필요하면 소유자에게 연결 카드가 표시됩니다. 계정이 여러 개인 직원은 명령에 --account <label>을 추가해 하나를 고릅니다. Nebo는 바이너리에 전달하기 전에 이 플래그를 제거합니다.

형태가 아니라 서비스의 이름을 붙이세요. 플러그인 이름은 "Example Notes"처럼 무엇에 연결되는지를 나타내야 합니다. 플러그인 이름에 "CLI"를 넣지 마세요. 직원과 소유자에게 플러그인은 명령줄이 아니라 연결입니다.

다음 단계