NeboAI
NeboAI
Bắt đầu

Tham chiếu plugin.json

plugin.json là tệp kê khai mà Nebo đọc để cài đặt và chạy một plugin. Các khóa viết theo kiểu camelCase. Trang này liệt kê mọi trường Nebo đang đọc và chức năng của từng trường.

Các trường cấp cao nhất

TrườngKiểuBắt buộcÝ nghĩa
idstringcóMã định danh của plugin trên chợ ứng dụng. Dùng slug trong lúc phát triển.
slugstringcóMã định danh cố định. [a-z0-9-], tối đa 64 ký tự, không có dấu gạch nối ở đầu, ở cuối hoặc hai dấu liền nhau. Dùng để đặt tên công cụ plugin__<slug> và biến <SLUG>_BIN.
namestringcóTên hiển thị. Hãy nêu tên dịch vụ mà nó kết nối tới.
versionstringcóPhiên bản ngữ nghĩa, chẳng hạn 0.1.0.
platformsmapcóÁnh xạ khóa nền tảng tới tệp nhị phân. Xem phần Nền tảng.
descriptionstringkhôngMột câu dành cho mọi người và nhân viên.
authorstringkhôngTên nhà phát hành.
categorystringkhôngGiúp nhân viên tìm thấy plugin.
triggersdanh sách chuỗikhôngCác từ mô tả khi nào plugin được áp dụng. Dùng trong gợi ý tìm kiếm.
entrySkillsdanh sách chuỗikhôngCác kỹ năng đi kèm được nêu tên đầu tiên trong mô tả công cụ của plugin.
dependenciesdanh sách {name, version, optional}khôngCác plugin khác mà plugin này chạy. version mặc định là "*"; optional mặc định là false. Đường dẫn <SLUG>_BIN của chúng được đặt ở mỗi lần gọi.
authobjectkhôngĐăng nhập và tài khoản. Xem phần Xác thực.
capabilitiesobjectkhôngconfigSchema, hooks, commands, routes, providers.
permissionsobjectkhôngLọc môi trường và giới hạn thời gian chờ tối đa.
eventslistkhôngCác trình theo dõi cung cấp dữ liệu cho quy trình làm việc của nhân viên.
interfaceBindingsmapkhôngCác thao tác có kiểu mà plugin cung cấp.
channelobjectkhôngCầu nối lâu dài tới một dịch vụ nhắn tin.
setupobjectkhôngTrình hướng dẫn thiết lập từng bước.

Nebo xác thực các lượt cài đặt từ chợ ứng dụng: quy tắc slug, phiên bản ngữ nghĩa, ít nhất một nền tảng, binaryName không chứa dấu phân cách đường dẫn hay .., lệnh login trừ khi auth.type là env, tên sự kiện và lệnh không rỗng, và các mẫu ràng buộc phân tích được. Plugin trong thư mục plugin của người dùng được bỏ qua bước xác thực.

Nền tảng

Các khóa là darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 và windows-amd64. Mỗi mục có đủ năm trường bên dưới. Khi bạn phát hành, chợ ứng dụng sẽ ghi giá trị băm, kích thước, chữ ký và URL tải xuống thật, nên hãy để trống chúng trong tệp bạn tải lên.

"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": "" }
}
TrườngÝ nghĩa
binaryNameTên tệp thực thi. Thêm .exe trên Windows.
sha256Giá trị băm của tệp nhị phân. Được kiểm tra khi cài đặt.
signatureChữ ký của tệp nhị phân. Được kiểm tra khi cài đặt nếu có khóa ký.
sizeKích thước tính bằng byte.
downloadUrlNơi Nebo tải gói xuống.

Xác thực

