เข้าสู่ระบบนัดหมายรับฟังข้อมูลสรุป (or นัดหมายพูดคุยกับทีมงาน)

บทที่ 2.21

Plugin SDK

การติดตั้ง Plugin SDK (ชุดพัฒนาซอฟต์แวร์) เครื่องมือบรรทัดคำสั่ง การสำรวจเทมเพลตแบบบริการเต็มรูปแบบ รายละเอียดทีละฟิลด์ของ Manifest รุ่น v2 และเกตทั้งยี่สิบสองด่านที่ควบคุมให้ปลั๊กอินปฏิบัติตามกฎ

หน้านี้แปลโดย AI จากต้นฉบับภาษาอังกฤษ หากมีส่วนใดไม่ชัดเจน โปรดอ้างอิงจากหน้าภาษาอังกฤษ อ่านหน้านี้เป็นภาษาอังกฤษ

ใช้เวลาอ่าน 22 นาที

ปลั๊กอินตัวที่สองของผมใช้เวลาเพียงหนึ่งในสามของตัวแรก และเวลาที่ประหยัดได้เกือบทั้งหมดมาจาก SDK (ชุดพัฒนาซอฟต์แวร์) ครั้งแรก ผมเขียนตัวตรวจสอบขอบเขต ตัวโหลดการกำหนดค่า และตัวรันการย้ายข้อมูลเอง และผู้ตรวจทานส่งทุกชิ้นกลับมาให้แก้ ครั้งที่สอง ผมรันคำสั่งสร้างโครงเพียงคำสั่งเดียว ลบสกิลวิเคราะห์ความรู้สึกที่เป็นตัวอย่างทิ้ง แล้วใช้เวลาทั้งหมดไปกับระเบียนการตรวจทานความผิดปกติที่ทีมพลวัตการบินของเราต้องการจริง ๆ

@adverant-nexus/plugin-sdk เป็นแพ็กเกจ npm เพียงแพ็กเกจเดียว ประกอบด้วยสคีมาแมนิเฟสต์ v2 และตัวตรวจสอบความถูกต้องที่อ่านสคีมานั้น (definePlugin, defineSkill) โมดูลรันไทม์ที่ปลั๊กอินของคุณนำเข้าสำหรับขอบเขต ฐานข้อมูล การส่งต่องาน และส่วนอื่น ๆ ตัวช่วยการทดสอบ เกตตรวจสอบการปฏิบัติตาม และเครื่องมือบรรทัดคำสั่ง บทนี้ครอบคลุมการติดตั้ง เครื่องมือ เทมเพลต แมนิเฟสต์ และเกตต่าง ๆ ส่วนบทที่ 2.22 รันไทม์ของปลั๊กอิน ครอบคลุมโมดูลรันไทม์ในโค้ดที่กำลังทำงานของคุณ

การติดตั้ง

แพ็กเกจนี้มาจากรีจิสทรีของ Adverant ที่ https://registry.adverant.ai/npm/ ไม่ใช่รีจิสทรี npm สาธารณะ และคุณต้องใช้โทเค็นสำหรับดึงจากหน้า "Pull tokens and install commands" ในบัญชีของคุณ กำหนดให้สโคป @adverant-nexus ชี้ไปยังรีจิสทรีนี้ใน .npmrc ของรีโพซิทอรีของคุณ:

@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>

<pull-token> คือโทเค็นจากหน้าบัญชีของคุณ ในไปป์ไลน์ ให้ส่งค่านี้เข้ามาจากซีเคร็ตและห้ามคอมมิตเด็ดขาด Dockerfile ของเทมเพลตจะไม่ยอมบิลด์หากไม่มีโทเค็นนี้ และจะลบ .npmrc ออกจากขั้นบิลด์เมื่อ npm ci ทำงานเสร็จ โทเค็นจึงไม่ถูกรวมไปในอิมเมจ

จากนั้นตรึงเวอร์ชันให้ตรงทุกตัว:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

คอมมิต package-lock.json ในการติดตั้งครั้งแรก การบิลด์อิมเมจของเทมเพลตจะรัน npm ci และไม่ยอมถอยกลับไปใช้ npm install เพราะไฟล์ล็อกคือสัญญา SDK เองรองรับขั้นต่ำ Node 18 ส่วนเทมเพลตมุ่งเป้าที่ Node 20

เครื่องมือบรรทัดคำสั่งมาพร้อมอยู่ในแพ็กเกจ ดังนั้นทุกคำสั่งในเอกสารนี้จึงระบุชื่อแพ็กเกจและเวอร์ชันด้วย npx -p หากใช้ npx create-nexus-plugin เพียงอย่างเดียว ระบบจะค้นหาบนรีจิสทรีสาธารณะ และชื่อนั้นไม่ใช่แพ็กเกจนี้

เครื่องมือบรรทัดคำสั่ง

เครื่องมือ สิ่งที่ทำ
create-nexus-plugin สร้างโครงปลั๊กอิน ตรวจสอบความถูกต้องของแมนิเฟสต์ ย้ายแมนิเฟสต์ v1 เป็น v2 และสร้างคู่มือผู้ใช้งานสำหรับนักพัฒนาฟรอนต์เอนด์ของคุณ
nexus-tenancy สร้าง SQL สำหรับการแยกผู้เช่าของสคีมาคุณจากแมนิเฟสต์ ได้แก่ บทบาท สิทธิ์ที่มอบ เทมเพลตความปลอดภัยระดับแถว และตารางกราฟ
nexus-migrate ใช้การย้ายข้อมูลของคุณ: จัดเตรียมบทบาทครั้งเดียว แล้วรันไฟล์ที่มีหมายเลขแต่ละไฟล์ในฐานะบทบาท migrator
nexus-gates รันเกตตรวจสอบการปฏิบัติตามทุกเกต และการทดสอบตัวเองของแต่ละเกต

