รุ่น 1.0.0-alpha.1ล่าสุด
บทที่ 2.19
กฎที่ทุกส่วนขยายรับช่วงต่อ
การแยกส่วนบนสามแกน การประมวลผลผ่าน UNO การใช้ AI (ปัญญาประดิษฐ์) ผ่านตัวจัดเส้นทาง คีย์ที่เป็นขององค์กร และการตรวจสอบใบอนุญาต ความหมายของแต่ละกฎที่มีต่อโค้ดของคุณ เกตใดที่เป็นตัวบังคับใช้ และเหตุผลที่คุณรับช่วงต่อกฎเหล่านี้แทนที่จะต้องเขียนขึ้นเอง
หน้านี้แปลโดย AI จากต้นฉบับภาษาอังกฤษ หากมีส่วนใดไม่ชัดเจน โปรดอ้างอิงจากหน้าภาษาอังกฤษ อ่านหน้านี้เป็นภาษาอังกฤษ

การปฏิเสธครั้งแรกที่ปลั๊กอินตรวจทานความผิดปกติของผมเคยส่งออกไปนั้น ส่งมาถึงตัวผมเอง ผมได้เขียนไคลเอนต์ทดสอบที่โพสต์รายการตรวจทานใหม่โดยใส่ id ขององค์กรไว้ในเนื้อหาคำขอ ตามความเคยชินจากอีกแพลตฟอร์มหนึ่ง และปลั๊กอินก็ตอบกลับก่อนที่ handler ของผมจะทำงานเสียอีก:
{
"error": true,
"code": "TENANT_NOT_A_PARAMETER",
"message": "The request body names the organisation. Tenancy comes from the token.",
"resolved": ["tenant", "owner"],
"missing": [],
"troubleshooting": ["Remove organizationId from the body. The organisation is read from your sign-in."]
}ผมไม่ได้เขียนการตรวจสอบนั้นเอง มันมาพร้อมกับ scope guard ที่เทมเพลตของ SDK (ชุดพัฒนาซอฟต์แวร์) ต่อเข้ากับทุกเส้นทาง /api และจะทำงานแม้ว่า id ในเนื้อหาคำขอจะเป็นของผู้เรียกเองก็ตาม นี่คือรูปแบบของทั้งบทนี้ กล่าวคือ มีกฎจำนวนไม่มาก แต่ละข้อบังคับใช้ด้วยกลไกที่คุณได้รับสืบทอดมา และแต่ละข้อมีด่านตรวจที่จะทำให้การ build ของคุณล้มเหลวหากโค้ดของคุณหลบเลี่ยงกฎนั้น บน Nexus ปลั๊กอินของคุณได้รับการแยกส่วนสืบทอดมาจากแพลตฟอร์ม และด่านตรวจจะตรวจสอบสิ่งนั้น
มีกฎอยู่ห้าข้อ และหัวข้อด้านล่างจะกล่าวถึงทีละข้อ ได้แก่ การแยกส่วนบนสามแกน การประมวลผลที่ทำงานผ่านการ dispatch ของ UNO เท่านั้น AI (ปัญญาประดิษฐ์) ที่ใช้งานผ่าน AI Provider Router เท่านั้น คีย์โมเดลที่เป็นขององค์กร และฟีเจอร์ที่ต้องมีใบอนุญาตซึ่งตรวจสอบกับใบอนุญาต ทุก manifest ยังระบุกฎสามข้อในจำนวนนี้ซ้ำไว้ในประโยคชุดเดียวด้วย
กฎข้อที่ 1: การแยกส่วนบนสามแกน จากคำขอที่ผ่านการยืนยันตัวตนแล้ว
การอ่านและการเขียนทุกครั้งในส่วนขยายถูกกำหนดขอบเขตบนสามแกน และการเรียกเครื่องมือและการ dispatch สกิลทุกครั้งก็เช่นกัน
| แกน | คอลัมน์ | ตอบคำถาม | เส้นแบ่งเข้มงวดเพียงใด |
|---|---|---|---|
| ผู้เช่า (Tenant) | organization_id |
องค์กรใด | ขอบเขตที่เข้มงวด ข้ามได้เฉพาะผ่านสิทธิ์แบบอ่านอย่างเดียวที่มีการบันทึกไว้ |
| เจ้าของ (Owner) | owner_user_id |
บุคคลใดภายในองค์กร | เป็นส่วนตัวแม้ภายในองค์กรเดียวกัน สำหรับสิ่งใดก็ตามที่เป็นของส่วนบุคคล |
| หน่วย (Unit) | business_unit_id |
ส่วนใดขององค์กร | รั้วกั้นที่เป็นทางเลือกภายใน tenant |
แกนเจ้าของคือแกนที่ผู้เริ่มต้นมักเข้าใจผิด กล่องจดหมายเป็นของส่วนบุคคล และมุมมองที่บันทึกไว้หรือกราฟที่สร้างจากข้อมูลของบุคคลหนึ่งก็เช่นกัน สมาชิกสองคนขององค์กรเดียวกัน ในหน่วยเดียวกันและมีบทบาทเดียวกัน จะไม่เห็นแถวที่กำหนดขอบเขตตามเจ้าของของกันและกัน สำหรับสิ่งที่เป็นขององค์กร เช่น การอนุมัติหรือบันทึกเคส เจ้าของจะหมายถึงที่มาแทน กล่าวคือ บันทึกว่าใครเป็นผู้ดำเนินการ และการอ่านจะกำหนดขอบเขตตาม tenant เพื่อให้ร่องรอยการตรวจสอบยังคงมองเห็นได้สำหรับผู้ที่ต้องการ คุณเป็นผู้ตัดสินใจสำหรับแต่ละตารางว่าเป็นประเภทใด และชั้น repository จะเข้ารหัสสิ่งนั้นไว้ ไม่ใช่กรณีพิเศษในเส้นทางใดเส้นทางหนึ่ง
แกนทั้งสามมาจากคำขอที่ผ่านการยืนยันตัวตนและไม่มาจากที่อื่นใด ตัวแปรสภาพแวดล้อมไม่สามารถระบุค่าเหล่านี้ได้ และพารามิเตอร์ query, ส่วนของ path, header ของไคลเอนต์ หรือค่าคงที่ตอน build ก็ไม่สามารถระบุได้เช่นกัน SDK ทำให้การเขียนสิ่งที่ผิดเป็นเรื่องยาก: resolveScope(identity, options) ไม่มีพารามิเตอร์องค์กรเลย องค์กรอยู่ภายใน identity และมีเพียงโทเค็นที่ผ่านการตรวจสอบเท่านั้นที่สร้างสิ่งนี้ได้ ไม่มีช่องทางใดให้ส่ง id ผ่านเข้าไป
นั่นคือเหตุผลที่เนื้อหาคำขอซึ่งระบุ tenant จะถูกปฏิเสธแทนที่จะถูกเพิกเฉย guard จะปฏิเสธชื่อฟิลด์ใดก็ตามในห้าชื่อนี้ ได้แก่ orgId, organizationId, organization_id, tenant และ tenantId ฟิลด์ที่ถูกเพิกเฉยอย่างเงียบ ๆ จะสอนให้ผู้เรียกเข้าใจว่าฟิลด์นั้นใช้งานได้ ผู้เรียกรายแรกทดสอบและเห็นข้อมูลของตนเอง ผู้เรียกรายที่สองส่ง id ขององค์กรอื่นมา การปฏิเสธตั้งแต่คำขอแรกจะระบุข้อตกลงให้ชัดเจนก่อนที่ใครจะสร้างระบบบนข้อตกลงที่ผิด กฎเดียวกันนี้ใช้กับ inputParams ของการ dispatch ด้วย กล่าวคือ อินพุตของสกิลที่มี id องค์กรจะถูกปฏิเสธตั้งแต่ตอน dispatch
แกนหน่วยงานจะต้องประกาศและบังคับใช้ หรือไม่ใช้เลย เส้นทางที่ประกาศ needsUnit: true จะปฏิเสธเมื่อข้อมูลประจำตัวไม่สามารถระบุหน่วยงานได้ โดยระบุ unit ไว้ใน missing[] อย่าสังเคราะห์หน่วยงานขึ้นจาก subdomain หรือ header และอย่ากำหนดค่าเริ่มต้นให้ หน่วยงานที่สร้างขึ้นเองจะกั้นรั้วต่างจากหน่วยงานจริงขององค์กร และจะรวมแถวที่ไม่ควรรวม
พื้นผิวการทำงานที่ไม่สามารถระบุเงื่อนไขได้จะทำการปฏิเสธ
หากเส้นทางใดไม่สามารถระบุได้ว่าแถวหนึ่งเป็นของ tenant และเจ้าของรายใด และของหน่วยงานใดเมื่อจำเป็น เส้นทางนั้นจะปฏิเสธ ไม่มีการอ่านทั้งองค์กรเป็นทางสำรอง และไม่มีค่าตัวยึดตำแหน่ง ค่าตัวยึดตำแหน่งเป็นทางเลือกที่แย่ที่สุด เพราะค่าตัวยึดตำแหน่งก็เป็นค่า และค่าย่อมตรงกับแถว: tool router ตัวหนึ่งที่กำหนดค่าเริ่มต้นทั้ง tenant และผู้ใช้เป็นสตริง 'unknown' ได้ส่งข้อมูลทั้งองค์กรให้แก่ผู้ใดก็ตามที่เรียกใช้ บนขอบเขตของ tenant ?? 'unknown' ถือเป็นข้อบกพร่อง
การปฏิเสธมีรูปแบบเดียวกันทุกที่บนแพลตฟอร์ม และมีข้อมูลเพียงพอให้ไคลเอนต์แสดงวิธีแก้ไขได้:
{
"error": true,
"code": "SCOPE_PREDICATE_MISSING",
"message": "Request cannot be scoped to a tenant from the presented credential.",
"resolved": ["tenant", "owner"],
"missing": ["unit"],
"troubleshooting": [
"The credential resolved tenant+owner; this route additionally requires a business unit.",
"Select a business unit in the client and retry — re-authentication will not change this outcome."
]
}error เป็น true เสมอ code มาจากแคตตาล็อกรหัสของแพลตฟอร์ม resolved[] ระบุแกนที่ได้มา และ missing[] ระบุแกนที่เส้นทางต้องการแต่ไม่ได้รับ troubleshooting[] บอกว่าสิ่งใดจะแก้ไขปัญหาได้จริง คำว่า "forbidden" เพียงลำพังไม่ได้สอนอะไรใครเลย
แยก 401 และ 403 ออกจากกัน เพราะไคลเอนต์ตอบสนองต่อทั้งสองแตกต่างกัน
| สถานะ | ความหมาย | สิ่งที่ไคลเอนต์ทำ |
|---|---|---|
| 401 | ยังไม่ได้ยืนยันตัวตน | ลงชื่อเข้าใช้อีกครั้ง |
| 403 | ยืนยันตัวตนแล้ว แต่ไม่สามารถกำหนดขอบเขตของคำขอได้ หรือผู้เรียกไม่มีสิทธิ์ | หยุดลองใหม่และเปลี่ยนคำขอ |
การปฏิเสธด้านขอบเขตที่ตอบกลับเป็น 401 จะทำให้ไคลเอนต์ติดอยู่ในวงวนการลงชื่อเข้าใช้ที่ไม่มีการลงชื่อเข้าใช้ใดยุติได้ กล่าวคือ ไคลเอนต์ทิ้งเซสชันและลงชื่อเข้าใช้อีกครั้ง ลองใหม่และได้ 401 อีก ขณะที่ผู้ใช้เฝ้ามองไอคอนหมุนไปตลอดกาล
มีกลไกอีกสองอย่างที่ทำให้การปฏิเสธครอบคลุมทั้งหมด ภายใน handler scopeOf(req) เป็นวิธีเดียวในการอ่านขอบเขต และจะ throw หาก guard ไม่ได้ทำงาน นอกจากนี้ guard จะทำงานหลังการแยกวิเคราะห์เนื้อหาคำขอและก่อน handler ใด ๆ handler ที่เข้าถึงได้โดยไม่มีเงื่อนไข predicate จะตอบกลับ 500 พร้อม MIDDLEWARE_ORDERING_ERROR อย่างจงใจ เพื่อให้ไปปรากฏใน error budget ของคุณ แทนที่จะไปปรากฏในรายงานเหตุการณ์
ฐานข้อมูลรักษามาตรฐานเดียวกันนี้ด้วยตัวเอง
รั้วกั้นในโค้ดและรั้วกั้นในฐานข้อมูลเป็นกลไกสองอย่างสำหรับกฎข้อเดียว และคุณได้รับทั้งสองอย่าง
ทุกคำสั่งที่กระทำต่อตารางที่มีการกำหนดขอบเขตจะประกอบ tenantFence(scope) จาก SDK คุณไม่ต้องเขียน predicate ด้วยมือเลย ทุกคำสั่งยังทำงานภายใน withScopedTx ซึ่งผูกแกนทั้งสามสำหรับธุรกรรมนั้นธุรกรรมเดียวผ่านฟังก์ชันฐานข้อมูลเดียว และปฏิเสธการผูกครั้งที่สอง (SCOPE_ALREADY_BOUND) เบื้องล่าง ทุกตารางใน schema ของคุณมีการบังคับเปิดใช้ row-level security และบทบาทที่เส้นทางคำขอของคุณใช้เชื่อมต่อไม่สามารถเปลี่ยน tenant ที่ผูกไว้ได้เอง โปรเซสที่เชื่อมต่อด้วยบทบาทที่สามารถข้าม row-level security ได้จะปฏิเสธการบูตด้วย DB_ROLE_BYPASSES_ISOLATION บทที่ 2.22 The plugin runtime แสดงโค้ด ส่วน บทที่ 2.21 The Plugin SDK แสดงวิธีที่ระบบสร้างบทบาทให้คุณ
การข้ามขอบเขตเพียงหนึ่งเดียว: การอนุญาตที่มีการบันทึกไว้
มีเพียงวิธีเดียวเท่านั้นในการข้ามขอบเขต tenant องค์กรที่ถือครองแถวข้อมูลจะบันทึกสิทธิ์ที่ระบุว่าองค์กรใดสามารถอ่านตารางใดได้ ภายใต้ข้อตกลงใด และเป็นระยะเวลานานเท่าใด ฐานข้อมูลทำให้การอ่านนั้นเป็นแบบอ่านอย่างเดียว และทุกการเข้าดูจะถูกบันทึกไว้ก่อนการอ่าน ในทั้งสององค์กร โดยใช้ id เท่านั้น การเขียนไม่ข้ามขอบเขตเลย งานที่ส่งต่อให้บริษัทอื่นจะเดินทางในรูปของข้อความ บทบาทเจ้าของและผู้ดูแลระบบไม่อ่านข้ามขอบเขตเลยแม้แต่ครั้งเดียว และ manifest จะถูกปฏิเสธหากสิทธิ์ที่อนุญาตการอ่านข้ามองค์กรไม่ได้กีดกันบทบาทเหล่านั้นไว้ ปลั๊กอินที่ต้องการวิธีอื่นในการข้ามขอบเขตจะไม่ได้รับ
กฎข้อที่ 2: การประมวลผลทั้งหมดทำงานผ่านการจ่ายงานของ UNO
UNO ซึ่งเป็นเอนจินเวิร์กโฟลว์ เป็นเส้นทางการประมวลผลเพียงเส้นทางเดียว โค้ดของคุณจะไม่ fetch ผู้ให้บริการโมเดลหรือเอนจินโดยตรงเลย และไม่เรียกคิวหรือโฮสต์เวิร์กโฟลว์โดยตรงด้วย คุณส่ง envelope หนึ่งรายการไปยัง endpoint สำหรับ dispatch และได้รับ 202 พร้อมตัวระบุกลับมา ผลลัพธ์จะมาถึงด้วยการ polling หรือด้วย callback
มีแนวปฏิบัติสามข้อที่ตามมา และเทมเพลตมีครบทั้งสามข้อแล้ว
- ไฟล์เดียวเป็นเจ้าของ URL สำหรับ dispatch
UNO_DISPATCH_URLจะถูกอ่านครั้งเดียวใน config loader และต้องเป็นที่อยู่ภายในคลัสเตอร์ ที่อยู่สาธารณะจะถูกปฏิเสธตอนบูต เพราะไม่มีสิ่งใดออกไปนอกการติดตั้ง - รายการอนุญาตแบบปิดหนึ่งรายการ ที่ระบุว่าส่วนนี้สามารถ dispatch อะไรได้บ้าง backend ที่ยอม dispatch id สกิลใดก็ได้ที่เบราว์เซอร์ส่งมา คือ proxy อเนกประสงค์สำหรับทุกสกิลในรีจิสทรี รวมถึงสกิลของปลั๊กอินอื่นและสกิลที่ใช้งบประมาณโมเดลของผู้อื่น รายการนี้เป็นค่าคงที่ระดับโมดูลของประเภทงานที่มี namespace ไม่ใช่ตัวแปรสภาพแวดล้อม id ที่ไม่อยู่ในรายการจะถูกปฏิเสธด้วย
SKILL_NOT_ALLOWED - ตรวจสอบสิ่งที่ได้กลับมาอีกครั้ง เมื่อคุณอ่านงานกลับมา ไคลเอนต์ของ SDK จะเปรียบเทียบ
organization_idของแถวที่ได้กลับมากับ tenant ของผู้เรียก ฝั่งของคุณในการเรียกผ่านเครือข่าย รั้วกั้นที่มีอยู่เฉพาะอีกฝั่งหนึ่งของการเรียกเป็นเพียงธรรมเนียมปฏิบัติ
กฎข้อที่ 3: AI ทั้งหมดต้องผ่าน AI Provider Router
ปลั๊กอินไม่เรียกโมเดลเลย ไม่ว่าที่ใด ไม่มี SDK ของผู้ให้บริการใน package.json ไม่มีคีย์โมเดลในสภาพแวดล้อม และไม่มีตัวส่งต่อ router เพียงผู้เดียวที่ถือข้อมูลประจำตัวผู้ให้บริการขององค์กร และเป็นผู้ตัดสินใจขั้นสุดท้ายว่าจะใช้ผู้ให้บริการและโมเดลใด
สิ่งที่ปลั๊กอินทำได้คือแสดงความต้องการ ณ เวลาลงทะเบียน บนแถวรีจิสทรีของสกิลใน manifest:
{
"execution_config_skill": {
"preferredProvider": "gemini",
"preferredModel": "gemini-3.5-flash",
"capabilityProfile": { "needsToolUse": true, "minContextWindow": 200000 }
}
}router จะทำตามความต้องการก็ต่อเมื่อองค์กรเปิดใช้งานและตั้งค่าข้อมูลประจำตัวของผู้ให้บริการรายนั้นไว้แล้วเท่านั้น มิฉะนั้นจะเลือกทดแทนจากกลุ่มผู้ให้บริการขององค์กรเอง capabilityProfile ไม่เคยเป็นตัวเลือก แต่ใช้กรอง และฟิลด์ dataResidency ของมันเป็นข้อจำกัดด้านเขตอำนาจที่เข้มงวด ซึ่ง router จะต้องปฏิบัติตามหรือปฏิเสธ การละเว้นทั้งหมดนี้เป็นค่าเริ่มต้นที่เหมาะสมสำหรับสกิลส่วนใหญ่ ในกรณีนั้นการกำหนดบทบาทขององค์กรเองจะเป็นตัวตัดสิน และองค์กรเป็นผู้ชำระค่าใช้จ่าย
การปฏิเสธที่ส่งกลับมามีสองประเภท และมีความหมายแตกต่างกันมาก
| รหัส | สถานะ | ความหมาย |
|---|---|---|
MISSING_CALLER_IDENTITY, UNAUTHORIZED_CALLER |
403 | โค้ดของคุณพยายามเรียก router เอง ให้หยุด นี่คือจุดเชื่อมต่อที่ปฏิเสธโดยการออกแบบ และไม่สามารถลองใหม่ได้ |
MODEL_CAPABILITY_UNAVAILABLE |
422 | ไม่มีผู้ให้บริการที่เปิดใช้งานรายใดมีโมเดลที่ตรงตามโปรไฟล์ ให้ผ่อนปรนโปรไฟล์ หรือให้องค์กรเปิดใช้งานผู้ให้บริการที่มีความสามารถเพียงพอ |
NO_PROVIDER_FOR_ROLE |
422 | องค์กรยังไม่ได้กำหนดค่าการกำหนดเส้นทางสำหรับบทบาทนี้ ให้แสดงข้อความแนวทางแก้ไขของ router แก่ผู้ใช้ |
คู่ที่สองควรแสดงบนหน้าจอ ไม่ใช่ในบันทึก ไม่มีโมเดลเริ่มต้นและไม่มีผู้ให้บริการสำรอง บทบาทที่องค์กรยังไม่ได้ตั้งค่าจะล้มเหลวอย่างชัดเจน พร้อมประโยคที่บอกว่าต้องกำหนดค่าอะไร
การอ่านจาก router เพียงอย่างเดียวที่ปลั๊กอินทำได้คือ effectiveRoute() จาก runtime/ai-route ซึ่งตอบว่า router จะเลือกผู้ให้บริการและโมเดลใดสำหรับองค์กรที่ลงชื่อเข้าใช้อยู่ โดยไม่ส่งคำขอ AI และจะส่งคืนคำปฏิเสธของ router เป็นข้อความเมื่อไม่มีโมเดล บทที่ 2.22 The plugin runtime แสดงวิธีการนี้
ลำดับขั้นความไว้วางใจเพิ่มเส้นแบ่งอีกหนึ่งเส้น เฉพาะปลั๊กอิน core และ verified เท่านั้นที่สามารถประกาศสกิลใน manifest สองระดับที่เข้าถึง router ได้ คือ tool_using และ llm_only ปลั๊กอินอื่นทั้งหมดเป็นตัวกลางสำหรับงานแบบกำหนดผลแน่นอน และปล่อยให้แพลตฟอร์มทำส่วนที่ต้องเข้าถึงโมเดล
กฎข้อที่ 4: คีย์เป็นขององค์กร
แต่ละองค์กรนำบัญชีและคีย์ผู้ให้บริการของตนเองมาใช้ และชำระค่าใช้จ่ายของตนเอง คีย์จะอยู่ในกลุ่มผู้ให้บริการ AI ขององค์กร ซึ่งผู้ดูแลระบบขององค์กรเองจัดการจากคอนโซล และ router จะดึงคีย์มาใช้ ณ เวลาเรียก ไม่มีคีย์แพลตฟอร์มที่ใช้ร่วมกันอยู่เบื้องหลัง tenant ใด ดังนั้นจึงไม่มีองค์กรใดใช้งบประมาณขององค์กรอื่น
สำหรับส่วนขยาย สิ่งนี้หมายถึงสามประการ
- คุณไม่ถือคีย์โมเดลเลย ไม่ว่าในโค้ด การกำหนดค่า หรือที่เก็บข้อมูลลับ ด่านตรวจ
no-credentialsจะทำให้การ build ล้มเหลวหากอ่านคีย์ได้ และ config loader จะปฏิเสธการบูตหากมีคีย์อยู่ - คุณไม่ไล่รายการคีย์ขององค์กรเลย หากปลั๊กอินของคุณคิดว่าจำเป็นต้องทำ แสดงว่าข้อกำหนดนั้นอยู่ผิดที่
- องค์กรที่ไม่มีคีย์จะไม่ได้รับคำตอบจาก AI ซึ่งเป็นสถานะที่คาดไว้และมีหน้าจอจริงรองรับ ให้ระบุบทบาทที่ขาดหายไปและยกข้อความแนวทางแก้ไขมาแสดง จากนั้นแนะนำผู้ใช้ไปยังการตั้งค่าผู้ให้บริการของตน อย่าแสดงผลเป็นผลลัพธ์ว่างเปล่า
กฎข้อที่ 5: ฟีเจอร์ที่ต้องใช้ใบอนุญาตจะถูกตรวจสอบกับใบอนุญาต
สิ่งที่การติดตั้งสามารถใช้ได้นอกเหนือจากระดับพื้นฐานของ Community มาจากแหล่งเดียว คือเอกสารใบอนุญาตที่ Adverant ลงนาม ซึ่งตรวจสอบบนการติดตั้งด้วยคีย์สาธารณะเท่านั้น ส่วนขยายของคุณจะไม่ตัดสินใจจากสิ่งใดที่อ่อนกว่านี้ เช่น ชื่อแผนในโทเค็น หรือแฟล็กในการกำหนดค่า
ในปลั๊กอิน วิธีที่ง่ายที่สุดในการผูกฟีเจอร์เข้ากับใบอนุญาตคือผูกไว้กับสิทธิ์ที่ปกป้องฟีเจอร์นั้น สิทธิ์ในทะเบียน rights ของ manifest สามารถระบุฟีเจอร์ licence ได้:
"rights": {
"evidence.export": {
"summary": "Export the evidence pack for an inspection.",
"roles": ["owner", "admin", "member"],
"licence": "compliance-packs"
}
}ผู้ใดก็ตามที่เรียกเส้นทางซึ่งปกป้องด้วยสิทธิ์นั้นจะถูกปฏิเสธด้วย LICENCE_LOCKED (403) ไม่ว่าจะมีบทบาทและที่นั่งใดก็ตาม เมื่อใบอนุญาตขององค์กรไม่มี compliance-packs การปฏิเสธจะระบุฟีเจอร์และสิ่งที่ให้สิทธิ์ฟีเจอร์นั้น และบอกว่าใครสามารถเปิดใช้งานได้
สถานะของใบอนุญาตก็มีความสำคัญเช่นกัน ขณะที่ใบอนุญาตยังมีผลหรืออยู่ในช่วงเตือน ฟีเจอร์ที่มีใบอนุญาตจะทำงาน และยังคงทำงานต่อในช่วงผ่อนผัน โดยช่วงผ่อนผันจะแสดงประกาศ LICENCE_IN_GRACE เมื่อใบอนุญาตเลยช่วงผ่อนผันแล้วจะถูกจำกัด งานที่กำลังทำงานและการอ่านจะดำเนินต่อไป รวมถึงการส่งออกและการอัปเดตความปลอดภัย แต่การสร้างสิ่งใหม่ภายใต้ฟีเจอร์ที่มีใบอนุญาตจะถูกปฏิเสธด้วย LICENCE_LOCKED ให้สร้างเส้นทางการสร้างของคุณโดยคาดการณ์คำตอบนั้นไว้
เมื่อปลั๊กอินของคุณสอบถามการตรวจสอบสิทธิ์การใช้งานว่าองค์กรมีฟีเจอร์หนึ่งหรือไม่ จะได้รับผลการตัดสิน ไม่ใช่ค่า boolean เพียงอย่างเดียว "เข้าถึงไม่ได้" และ "เข้าถึงได้และไม่มี" เป็นข้อเท็จจริงที่ต่างกันและมีรหัสต่างกัน คือ ENTITLEMENT_UNREACHABLE (502) และ ENTITLEMENT_DENIED (403) ความขัดข้องชั่วขณะในการเข้าถึงต้องไม่ลดระดับลูกค้าทุกรายลงสู่ระดับพื้นฐานแบบฟรีอย่างเงียบ ๆ
MANIFEST_SCOPE_WIDENED จนกว่าผู้ตรวจทานสองคนและเจ้าหน้าที่กำกับดูแลการปฏิบัติตามข้อกำหนดจะเห็นชอบไฟล์ Manifest จะระบุกฎเกณฑ์ซ้ำอีกครั้ง
manifest v2 ทุกฉบับมีบล็อก architecture ซึ่งประกอบด้วยประโยคบังคับสามประโยค และตัวตรวจสอบ (validator) กำหนดถ้อยคำของประโยคเหล่านั้นไว้ตายตัว ในปลั๊กอินที่คุณสร้างขึ้นสำหรับการติดตั้งของคุณเอง ประโยคเหล่านั้นมีข้อความดังนี้:
"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."
}ประโยคเหล่านั้นได้รับการตรวจสอบ ปลั๊กอินที่ manifest ยอมรับกฎเหล่านี้ ขณะที่โค้ดของปลั๊กอินเรียกผู้ให้บริการโมเดลโดยตรง ก็เท่ากับโกหกในสัญญาของตนเอง และเกตต่าง ๆ มีไว้เพื่อให้ตรวจพบการโกหกนั้นได้
เกตที่บังคับใช้แต่ละกฎ
SDK มาพร้อมเกตตรวจสอบการปฏิบัติตามกฎ (adherence gate) ยี่สิบสองรายการในรูปคำสั่งเดียว คือ nexus-gates บทที่ 2.21 The Plugin SDK อธิบายเกตทุกรายการไว้ ในที่นี้จะจัดกลุ่มตามกฎที่แต่ละเกตบังคับใช้
| กฎ | เกต | สิ่งที่ทำให้การ build ล้มเหลว |
|---|---|---|
| การแยกข้อมูลในชั้นเส้นทาง (route layer) | scope-adherence, one-fence, rights-register, crud-adherence |
เส้นทาง /api ที่ไม่มี scope guard, เงื่อนไขกรองผู้เช่า (tenant predicate) ที่เขียนด้วยมือซ้ำอีกชุด, เส้นทางแบบ scope ที่ไม่มีสิทธิ์กำกับ, เส้นทางที่แก้ไขข้อมูลซึ่งสิทธิ์ของมันไม่ได้ระบุสิ่งใดเลย |
| การแยกข้อมูลใน SQL | sql-fence, no-set-config |
คำสั่งบนตารางที่มีขอบเขต (scoped table) ที่ไม่มีรั้วกั้น (fence); โค้ดของปลั๊กอินที่ผูกค่าการตั้งค่าผู้เช่าด้วยตนเอง |
| การแยกข้อมูลในฐานข้อมูล | migrations-are-scoped, rls-present, db-role-honest |
ตารางที่ขาดแกน (axis) หรือขาดคีย์ที่ขึ้นต้นด้วยผู้เช่า, ตารางที่ไม่ได้บังคับใช้ row-level security, เส้นทางคำขอที่เชื่อมต่อในฐานะเจ้าของหรือ superuser |
| จุดข้ามเพียงจุดเดียว | grants-declared |
ตารางที่ได้รับสิทธิ์ใน migration แต่ manifest ไม่ได้ประกาศไว้ หรือที่นั่งสำหรับอ่าน (read seat) ที่ได้รับสิทธิ์ด้วยมือ |
| การประมวลผลผ่าน UNO | no-direct-compute |
การ fetch โดยตรงไปยังผู้ให้บริการโมเดลหรือเอนจิน หรือไปยังโฮสต์คิวหรือเวิร์กโฟลว์; ผู้อ่าน URL สำหรับ dispatch รายที่สอง |
| AI และคีย์ | no-credentials |
ข้อมูลรับรอง (credential) ของผู้ให้บริการโมเดลที่อ่านได้ใน repository หรือในสภาพแวดล้อม |
| สัญญาที่ประกาศไว้ | api-contract, platform-clients, declared-input |
เส้นทางที่ลงทะเบียนแต่ไม่ได้ประกาศ หรือประกาศแต่ไม่ได้ลงทะเบียน; ไคลเอนต์ของแพลตฟอร์มที่ import แต่ไม่ได้ระบุชื่อ |
เกตทุกรายการมีการทดสอบตนเอง (self-test) ที่พิสูจน์ว่าเกตจะล้มเหลวกับ fixture ที่สร้างขึ้นมาเพื่อให้เกตทำงาน npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test จะรันการทดสอบทั้งหมด และเกตที่ไม่ล้มเหลวกับ fixture ของตนเองอีกต่อไป ก็คือเกตที่หยุดทำงานแล้ว
ก่อนที่คุณจะขอรับการตรวจทาน
นี่คือรายการที่ผมไล่ตรวจก่อนจะขอให้เพื่อนร่วมงานรีวิวปลั๊กอิน แต่ละข้อคือสิ่งที่ผู้รีวิวที่ Corrán Orbital เคยส่งกลับมาให้ผมแก้อย่างน้อยหนึ่งครั้ง
- เส้นทาง
/apiทุกเส้นทางลงทะเบียน scope guard และเส้นทางแบบไม่ระบุตัวตนมีเพียงเส้นทางแบบตรงตัวที่ประกาศไว้auth: publicด้วยallowAnonymous: trueเท่านั้น - ทุกเส้นทางที่ scope guard ให้บริการระบุ
rightจากทะเบียนใน manifest และไม่มี handler ใดตรวจสอบสิทธิ์ด้วยตนเอง - ไม่มี handler ใดอ่านองค์กร บุคคล หรือหน่วยงานจาก body, query หรือ header
- ทุกคำสั่งบนตารางที่มีขอบเขตต้องผ่าน
tenantFenceภายในwithScopedTxและไม่มีสิ่งใดใน repository เรียกset_config - ทุกตารางมีคอลัมน์แกนทั้งสามคอลัมน์ มี primary key ที่ขึ้นต้นด้วย
organization_idและมี foreign key แบบผสม (composite) ที่มีผู้เช่ารวมอยู่ด้วย - URL สำหรับ dispatch ถูกอ่านในไฟล์เดียว และรายการอนุญาตของ dispatch เป็นค่าคงที่ของประเภทงานที่มี namespace
- ไม่มีสิ่งใดใน
package.jsonติดต่อกับผู้ให้บริการโมเดล และไม่มีคีย์อยู่ในสภาพแวดล้อม - ทุกฟีเจอร์ที่มีเฉพาะในบางใบอนุญาตระบุ
licenceของตนไว้บนสิทธิ์ที่คุ้มครองฟีเจอร์นั้น npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-testผ่าน (เป็นสีเขียว) และnpx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.jsonก็ผ่านเช่นกัน
หากทั้งเก้าข้อเป็นจริง การรีวิวก็จะมุ่งไปที่ผลิตภัณฑ์ของคุณ ซึ่งเป็นสิ่งที่ผู้รีวิวควรใช้เวลาด้วย
เหตุใดแพลตฟอร์มจึงบังคับใช้กฎเหล่านี้
กฎแต่ละข้อข้างต้นเคยเป็นเพียงธรรมเนียมปฏิบัติในที่ใดที่หนึ่ง และธรรมเนียมปฏิบัติแต่ละข้อล้มเหลวในลักษณะเดียวกัน คือเส้นทางที่จำได้ก็ไม่มีปัญหา ส่วนเส้นทางที่ลืมก็กลายเป็นเหตุการณ์ (incident) รั้วกั้นระดับหน่วยธุรกิจที่ใช้เป็น middleware แบบไม่บังคับถูกเลี่ยงได้หกวิธีโดยอิสระต่อกัน ทุกกรณีคือเส้นทางที่ไม่เคยเลือกใช้งาน ตัวแปรสภาพแวดล้อมที่เขียนทับตัวตนของผู้เช่าทำให้องค์กรหนึ่งได้รับรายชื่อผู้ติดต่อ 1,406 รายขององค์กรอื่น และมันดูถูกต้องในการรีวิว เพราะมันถูกต้องสำหรับ pod ที่มันถูกเขียนขึ้นมา
ดังนั้น แพลตฟอร์มจึงวางเงื่อนไขกรองไว้ในจุดที่ทุกส่วนต้องผ่านอยู่แล้ว ได้แก่ ใน scope guard และฟังก์ชันรั้วกั้น ใน transaction wrapper และ row-level security แบบบังคับ และใน dispatch client จากนั้นเกตจะไล่ตรวจทุกเส้นทาง ทุกคำสั่ง และทุกการ import และทำให้การ build ล้มเหลวเมื่อมีรายการใดเข้าถึงตารางที่มีขอบเขต โมเดล หรือเอนจินประมวลผลโดยไม่ผ่านกลไกเหล่านั้น ต้นทุนของการออกแบบนี้คือปลั๊กอินตัวแรกของคุณจะรู้สึกถูกจำกัด ผลตอบแทนคือปลั๊กอินตัวที่หนึ่งพันจะถูกแยกข้อมูลโดยที่ผู้เขียนไม่จำเป็นต้องรู้ว่าฟีเจอร์นี้มีอยู่ เพราะไม่มีเส้นทางอื่นไปสู่ข้อมูลให้มันใช้
ทั้งหมดนี้มีข้อจำกัดที่ต้องยอมรับตามตรง เกตพิสูจน์ได้ว่าโค้ดของคุณผ่านกลไกต่าง ๆ แต่ไม่สามารถพิสูจน์ได้ว่าตรรกะของผลิตภัณฑ์ของคุณถูกต้อง เส้นทางที่กำหนดขอบเขตคิวรีให้อยู่ในแถวของเจ้าของได้อย่างถูกต้อง ก็ยังอาจแสดงแถวที่ผิดให้เจ้าของที่ถูกต้องเห็นได้ ชุดทดสอบการแยกข้อมูลในบทที่ 2.22 The plugin runtime จะโจมตีทุกเส้นทางในฐานะองค์กรอื่นและในฐานะเพื่อนร่วมงาน โดยถอดรั้วกั้นออกทีละชั้น และนั่นคือการทดสอบที่ผมจะรันก่อนที่จะเชื่อความเข้าใจของตัวเองในเรื่องใด ๆ เหล่านี้

