로그인브리핑 예약

챕터 2.27

빌드 시나리오

단일 스킬부터 에어갭 배포까지, 열세 가지 빌드를 담은 쿡북입니다. 각 레시피는 목표, 구성 요소, 단계 및 명령어, 작동을 증명하는 게이트, 그리고 에디션 및 배포 형태에 따라 달라지는 점을 제시합니다.

이 페이지는 AI에 의해 영어 원문에서 번역되었습니다. 불명확한 내용이 있는 경우 영어 페이지를 기준으로 삼으십시오. 이 페이지를 영어로 읽기

읽는 시간 25분

다음은 Corrán Orbital이나 고객사에서 누군가 "Nexus가 X를 하도록 하고 싶다"고 말할 때 제가 꺼내 드는 레시피입니다. 각 레시피는 의도적으로 짧게 작성했습니다. 각 단계의 근거는 이 장 앞의 장들에 있습니다. 2.20장 스킬, 소프트웨어 개발 키트를 다루는 2.21장 Plugin SDK, 그리고 2.23장 도메인 팩과 그 뒤에 이어지는 빌드에 관한 세 개의 장입니다. 여기서는 목표, 사용할 구성 요소, 단계, 명령, 성공 여부를 알려 주는 게이트, 그리고 에디션 및 제공 관련 참고 사항을 확인할 수 있습니다.

가장 중요한 것은 게이트입니다. 레시피는 게이트가 녹색이 되었을 때 완료됩니다. 이 장의 모든 게이트는 직접 실행하거나 플랫폼이 대신 실행하는 것이며, 조건이 충족되지 않으면 각 게이트는 0이 아닌 코드로 종료되거나 코드와 함께 거부합니다.

시나리오 주요 구성 요소 이를 증명하는 게이트 에디션
새 Skills Engine 스킬 SKILL.md 패키지 오류 0건의 skill:validate Community 및 Enterprise
host_callback이 포함된 매니페스트 스킬 플러그인 매니페스트 skills[] create-nexus-plugin validate 및 nexus-gates Community 및 Enterprise
기존 팩 확장 inherits를 포함한 pack.json 파일럿 게이트의 렌즈 정책 검사 Enterprise 및 팩 라이선스
처음부터 만드는 새 팩 도메인 팩 골든 패스 스테이징 및 파일럿 게이트 Enterprise
데이터 커넥터 plugin_queue 스킬 validate, nexus-gates, 외부 송신 거부 Community 및 Enterprise
MCP(Model Context Protocol) 도구 매니페스트 mcpTools[] validate(최상위 결합자 없음) Community 및 Enterprise
화이트 라벨 스토어프런트 매니페스트 domains 및 branding scope-adherence 공개 규칙 Enterprise 및 Storefront 애드온
Edge 미션 팩 미션 팩 온보드 테스트 케이스, 3개 중 2개의 서명 Enterprise 및 Nexus Edge 애드온
에어갭 환경 제공 봉인된 번들 nexus-airgap verify Enterprise
Enterprise 전용 모듈 @adverant/nexus-spi 라이선스 경계 게이트, 에디션 빌드 Enterprise
오픈 코어 포크 또는 확장 Community 소스 테스트, 린트 및 타입 검사 Community
Team 에디션 클라우드 앱 퍼블리셔 클러스터 서명된 릴리스, 검토, 고객 승인 Team
기존 내부 앱 래핑 /plugin-create migrate, validate, nexus-gates Community 및 Enterprise
위에서 아래로 읽는 의사 결정 트리입니다. 첫 번째 마름모는 "코드가 항상 실행되어야 합니까?"라고 묻습니다. "아니요"는 "어시스턴트를 위한 지침입니까?"라는 마름모로 이어지며, 이 마름모의 "예"는 "Skills Engine 스킬"로, "아니요"는 "기존 팩의 렌즈"로 끝납니다. "예"는 "플랫폼에 대한 한 산업의 관점입니까?"라는 마름모로 이어지며, 이 마름모의 "예"는 "도메인 팩(플러그인 포함)"으로 끝나고 "아니요"는 마지막 마름모 "비공개 및 라이선스 상태를 유지해야 합니까?"로 이어져, "예"이면 "Enterprise 모듈"로, "아니요"이면 "플러그인"으로 끝납니다.
어떤 구성 요소에서 시작할 것인가.