create-nexus-plugin ไม่เรียกใช้เครือข่ายและไม่โหลดโค้ดระยะไกล โดยรันตัวตรวจสอบความถูกต้องภายในโปรเซสชุดเดียวกับที่กระบวนการเริ่มใช้งานของแพลตฟอร์มใช้ จึงไม่มีความคลาดเคลื่อนระหว่าง "ผ่านการตรวจสอบบนเครื่องของฉัน" กับ "แพลตฟอร์มยอมรับแล้ว"

คำสั่งการทำงาน แฟล็ก สิ่งที่ทำ รหัสสถานะการจบการทำงาน (Exit Codes)
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print เขียนไดเรกทอรีปลั๊กอินใหม่ ส่วน --print จะพิมพ์เฉพาะแมนิเฟสต์ 0 เขียนแล้ว · 1 ปฏิเสธการเขียนทับ · 2 ใช้งานไม่ถูกต้อง
validate <file> ตรวจสอบความถูกต้องของ nexus.manifest.json หรือโมดูล .ts หรือ .js ที่ส่งออกแมนิเฟสต์ 0 ถูกต้อง · 1 ไม่ถูกต้องหรืออ่านไม่ได้ · 2 ใช้งานไม่ถูกต้อง
migrate <file> --write ยกระดับแมนิเฟสต์ v1 เป็น v2 แล้วพิมพ์ออกมา หรือเขียนทับในที่เดิม 0 · 1 · 2 ตามข้างต้น
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint สร้างคู่มือผู้ใช้งานจากแมนิเฟสต์และคำอธิบายของคุณ ส่วน --check จะเปรียบเทียบกับสำเนาที่คอมมิตไว้และไม่เขียนสิ่งใด 0 · 1 มีความคลาดเคลื่อนหรือมีจุดที่ไม่ผ่าน lint · 2 ใช้งานไม่ถูกต้อง
help พิมพ์วิธีใช้งาน 0

การสร้างโครงร่าง และระดับทั้งสาม (Tiers)

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service

--tier มีค่าเริ่มต้นเป็น full-service ตัวสร้างโครงจะไม่ยอมเขียนลงในไดเรกทอรีที่มีอยู่แล้ว และแมนิเฟสต์ที่สร้างขึ้นผ่านการตรวจสอบความถูกต้องอยู่แล้ว โดยจะไม่สร้างแมนิเฟสต์ที่ไม่ถูกต้องเลย

เลือกระดับตามสิ่งที่ปลั๊กอินของคุณมี

ระดับ มี ต้องประกาศ
skills-only มีเฉพาะสกิลในแมนิเฟสต์ skills[] โดยมีอย่างน้อยหนึ่งรายการ
ui-only ส่วนติดต่อฟรอนต์เอนด์ภายในเชลล์ frontend
full-service แบ็กเอนด์และฟรอนต์เอนด์ ซึ่งโดยทั่วไปมีสคีมาของตัวเอง backend และ frontend และเนื่องจากมีแบ็กเอนด์ จึงต้องมี runtime.healthCheck

หากคุณไม่แน่ใจ ให้สร้างโครงแบบ full-service แล้วลบส่วนที่ไม่ต้องการออก การทำในทางกลับกันหมายความว่าคุณต้องเขียนส่วนที่เทมเพลตจะให้มาเอง

การสำรวจเทมเพลตแบบบริการเต็มรูปแบบ

เทมเพลตคือปลั๊กอินอ้างอิง ซึ่งสร้างตามรูปแบบที่เข้มงวดที่บทต่อ ๆ ไปทุกบทยึดถือ ให้คัดลอกโครงสร้างของเทมเพลต ไม่ใช่ตรรกะตัวอย่าง

