ปลั๊กอินทำงานอย่างไร
ปลั๊กอินคือโปรแกรมที่เรียกใช้ได้บวกกับ manifest Nebo ไม่ได้ให้โปรเซสของปลั๊กอินทำงานค้างไว้ระหว่างการเรียก ทุกครั้งที่พนักงานใช้ปลั๊กอิน Nebo จะเริ่มไบนารีพร้อมคำสั่งและอาร์กิวเมนต์ รอให้จบการทำงาน แล้วส่งเอาต์พุตกลับไปให้พนักงาน
- คำสั่งคืออาร์กิวเมนต์ พนักงานเลือกคำสั่ง เช่น
notes searchและอาร์กิวเมนต์แบบมีชื่อ Nebo ส่งแต่ละอาร์กิวเมนต์เป็น--name valueไม่มีเชลล์ ดังนั้นไปป์และการเปลี่ยนทิศทางจะไม่มีผล - เอาต์พุตคือ stdout เขียนผลลัพธ์ไปที่ stdout ซึ่ง JSON ใช้ได้ดี
- อินพุตมาตรฐานถูกปิด สำหรับการเรียกทั่วไป Hook เส้นทาง และผู้ให้บริการแชตใช้ 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 |
timeout | integer | จำนวนวินาทีที่รอ ค่าเริ่มต้นคือ 120 และไม่เกิน permissions.maxTimeoutSeconds ของ manifest |
display | string | ประโยคที่เจ้าของเห็นเมื่อการเรียกนั้นต้องได้รับอนุมัติ |
สร้างปลั๊กอินแรกของคุณ
เขียนไบนารีด้วยภาษาใดก็ได้ที่อ่านคำสั่งจากอาร์กิวเมนต์และแสดงผลลัพธ์ จากนั้นวางไว้ข้าง 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 จะหาไบนารีที่ตั้งชื่อตาม slug ข้าง plugin.json จากนั้นจึงหาใน target/release/ และ target/debug/ เมื่อคุณเผยแพร่ มาร์เก็ตเพลสจะกรอก platforms ให้สำหรับทุกไบนารีที่คุณอัปโหลด
<data> คือ ~/Library/Application Support/Nebo บน macOS, %APPDATA%\Nebo บน Windows และ ~/.local/share/nebo บน Linux หรือค่าของ NEBO_HOME ปลั๊กอินในไดเรกทอรีของผู้ใช้จะใช้แทนปลั๊กอินจากมาร์เก็ตเพลสที่มี slug เดียวกัน จึงเป็นที่สำหรับทดสอบบิลด์ใหม่
สอนพนักงานให้ใช้งาน
วางโฟลเดอร์ skills/ ไว้ข้าง plugin.json ทักษะแต่ละรายการในโฟลเดอร์นั้นจะพร้อมให้พนักงานทุกคนใช้ขณะที่ติดตั้งปลั๊กอินอยู่ และจะระบุปลั๊กอินเป็นสิ่งที่ต้องพึ่งพาโดยอัตโนมัติ ใช้ทักษะเพื่อบอกว่ามีคำสั่งอะไรบ้าง แต่ละคำสั่งส่งค่าอะไรกลับมา และควรใช้เมื่อใด ระบุชื่อทักษะที่มีประโยชน์ที่สุดไว้ใน entrySkills เพื่อให้คำอธิบายเครื่องมือของปลั๊กอินชี้ไปที่ทักษะเหล่านั้นก่อน
หน้ารายการในมาร์เก็ตเพลสเป็นไฟล์แยกชื่อ PLUGIN.md Nebo ไม่ได้อ่านไฟล์นี้ขณะทำงาน แต่เป็นหน้าที่ผู้คนเห็นก่อนติดตั้ง ดูที่ การเผยแพร่ปลั๊กอิน
สภาพแวดล้อม
แต่ละการเรียกจะสืบทอดสภาพแวดล้อมของบอทโดยนำตัวแปรของตัวโหลดและตัวแปรที่ใช้แทรกคำสั่งเชลล์ออก แล้วเพิ่มค่าเหล่านี้ รายการที่อยู่หลังจะมีผลเหนือกว่า
| ตัวแปร | ค่า |
|---|---|
คีย์ auth.env | ค่าเริ่มต้นจาก manifest |
<SLUG>_BIN | พาธของไบนารีของปลั๊กอินนี้ และของปลั๊กอินแต่ละตัวที่ปลั๊กอินนี้พึ่งพา slug จะเป็นตัวพิมพ์ใหญ่และเปลี่ยนขีดกลางเป็นขีดล่าง |
NEBO_DATA_DIR | โฟลเดอร์ข้อมูลของปลั๊กอินเอง <data>/appdata/plugins/<slug>/ และยังเป็นไดเรกทอรีทำงานด้วย โฟลเดอร์นี้จะยังอยู่หลังการถอนการติดตั้ง |
PATH | โฟลเดอร์ปลั๊กอินมาก่อน แล้วตามด้วยพาธที่สืบทอดมา |
| การตั้งค่า | ค่าที่เจ้าของบันทึกไว้สำหรับฟิลด์ใน configSchema |
NEBO_AGENT_ID | พนักงานที่เป็นผู้เรียก |
profileDirEnv | โฟลเดอร์บัญชีสำหรับพนักงานและบัญชีนี้ เมื่อปลั๊กอินรองรับบัญชี |
permissions.envAllow และ permissions.envDeny จำกัดสิ่งที่ปลั๊กอินสืบทอดจากบอท แต่จะไม่นำตัวแปรการยืนยันตัวตนของปลั๊กอินเองออก
บัญชีและข้อมูลรับรอง
ปลั๊กอินที่ลงชื่อเข้าใช้บริการควรมีบัญชีหนึ่งบัญชีต่อพนักงานหนึ่งคน พนักงานทำบัญชีลงชื่อเข้าใช้ด้วยบัญชีฝ่ายการเงิน ผู้ช่วยลงชื่อเข้าใช้ด้วยบัญชีของตัวเอง และไม่มีใครเห็นโทเค็นของอีกฝ่าย คุณประกาศสิ่งนี้ไว้ใน manifest แล้ว 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 }
]
} auth.envระบุชื่อข้อมูลรับรองcapabilities.configSchemaตั้งป้ายกำกับและกำหนดลำดับในแบบฟอร์มเชื่อมต่อauth.profileDirEnvระบุชื่อตัวแปรที่ปลั๊กอินของคุณอ่านเพื่อหาโฟลเดอร์ข้อมูลรับรอง Nebo จะสร้างโฟลเดอร์หนึ่งโฟลเดอร์สำหรับพนักงานและบัญชีแต่ละรายการ และตั้งค่าตัวแปรนั้นในทุกการเรียก- เมื่อเจ้าของเชื่อมต่อบัญชี Nebo จะเรียกคำสั่ง
loginของคุณพร้อมค่าที่เจ้าของพิมพ์และโฟลเดอร์บัญชีที่ตั้งไว้ ปลั๊กอินของคุณบันทึกสิ่งที่ต้องใช้ไว้ในโฟลเดอร์นั้น Nebo ไม่เก็บค่าเหล่านั้นไว้ - คำสั่ง
statusของคุณจะพิมพ์ JSON เช่น{"authenticated": true}เมื่อโทเค็นหมดอายุ Nebo จะรันrefreshหากคุณประกาศไว้
สำหรับการลงชื่อเข้าใช้ผ่านเบราว์เซอร์ ให้ตั้ง type เป็น oauth_cli และให้ login แสดงหรือเปิด URL ลงชื่อเข้าใช้ของผู้ให้บริการ พนักงานจะไม่ลงชื่อเข้าใช้เอง เมื่อการเรียกต้องลงชื่อเข้าใช้ เจ้าของจะเห็นการ์ดเชื่อมต่อ พนักงานที่มีหลายบัญชีเลือกบัญชีได้ด้วยการเพิ่ม --account <label> ลงในคำสั่ง Nebo จะนำแฟล็กนั้นออกก่อนที่ไบนารีของคุณจะเห็น
ตั้งชื่อตามบริการ ไม่ใช่ตามรูปแบบ ชื่อปลั๊กอินบอกว่าเชื่อมต่อกับอะไร เช่น "Example Notes" อย่าใส่คำว่า "CLI" ในชื่อปลั๊กอิน เพราะสำหรับพนักงานและเจ้าของ ปลั๊กอินคือการเชื่อมต่อ ไม่ใช่บรรทัดคำสั่ง
ถัดไป
- ข้อมูลอ้างอิง plugin.json ทุกฟิลด์ รวมถึงอีเวนต์ hook และการดำเนินการแบบมีชนิดข้อมูล
- การเผยแพร่ปลั๊กอิน แพลตฟอร์ม ไบนารี การลงลายเซ็น และการอัปเดต
- การเผยแพร่ ขั้นตอนในมาร์เก็ตเพลสสำหรับทุกผลงาน