1. 새로운 Skills Engine 스킬

목표는 통관 신고서를 규칙에 따라 검사하는 것처럼 어시스턴트, 에이전트, 워크플로 및 개발자 도구가 모두 실행할 수 있는 재사용 가능한 지침을 만드는 것입니다. 구성 요소는 스킬 이름을 딴 폴더 안의 SKILL.md 패키지, 트리거와 태그를 위한 선택적 skill.yaml, 그리고 함께 번들로 묶이는 선택적 scripts/ 폴더입니다.

  1. skills/<slug>/을 만들고 프런트매터와 함께 SKILL.md를 작성하십시오. 프런트매터에는 name(kebab-case, 폴더 이름과 동일), description(최대 500자), allowed-tools, 그리고 선택적으로 triggers, capabilities, version을 포함합니다.
  2. 모델을 위한 본문을 작성하십시오. 스킬을 언제 사용하는지, 단계, 예시, 그리고 절대 해서는 안 되는 일을 기술합니다.
  3. 테스트 케이스를 추가하십시오. 입력에 심어 둔 지시를 스킬이 따르지 않아야 하는 케이스를 하나 포함하십시오.
  4. 검증하고, 업로드 계획을 확인한 다음 업로드하십시오.
  5. 게시하십시오. 쓰기 도구를 추가하는 스킬은 지정된 두 사람이 패스키로 승인할 때까지 보류되며, 제안자는 자신의 변경을 승인할 수 없습니다.
npm run skill:validate skills/check-a-customs-filing
npm run skill:upload skills/check-a-customs-filing --dry-run
npm run skill:upload skills/check-a-customs-filing

게이트는 skill:validate이며, 무엇이든 게시하기 전에 오류가 0건이어야 합니다. 차단 오류는 이름 또는 설명 누락, 그리고 슬러그 또는 작업 유형 중복입니다. 이미 게시된 콘텐츠를 업로드하면 기존 버전(CONTENT_HASH_ALREADY_PUBLISHED)이 반환되므로 업로드는 반복해도 안전합니다.

Community에서는 생성기, 라이브러리, 버전, 이전 버전으로 전환, 가져오기 및 테스트 전체를 사용할 수 있습니다. Enterprise에서는 게시 시 섀도와 카나리 단계도 거칩니다. 승인된 버전이 섀도로 실행된 후, 지정된 게이트를 거쳐 한 단위에서 실행되고, 이어서 모두에게 적용되며, 게이트가 충족되지 않으면 스스로 중지됩니다. 에어갭 환경의 고객에게는 스킬이 봉인된 번들 안에 사전 서명된 상태로 전달됩니다(시나리오 9).

2. host_callback을 사용하는 매니페스트 스킬

목표는 측정값으로부터 이탈 기록을 여는 것처럼 플랫폼이 디스패치할 수 있는 결정론적 연산을 자체 플러그인에 구현하는 것입니다. 매니페스트의 skills[]에 티어 host_callback로 행을 추가하고, 백엔드에 SDK의 서비스 가드로 보호되는 /internal 라우트를 사용합니다.

  1. 스킬을 선언하십시오. lower_snake 형식의 id, tier: "host_callback", 플러그인의 신뢰 상한 이하의 classification, inputSchema, outputSchema, 그리고 1초에서 6시간 사이의 timeoutMs을 지정합니다.
  2. hostCallback을 채우십시오. 자체 Service 이름, 해당 포트, /internal/skills/excursion_open 같은 상대 경로, 두 바이트 상한(maxRequestBytes 및 maxResponseBytes), 그리고 tenantHeader: "X-Organization-ID"를 지정합니다.
  3. api.endpoints[]에 auth: "service-key" 또는 auth: "internal"로 라우트를 선언하고, 사용자 범위 가드가 아닌 requireService 또는 serviceMiddleware로 보호하십시오.
  4. 검증하고 게이트를 실행한 다음, 온보딩이 compileRegistry을 통해 스킬을 레지스트리에 동기화하도록 하십시오. 레지스트리 SQL을 직접 작성할 일은 없습니다.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test