TrườngÝ nghĩa
typeoauth_cli cho đăng nhập qua trình duyệt do plugin thực hiện; env cho thông tin đăng nhập được nhập dưới dạng giá trị; neboai để nhận token NeboAI của chủ sở hữu trong mọi khóa auth.env kết thúc bằng _TOKEN.
envÁnh xạ tên biến tới giá trị mặc định. Đây cũng là những tên thông tin đăng nhập duy nhất mà Nebo truyền cho login.
commands.loginĐăng nhập. Bắt buộc trừ khi type là env. Chạy với thư mục tài khoản đã được đặt.
commands.statusIn ra JSON cho biết tài khoản đã đăng nhập hay chưa.
commands.refreshGia hạn token mà không cần tương tác.
commands.logoutĐăng xuất. Chỉ chủ sở hữu mới có thể chạy.
profileDirEnvBiến nhận một thư mục thông tin đăng nhập riêng cho từng nhân viên và tài khoản. Nếu không có, plugin chỉ giữ một tài khoản dùng chung.
label, descriptionNội dung trên thẻ kết nối.
help{url, urlLabel, text} hiển thị trong khi kết nối.
publicRedirectĐặt true khi nhà cung cấp từ chối chuyển hướng http://localhost; khi đó việc đăng nhập sẽ đi qua địa chỉ chuyển hướng công khai của NeboAI.

Nebo đọc trường đầu tiên trong số authenticated, isAuthenticated, logged_in, loggedIn hoặc token_valid trong kết quả trạng thái. Một token_error không rỗng, hoặc giá trị none trong credential_source, auth_method, storage hay status, nghĩa là đã đăng xuất. Lệnh trạng thái có 45 giây.

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

configSchema

capabilities.configSchema mô tả các giá trị mà chủ sở hữu đặt cho plugin. Mỗi giá trị tới tệp nhị phân dưới dạng một biến môi trường có tên theo key. Với các khóa thông tin đăng nhập cũng được liệt kê trong auth.env, schema đặt nhãn cho các trường của biểu mẫu kết nối theo từng nhân viên.

TrườngKiểuMặc địnhÝ nghĩa
keystringbắt buộcTên biến môi trường.
labelstringbắt buộcNhãn của trường.
descriptionstring""Văn bản trợ giúp.
fieldTypestring"string"Kiểu nhập liệu, chẳng hạn string, number, boolean, select hoặc password.
defaultstringkhông cóGiá trị điền sẵn.
requiredbooleanfalsePlugin chưa sẵn sàng cho đến khi giá trị này được đặt.
secretbooleanfalseGiá trị được che khi đọc lại.
optionsdanh sách chuỗikhông cóCác lựa chọn cho select.

permissions

TrườngMặc địnhÝ nghĩa
envAllow[]Các biến kế thừa mà plugin được phép thấy. Để trống thì cho phép tất cả.
envDeny[]Các biến kế thừa luôn bị loại bỏ.
maxTimeoutSeconds300Giới hạn trên cho thời gian chờ của mọi lần gọi.
networkfalseKhai báo việc sử dụng mạng. Chỉ mang tính thông tin; không được thực thi.

events

Sự kiện là một trình theo dõi chạy lâu dài. Nebo khởi động nó khi quy trình làm việc của một nhân viên theo dõi nó, và khởi động lại nếu nó thoát. Mỗi dòng trình theo dõi ghi ra stdout là một sự kiện. Tên sự kiện được thêm tiền tố slug khi chạy, nên note.created trở thành notes-sync.note.created.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]
TrườngÝ nghĩa
nameTên sự kiện, không kèm slug. Bắt buộc.
commandCác đối số khởi động trình theo dõi. Bắt buộc. {{key}} được thay bằng giá trị đầu vào của nhân viên.
descriptionĐiều gì gây ra sự kiện.
multiplexedKhi là true, một trình theo dõi phát ra nhiều loại sự kiện và mỗi dòng mang một trường "event".

Quy trình làm việc đăng ký nhận sự kiện bằng trình kích hoạt watch. Xem Trình kích hoạt.

interfaceBindings

