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 |
|---|---|---|
command | chuỗi, bắt buộc | Lệnh của plugin và mọi từ theo vị trí. |
args | đối tượng gồm các chuỗi | Các đối số có tên. Mỗi đối số trở thành --key value. |
timeout | integer | Số giây chờ. Mặc định 120, giới hạn bởi permissions.maxTimeoutSeconds của tệp kê khai. |
display | string | Câ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ến | Giá trị |
|---|---|
Các khóa auth.env | Giá 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_DIR | Thư 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. |
PATH | Các thư mục plugin trước, rồi tới đường dẫn kế thừa. |
| Cài đặt | Các giá trị chủ sở hữu đã lưu cho các trường configSchema. |
NEBO_AGENT_ID | Nhân viên thực hiện lần gọi. |
profileDirEnv | Thư 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 }
]
} auth.envđặt tên cho các thông tin đăng nhập.capabilities.configSchemagắn nhãn cho chúng và đặt thứ tự của chúng trong biểu mẫu kết nối.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.- Khi chủ sở hữu kết nối một tài khoản, Nebo chạy lệnh
logincủ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. - Lệnh
statuscủa bạn in ra JSON, ví dụ{"authenticated": true}. Khi token hết hạn, Nebo chạyrefreshnế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
- Tài liệu tham khảo plugin.json: mọi trường, bao gồm sự kiện, hook và thao tác có kiểu.
- Phát hành plugin: nền tảng, tệp nhị phân, ký và cập nhật.
- Phát hành: quy trình trên chợ ứng dụng cho mọi sản phẩm.