validate은 동기화 전에 레지스트리 동기화 자체의 규칙을 적용하며, 각 위반은 수신 측의 코드로 거부됩니다. 스킴, // 또는 백슬래시가 포함된 경로는 교차 출처로 거부됩니다. 바이트 상한 누락은 ENDPOINT_BYTE_CAP_REQUIRED, 다른 티어의 필드는 FIELD_NOT_FOR_TIER, 범위를 벗어난 타임아웃은 TIMEOUT_OUT_OF_BOUNDS입니다. 이어서 nexus-gates이 /internal 라우트에 서비스 가드가 있고 internal 또는 service-key로 선언되었는지 확인합니다. 이 두 게이트가 증명입니다.

동기화는 선언적입니다. 누락된 스킬은 비활성화되므로 매번 전체 스킬 세트를 게시하고, 200 이외의 상태에서는 배포 단계를 실패 처리하십시오. Enterprise에서는 플러그인 동기화가 전체 단위로 검사됩니다. 스킬 하나가 규칙을 위반하면 해당 동기화 전체가 받아들여지지 않으며(PLUGIN_SYNC_ALL_OR_NOTHING) 이전 버전이 계속 실행됩니다. 커뮤니티 신뢰 수준의 플러그인은 모델에 접근하는 티어인 tool_using 및 llm_only을 사용할 수 없으며, 이를 사용하려면 신뢰 수준 core 또는 verified가 필요합니다.

플러그인 및 MCP 동기화
플러그인 및 MCP 동기화
스킬을 제공하는 플러그인과 각 동기화에서 검사된 항목입니다. 다섯 개 스킬 중 하나가 플랫폼만 호스팅할 수 있는 티어를 사용하여 동기화 전체가 거부되었지만 이전 버전은 계속 실행된 플러그인에 주목하십시오.

3. 기존 팩 확장하기

목표는 Insurance 팩의 구조 위에 대출 및 카드 분쟁을 구축하는 것처럼 기존 팩의 대부분을 재사용하는 새 산업 또는 하위 산업을 만드는 것입니다. 구성 요소는 inherits에 상위 팩을 지정하고 자체 렌즈 클러스터와 용어만 추가하는 pack.json입니다.

  1. 도메인 팩 골든 패스로 팩을 시작한 다음, inherits을 상위 팩의 id로 설정하십시오.
  2. 각각의 좌석, 목적 및 어휘집 참조를 포함한 자체 lens 클러스터를 추가하십시오.
  3. 용어를 어휘집에 추가하고 각각에 평이한 설명을 붙이십시오. 표기된 그대로 표시해야 하는 용어는 exact로 표시하십시오.
  4. 자체 렌즈를 그리기보다 공유 렌즈를 재사용하십시오. 외주 기술 등록부처럼 여러 팩에 필요한 규제 체계는 하나의 공유 렌즈입니다.
  5. 라이선스 체인을 확인하십시오. 팩은 상위 팩의 애드온 요구 사항을 상속합니다.
  6. 합성 브랜치에서 각 렌즈를 특정 사용자로서 미리 보십시오.
{ "id": "fintech", "name": "Banking and payments", "version": "0.1", "inherits": "insurance" }

증명은 파일럿 게이트의 정책 검사로, 각 렌즈가 기본 렌즈를 좁히기만 하고 개인 필드를 기본적으로 숨기는지 확인합니다. 기본 렌즈가 숨기는 것을 표시하려는 렌즈는 LENS_CANNOT_WIDEN로 거부됩니다. 라이선스 측면에서는 상위 팩에 필요한 애드온 없이 팩의 라이선스를 발급하는 것을 콘솔이 거부합니다. Insurance 팩에는 Decision rooms와 봉인된 기록이 필요합니다.

도메인 팩은 Enterprise 전용이며 팩별로 라이선스가 부여됩니다. 팩의 휴대폰 화면에는 Mobile apps 애드온도 필요합니다. 하위 팩은 셸, 컴포넌트 또는 작성 규칙을 변경할 수 없습니다.

4. 처음부터 새로운 팩 만들기