Một ràng buộc ánh xạ một thao tác giao diện tới một trong các lệnh của bạn. Mỗi ràng buộc trở thành một công cụ có kiểu cho nhân viên, được đặt tên theo thao tác viết thường, với dấu chấm và dấu gạch nối thành dấu gạch dưới: notes.search trở thành notes_search. Ràng buộc là cách một plugin đáp ứng các năng lực mà nhân viên yêu cầu; xem Năng lực.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}
Phần giữ chỗMở rộng thành
{field}Giá trị của trường dưới dạng một từ. Trường đó không được truyền thêm dưới dạng cờ.
{field[]:--flag}Một cặp --flag <item> cho mỗi phần tử trong trường danh sách.
{field?:--flag}--flag <value> khi trường có mặt; không có gì khi trường vắng mặt.
{field:cents->dollars}Một số tiền nguyên tính bằng cent, được viết thành đô la.

Các trường đầu vào mà mẫu không nêu tên sẽ được nối thêm dưới dạng --field value. Phần giữ chỗ danh sách và tùy chọn phải là những từ trọn vẹn. Một thao tác cần phê duyệt không thể được gọi tới bằng cách chạy cùng lệnh đó qua plugin__<slug>.

Hook, lệnh gạch chéo và route

"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 chạy lệnh của bạn tại một thời điểm trong lượt làm việc của nhân viên. Nebo ghi một payload JSON vào stdin. Đầu ra của hook action bị bỏ qua. Hook filter trả về {"payload": ..., "handled": false}; "handled": true sẽ dừng các hook phía sau. Lỗi và hết thời gian chờ sẽ giữ lại payload trước đó và không bao giờ chặn lượt làm việc. Sau ba lần lỗi liên tiếp, hook bị tạm dừng trong năm phút.

TrườngMặc địnhÝ nghĩa
hookbắt buộcMột trong tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue.
hookType"action"action hoặc filter.
commandbắt buộcCác đối số cho tệp nhị phân của bạn.
priority100Giá trị thấp hơn chạy trước.
timeoutMs500Giới hạn thời gian tính bằng mili giây.

commands

Với "slash": true, gõ /name args trong cuộc trò chuyện sẽ chạy trực tiếp command args, không qua nhân viên. Kết quả đầu ra chính là câu trả lời. Giới hạn thời gian là 30 giây.

routes

Một route trả lời các yêu cầu HTTP tại /api/v1/plugins/<slug>/api/<path> trên bot, khớp theo path và method. Nội dung yêu cầu được đưa vào stdin và stdout của bạn là phản hồi. Giới hạn thời gian là 30 giây.

providers

Một nhà cung cấp thêm một nguồn mô hình trò chuyện. Khai báo id, displayName, providerType, modelsCommand và chatCommand. Nebo gửi yêu cầu trò chuyện dưới dạng JSON qua stdin tới chatCommand và đọc các sự kiện được truyền liên tục dưới dạng JSON phân tách bằng dòng mới trên stdout, trong tối đa 300 giây. Hiện tại chỉ dùng tính năng truyền phát trò chuyện.

channel

Một kênh làm cầu nối tới một dịch vụ nhắn tin. Nebo giữ command luôn chạy, đọc tin nhắn đến từ stdout của nó và ghi câu trả lời vào stdin của nó, cả hai đều dưới dạng JSON phân tách bằng dòng mới.

TrườngMặc địnhÝ nghĩa
commandbắt buộcCác đối số khởi động cầu nối.
name, description""Hiển thị trong cài đặt.
restartDelaySecs5Thời gian chờ trước khi khởi động lại sau sự cố.
sharedfalseMột cầu nối cho tất cả nhân viên; tin nhắn được định tuyến theo tên nhân viên và câu trả lời mang danh tính của từng nhân viên.
needsLocalApifalseCung cấp cho cầu nối địa chỉ API cục bộ của bot, một token và id của nhân viên. Tắt trừ khi bạn cần.

setup

Trình hướng dẫn thiết lập đưa chủ sở hữu qua các bước mà một biểu mẫu đơn lẻ không thể bao quát. Giá trị từ các bước form điền vào {{key}} trong các đối số generate phía sau. Giá trị từ các bước credentials được lưu thành biến môi trường của plugin.

"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" }
  ]
}
Loại bướcTrường
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Hiển thị kết quả của lệnh để sao chép.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. Bước hoàn tất khi verifyCommand thành công.

Các trường có key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) và required.