NeboAI
NeboAI
Bắt đầu

Plugin

Plugin cho nhân viên một thứ để thao tác: một dịch vụ trực tuyến, một hệ thống kinh doanh hoặc một chương trình trên máy tính. Bạn xây dựng nó dưới dạng tệp nhị phân dòng lệnh và mô tả nó bằng tệp kê khai plugin.json. Nhân viên gọi các lệnh của nó, còn Nebo lo việc cài đặt, tài khoản theo từng nhân viên và cập nhật.

Cách plugin hoạt động

Plugin là một tệp thực thi cộng với một tệp kê khai. Nebo không giữ tiến trình plugin nào chạy giữa các lần gọi. Mỗi lần nhân viên dùng plugin, Nebo khởi động tệp nhị phân với một lệnh và các đối số, chờ nó thoát, rồi trả kết quả lại cho nhân viên.

  • Lệnh là đối số. Nhân viên chọn một lệnh, chẳng hạn notes search, và các đối số có tên. Nebo truyền mỗi đối số dưới dạng --name value. Không có shell, nên pipe và chuyển hướng không bao giờ áp dụng.
  • Kết quả là stdout. Ghi kết quả ra stdout. JSON là lựa chọn tốt.
  • Đầu vào chuẩn bị đóng với các lần gọi thông thường. Hook, route và nhà cung cấp trò chuyện dùng stdin; xem tài liệu tham khảo plugin.json.

Mỗi plugin đã cài và bật đều hiện với nhân viên thành một công cụ tên plugin__<slug>. Nhân viên gọi nó như sau:

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

Nebo chạy:

notes-sync notes search --query "quarterly plan" --limit 5
Tham sốKiểuÝ nghĩa
commandchuỗi, bắt buộcLệnh của plugin và mọi từ theo vị trí.
argsđối tượng gồm các chuỗiCác đối số có tên. Mỗi đối số trở thành --key value.
timeoutintegerSố giây chờ. Mặc định 120, giới hạn bởi permissions.maxTimeoutSeconds của tệp kê khai.
displaystringCâu mà chủ sở hữu nhìn thấy khi lần gọi cần phê duyệt.

Xây dựng plugin đầu tiên của bạn

Viết một tệp nhị phân bằng bất kỳ ngôn ngữ nào, đọc lệnh từ các đối số và in ra kết quả. Sau đó đặt nó cạnh một tệp plugin.json trong thư mục plugin của người dùng trên một bot.

<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 và platforms là bắt buộc. Trong thư mục plugin của người dùng, ánh xạ platforms có thể để trống: Nebo tìm tệp nhị phân có tên theo slug cạnh plugin.json, rồi trong target/release/ và target/debug/. Khi bạn phát hành, chợ ứng dụng điền platforms cho mọi tệp nhị phân bạn tải lên.

<data> là ~/Library/Application Support/Nebo trên macOS, %APPDATA%\Nebo trên Windows và ~/.local/share/nebo trên Linux, hoặc giá trị của NEBO_HOME. Plugin trong thư mục người dùng ghi đè plugin trên chợ ứng dụng có cùng slug, nên đây là nơi để kiểm thử bản dựng mới.

Dạy nhân viên cách dùng

Đặt một thư mục skills/ cạnh plugin.json. Mỗi kỹ năng trong đó đều dùng được cho mọi nhân viên khi plugin đang được cài, và tự động liệt kê plugin là phần phụ thuộc. Dùng kỹ năng để nói có những lệnh nào, chúng trả về gì và khi nào dùng từng lệnh. Nêu tên các kỹ năng hữu ích nhất trong entrySkills để mô tả công cụ của plugin chỉ tới chúng trước tiên.

Trang niêm yết trên chợ ứng dụng là một tệp riêng, PLUGIN.md. Nebo không đọc tệp này khi chạy; đó là trang mọi người xem trước khi cài đặt. Xem Phát hành plugin.

Môi trường

Mỗi lần gọi kế thừa môi trường của bot sau khi đã loại bỏ các biến của trình nạp và biến chèn shell, rồi thêm các giá trị sau. Mục sau được ưu tiên hơn.

BiếnGiá trị
Các khóa auth.envGiá trị mặc định từ tệp kê khai.
<SLUG>_BINĐường dẫn tới tệp nhị phân của plugin này và của từng plugin mà nó phụ thuộc. Slug được viết hoa, dấu gạch nối thành dấu gạch dưới.
NEBO_DATA_DIRThư mục dữ liệu riêng của plugin, <data>/appdata/plugins/<slug>/. Đây cũng là thư mục làm việc, và nó vẫn còn sau khi gỡ cài đặt.
PATHCác thư mục plugin trước, rồi tới đường dẫn kế thừa.
Cài đặtCác giá trị chủ sở hữu đã lưu cho các trường configSchema.
NEBO_AGENT_IDNhân viên thực hiện lần gọi.
profileDirEnvThư mục tài khoản cho nhân viên và tài khoản này, khi plugin hỗ trợ tài khoản.

permissions.envAllow và permissions.envDeny thu hẹp những gì plugin kế thừa từ bot. Chúng không bao giờ loại bỏ các biến xác thực riêng của plugin.

Tài khoản và thông tin đăng nhập

Một plugin đăng nhập vào dịch vụ nên giữ một tài khoản cho mỗi nhân viên. Nhân viên kế toán đăng nhập bằng tài khoản tài chính, trợ lý đăng nhập bằng tài khoản riêng, và không ai thấy token của người kia. Bạn khai báo điều này trong tệp kê khai; Nebo lo phần còn lại.

"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 đặt tên cho các thông tin đăng nhập. capabilities.configSchema gắn nhãn cho chúng và đặt thứ tự của chúng trong biểu mẫu kết nối.
  2. auth.profileDirEnv đặt tên cho biến mà plugin của bạn đọc để lấy thư mục thông tin đăng nhập. Nebo tạo một thư mục cho mỗi nhân viên và tài khoản, và đặt biến đó ở mỗi lần gọi.
  3. Khi chủ sở hữu kết nối một tài khoản, Nebo chạy lệnh login của bạn với các giá trị chủ sở hữu đã nhập và thư mục tài khoản đã được đặt. Plugin của bạn lưu những gì nó cần vào thư mục đó. Nebo không giữ các giá trị này.
  4. Lệnh status của bạn in ra JSON, ví dụ {"authenticated": true}. Khi token hết hạn, Nebo chạy refresh nếu bạn có khai báo.

Với đăng nhập qua trình duyệt, đặt type thành oauth_cli và để login in ra hoặc mở URL đăng nhập của nhà cung cấp. Nhân viên không bao giờ tự đăng nhập: khi một lần gọi cần đăng nhập, chủ sở hữu sẽ thấy thẻ kết nối. Nhân viên có nhiều tài khoản chọn một tài khoản bằng cách thêm --account <label> vào lệnh. Nebo gỡ cờ đó trước khi tệp nhị phân của bạn nhìn thấy.

Đặt tên theo dịch vụ, không theo hình thức. Tên plugin cho biết nó kết nối tới đâu, chẳng hạn "Example Notes". Đừng bao giờ đưa "CLI" vào tên plugin; với nhân viên và chủ sở hữu, đó là một kết nối, không phải một dòng lệnh.

Tiếp theo