목표는 특정 산업 관점의 Nexus, 즉 지식 모델, 역할별 렌즈, 규칙이 요구하는 증거, 그리고 데이터를 최신 상태로 유지하는 플러그인을 만드는 것입니다. 2.24장 맞춤형 버티컬 엔드투엔드 구축에서 이 빌드 전체를 다루며, 여기서는 요약본을 제공합니다.

  1. 도메인 팩 골든 패스를 실행하고 팩을 기술하십시오. 목적, 단위, 기본 모델, 그리고 매핑하는 규칙을 기술합니다.
  2. 기본 모델 위에 지식 모델을 구축하고, 속성을 추가할 때마다 분류하십시오.
  3. 계획을 읽고 패스키로 지문을 확인한 다음 생성하십시오.
  4. Lens builder에서 각각 기본 렌즈를 좁히는 방식으로 렌즈를 구성하십시오.
  5. 팩에 필요한 플러그인과 Skills Engine 스킬을 작성하십시오.
  6. 관심 있는 예외 사례를 포함한 시드 기반 합성 데이터를 생성하고, 각 렌즈를 특정 사용자로서 미리 보십시오.
  7. 개발 공간에서 스테이징으로, 파일럿 단위로, 그리고 모든 단위로 승격하십시오.

증명은 승격 게이트입니다. 스테이징으로 가려면 합성 브랜치에서 모든 테스트가 통과해야 하고, 이어서 작성자가 아닌 검토자 두 명의 승인, 그리고 오류율 1,000분의 1 미만으로 파일럿에서 14일을 거쳐야 합니다. 어떤 단계도 건너뛸 수 없습니다(GATE_CANNOT_BE_SKIPPED). 팩은 Enterprise 전용입니다. Community에서는 도메인 팩 골든 패스가 제공되지 않습니다.

5. 데이터 커넥터

목표는 터미널 운영 시스템의 게이트 이벤트처럼 외부 시스템의 데이터가 일정에 따라 플러그인 자체 테이블로 유입되도록 하는 것입니다. 구성 요소는 plugin_queue 스킬, 큐를 가져오는 워커, 대상 테이블용 마이그레이션, 그리고 매니페스트에 선언된 아웃바운드 주소입니다.

  1. queueName를 <plugin name>.<name>로 표기한 plugin_queue 스킬을 선언하십시오. 콜론은 허용되지 않으며, 오케스트레이터가 직접 해당 큐에 넣으므로 이름이 매니페스트에 있어야 합니다.
  2. 큐를 가져와 외부 시스템을 호출하는 워커를 작성하십시오.
  3. 외부 시스템의 주소를 아웃바운드 주소로 선언하십시오. 목록에 없는 주소는 모두 차단됩니다.
  4. 수신된 데이터는 모든 행에 organization_id, owner_user_id, business_unit_id을 포함하여 자체 스키마에 저장하십시오.
  5. 외부 시스템의 자격 증명은 환경에서 이름으로 읽고, 해당 변수를 scripts/ci/required-env에 나열하십시오.
  6. 가져오기 작업은 엔진을 직접 호출하는 타이머가 아니라 워크플로 엔진인 UNO를 통해 디스패치하십시오.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --only no-credentials --only no-direct-compute --only migrations-are-scoped
node scripts/ci/required-env

validate은 레지스트리 동기화 규칙에 따라 큐 이름과 타임아웃을 검사합니다. 세 게이트는 모델 자격 증명이 없고, 직접 연산이 없으며, 테이블 범위가 올바르게 지정되었음을 증명합니다. --only은 실행 범위를 좁히고 요약에 그 사실을 표시하므로, 푸시하기 전에 전체 nexus-gates를 실행하십시오. 실행 시 매니페스트에 선언되지 않은 주소로의 호출은 엣지에서 EGRESS_NOT_DECLARED로 차단됩니다.

변경 캡처와 계보를 갖춘, 드라이브, 위키, 메일 저장소 및 레거시 시스템에 대한 플랫폼 자체 커넥터는 Data connectors 애드온에 포함됩니다. 직접 구축한 커넥터는 플러그인이므로 모든 에디션에서 작동합니다. 이후 릴리스에서 아웃바운드 주소를 추가하는 것은 범위 확대에 해당하며, 검토자 두 명이 수락할 때까지 보류됩니다.

6. MCP 도구

