รุ่น 1.0.0-alpha.1ล่าสุด
บทที่ 2.21
Plugin SDK
การติดตั้ง Plugin SDK (ชุดพัฒนาซอฟต์แวร์) เครื่องมือบรรทัดคำสั่ง การสำรวจเทมเพลตแบบบริการเต็มรูปแบบ รายละเอียดทีละฟิลด์ของ Manifest รุ่น v2 และเกตทั้งยี่สิบสองด่านที่ควบคุมให้ปลั๊กอินปฏิบัติตามกฎ
หน้านี้แปลโดย AI จากต้นฉบับภาษาอังกฤษ หากมีส่วนใดไม่ชัดเจน โปรดอ้างอิงจากหน้าภาษาอังกฤษ อ่านหน้านี้เป็นภาษาอังกฤษ

ปลั๊กอินตัวที่สองของผมใช้เวลาเพียงหนึ่งในสามของตัวแรก และเวลาที่ประหยัดได้เกือบทั้งหมดมาจาก 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 จะนำมาใช้ร่วมกับเกตในตัว
ไปป์ไลน์ของเทมเพลต
เทมเพลตไม่มีเวิร์กโฟลว์ที่เขียนด้วยมือ การกำหนดค่าไปป์ไลน์ระบุ Dockerfile อาร์กิวเมนต์บิลด์เพียงตัวเดียว (โทเคนรีจิสทรี) การทดลองรันการย้ายข้อมูล การตรวจสอบการบูต และเกตที่คิวการ merge รัน ลำดับคือลำดับที่คุณต้องการให้ล้มเหลว
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifestซึ่งคือcreate-nexus-plugin validate nexus.manifest.jsonnpm run gatesซึ่งคือnexus-gates --self-testnode scripts/ci/required-env
มีการตรวจสอบอีกสองรายการที่รันรอบอิมเมจ การทดลองรันการย้ายข้อมูล จะนำทุกไฟล์ไปใช้กับ Postgres ชั่วคราวก่อนที่อิมเมจจะเผยแพร่ได้ ด้วยตัวรันเดียวกับที่ใช้ในการผลิต ได้แก่ nexus-migrate provision หนึ่งครั้งในฐานะ superuser จากนั้นแต่ละไฟล์ที่มีหมายเลขในฐานะ migrator การตรวจสอบการบูต จะเริ่มอิมเมจที่บิลด์แล้วด้วย entrypoint ของตัวเองและทุกตัวแปรที่ required-env แสดง โดยชี้ไปยังตัวแทนที่รับการเชื่อมต่อแต่ไม่ตอบกลับ เซิร์ฟเวอร์จะรอฐานข้อมูลภายในกรอบเวลาที่จำกัด และการรอนั้นคือสัญญาณว่าผ่าน ตัวโหลดการกำหนดค่าที่ปฏิเสธการบูตจะทำให้บิลด์ล้มเหลวที่จุดนั้น ไม่ใช่ในการผลิต
ค่าใช้จ่าย
SDK ตัดสินใจแทนคุณ และบางเรื่องคุณอาจตัดสินใจต่างออกไป manifest ปฏิเสธคีย์ที่ไม่รู้จัก ตารางเส้นทางต้องตรงกับโค้ดของคุณทุกประการ บทบาทฐานข้อมูลไม่ใช่สิ่งที่คุณออกแบบเอง และเกตจะทำให้บิลด์ล้มเหลวหากขาดสิทธิ์ในการอ่าน ในปลั๊กอินแรกของผม ผมใช้เวลาหนึ่งวันโต้แย้งกับ api-contract เรื่องเส้นทางที่ผมลงทะเบียนไว้แต่ลืมประกาศ ปรากฏว่ามันถูก เส้นทางนั้นไม่มีการป้องกัน คาดว่าปลั๊กอินแรกจะรู้สึกช้า และคาดว่าปลั๊กอินที่สองจะใช้เวลาเพียงหนึ่งในสาม