พาธ คำอธิบาย
nexus.manifest.json แมนิเฟสต์ v2: กฎสามข้อที่ระบุซ้ำ ตารางเส้นทาง และทะเบียนสิทธิ์
src/config.ts ตัวโหลดการกำหนดค่า ข้อกำหนดเดียว อ่านครั้งเดียว รวบรวมทุกปัญหาก่อนที่โปรเซสจะปฏิเสธการบูต
src/scope.ts ไฟล์เดียวที่แปลงคำขอเป็นขอบเขต พร้อมตัวตรวจสอบโทเค็นแบบเข้มงวดของ SDK และสองรูปแบบ ได้แก่ bearer token ของบุคคล และการเรียกใช้บริการของแพลตฟอร์ม
src/db.ts ทุกคำสั่งประกอบ tenantFence() และทำงานภายใน withScopedTx
src/uno.ts ไฟล์ส่งต่องานไฟล์เดียว: URL เดียว ไคลเอนต์เดียว รายการอนุญาตแบบปิด
src/routes/*.ts health (ไม่ระบุตัวตน เส้นทางตรงทุกตัว) เส้นทาง /api (มีขอบเขต) และคอลแบ็ก /internal (ป้องกันด้วยบริการ)
src/skills/sentiment.ts สกิล host_callback แบบกำหนดผลแน่นอน ให้แทนที่พจนานุกรมคำด้วยตรรกะของคุณเอง
src/server.ts จุดประกอบหลัก: ติดตั้งบัญชีบันทึกการปฏิเสธครั้งเดียว รอฐานข้อมูล (มีขีดจำกัดเวลา) จากนั้นรันการตรวจสอบการแยกข้อมูลและบัญชีบันทึกก่อนเริ่มรับการเชื่อมต่อ
migrations/000_tenancy.sql สร้างโดย nexus-tenancy render ตอนสร้างโครง: บทบาท สคีมา เทมเพลตความปลอดภัยระดับแถว
migrations/001_init.sql สองตารางที่มีคีย์ประกอบนำด้วยผู้เช่า และคีย์นอกแบบประกอบที่มีผู้เช่าอยู่ด้วย
migrations/002_refusal_ledger.sql ตารางที่บัญชีบันทึกการปฏิเสธเขียนข้อมูลลง
scripts/ci/required-env พิมพ์ชื่อตัวแปรสภาพแวดล้อมที่จำเป็นสำหรับการบูตเป็น JSON
scripts/ci/shadow-migrate-*.sh การทดลองรันการย้ายข้อมูลของไปป์ไลน์ ผ่าน nexus-migrate
gates/ ไดเรกทอรีข้อยกเว้นของเกต: ว่างเปล่า ซึ่งเป็นสถานะที่ถูกต้องสำหรับปลั๊กอินใหม่
test/ การทดสอบสำหรับขอบเขต เส้นทาง ฐานข้อมูล การส่งต่องาน และการบูต พร้อมตัวจำลองขอบเขตที่ทุกการทดสอบใส่เข้าไป
Dockerfile อิมเมจที่ไม่ใช่ root (user ID 10001) ที่มีการย้ายข้อมูลอยู่ภายใน

ไฟล์บางไฟล์ในนั้นควรค่าแก่การพิจารณาอย่างละเอียด

src/config.ts ปฏิบัติตามกฎสองข้อ ข้อแรก รวบรวมทุกปัญหาก่อนส่งข้อผิดพลาด ดังนั้นการรีสตาร์ตหนึ่งครั้งจะระบุตัวแปรที่ขาดทั้งห้าตัว แทนที่จะต้องรีสตาร์ตห้าครั้งเพื่อระบุทีละตัว ข้อสอง กำหนดค่าเริ่มต้นเฉพาะเมื่อค่าที่ผิดไม่สามารถทำให้เกิดผลลัพธ์ผิดโดยไม่มีสัญญาณเตือน PORT จึงมีค่าเริ่มต้นเป็น 8080 ได้ เพราะพอร์ตที่ผิดจะทำให้การผูกพอร์ตล้มเหลวอย่างเห็นได้ชัด ขณะที่ DATABASE_URL และ UNO_DISPATCH_URL เป็นค่าที่จำเป็นและต้องเป็นที่อยู่ภายในคลัสเตอร์ ที่อยู่สาธารณะจะถูกปฏิเสธตอนบูต

node scripts/ci/required-env
["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]

การทดสอบของเทมเพลตเองจะรันไฟล์นั้นและเปรียบเทียบผลลัพธ์กับชื่อที่ข้อกำหนดการกำหนดค่าระบุว่าจำเป็น ดังนั้นการเพิ่มตัวแปรที่จำเป็นโดยไม่อัปเดตรายการจะทำให้ npm test ล้มเหลว

src/server.ts จะไม่เริ่มรับการเชื่อมต่อจนกว่าฐานข้อมูลจะตอบสนอง และจำกัดเวลารอไว้ที่ 120 วินาที โดยบันทึกทุกความพยายามที่ล้มเหลวพร้อมสาเหตุ จากนั้นจะพิสูจน์ตามลำดับว่าบทบาทแอปไม่สามารถผูกผู้เช่าใหม่ได้และทุกตารางถูกบังคับให้อยู่ภายใต้ความปลอดภัยระดับแถว ว่าพูลของแต่ละพ็อดอยู่ภายในขีดจำกัดการเชื่อมต่อของบทบาท และว่าตารางของบัญชีบันทึกการปฏิเสธรับแถวข้อมูลได้ หากการตรวจสอบใดในสามข้อนี้ปฏิเสธ จะพิมพ์รายละเอียดทั้งหมดและโปรเซสจะออกด้วยรหัส 2

Manifest รุ่น v2 ทีละฟิลด์

แมนิเฟสต์คือสัญญาที่เครื่องอ่านได้ระหว่างปลั๊กอินกับแพลตฟอร์ม โดยจะถูกตรวจสอบความถูกต้องเมื่อคุณเขียน เมื่อแพลตฟอร์มเริ่มใช้งาน และต่อเนื่องหลังจากนั้น สคีมาเป็น additionalProperties: false ในทุกระดับ หากปลั๊กอินของคุณมีส่วนใด ก็จะมีพร็อพเพอร์ตีสำหรับส่วนนั้น และคีย์ที่ไม่ได้ประกาศจะถูกปฏิเสธ วิธีแก้ไขคือใช้พร็อพเพอร์ตีทางเลือกที่ถูกต้องเสมอ

แกนหลักที่จำเป็น

ฟิลด์ กฎ
manifestVersion ต้องเป็น "2" เท่านั้น เอกสาร v1 จะถูกย้าย ไม่ใช่ตรวจสอบซ้ำในที่เดิม
name ^[a-z0-9]+([-.][a-z0-9]+)*$ ไม่เกิน 64 อักขระ เป็นรหัสปลั๊กอินที่ใช้ในการลงทะเบียน การกำหนดเนมสเปซการส่งต่องาน และแถวข้อมูลที่จำกัดตามผู้เช่า ปลั๊กอินที่ประกาศสกิลต้องมีชื่อที่ไม่มีจุดและไม่ขึ้นต้นด้วยตัวเลขด้วย
displayName 1 ถึง 120 อักขระ
version Semantic version ตามรอบการออกรุ่นของคุณเอง
description, author, license อย่างน้อยหนึ่งอักขระต่อรายการ
tier skills-only, ui-only หรือ full-service
trust core, verified, community หรือ untrusted
runtime จำเป็น: executionMode, isolationLevel (1 ถึง 4), entrypoint ทางเลือก: nodeVersion, healthCheck, readinessCheck, livenessCheck โดยแต่ละรายการเป็นพาธที่ขึ้นต้นด้วย / โหมดได้มาจากระดับ: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai และ deploy คือกฎสามข้อของแพลตฟอร์มที่ระบุซ้ำ ตัวตรวจสอบความถูกต้องกำหนดถ้อยคำไว้ตายตัว

สำหรับปลั๊กอินที่คุณสร้างเพื่อการติดตั้งของคุณเอง ประโยคทั้งสามมีดังนี้ ประโยค ai ครอบคลุมปัญญาประดิษฐ์ (AI) และเป็นที่สำหรับระบุว่าปลั๊กอินไม่ถือข้อมูลประจำตัวของโมเดลใด ๆ

"architecture": {
  "compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
  "ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
  "deploy": "Deploy is through the installation's release channels only."
}

ตารางเส้นทาง: api และ rights

api ต้องมี version และ basePath และอาจมี websocket (path, auth) และ endpoints[] ตารางเส้นทางคือแนวคิดที่ทรงพลังที่สุดในสคีมา เกตจะเปรียบเทียบตารางนี้กับเส้นทางที่โค้ดของคุณลงทะเบียนจริงในทั้งสองทิศทาง แมนิเฟสต์จึงเป็นสัญญาที่ตรวจสอบได้ ไม่ใช่เพียงเอกสาร

แต่ละเอนด์พอยต์ต้องมี method (GET, POST, PUT, PATCH หรือ DELETE) และ path ส่วนที่เหลือ:

ฟิลด์ ความหมายของข้อมูล
auth หนึ่งในห้าคลาส: scope (เส้นทางของบุคคล อยู่หลังตัวป้องกันขอบเขต), service-key และ internal (เซิร์ฟเวอร์ถึงเซิร์ฟเวอร์ ไม่สามารถเข้าถึงจากเบราว์เซอร์ได้), public (เป็นเส้นทางที่ตรงทุกตัวพร้อม allowAnonymous เท่านั้น) และ device (เครื่องที่มีข้อมูลประจำตัวของตนเอง อยู่หลังตัวป้องกันอุปกรณ์)
right จำเป็นในทุกเส้นทางที่ตัวป้องกันขอบเขตให้บริการ และถูกปฏิเสธในเส้นทางอื่น: ชื่อของสิทธิ์ในทะเบียน rights
needsUnit เส้นทางจะปฏิเสธเมื่อไม่สามารถระบุหน่วยงานของผู้เรียกได้
allowAnonymous รายการอนุญาตแบบตรงทุกตัวเท่านั้น กฎแบบคำนำหน้าคือสาเหตุที่ทำให้ /health-of-tenant-42 กลายเป็นสาธารณะ
group, serves, screens ภายใต้บล็อก release: กลุ่มความสามารถที่เส้นทางให้บริการ สิ่งที่ตอบกลับเมื่อฟีเจอร์ตามสิทธิ์การใช้งานของกลุ่มนั้นถูกล็อก (data, teaser, sighting หรือ ask) และหน้าจอที่เส้นทางให้บริการ
query required (แต่ละชื่อพร้อมค่าตัวอย่าง) และ allowed: พารามิเตอร์คิวรีที่เส้นทางอ่าน
body example: เนื้อหาตัวอย่างของเส้นทางเขียน ซึ่งตัวตรวจสอบความถูกต้องของเส้นทางนั้นยอมรับ ห้ามใช้กับ GET

rights คือทะเบียนที่เส้นทางเหล่านั้นอ้างถึง สิทธิ์แต่ละรายการมี roles (เพดานสูงสุด) และอาจมี summary, never (บทบาทที่ไม่สามารถใช้สิทธิ์นี้ได้เลย ไม่ว่าจะถือสิทธิ์อื่นใด), barred (ถ้อยคำของผลิตภัณฑ์เองสำหรับการปฏิเสธบทบาท never), seat (ต้องมีที่นั่งที่ใช้งานอยู่ด้วย), self (บุคคลที่ยืนยันตัวตนแล้วทุกคนถือสิทธิ์นี้ สำหรับสิทธิ์เหนือเซสชันของตนเอง), grants (ผู้ถือสิทธิ์มอบที่นั่งได้ มีได้ไม่เกินหนึ่งสิทธิ์), licence (ฟีเจอร์ตามสิทธิ์การใช้งานที่ใบอนุญาตขององค์กรต้องมี) installation (ถือได้เฉพาะผู้ดูแลระบบของการติดตั้งนั้น) และ platform (ถือได้เฉพาะผู้ดูแลแพลตฟอร์มของ Adverant โดยไม่ระบุบทบาท) ชื่อสิทธิ์มีจุดอย่างน้อยหนึ่งจุด: project.read, money.pay

"api": {
  "version": "1",
  "basePath": "/",
  "endpoints": [
    { "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
    { "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
    { "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
    { "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
  ]
},
"rights": {
  "project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
  "project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}

definePlugin จะปฏิเสธเส้นทางขอบเขตที่ไม่มีสิทธิ์ (ENDPOINT_RIGHT_MISSING) สิทธิ์ที่ไม่มีในทะเบียน (ENDPOINT_RIGHT_NOT_REGISTERED) และสิทธิ์บนเส้นทางที่ไม่มีตัวป้องกันใดให้บริการ (ENDPOINT_RIGHT_UNGUARDED) นอกจากนี้ยังปฏิเสธทะเบียนที่ขัดแย้งในตัวเอง และการเขียนเส้นทางเดียวกันสองแบบ (:id และ :recordId) ในฐานะ DUPLICATE_ENDPOINT

ข้อมูลของคุณ: databases, schema และ db

schema คือสคีมา Postgres เดียวที่ปลั๊กอินเป็นเจ้าของ ห้ามใช้ public, plugins, auth และ nexus และหาก databases[] ระบุสคีมา Postgres ด้วย ทั้งสองต้องตรงกัน

databases[] ประกาศแต่ละที่เก็บข้อมูลตามเอนจิน: postgresql (schema, tables, migrations และ granted ซึ่งเป็นตารางที่องค์กรอื่นอาจอ่านได้ภายใต้การอนุญาตที่บันทึกไว้), neo4j (schemas), qdrant (collections) หรือ redis (purpose)

db เก็บขีดจำกัดเซสชันสำหรับทุกการเชื่อมต่อที่ปลั๊กอินเปิด โดยประกาศไว้ที่นี่แทนการเขียนในโค้ด เพื่อให้ทั้งผู้ตรวจทานและการปรับใช้อ่านได้:

ฟิลด์ สิ่งที่จำกัด
maxConnections พูลต่อเรพลิกา
pods จำนวนพ็อดสูงสุดที่ถือพูลพร้อมกัน คือเรพลิการวมกับส่วนเพิ่มชั่วคราวระหว่างการอัปเดตแบบทยอย ขีดจำกัดการเชื่อมต่อของแต่ละบทบาทจะสร้างเป็น maxConnections × pods หากละไว้ definePlugin จะเตือน DB_PODS_UNDECLARED
statementTimeoutMs หนึ่งคำสั่ง
idleInTransactionTimeoutMs ทรานแซกชันที่เปิดอยู่แต่ไม่ได้รันสิ่งใด
workMemKB โหนด sort หรือ hash หนึ่งโหนด ต่อโหนด ไม่ใช่ต่อคิวรี
piiMask[] รายการ table.column ที่มีข้อมูลส่วนบุคคล ซึ่งจะถูกปิดบังในคอนโซล SQL ที่มีการกำกับดูแลและในบันทึก

สกิลและเครื่องมือ: skills, mcpTools, entitlements

skills[] เก็บสกิลในแมนิเฟสต์ ส่วนบทที่ 2.20 สกิล ครอบคลุมฟิลด์และระดับของสกิล mcpTools[] เก็บเครื่องมือ MCP (Model Context Protocol) ที่ปลั๊กอินเผยแพร่ แต่ละรายการมี name, description และ inputSchema โดยไม่มี oneOf, allOf หรือ anyOf ในระดับบนสุด

entitlements ต้องมี featureIdPattern และยอมรับ alwaysOn[], source และ store รูปแบบนี้ระบุเนมสเปซที่รหัสฟีเจอร์ของคุณอยู่ ตามธรรมเนียมคือ name ของปลั๊กอินบวกหนึ่งส่วนที่โค้ดของคุณเติมให้ในแต่ละส่วนติดต่อ alwaysOn[] คือรายการสั้นและแน่นอนที่ต้องตอบสนองได้แม้ไม่สามารถได้รับผลการตัดสินสิทธิ์ใด ๆ ได้แก่ สถานะความสมบูรณ์ของระบบ ความพร้อมใช้งาน การลงชื่อเข้าใช้ และการตั้งค่าที่ผู้ดูแลระบบต้องใช้เพื่อแก้ไขสิทธิ์

การควบคุมการเปลี่ยนแปลง: changePolicy

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

การอนุมัตินับตามจำนวนบุคคลที่แตกต่างกัน และผู้เสนอการเปลี่ยนแปลงจะไม่ถูกนับรวมเลย หากไม่มีทั้งสองเงื่อนไข "การอนุมัติสองครั้ง" จะกลายเป็นคนคนเดียวคลิกสองครั้ง enabled: true ต้องมี classes และทุกคลาสที่ระบุต้องมีจำนวนของตนเอง คลาสที่คุณละไว้จะไม่มีการกำกับดูแล ซึ่งเป็นทางเลือกที่ชอบธรรมที่สคีมาบังคับให้คุณเขียนระบุไว้

คุณคือใคร: domains, branding, routing

domains[] (แต่ละรายการมี primary และ aliases[] ส่วน domain เป็นรูปแบบโดเมนเดียว) ระบุตำแหน่งที่ปลั๊กอินตอบสนอง branding ต้องมี appName และยอมรับ tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId และ gaId ทุกอย่างใน branding เป็นข้อมูลสาธารณะ หน้าลงชื่อเข้าใช้อ่านข้อมูลนี้ก่อนที่ใครจะมีข้อมูลประจำตัว จึงห้ามมีซีเคร็ตหรือที่อยู่ภายในเด็ดขาด routing (type, gateway, virtualService) ใช้สำหรับปลั๊กอินที่อธิบายการกำหนดเส้นทางของตนเอง

การกำหนดขนาดและส่วนอื่น ๆ

resources กำหนดให้ต้องมี cpuMillicores (10 ถึง 64,000) และ memoryMB (16 ถึง 262,144) และยอมรับ diskGB, timeoutMs, port และ wsPort backend เก็บ port, healthPath, apiPrefix, framework และ platformClients[] ซึ่งเป็นไคลเอนต์ SDK ที่แบ็กเอนด์ของคุณนำเข้าตามชื่อ รายการนี้เป็นรายการปิด และมีเกตตรวจสอบรายการนี้เทียบกับการนำเข้าของคุณ สคีมาอนุญาตชื่อสิบสี่ชื่อ ได้แก่ access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin และ uno รวมถึงอีกหนึ่งชื่อสำหรับไคลเอนต์ที่ตอบการปฏิเสธด้านสิทธิ์ตามแผน ซึ่งใช้ชื่อภายใน ไคลเอนต์สิทธิ์การใช้ฟีเจอร์ runtime/entitlements ไม่ได้เป็นหนึ่งในนั้นและจะไม่อยู่ในรายการเลย เนื่องจากบล็อก entitlements ของคุณได้ประกาศไว้แล้ว และแบ็กเอนด์ที่นำเข้าไคลเอนต์นี้โดยไม่มีบล็อก entitlements จะไม่ผ่านเกตเดียวกันนี้ frontend เก็บ basePath, mountPath และ framework nexus เก็บ minVersion, maxVersion, capabilities[] และ permissions[]

บล็อกที่เหลือแต่ละบล็อกมีไว้สำหรับงานเดียว:

บล็อก สำหรับ
settings การตั้งค่าของคุณบนเฟรมเวิร์กที่ใช้ร่วมกัน: groups และ keys ซึ่งตั้งค่าในระดับที่แต่ละรายการระบุ
people sweep (service, port): สมาชิกขององค์กร ซึ่งซิงค์จากบริการระบุตัวตน โดยที่นั่งจะถูกปิดเมื่อมีผู้ออกจากองค์กร
ontology entityTypes และ relationshipTypes: กราฟแบบมีชนิดที่เก็บไว้ในสคีมาของคุณเอง
release groups และ frame: กลุ่มความสามารถที่ใช้จัดลำดับการเปิดใช้เส้นทางของคุณ โดยเผยแพร่ครั้งแรกในรูปแบบ canary
cells[] ปลั๊กอินที่ประกอบด้วยหลายส่วนที่ติดตั้งได้: แต่ละส่วนมี name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] สำหรับรายการในแค็ตตาล็อกของคุณ
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords ผู้เผยแพร่และตำแหน่งที่เก็บโค้ด
metrics, atlas อ็อบเจกต์สองรายการที่ตั้งใจเปิดไว้ สำหรับชื่อเมตริกของคุณเองและการสร้างเอกสารสถาปัตยกรรม

สิ่งที่สคีมาระบุไม่ได้

JSON Schema กำหนดรูปแบบโครงสร้าง ส่วน definePlugin เพิ่มกฎที่สคีมาไม่สามารถระบุได้ classification ของสกิลต้องไม่เกินเพดานความน่าเชื่อถือ เฉพาะปลั๊กอิน core และ verified เท่านั้นที่ประกาศสกิล tool_using และ llm_only ได้ ทุกพาธที่ประกาศต้องเป็นพาธสัมพัทธ์และอยู่ในต้นทางเดียวกัน โดยไม่มีสคีม ไม่มี // และไม่มีแบ็กสแลช เนื่องจากตัวแยกวิเคราะห์ URL จะแปลง \ เป็น / และ /\evil.example/x จะชี้ไปยังต้นทางอื่น กฎทุกข้อที่การซิงค์รีจิสทรีใช้กับสกิลจะถูกนำมาใช้ที่นี่ก่อน ด้วยโค้ดของการซิงค์เอง ดังนั้น validate และการซิงค์จึงระบุกฎที่ผิดในแบบเดียวกัน

การตรวจสอบความถูกต้อง และการย้ายจาก v1

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0

เมื่อล้มเหลว ระบบจะแสดงพาธที่แน่นอน และสำหรับกฎการซิงค์จะแสดงรหัสก่อน ควรตั้งเป็น commit hook

manifest เวอร์ชัน v1 ยกระดับได้โดยอัตโนมัติ migrate จะเพิ่มประโยคข้อกฎหมายสามประโยค ย้าย domain ไปยัง domains[] และจะไม่สร้าง entrypoint ที่คุณไม่เคยมีขึ้นมาเอง เครื่องมือจะตรวจสอบผลลัพธ์ก่อนแสดงหรือเขียนสิ่งใด ดังนั้นการย้ายข้อมูลจะไม่ย้ายความล้มเหลวจากเครื่องมือเข้าไปในรีโพสิทอรีของคุณ

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --write

อ่าน diff ก่อนคอมมิต ประโยคข้อกฎหมายที่เพิ่มเข้ามาคือถ้อยคำที่ตัวตรวจสอบกำหนดตายตัวไว้ สำหรับการติดตั้งของคุณเอง ให้ตั้งค่า deploy เป็นประโยคที่แสดงไว้ก่อนหน้านี้

การเรนเดอร์ผู้เช่า (Tenancy) และการจัดเตรียมบทบาท

คุณไม่ต้องเขียนการมอบสิทธิ์บทบาทหรือเทมเพลตความปลอดภัยระดับแถวด้วยตนเอง nexus-tenancy render จะเขียนให้จาก schema และ db ใน manifest:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sql

ไฟล์ที่สร้างขึ้นจะสร้างบทบาทห้าบทบาทสำหรับสคีมา โดยแต่ละบทบาทมีสิ่งที่ห้ามถือครองกำกับไว้ ได้แก่ migrator ที่ทำได้เพียงสวมบทบาทเป็นเจ้าของ เจ้าของที่ไม่สามารถเข้าสู่ระบบได้ บทบาทแอปสำหรับเส้นทางคำขอ บทบาทรายงานที่เห็นเฉพาะข้อมูลสรุปรวม และบทบาทบัญชีแยกประเภทที่ทำได้เพียงเพิ่มข้อมูลต่อท้าย ไม่มีบทบาทใดถือครอง BYPASSRLS วิธีเดียวในการผูก tenant คือฟังก์ชันฐานข้อมูลหนึ่งฟังก์ชัน และ set_config ถูกเพิกถอนจากทุกบทบาทยกเว้นเจ้าของ

ไฟล์ tenancy ที่นำไปใช้แล้วจะไม่ถูกแก้ไข การเปลี่ยนแปลงคือการแก้ไขฉบับใหม่ที่มีไฟล์หมายเลข 0 ของตัวเอง และที่นั่งอ่านสำหรับการมอบสิทธิ์ข้ามองค์กรก็มาในลักษณะนี้ ในฐานะการแก้ไขฉบับที่ 2 --graph จะสร้างตารางสองตารางของกราฟแบบมีชนิดที่ ontology ของคุณประกาศไว้ เป็นการย้ายข้อมูลลำดับถัดไปของคุณ

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sql

ไฟล์ tenancy สร้างบทบาทที่ตัวรันใช้เชื่อมต่อ ดังนั้นจึงต้องนำไปใช้โดยเจ้าของฐานข้อมูลด้วย nexus-migrate provision:

DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir>

<database-owner-url> คือสตริงการเชื่อมต่อสำหรับเจ้าของฐานข้อมูล และ <dir> คือไดเรกทอรีส่วนตัว Provision จะนำไฟล์ tenancy พื้นฐานและการแก้ไขทุกฉบับไปใช้ตามลำดับ เขียน migrator.url และ app.url (และ seat.url เมื่อมีการแก้ไขฉบับที่ 2) ลงใน <dir> ด้วยโหมด 0600 และไม่แสดงข้อมูลลับใดๆ ระบบจะตั้งค่าขีดจำกัดการเชื่อมต่อของแต่ละบทบาทจาก db.maxConnections × db.pods ในทุกครั้งที่รัน การรันซ้ำจะคงรหัสผ่านเดิมไว้ เว้นแต่คุณจะร้องขอ โดย --passwords <dir> จะตั้งค่ารหัสผ่านจากไฟล์ และ --rotate <roles> จะสร้างรหัสผ่านใหม่ให้บทบาทที่ระบุ จากนั้นให้แปลงไฟล์เหล่านี้เป็นข้อมูลลับของการติดตั้งใช้งานของคุณ

หลังจากนั้น การนำไปใช้จะเชื่อมต่อด้วยสตริงการเชื่อมต่อของ migrator ที่ provision เขียนไว้:

DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.json

ระบบจะรันไฟล์ตั้งแต่ 001 เป็นต้นไปในฐานะ migrator ทุกไฟล์ภายใต้ SET ROLE <schema>_owner หนึ่งทรานแซกชันต่อหนึ่งไฟล์ ระบบเก็บบัญชีแยกประเภท <schema>.schema_migrations พร้อม checksum ของแต่ละไฟล์ ไฟล์ที่นำไปใช้แล้วแต่มีไบต์เปลี่ยนไปจะถูกปฏิเสธโดยระบุชื่อ (CHECKSUM_DRIFT) โดยจะไม่รันซ้ำและไม่ข้าม ทุกไฟล์ที่รอดำเนินการจะถูกแยกวิเคราะห์ด้วยไวยากรณ์ Postgres จริงก่อนที่ไฟล์แรกจะรัน ดังนั้นการปฏิเสธจะไม่ทำให้ฐานข้อมูลเปลี่ยนแปลง ส่วนหัวเดียวที่ไฟล์อาจมีได้คือ -- nexus-migration: transaction=file|per-statement พร้อมค่าหมดเวลาของล็อกและคำสั่งซึ่งเป็นตัวเลือก per-statement ใช้สำหรับ CREATE INDEX CONCURRENTLY

เกตตรวจสอบ (Gates)

nexus-gates รันเกตยี่สิบสองเกต แต่ละเกตครอบคลุมข้อบกพร่องหนึ่งประเภทเพื่อไม่ให้หลุดออกไปซ้ำอีก และแต่ละเกตมีการทดสอบตัวเองที่พิสูจน์ว่าเกตล้มเหลวกับ fixture ที่สร้างขึ้นเพื่อกระตุ้นให้ล้มเหลว ให้รันก่อน push:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
เกต สิ่งที่ตรวจจับ
scope-adherence เส้นทาง /api ที่ไม่มีตัวป้องกันขอบเขต พาธแบบไม่ระบุตัวตนที่ไม่ตรงกับพาธที่ประกาศไว้ทุกประการ เส้นทางอุปกรณ์ที่ไม่มีตัวป้องกันอุปกรณ์ หรือมีตัวป้องกันของบุคคลอยู่ด้วย
one-fence เพรดิเคต tenant ที่กำหนดไว้ที่อื่นนอกเหนือจากจุดเดียว รวมถึงรั้วที่นั่งหรือการมอบสิทธิ์ที่เขียนขึ้นเอง
sql-fence คำสั่งที่อ่านหรืออัปเดตตารางที่มีขอบเขตโดยไม่มีรั้ว ในเป้าหมาย FROM, JOIN, USING หรือ UPDATE ใดๆ
migrations-are-scoped ตารางที่ขาดแกน คีย์ผสมที่ขึ้นต้นด้วย tenant คีย์นอกที่มี tenant หรือคอลัมน์เดโม
migrations-commit-what-they-open การย้ายข้อมูลที่จำนวน BEGIN ไม่ตรงกับจำนวน COMMIT และ ROLLBACK
no-direct-compute การเรียกโดยตรงไปยังผู้ให้บริการโมเดล เอนจิน คิว หรือโฮสต์เวิร์กโฟลว์ ผู้อ่าน URL การส่งงานรายที่สอง
no-credentials ข้อมูลประจำตัวของผู้ให้บริการโมเดลที่อ่านได้ในรีโพสิทอรีหรือในสภาพแวดล้อม
crud-adherence เส้นทางที่เปลี่ยนแปลงข้อมูลซึ่งการตรวจสอบสิทธิ์ไม่ได้ระบุสิ่งใดในทะเบียน
blocked-backends เส้นทางที่ไม่ได้ให้บริการ ไม่ได้ถูกบล็อกตามชื่อ ไม่ได้ถูกปฏิเสธตามกฎ และไม่ได้เป็นของที่อื่น
every-test-runs การทดสอบที่ glob ของสคริปต์ทดสอบเข้าไม่ถึง
tiles-are-invariant จุดเชื่อมต่อแคชที่ไม่ขึ้นกับ tenant แต่อ่านค่า tenant หรือข้ามการยืนยันตัวตน
api-contract เส้นทางที่ลงทะเบียนแต่ manifest ไม่ได้ประกาศ หรือเส้นทางที่ประกาศแต่โค้ดไม่เคยลงทะเบียน
rls-present ตารางที่ไม่มีการบังคับใช้ความปลอดภัยระดับแถว ฟังก์ชัน SECURITY DEFINER ที่ไม่มี search_path กำหนดตายตัว
no-set-config โค้ดปลั๊กอินที่ผูกการตั้งค่า tenant เอง
db-role-honest เส้นทางคำขอที่เชื่อมต่อในฐานะเจ้าของหรือ migrator หรือขอ SUPERUSER หรือ BYPASSRLS
platform-clients ไคลเอนต์ SDK ที่นำเข้าแต่ไม่ได้อยู่ใน backend.platformClients หรืออยู่ในรายการแต่ไม่เคยนำเข้า
rights-register เส้นทางขอบเขตที่ไม่มีสิทธิ์ที่ประกาศไว้ การตรวจสอบสิทธิ์ที่อยู่นอกทะเบียน
refusal-ledger ตารางการปฏิเสธที่ประกาศไว้แต่ไม่ได้ติดตั้งบัญชีแยกประเภท หรือเนื้อหาการปฏิเสธที่ส่งโดยเลี่ยงบัญชีแยกประเภท
grants-declared ตารางที่มอบสิทธิ์แต่ manifest ไม่ได้ประกาศ สิทธิ์ที่นั่งอ่านที่มอบให้ด้วยตนเอง
people-declared บล็อก people ที่ไม่มีเส้นทาง sweep ตัวป้องกัน และตารางของบล็อกนั้น
functions-closure ปลั๊กอิน Azure Functions ที่เส้นทางที่ให้บริการและเส้นทางที่ประกาศไม่ตรงกัน
declared-input รายการพารามิเตอร์คิวรีของ handler ที่ไม่ตรงกับ query ที่ประกาศไว้ของเส้นทาง

ไดเรกทอรี gates/ เก็บไฟล์ข้อยกเว้นห้าไฟล์ที่เกตอาจอ่านได้ (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json และ invariant-seams.json) โดยมีเหตุผลหนึ่งข้อต่อหนึ่งรายการ เหตุผลที่ว่างเปล่าจะถือว่าไม่มีรายการ และรายการที่ระบุสิ่งที่ไม่มีอยู่แล้วจะทำให้เกตล้มเหลว คุณยังสามารถวางโมดูลเกตของคุณเองไว้ที่นั่น และ nexus-gates จะนำมาใช้ร่วมกับเกตในตัว

ความเข้ากันได้
ความเข้ากันได้
ความเข้ากันได้แสดงว่า SDK เวอร์ชันใดทำงานร่วมกับแพลตฟอร์มเวอร์ชันใด จากการรัน quickstart ทุกคืน คู่ที่ยังไม่ได้ทดสอบจะระบุไว้เช่นนั้น และคู่ที่ล้มเหลวจะระบุการเปลี่ยนแปลงที่ทำให้ใช้งานไม่ได้

ไปป์ไลน์ของเทมเพลต

เทมเพลตไม่มีเวิร์กโฟลว์ที่เขียนด้วยมือ การกำหนดค่าไปป์ไลน์ระบุ Dockerfile อาร์กิวเมนต์บิลด์เพียงตัวเดียว (โทเคนรีจิสทรี) การทดลองรันการย้ายข้อมูล การตรวจสอบการบูต และเกตที่คิวการ merge รัน ลำดับคือลำดับที่คุณต้องการให้ล้มเหลว

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest ซึ่งคือ create-nexus-plugin validate nexus.manifest.json
  6. npm run gates ซึ่งคือ nexus-gates --self-test
  7. node scripts/ci/required-env

มีการตรวจสอบอีกสองรายการที่รันรอบอิมเมจ การทดลองรันการย้ายข้อมูล จะนำทุกไฟล์ไปใช้กับ Postgres ชั่วคราวก่อนที่อิมเมจจะเผยแพร่ได้ ด้วยตัวรันเดียวกับที่ใช้ในการผลิต ได้แก่ nexus-migrate provision หนึ่งครั้งในฐานะ superuser จากนั้นแต่ละไฟล์ที่มีหมายเลขในฐานะ migrator การตรวจสอบการบูต จะเริ่มอิมเมจที่บิลด์แล้วด้วย entrypoint ของตัวเองและทุกตัวแปรที่ required-env แสดง โดยชี้ไปยังตัวแทนที่รับการเชื่อมต่อแต่ไม่ตอบกลับ เซิร์ฟเวอร์จะรอฐานข้อมูลภายในกรอบเวลาที่จำกัด และการรอนั้นคือสัญญาณว่าผ่าน ตัวโหลดการกำหนดค่าที่ปฏิเสธการบูตจะทำให้บิลด์ล้มเหลวที่จุดนั้น ไม่ใช่ในการผลิต

การพัฒนาบน Community
การพัฒนาบน Community
ใน Community นักพัฒนาจะได้เส้นทางมาตรฐานเดียวกัน พื้นที่พัฒนา และสาขาข้อมูลบนเซิร์ฟเวอร์เดียว โดยมีโค้ดอยู่ในโฮสต์ Git ของตนเอง Staging หน่วยนำร่อง และสำเนาข้อมูลจริงที่ปกปิดแล้วมาพร้อมกับ Enterprise

ค่าใช้จ่าย

SDK ตัดสินใจแทนคุณ และบางเรื่องคุณอาจตัดสินใจต่างออกไป manifest ปฏิเสธคีย์ที่ไม่รู้จัก ตารางเส้นทางต้องตรงกับโค้ดของคุณทุกประการ บทบาทฐานข้อมูลไม่ใช่สิ่งที่คุณออกแบบเอง และเกตจะทำให้บิลด์ล้มเหลวหากขาดสิทธิ์ในการอ่าน ในปลั๊กอินแรกของผม ผมใช้เวลาหนึ่งวันโต้แย้งกับ api-contract เรื่องเส้นทางที่ผมลงทะเบียนไว้แต่ลืมประกาศ ปรากฏว่ามันถูก เส้นทางนั้นไม่มีการป้องกัน คาดว่าปลั๊กอินแรกจะรู้สึกช้า และคาดว่าปลั๊กอินที่สองจะใช้เวลาเพียงหนึ่งในสาม