목표는 선박의 검사 이력 조회처럼 Claude Code, 에이전트 및 기타 MCP(Model Context Protocol) 클라이언트가 호출할 수 있는 도구를 만드는 것입니다. 구성 요소는 name, description, inputSchema를 포함한 매니페스트의 mcpTools[] 항목입니다.

  1. 도구의 이름을 정하고 평이하게 설명하십시오. 모델은 이 설명을 읽고 호출 여부를 결정합니다.
  2. inputSchema을 하나의 객체 스키마로 작성하십시오. 최상위 수준에 oneOf, allOf 또는 anyOf를 넣지 마십시오.
  3. 도구를 제공하는 라우트는 다른 모든 /api 라우트와 마찬가지로 범위 가드 뒤에 두어, 테넌시가 호출자의 토큰에서 결정되도록 하십시오.
  4. 매니페스트를 검증하십시오.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json

증명은 validate입니다. 최상위 결합자는 작성 시점에 거부됩니다. 실행 시점에는 이를 가져오는 모든 MCP 서브에이전트에서 도구가 실패하여, 도구는 존재하지만 아무도 호출할 수 없게 되기 때문입니다.

Enterprise에서는 IDE(통합 개발 환경)가 호출할 수 있는 모든 도구가 티어, 변경 수행 여부, 고정된 지문, 사용 가능한 역할과 함께 Workbench 도구 카탈로그에 등록됩니다. 새 릴리스에서 도구 설명이 변경되면 카탈로그는 사람이 변경을 검토할 때까지 도구를 보류합니다. 이는 의도된 것입니다. 설명 변경은 도구가 모델에 해서는 안 될 요청을 하기 시작하는 경로가 될 수 있기 때문입니다. 호출자의 패스 범위를 벗어난 호출은 CONNECTION_SCOPE_EXCEEDED로 거부됩니다.

7. 화이트라벨 스토어프론트

목표는 고객의 고객이 사용하는 앱을 Adverant의 흔적 없이 고객의 도메인과 브랜드로 제공하는 것입니다. 구성 요소는 매니페스트의 domains 및 branding 블록, SDK의 로그인 헬퍼, 그리고 고객의 Storefront / white-label 애드온입니다.

  1. 고객의 도메인을 domains[]에 primary로 넣고, 필요한 경우 aliases도 함께 지정하십시오.
  2. branding을 채우십시오. appName, tagline, primaryColor, accentColor, 도메인과 동일한 passkeyRpId, 그리고 oauthClientRef을 지정합니다.
  3. SDK의 로그인 헬퍼를 통해 사용자를 로그인시키고, 두 공개 라우트를 auth: "public" 및 allowAnonymous: true로 정확히 선언하십시오.
  4. 모든 프런트엔드 호출은 BFF(backend for frontend) 허용 목록 프록시를 거치도록 하십시오. 클라이언트에 서비스 주소를 넣지 마십시오.
  5. 결제는 게이트웨이를 연결하고 브랜드 결제 화면을 설정하는 고객의 관리자에게 맡기십시오.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --only scope-adherence --only api-contract

증명은 scope-adherence입니다. 이는 매니페스트가 해당 메서드와 경로를 정확히 공개로 선언하고 그 경로가 로그인 라우트 중 하나인 경우에만 가드 없는 /api 라우트를 허용합니다. 그 밖의 공개 선언은 실패하며 허용된 두 경로를 알려 줍니다. 이어서 api-contract이 선언된 라우트와 실제 라우트를 양방향으로 비교합니다. definePlugin는 상대 경로의 동일 출처 경로가 아닌 frontend.basePath도 거부합니다.

화이트 라벨은 Enterprise의 Storefront / 화이트 라벨 애드온이며, 이 애드온은 결제에 대한 라이선스도 함께 제공합니다. 카드 정보는 Nexus에 전혀 닿지 않습니다. 브랜드는 고객의 관리자가 소유하며, 플랫폼은 귀하의 코드가 아니라 조직으로부터 브랜드를 확인합니다.

8. Edge 미션 팩

목표는 Nexus Edge를 실행하는 위성 또는 드론을 위한 새 미션이나 업데이트된 미션입니다. 예를 들어 해상 감시 미션에 선박 탐지 어댑터를 추가하는 경우가 있습니다. 구성 요소는 지상에서 빌드되고 서명되는 미션 팩입니다.

  1. 미션 팩 빌드 페이지에서 현재 팩부터 시작하십시오. 이 페이지는 이전 버전을 바탕으로 새 버전의 초안을 작성하고 모든 변경 사항을 표시합니다.
  2. 미션에 필요한 부분만 변경하십시오. 가능하다면 언어 모델과 온톨로지 같은 큰 부분은 그대로 유지하십시오.
  3. 모든 성능 저하 단계에서 배치 표를 확인하여, 각 보드가 실행하는 작업을 여전히 감당할 수 있도록 하십시오.
  4. 동일한 보드를 갖춘 벤치 장비에서 팩의 탑재 테스트 케이스를 실행하십시오.
  5. 서명을 요청하십시오. 세 개의 서명 중 두 개가 필요합니다.
  6. 하나의 플랫폼에 릴리스하십시오. 팩은 유휴 슬롯에 설치되며, 탑재 상태에서 테스트 케이스를 통과한 후에만 활성화됩니다.
  7. 일주일 동안 문제가 없으면 다음 플랫폼에 배포하십시오.
미션 팩
미션 팩
각 팩이 포함하는 내용과 이를 실행하는 플랫폼을 보여 주는 미션 팩 라이브러리입니다. 되돌아갈 수 있도록 탑재 상태로 유지되는 이전 버전과, 모든 팩이 해당 하드웨어에서 통과해야 하는 테스트 케이스의 수를 확인하십시오.

이 레시피에는 명령이 없으며, 콘솔의 Nexus Edge 페이지에서 진행됩니다. 검증 기준은 팩이 활성화되기 전에 모두 통과해야 하는 탑재 테스트 케이스와 두 개의 서명입니다. 탑재 상태에서 테스트가 실패하면 플랫폼은 이전 팩을 유지하며, 실패 정보는 다음 통과 시 지상으로 전송됩니다. 검증되지 않은 하드웨어에 팩을 설치하려고 하면 PACK_NOT_CHECKED_FOR_HARDWARE 오류와 함께 거부됩니다.

Nexus Edge는 플랫폼별 또는 플릿별로 라이선스가 부여되는 애드온입니다. 플랫폼이 통신 범위를 벗어나 있는 동안에도 팩은 유효하게 유지됩니다. 업링크 대역폭이 좁으므로 이에 맞춰 크기를 계획하십시오. 당사의 1.5 릴리스는 412 MB였으며, 새 언어 모델을 포함한 팩은 9.8 GB였습니다.

9. 고객에게 에어갭 배포

목표는 네트워크가 없는 고객 사이트에 귀하의 플러그인이나 팩을 설치하는 것입니다. 구성 요소는 @adverant/nexus-sovereign에서 생성한 봉인된 번들, 귀하의 릴리스 서명 키, 그리고 고객의 자체 릴리스 채널입니다.

  1. 모든 게이트를 통과한 상태로, 네트워크에 연결된 고객의 경우와 똑같이 플러그인과 이미지를 빌드하십시오.
  2. airgap 프로필을 사용하여 이미지, 마이그레이션, 사전 서명된 스킬, 그리고 라이선스가 포함된 SBOM(소프트웨어 자재 명세서)을 담은 봉인된 번들을 만드십시오.
  3. Ed25519 릴리스 키로 서명하십시오.
  4. 깨끗한 머신에서 직접 검증하십시오.
  5. 번들은 매체로 전달하고, 공개 키와 번들의 SHA-256은 별도의 경로로 전달하십시오.
  6. 고객의 운영자는 귀하의 키로 번들을 검증한 다음, 자체 릴리스 채널을 통해 릴리스를 반입합니다.
nexus-airgap bundle
nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgap

nexus-airgap bundle은 번들 구성을 바탕으로 번들을 빌드합니다. 검증 기준은 고객 측의 nexus-airgap verify입니다. 이 명령은 모든 파일의 해시를 다시 계산하고, 매니페스트에 없는 파일은 거부하며, 신뢰할 수 있는 서명자를 요구하고, 네트워크 허용 목록이 비어 있지 않은 번들은 거부합니다. 변경된 파일은 BUNDLE_INTEGRITY_VIOLATION 오류로 실패합니다. 이를 우회하기 위해 엄격한 검사를 꺼서는 절대 안 됩니다.

에어갭 설치는 Enterprise 전용입니다. 번들의 어떤 요소도 설치 시 외부에서 무언가를 가져와서는 안 되며, 플러그인에 필요한 모델은 AI(인공지능) Provider Router를 통해 고객의 자체 모델 서버에서 제공됩니다.

10. Enterprise 전용 모듈

목표는 오픈 코어에 연결되는 비공개 라이선스 기능입니다. 예를 들어 Enterprise 고객에게만 판매되는 장기 보존 감사 추적이 있습니다. 구성 요소는 인터페이스 패키지 @adverant/nexus-spi이며, Community의 다른 요소는 사용하지 않습니다.

  1. 빌드된 인터페이스 패키지의 바이트 고정 사본을 SHA256SUMS 고정값과 함께 로컬 file: 패키지로 리포지토리에 보관하십시오.
  2. 이를 기반으로, 제공할 기능 그룹과 함께 RouteModule(콘솔 화면의 경우 ScreenModule)을 작성하십시오.
  3. 모든 라우트를 ctx.requireScope 뒤에서 실행하고, 응답하기 전에 모듈 자체의 권한 부여를 확인하십시오.
  4. 조직에 권한이 없으면 LICENCE_LOCKED로 거부하고, 기능의 데이터가 아닌 티저만 표시하십시오.
  5. 리포지토리가 라이선스 경계를 지키도록 한 다음, 각 에디션의 구성 트리를 빌드하십시오.
npm ci
npm test
npm run build

검증 기준은 라이선스 경계 규칙입니다. 인터페이스 패키지를 제외한 Community 범위에서의 가져오기 금지, 리포지토리 외부로의 상대 경로 가져오기 금지, 그리고 리포지토리 외부의 file:, link: 또는 workspace: 종속성 금지입니다. 그런 다음 위의 세 명령은 작업 트리뿐만 아니라 각 에디션의 구성 트리에서도 통과해야 합니다. 모듈 골격은 2.25장 에디션별 빌드에 있습니다.

모듈은 라이선스에 해당 기능 그룹이 포함된 설치 환경에서 시작 시 Community 서비스에 로드됩니다. 그 권한이 없으면 거부되므로, 동일한 빌드를 모든 곳에 배포해도 라이선스가 없는 곳에서는 아무 작업도 하지 않습니다.

11. 오픈 코어 포크 또는 확장

목표는 Community 자체에 대한 변경이며, 이를 포크에 유지하거나 기여할 수 있습니다. 구성 요소는 Apache License, Version 2.0에 따른 Community 소스입니다.

  1. 리포지토리를 포크하고 main에서 브랜치를 만드십시오.
  2. 원하는 것을 플러그인이나 스킬로 구현할 수 있다면 그쪽을 우선하십시오. 코어를 변경하면 모든 릴리스마다 귀하가 이를 유지 관리해야 합니다.
  3. 변경 사항이 없으면 실패하는 테스트와 함께 변경하십시오.
  4. 무엇이든 제안하기 전에 프로젝트에서 실행하는 검사를 실행하십시오.
  5. NOTICE 파일을 유지하고, 작업의 출처를 밝히는 것 이상으로 Adverant의 이름이나 상표를 사용하지 마십시오.
git checkout -b feature/your-change
npm test
npm run lint
npm run typecheck

검증 기준은 이 세 가지 검사의 통과와, 각 새 테스트가 변경 전에는 실패했다는 증거입니다. 포크에서도 오픈 코어의 한 가지 속성을 유지하십시오. Community는 키와 네트워크 없이 로컬 모델에서 에이전트를 처음부터 끝까지 실행합니다. 이를 깨뜨리는 변경은 Community를 단독으로 사용할 수 있게 하는 요소를 깨뜨립니다.

이는 Community 전용입니다. 비공개로 유지해야 하는 것은 대신 Enterprise 모듈(시나리오 10)에 속하므로, 라이선스 경계는 누구나 지적할 수 있는 곳에 유지됩니다.

12. Team 에디션 클라우드 앱

목표는 Team 고객이 설치할 수 있는 앱입니다. Team은 Adverant 클라우드에서만 실행되므로 앱은 카탈로그를 통해서만 고객에게 전달됩니다. 구성 요소는 플러그인과 퍼블리셔 클러스터, 즉 샘플 데이터가 있는 Adverant 클라우드상의 귀하 전용 가상 클러스터입니다.

  1. 샘플 데이터만 사용하여 퍼블리셔 클러스터에서 빌드하고 테스트하십시오.
  2. 앱에 필요한 모든 것을 매니페스트에 선언하되, 그 이상은 선언하지 마십시오.
  3. Adverant의 검토와 카탈로그 등재를 위해 서명된 상태로 릴리스하십시오.
  4. 각 고객은 선언된 각 범위를 단위별로 허가하면서 앱을 설치합니다.

검증은 두 부분으로 이루어집니다. 서명되고 검토된 릴리스를 통해 카탈로그에 등재됩니다. 그런 다음 고객의 허가가 해당 사이트에서 앱이 접근할 수 있는 범위를 결정하며, 선언되지 않은 호출은 CONNECTION_SCOPE_EXCEEDED로 거부됩니다. 누락된 범위는 고객이 검토하는 새 릴리스에서만 추가할 수 있습니다.

서드 파티 플러그인 설치
서드 파티 플러그인 설치
관리자가 타사 플러그인을 설치하면서 선언된 각 범위를 단위별로 허가하고 하나는 제외하는 모습입니다. 플레이트에는 플러그인이 선언하지 않은 호출이 거부되는 모습이 표시됩니다.

퍼블리셔 클러스터에는 어떤 고객으로의 경로도 없으며, 그곳에서 고객의 데이터를 요청하면 TENANT_BOUNDARY로 거부됩니다. 고객은 테스트 결과를 귀하와 공유할 수 있지만, 데이터는 절대 공유할 수 없습니다. Team에는 워크플로 운영 기능이 포함되어 있으므로, 앱에 워크플로가 포함되어 있다면 Team 고객이 직접 환경 간에 워크플로를 승격할 수 있습니다.

13. 기존 내부 앱을 플러그인으로 래핑

목표는 귀사에서 이미 운영 중인 앱을 Nexus로 가져와 로그인, 격리 및 거버넌스를 상속하도록 하는 것입니다. 구성 요소는 초안 작성을 위한 /plugin-create 스킬과, 이를 완성하기 위한 SDK의 매니페스트 도구 및 게이트입니다.

  1. 리포지토리를 대상으로 /plugin-create을 실행하십시오. 코드를 분석하고 래핑 전략을 선택한 다음 백엔드, 마이그레이션, 사용자 인터페이스(UI), 매니페스트 및 테스트를 생성합니다.
  2. 매니페스트를 v2 계약으로 올리십시오. migrate은 세 개의 규칙 문장을 추가하고 domain를 domains[]로 옮기며, 엔트리포인트를 임의로 만들어 내는 것은 거부합니다.
  3. 래퍼가 헤더에서 읽는 테넌트 값은 모두 SDK의 범위 가드로 대체하십시오.
  4. 테넌트가 앞에 오는 기본 키와 함께 모든 테이블에 organization_id, owner_user_id, business_unit_id를 추가하십시오.
  5. 모든 라우트를 해당 권한과 함께 선언하고, 거부 원장을 설치하십시오.
  6. 모든 게이트가 통과할 때까지 실행하십시오.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --write
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test

검증 기준은 nexus-gates이 0으로 종료되고 scope-adherence, one-fence, migrations-are-scoped, crud-adherence, api-contract가 모두 통과하는 것입니다. 첫 실행에서는 대부분이 실패할 것으로 예상하십시오. 당사의 경우 초안이 브라우저가 설정할 수 있는 헤더를 신뢰했기 때문에 모든 라우트가 범위 미지정으로 보고되었습니다. 게이트에는 의도적으로 자동 수정 스위치가 없습니다.

래핑된 앱은 모든 에디션에서 작동합니다. 배포는 설치 환경의 릴리스 채널을 통해서만 이루어지므로, 초안이 작성한 배포 파일은 무시하십시오. 시간이 가장 많이 드는 부분은 격리 작업입니다. 실제 앱의 경우 몇 시간이 아니라 며칠을 계획하십시오.