AnmeldenBriefing buchen

Kapitel 2.24

Eine maßgeschneiderte Branchenlösung durchgehend erstellen

Ein ausgearbeiteter Aufbau des Domain Packs für die Kühlkette, vom ersten Briefing bis zum produktiven Release für jede Einheit, mit seinem Wissensmodell, Linsen, einem Skill, einem Full-Service-Plugin und Beispieldaten. Anschließend, wie man ein bereits bestehendes Pack erweitert und wie man einem bereits ausgelieferten Pack eine Linse hinzufügt.

Diese Seite wurde mithilfe von KI aus dem englischen Original übersetzt. Bei Unklarheiten gilt die englische Seite als Referenz. Diese Seite auf Englisch lesen

19 Minuten Lesezeit

Ich bin Mateo Ruiz, Entwickler bei Corrán Orbital. Der größte Teil meiner Woche fließt in unsere eigene Nutzlastsoftware, aber in diesem Kapitel geht es um einen Auftrag, den wir für einen Kunden ausgeführt haben. Larkfield & Vane versichert Fracht, und ein wachsender Anteil davon wird in Kühlcontainern transportiert. Wenn ein Reefer am Kai den Landstrom verliert, steigt die Temperatur, die Fracht verdirbt und Wochen später folgt eine Schadensforderung. Larkfield wollte, dass ihre Mitarbeiter diese Kette in Nexus als ein Ganzes sehen, vom Stromausfall bis zur Schadensforderung, wobei jede Rolle nur ihren eigenen Teil sieht. Daraus wurde das Paket „Cold chain“ (Kühlkette).

Was folgt, ist der Aufbau in der Reihenfolge, in der wir ihn durchgeführt haben, mit den Bildschirmen, den Dateien und den Befehlen. Ich habe die Fehler dringelassen, denn zwei der Ablehnungen, auf die wir gestoßen sind, haben uns mehr über die Plattform gelehrt als der fehlerfreie Ablauf. Das Referenzmaterial befindet sich in den Kapiteln vor diesem, und ich verweise auf sie, anstatt sie zu wiederholen. Am meisten gestützt habe ich mich auf Kapitel 2.18, Das Erweiterungsmodell, und Kapitel 2.23, Domänenpakete, während Kapitel 2.21, Das Plugin-SDK, für das Software Development Kit selbst daneben geöffnet war.

Ein von links nach rechts verlaufender Pfad aus acht Kästchen: „Brief“, „Golden path“, „Knowledge model“, „Lenses“, „Skill and plugin“, „Sample data and preview“, „Release review“, „Promotion“. Unter dem letzten Kästchen zeigt eine zweite Reihe aus vier kleineren, durch Pfeile verbundenen Kästchen die Schritte der Hochstufung (Promotion): „Dev space“, „Staging“, „Pilot unit (Rotterdam)“, „All units“, wobei jeder Pfeil mit einem Vorhängeschloss-Symbol und der Beschriftung „gate“ versehen ist. Ein gestrichelter Pfeil direkt von „Dev space“ zu „All units“ ist durchgestrichen und mit GATE_CANNOT_BE_SKIPPED beschriftet.
Der Aufbau von Cold chain, vom Briefing bis zu jeder Einheit.

Das Briefing und wer was tut

Larkfield gab mir für die Dauer des Projekts einen Entwicklerplatz in ihrer Organisation. Das ist wichtig, denn ein privates Paket für einen einzelnen Kunden wird innerhalb der Installation dieses Kunden erstellt, in dessen Dev Spaces und Daten-Branches, unter den Genehmigungen seiner Mitarbeiter. Ein Paket, das für viele Kunden gedacht ist, wird anders erstellt, auf einem Publisher-Cluster nur mit Beispieldaten, und Kapitel 2.25, Erstellen für jede Edition, behandelt diesen Fall.

Das Briefing passte auf eine Seite:

  • Kühlcontainer am Kai und auf Schiffen: ihre Stromversorgung, ihre Temperaturabweichungen und die daraus folgenden Schadensforderungen.
  • Zwei Rollen für den Anfang: ein Reefer-Techniker am Kai und ein Kühlketten-Controller im Büro.
  • Ein Pilotprojekt, das zuerst in der Einheit Rotterdam läuft und danach nach Felixstowe zieht.
  • Nachweise für drei Regelwerke: das ATP-Übereinkommen für leicht verderbliche Lebensmittel, die gute Vertriebspraxis der EU für Arzneimittel und Aufzeichnungen zur Lebensmittelsicherheit gemäß HACCP (Hazard Analysis and Critical Control Points). Schadensforderungen gemäß den Haag-Visby-Regeln verwenden dieselben Abweichungsaufzeichnungen, weshalb wir sie für die Zeit nach dem Pilotprojekt vorgemerkt haben.

Domänenpakete sind eine Enterprise-Funktion. Larkfield nutzt Enterprise, sodass mir der Pfad für Domänenpakete offenstand. In der Community-Edition wird der Golden Path für ein Paket überhaupt nicht angeboten.

Start über den Golden Path

Alles beginnt auf der Seite „Start something new“ (Etwas Neues beginnen). Sie bietet sechs Golden Paths: Plugin, Domänenpaket, Lens, Plattform, Skill und Workflow. Jeder erstellt ein Repository aus einer versionierten Vorlage, ein Manifest, das deklariert, was das Element benötigt, Tests, einen Dev Space und Daten-Branches. Dieselben Pfade funktionieren in der Konsole, auf der Befehlszeile und aus Ihrer IDE (Integrated Development Environment) heraus, wo das Workbench-Tool nexus.create dieselbe Aufgabe mit einem Plan erledigt, den Sie zuerst bestätigen.

Etwas Neues starten
Etwas Neues starten
Die sechs Golden Paths, jeweils mit dem, was sie erstellen, ihrem nexus create-Befehl und ihrer fixierten Vorlage. Beachten Sie das Hinweisschild am Fuß: Das Manifest wird durchgesetzt, es ist nicht nur beratend, und ein Release, das mehr anfordert, wird zurückgehalten, bis zwei Personen es überprüft haben.

Wir haben von dieser Seite aus den Domänenpaket-Pfad gewählt, das Paket cold-chain und seine erste Einheit Rotterdam genannt. Das Ergebnis nennt die fixierte Vorlage domain-pack@1.6.0 und listet auf, was erstellt wurde: das Repository, ein Manifest, das vier Scopes, zwei Speicher und keine ausgehenden Adressen deklariert, 66 Tests aus der Vorlage, einen Dev Space in Rotterdam, drei synthetische Daten-Branches und einen Entwurfseintrag in Larkfields eigenem Katalog, den nur ich sehen konnte. Die Vorlagenversion ist fixiert, und ein späteres Upgrade kommt wie jede andere als überprüfte Änderung an, sodass sich das Paket von niemandem unter der Hand verändert, nur weil sich eine Vorlage geändert hat. Ich habe für unser erstes Paket trotzdem den Konsolen-Assistenten verwendet, weil er den Plan anzeigt, bevor er etwas erstellt.

Schritt 1: Festlegen, wofür das Pack gedacht ist

Der Assistent „New domain pack“ (Neues Domänenpaket) hat drei Schritte: Informationen dazu, Wissensmodell sowie Überprüfen und Erstellen. Schritt 1 fragt die wenigen Dinge ab, die alles Nachfolgende formen.

Feld Was wir eingegeben haben Hinweis
Name Kühlkette Verwendet für das Repository und den Katalog
Wofür es dient Kühlcontainer am Kai und auf Schiffen: Stromversorgung, Temperaturabweichungen und die daraus folgenden Schadensforderungen
Branche Logistik und Schifffahrt Baut auf dem Paket „Logistics and maritime“ (Logistik und Seefahrt) auf
Eigentümer (Owner) Die erstellende Person Im Assistenten gesperrt
Einheiten Rotterdam (Pilot) Felixstowe nach dem Pilotprojekt
Vorlage domain-pack@1.6.0 Gesperrt; Upgrades kommen als überprüfte Änderungen
Abgebildete Regeln ATP-Übereinkommen, gute Vertriebspraxis der EU, Aufzeichnungen zur Lebensmittelsicherheit Jede Regel wird zu einer Seite in der Nachweiskarte des Pakets

Der Assistent im Dock schlug die letzte Zeile vor, einschließlich des Punkts, dass Frachtschadensforderungen dieselben Abweichungsaufzeichnungen wiederverwenden. Ein Hinweisschild am Fuß der Seite besagt, dass noch nichts erstellt wurde. Das Repository, der Dev Space und die Daten-Branches werden erst erstellt, wenn Sie in Schritt 3 auf „Create“ (Erstellen) drücken, nachdem Sie den Plan gesehen haben. Sie können einen Entwurf speichern und später zurückkehren.

Schritt 2: Das Wissensmodell

Das Wissensmodell ist die Menge der Arten von Dingen, die das Paket kennt, und wie sie miteinander verknüpft sind. Cold chain begann mit dem Logistik-Basismodell logistics-base 4.2, das aus dem SDK importiert wurde und uns fünf Basisarten gab, auf denen wir aufbauen konnten (Vessel, Port, Container, Carrier und Shipment). Basisarten sind im Assistenten schreibgeschützt. Wenn sich eine ändern muss, ändert sie sich in dem Paket, dem sie gehört.

Wir haben fünf eigene Arten hinzugefügt:

Art Was es ist Eigenschaften
Kühlaggregat Ein Kühlcontainer 9
Schiffsanlauf Ein Schiff an einem Liegeplatz 6
Temperaturabweichung Eine Temperatur außerhalb ihrer Grenzwerte 8
Stromversorgung Ein Land- oder Schiffsstromanschluss 4
Beanspruchen Gefordertes Geld für verdorbene Fracht 7
Neues Domänenpaket: Wissensmodell
Neues Domänenpaket: Wissensmodell
Der Wissensgraph mit fünf Basisarten und fünf neuen Arten. Betrachten Sie die Eigenschaften von „Excursion“ auf der rechten Seite: Jede Eigenschaft erhält bei ihrer Erstellung ihre Klasse, und das Hinweisschild besagt, dass Schadensbeträge kommerziell sind, sodass Techniker-Lenses sie nicht anzeigen können.

Jede Eigenschaft wird beim Erstellen klassifiziert. „Reported by“ (Gemeldet von) bei einer Excursion ist personenbezogen. „Cargo value at risk“ (Gefährdeter Frachtwert) sowie Betrag und Begleichung einer Schadensforderung sind kommerziell. Das fühlte sich am ersten Tag wie Papierkram an und hat uns später zweimal gerettet, denn die Klassen entscheiden darüber, was eine Lens anzeigen darf, was eine maskierte Kopie ersetzt und was eine Protokollzeile verbirgt.

Zwei unserer Relationen reichen in das Basismodell hinein: Eine Reefer unit ist an eine Power supply angeschlossen, und ein Claim bezieht sich auf ein Shipment. Das Basismodell selbst wird nicht geändert. Eine Eigenschaft, die Sie zurückziehen, bleibt in Version 1.0 des Modells erhalten und fällt erst in einer späteren Version weg, sodass nichts, was für alte Datensätze galt, unlesbar wird.

Schritt 3: Überprüfen und erstellen

Schritt 3 ist der Plan. Er listet auf, was erstellt wird, welche Scopes das Manifest deklarieren wird, die Daten-Branches und den Dev Space. Sie bestätigen den Plan mit Ihrem Passkey, und der Plan erhält einen Fingerabdruck. Die Erstellung folgt dann genau diesem Plan, Schritt für Schritt, und Sie können bei jedem Schritt anhalten und behalten, was bereits erstellt wurde.

Der Plan für Cold chain deklarierte vier Scopes:

Umfang Warum das Paket ihn benötigt
Kühlcontainer-Telemetrie lesen Strom- und Temperaturmesswerte
Temperaturabweichungen schreiben Zeichnet eine Abweichung auf, wenn Grenzwerte überschritten werden
Sendungen lesen Verknüpft eine Schadensforderung mit ihrer Sendung
Schadensnotizen entwerfen Nur Entwürfe; eine Person sendet

Seine Speicher waren der Graph und die Datensätze. Es hatte keine ausgehenden Adressen und das Standard-Sandbox-Profil. Der Dev Space wurde mit 4 Kernen, 16 GiB Arbeitsspeicher und 50 GiB Speicherplatz, einem bis auf die Deklarationen im Manifest geschlossenen Netzwerk, ausschließlich signierten Images und einem Ablauf nach 7 inaktiven Tagen bereitgestellt. Wenn er endet, bleibt seine Definition im Repository, sodass Sie ihn von dort aus neu erstellen können.

Die drei Daten-Branches stammten aus dem synthetischen Generator. Es wurden keine Kundendaten kopiert. Eine maskierte Kopie von Rotterdam erfordert die Zustimmung der Dateneigentümerin – bei Larkfield ist das Priya Natarajan –, und Sie fordern diese separat an.

Das Pack-Manifest

Das Repository enthält das Manifest des Pakets, pack.json. Es nennt das Paket, seine Version, das Paket, von dem es erbt (falls vorhanden), seine Cluster und seine Wörter. Ein Cluster ist entweder eine Lens, also das, was eine Rolle innerhalb des Pakets sieht, oder geteilt (shared), was über jede Lens hinweg läuft. Hier ist das Kernstück unseres Manifests:

{
  "id": "cold-chain",
  "name": "Cold chain",
  "version": "0.4.0",
  "clusters": [
    {
      "id": "CC01",
      "kind": "lens",
      "name": "Reefer technician",
      "seats": "Technicians on the quay",
      "purpose": "Which reefers have lost power or warmed up, and what to do next.",
      "lexicon": ["cold"],
      "menu": [],
      "screens": []
    },
    {
      "id": "CC02",
      "kind": "lens",
      "name": "Cold-chain controller",
      "seats": "Controllers in the operations office",
      "purpose": "Every excursion from first reading to closed claim, with its evidence.",
      "lexicon": ["cold"],
      "menu": [],
      "screens": []
    }
  ],
  "lexicon": {
    "core": [],
    "cold": [
      ["excursion", "a time when the temperature left its limits", ""],
      ["set point", "the temperature a reefer is told to hold", ""],
      ["shore power", "electricity from the quay rather than the ship", ""]
    ]
  }
}

Das Lexikon enthält die eigenen Wörter des Pakets mit einer einfachen Erklärung für jedes Wort, kurz genug, um auf einem Telefon gelesen zu werden.

Neben pack.json deklariert das Manifest auch, worauf das Paket zugreifen darf: seine Scopes, Speicher, ausgehenden Adressen und sein Sandbox-Profil. Nexus gewährt genau das und nicht mehr. Jeder Tool-Aufruf wird gegen die deklarierten Scopes geprüft, und eine externe Adresse wird blockiert, sofern sie nicht aufgeführt ist. Sie können die Deklaration und die Änderung gegenüber dem letzten Release auf der Seite „Manifest and permissions“ (Manifest und Berechtigungen) des Pakets lesen.

Linsen: Was jede Rolle sieht

Eine Lens kann das, was ihre Basis anzeigt, immer nur einschränken, und diese eine Regel hat unser Design stärker geprägt als jede andere. Eine Lens zeigt einen Teil dessen an, was ihre Basis-Lens anzeigt, und Berechtigungen stammen weiterhin aus Rollen: Eine Lens entscheidet, was eine Rolle im Paket sieht, nicht, was sie tun darf.

Die Lens „Reefer technician“ (Reefer-Techniker) schränkt „Operations controller“ (Betriebs-Controller) ein, die Basis-Lens, die Larkfield bereits für Logistikarbeiten einsetzt. Im Lens Builder kreuzen Sie die Karten, Felder und Aktionen an, die die Lens anzeigt. Elemente, die die Basis nicht anzeigt, sind gesperrt.

Komponente Reefer technician zeigt an Weggelassen
Karten Kühlcontainer am Kai, offene Abweichungen, Stromanschlüsse, heutige Schiffsanläufe Alles rund um Schadensforderungen
Felder Stromstatus, Sollwert, letzter Messwert, höchste Temperatur Schadensbetrag (nicht in der Basis-Lens), personenbezogene Felder (standardmäßig aus)
Aktionen Abweichungsursache aufzeichnen, Stromprüfung anfordern Sollwert ändern und Abweichung schließen (nur Controller), Schadensnotiz entwerfen
Perspektiven-Editor
Perspektiven-Editor
Der Lens Builder für „Reefer technician“, abgehakt gegenüber seiner Basis-Lens. Das Hinweisschild unten links ist die Ablehnung, die Sie erhalten, wenn Sie den Schadensbetrag ankreuzen: Die Basis-Lens zeigt ihn nicht an, also kann diese Lens es auch nicht.

Ich habe trotzdem versucht, den Schadensbetrag zur Techniker-Lens hinzuzufügen, weil ein Techniker darum gebeten hatte. Der Builder lehnte dies mit LENS_CANNOT_WIDEN ab und speicherte nichts. Es gibt keinen Workaround innerhalb der Lens: Der Weg nach vorn ist eine Lens auf einer breiteren Basis, eine andere Anfrage, über die der Organisationsadministrator entscheidet. Wir haben es weggelassen.

Etwas in einer Lens auszublenden, entfernt es nicht aus Nexus. Es bedeutet, dass diese Rolle es nicht sieht. Der Builder zeigt an, wie viele Personen eine Lens im Pilotprojekt erreichen wird (in unserem Fall 29), und führt ein Protokoll über jedes Hinzufügen, Ändern und Zurückziehen. Eine Lens wird einmal für die Organisation definiert und pro Einheit einer Plattformrolle gewährt, sodass dieselbe Lens „Reefer technician“ diesen Monat den Technikern in Rotterdam und nächsten Monat denen in Felixstowe gegeben werden kann.

Ein Skill zum Entwerfen von Schadensnotizen

Controller wollten einen ersten Entwurf der Notiz, die nach einer Abweichung an einen Frachteigentümer geht. Das ist Spracharbeit, läuft also über ein Modell, und die Frage war, wo man es unterbringt.

Es gibt zwei Arten von Skills in Nexus, und der Unterschied ist hier wichtig. Ein Manifest-Skill ist eine typisierte Zeile in der skills[] eines Plugins, die von der Plattform disponiert wird. Ein Skills-Engine-Skill ist ein SKILL.md-Paket in der Skill-Bibliothek der Organisation, das Agenten, KI-Schaltflächen (künstliche Intelligenz), Workflows und Entwickler-Tools alle auf dieselbe Weise ausführen. Kapitel 2.20, Skills, behandelt beide.

Die Vertrauensstufe unseres Plugins ist community, und ein Community-Plugin darf nur Manifest-Skills deklarieren, die kein Modell erreichen (host_callback und plugin_queue). Die beiden Stufen, die den AI Provider Router erreichen, tool_using und llm_only, benötigen die Vertrauensstufe core oder verified. Daher wurde das Entwerfen von Schadensnotizen zu einem Skills-Engine-Skill, und der Router wählt das Modell aus Larkfields eigenem Pool aus:

---
name: draft-claim-note
description: Draft a note to a cargo owner about one reefer excursion, from the excursion record and its readings. Drafts only; a person reviews and sends.
allowed-tools: Read, Grep
triggers:
  - /draft-claim-note
capabilities:
  - name: draft_note
    description: Write a first draft for one excursion
version: 1.0.0
---

# Draft a claim note

Use this when a controller asks for a note about one excursion.

## Steps

1. Read the excursion: unit, start, length, highest temperature and cause.
2. Read the shipment it belongs to, for the cargo owner's name.
3. Write four short paragraphs: what happened, when, what the readings show, what happens next.
4. Never state a claim amount. Never send anything.

Das Paket liegt in skills/draft-claim-note/ im Repository, wobei der Ordnername dem Namen des Skills entspricht. Wir haben es über das Terminal validiert und hochgeladen:

npm run skill:validate skills/draft-claim-note
npm run skill:upload skills/draft-claim-note --dry-run
npm run skill:upload skills/draft-claim-note

Das zweimalige Hochladen desselben Inhalts gibt die bestehende Version zurück statt einer neuen (CONTENT_HASH_ALREADY_PUBLISHED), sodass ein erneutes Ausführen des Uploads sicher ist. Bevor eine Version veröffentlicht wird, führt die Skills Engine ihre Testfälle, einen Testlauf im Schattenbetrieb mit vergangener Arbeit und eine Blindprüfung durch ein Modell eines anderen Unternehmens durch, samt Zeit- und Kostenangabe für jeden Durchlauf.

Das Full-Service-Plugin

Das Paket benötigte außerdem Code, der ständig läuft: einen Reader für den Reefer-Telemetrie-Feed und einen Writer, der einen Abweichungsdatensatz öffnet, wenn ein Messwert seine Grenzwerte überschreitet. Solcher Code gehört in ein Full-Service-Plugin, und wir haben das Grundgerüst dafür mit dem eigenen Befehl des SDKs erstellt, der den gesamten Referenzbaum mit dem eingesetzten Namen schreibt:

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold cold-chain --tier full-service
cd cold-chain
npm install
npm ci
npm run typecheck && npm test && npm run build
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

Das SDK wird von https://registry.adverant.ai/npm/ mit dem Pull-Token von der Seite „Pull tokens and install commands“ (Pull-Tokens und Installationsbefehle) Ihres Adverant-Kontos installiert. Committen Sie die package-lock.json, die bei der ersten Installation geschrieben wird; der Image-Build führt npm ci aus und verweigert den Dienst ohne sie.

Hier ist der Teil unserer nexus.manifest.json, der von der Vorlage abweicht. Es ist nicht die gesamte Datei: Die Blöcke description, author, license, runtime, backend und frontend des Grundgerüsts bleiben unverändert, und der Validator lehnt ein Full-Service-Manifest ohne sie ab. Die drei architecture-Sätze sind das Gesetz, das jedes Plugin wiederholt, und der Validator prüft den Wortlaut. UNO im ersten Satz ist die Workflow-Engine:

{
  "manifestVersion": "2",
  "name": "cold-chain",
  "displayName": "Cold chain",
  "version": "0.4.0",
  "tier": "full-service",
  "trust": "community",
  "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": {
    "version": "1",
    "basePath": "/",
    "endpoints": [
      { "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
      { "method": "GET", "path": "/api/excursions", "summary": "List the unit's excursions", "auth": "scope", "right": "excursion.read", "needsUnit": true },
      { "method": "POST", "path": "/api/excursions", "summary": "Record an excursion", "auth": "scope", "right": "excursion.create", "needsUnit": true },
      { "method": "POST", "path": "/internal/skills/excursion_open", "summary": "host_callback receiver the platform POSTs to", "auth": "internal" }
    ]
  },
  "rights": {
    "excursion.read": { "summary": "Read the unit's excursions.", "roles": ["owner", "admin", "member", "viewer"] },
    "excursion.create": { "summary": "Record an excursion.", "roles": ["owner", "admin", "member"] }
  },
  "skills": [
    {
      "id": "excursion_open",
      "displayName": "Open an excursion",
      "description": "Open an excursion record when a reading breaks its set point limits. No model; runs in the plugin's own backend.",
      "tier": "host_callback",
      "classification": "tenant",
      "dataResidency": "eu",
      "inputSchema": { "type": "object", "properties": { "readingId": { "type": "string" } }, "required": ["readingId"] },
      "outputSchema": { "type": "object", "properties": { "opened": { "type": "boolean" } }, "required": ["opened"] },
      "hostCallback": {
        "service": "cold-chain",
        "port": 8080,
        "path": "/internal/skills/excursion_open",
        "maxRequestBytes": 65536,
        "maxResponseBytes": 16384,
        "tenantHeader": "X-Organization-ID"
      },
      "timeoutMs": 10000
    }
  ],
  "changePolicy": {
    "enabled": true,
    "classes": ["website", "bff", "migration"],
    "approvals": { "website": 1, "bff": 1, "migration": 2 }
  }
}

excursion_open ist ein Manifest-Skill mit der Stufe host_callback: Die Plattform sendet die Eingabe per POST an unseren eigenen Service innerhalb unseres Namespaces und niemals an einen von uns genannten Host. Die Empfängerroute ist als auth: internal deklariert und mit serviceMiddleware des SDKs geschützt, der Express-Form des Guards, die jedes Call-Token ablehnt, das für ein anderes Plugin, eine andere Organisation, einen anderen Skill oder eine andere Route geprägt wurde. Sein classification ist tenant, was die Obergrenze für ein Community-Plugin darstellt. Kapitel 2.27, Build-Szenarien, geht einen host_callback-Skill separat durch.

Zwei Gewohnheiten aus dieser Phase sind es wert, übernommen zu werden. Jede Tabelle enthält ab der ersten Migration organization_id, owner_user_id und business_unit_id, da das spätere Hinzufügen einer Achse eine Migration über Live-Zeilen hinweg bedeutet. Und wir haben vor jedem Push lokal nexus-gates ausgeführt, da es derselbe Befehl ist, den die Pipeline ausführt; ein Durchlauf, der nichts geprüft hat, beendet sich mit Code 2 und meldet dies. Kapitel 2.19, Die Regeln, die jede Erweiterung erbt, listet die Gates auf.

Beispieldaten zum Testen

Die Seite „Sample data for testing“ (Beispieldaten zum Testen) bietet drei Arten von Branches:

Art Inhalt Wer zustimmt
Synthetisch Daten, die aus von Ihnen festgelegten Anzahlen und Formen generiert werden; nichts stammt aus einer echten Einheit Niemand; sie gehören Ihnen
Maskierte Kopie Eine Kopie einer Einheit, bei der personenbezogene, sensible und kommerzielle Felder ersetzt wurden Der Dateneigentümer (Priya Natarajan für Rotterdam)
Nur Schema Die Form der Speicher, ohne Zeilen Niemand; für Migrationen

Wir haben eine arbeitsreiche Woche generiert: etwa 7 Abweichungen pro 100 Reefer, was einem geschäftigen August in Rotterdam entspricht. Die Sonderfälle waren wichtiger als das Volumen. Wir forderten Stromverlust beim Löschen der Ladung, eine offen gelassene Tür, eine Sensorlücke und zwei Schadensforderungen für eine Abweichung an. Die Seite kann Sonderfälle anhand der Abweichungsursachen im Wissensmodell vorschlagen, niemals anhand echter Datensätze.

Jeder Satz von Anzahlen und Formen wird als Seed gespeichert, wie etwa cold-chain-busy-01, zusammen mit seinem Fingerabdruck. Derselbe Seed liefert dieselben Daten, sodass jeder Testlauf auf jedem Branch dieselbe Woche sieht. Das hat unsere 66 Tests wiederholbar gemacht.

Ein Branch besteht standardmäßig 72 Stunden und höchstens 14 Tage. Ich bat darum, unseren arbeitsreichen Branch während einer langen Überprüfung für 30 Tage zu behalten, und die Seite lehnte dies mit BRANCH_LIFE_EXCEEDED ab. Die Lösung ist diejenige, die das Hinweisschild vorschlägt: Behalten Sie den Seed und erstellen Sie daraus einen frischen Branch, wenn Sie einen benötigen. Eine maskierte Kopie unterliegt denselben Begrenzungen, und ihre Anforderung enthält eine Begründung sowie eine Dauer von bis zu 14 Tagen.

Vorschau einer Linse aus Sicht einer Person

Bevor irgendjemand in Rotterdam Cold chain sah, betrachteten wir es so, wie sie es tun würden. „Preview a lens as a person“ (Vorschau einer Lens als Person) stellt das Paket auf einem Daten-Branch innerhalb eines gestrichelten Vorschaurahmens genauso dar, wie eine ausgewählte Rolle es sieht.

Vorschau einer Lens als Person
Vorschau einer Linse aus Sicht einer Person
Cold chain, wie es ein Rotterdamer Reefer-Techniker sieht, auf einem synthetischen Branch. Beachten Sie die Spalte für Schadensforderungen, die bei jeder offenen Abweichung mit „hidden by lens“ (durch Lens ausgeblendet) markiert ist, und das Seitenfenster, das angibt, was diese Lens ausblendet und warum.

Drei Regeln machen die freie Nutzung von Vorschauen sicher. Eine Vorschau verwendet einen Daten-Branch, niemals die Live-Einheit. Ihre eigenen Berechtigungen fließen nicht mit ein, sodass Sie sehen, was die Rolle sieht, und nicht, was Sie sehen können. Und sie endet nach 30 Minuten. Eine Vorschau auf eine Live-Einheit zu richten, wird mit CONNECTION_SCOPE_EXCEEDED abgelehnt; wenn Sie echte Formen benötigen, bitten Sie den Dateneigentümer um eine maskierte Kopie und führen Sie die Vorschau darauf aus.

In der Vorschau haben wir einen echten Fehler entdeckt. Das Temperaturdiagramm in der Technikeransicht zeigte den Sollwert, und Sollwertbearbeitungen waren nur für Controller gedacht. Das Diagramm war in Ordnung; die Bearbeitungsschaltfläche darunter war es nicht. Version 0.3.2 blendete Sollwertbearbeitungen für Techniker aus, und die Vorschau war der Ort, an dem wir es gefunden haben.

Ändern des Wissensmodells nach der Auslieferung

Bis zur Version 0.4.0 benötigten wir eine Art „Inspection“ (Inspektion) für Vorabreiseinspektionen, und die Relation „Excursion caused Claim“ (Abweichung verursachte Schadensforderung) las sich besser als „Excursion led to Claim“ (Abweichung führte zu Schadensforderung). Das Modell von 1.3 auf 1.4 zu heben, ist eine Wissensmodelländerung, und die Seite „Knowledge model changes“ (Wissensmodelländerungen) zeigt deren Diff, was sie berühren würde und wo sie sich auf ihrem Weg befindet.

Die Änderung durchläuft das System als Graph-Änderungsanforderung. Ihr Testlauf zählt auf der maskierten Kopie von Rotterdam als reine Anzahl, was sie berühren würde: bei uns wurden 1.284 Verknüpfungen umbenannt und nichts entfernt. Zwei Prüfer genehmigen sie, und die Pipeline wendet sie auf das Staging und dann auf das Pilotprojekt an. Niemand schreibt von Hand in den geteilten Graphen; ein Versuch wird abgelehnt und aufgezeichnet. Drei gespeicherte Fragen verwendeten das Wort „caused“, und die Änderung enthielt für jede davon eine automatische Umschreibung, die auf der Seite aufgelistet wurde. Lens-Filter änderten sich nicht, da beide Lenses weiterhin nur einschränkten.

In die Produktion überführen

Jedes Release bewegt sich auf einem einzigen Pfad: Dev Space, Staging, eine Piloteinheit, dann alle Einheiten. Jeder Schritt hat Gates, und nichts überspringt eines.

Nach Freigaben
Staging Alle Tests bestanden; Qualitätsprüfungen; Manifest unverändert oder die Erweiterung akzeptiert; signiertes Image
Pilot (Rotterdam) Testlauf der Modelländerung auf der maskierten Kopie ohne Fehler; Richtlinienprüfung der Lens- und Scope-Regeln; zwei Prüfer, die nicht der Autor sind, einer davon der Dateneigentümer
Alle Einheiten 14 Tage im Pilotprojekt; Fehler unter 1 zu 1.000, gezählt im Pilotprojekt; jeder Einheitenadministrator stimmt für seine Einheit zu; zwei Prüfer, die nicht der Autor sind
Umgebungen und Hochstufung
Umgebungen und Hochstufung
Cold chain 0.3.2 wartet am Pilot-Gate auf seinen zweiten Prüfer. Das Hinweisschild rechts ist die Ablehnung für den Versuch, direkt aus einem Dev Space auf alle Einheiten hochzustufen.

Ich habe die Abkürzung einmal an einem Freitag für einen Einzeiler-Fix ausprobiert: 0.4.0-dev aus meinem Dev Space auf alle Einheiten hochstufen. Es wurde mit GATE_CANNOT_BE_SKIPPED abgelehnt, und nichts wurde hochgestuft. Das Hinweisschild weist Sie an, stattdessen auf den nächsten Schritt hochzustufen, und das ist die einzige Antwort, die es gibt.

Die Release-Überprüfung selbst, die Nachweise, die ein zweiter Prüfer liest, und die Kanäle, die Einheiten wählen, finden Sie in Kapitel 2.28, Veröffentlichen Ihrer Erweiterung. Zwei Fakten daraus gehören hierher, weil sie prägen, wie Sie eine Branchenlösung planen. Der Autor zählt niemals als Prüfer, sodass ein Zweierteam für jedes Release eine dritte Person benötigt. Und jede Umgebung behält die vorherige Version für 30 Tage, sodass ein Rollback eine überprüfte Änderung ist, die die Pipeline in etwa einer Minute durchführt.

Ein bereits bestehendes Pack erweitern

Nicht jede Branchenlösung beginnt bei null. Ein Paket kann von einem anderen erben und nur das hinzufügen, was anders ist. Das Paket „Banking and payments“ (Bankwesen und Zahlungsverkehr), das die Larchmont Bank betreibt, ist das deutlichste Beispiel im Katalog. Sein Manifest beginnt wie folgt:

{
  "id": "fintech",
  "name": "Banking and payments",
  "version": "0.1",
  "inherits": "insurance",
  "clusters": [
    {
      "id": "FL01",
      "kind": "lens",
      "name": "Lending decisions",
      "seats": "Credit analysts, underwriters of loans, credit committee",
      "purpose": "Whether to lend, how much, at what price, and writing down why.",
      "lexicon": ["fin"],
      "menu": [],
      "screens": []
    }
  ],
  "lexicon": {
    "core": [],
    "fin": [
      ["APR", "the yearly cost of borrowing, fees included", "exact"],
      ["mandate", "the most one person may lend alone", ""]
    ]
  }
}

inherits nennt das Paket, auf dem es aufbaut. „Banking and payments“ behält die Form des Pakets „Insurance“ (Versicherung), seine geteilten Konversations-Cluster und seine Kernwörter bei und fügt drei eigene Lenses hinzu: „Lending decisions“ (Kreditentscheidungen), „Card disputes“ (Kartenreklamationen) und „My account“ (Mein Konto). Das dritte Element jedes Lexikoneintrags ist exact für einen Begriff, der genau wie geschrieben angezeigt werden muss, wie etwa APR (Annual Percentage Rate, effektiver Jahreszins), anstatt umformuliert zu werden.

Einige Dinge können Sie durch Vererbung nicht tun. Ein Paket ändert niemals die Shell, die Komponenten oder die Schreibregeln, sodass ein untergeordnetes Paket die Konsole nicht umgestalten kann. Ein Regelwerk, das mehrere Pakete benötigen, ist eine geteilte Lens statt einer Kopie in jedem Paket: Das Register ausgelagerter Technologien dient sowohl „Insurance“ als auch „Banking and payments“. Wenn Ihr untergeordnetes Paket eine Lens benötigt, die bereits als geteilte Lens existiert, verwenden Sie diese, anstatt Ihre eigene zu entwerfen.

Die Lizenzierung folgt der Vererbung. Ein Paket wird zusätzlich zu Enterprise lizenziert und benötigt möglicherweise Add-ons, und das Lizenzdokument enthält diese Abhängigkeiten. „Insurance“ benötigt „Decision rooms and sealed records“ (Entscheidungsräume und versiegelte Datensätze), sodass ein Kunde, der ein davon erbendes Paket lizenziert, dieses Add-on ebenfalls benötigt, und die Konsole weigert sich, eine Lizenz auszustellen, die es auslässt. Die Telefonbildschirme eines Pakets benötigen außerdem das Add-on „Mobile apps“. Prüfen Sie die Anforderungskette, bevor Sie einem Kunden einen Termin versprechen.

Einem bereits ausgelieferten Pack eine Linse hinzufügen

Die kleinste vertikale Arbeit ist eine neue Ansicht (Lens) für ein Paket (Pack), das Sie nicht selbst geschrieben haben. Sechs Monate nach Beginn des Pilotprojekts wünschte sich das Team für Transportschäden von Larkfield eine eigene Ansicht innerhalb von „Kühlkette“ (Cold chain): Temperaturabweichungen und Schadensfälle, keine Stromanschlüsse, keine Sollwerte. Wir haben den Code des Pakets nicht angerührt. Eine Ansicht ist eine Zeile im Ansichtenverzeichnis der Organisation, die dem Paket gehört. Daher haben wir sie über den Golden Path für Ansichten unter „Etwas Neues beginnen“ (Start something new) gestartet und sie im Lens Builder auf Basis der Ansicht „Kühlketten-Controller“ (Cold-chain controller) gestaltet. Es gilt dieselbe Regel wie zuvor: Die neue Ansicht kann ausblenden, was ihre Basis anzeigt, aber niemals mehr zeigen. Sie wird einmalig für die Organisation definiert und in jeder Einheit einer Plattformrolle zugewiesen. Eine Zuweisung wird widerrufen, niemals gelöscht, und eine erneute Vergabe der Ansicht erzeugt eine neue Zuweisung, sodass jederzeit nachvollziehbar bleibt, wer wann welche Ansicht innehatte. Das Verzeichnis zählt monatlich, wie viele Personen eine Ansicht innehatten, jedoch niemals, wer.

Die Seite „Ansichten und wer sie sieht“ (Lenses and who sees them) zeigt das Ergebnis als Matrix aus Ansicht nach Einheit und Rolle, mit den Optionen „Hinzufügen“ (Add), „Ändern“ (Change) und „Widerrufen“ (Withdraw) in jeder Zelle. Zeigen Sie die neue Ansicht in der Vorschau aus der Perspektive einer Person an, bevor Sie sie zuweisen, genau wie oben beschrieben.

Was es ehrlich gekostet hat

Ein Paket greift auf die Datensätze eines Kunden zu; daher verlangsamt die Plattform einige Vorgänge absichtlich, und Sie sollten dies vom ersten Tag an einplanen.

  1. Eine maskierte Kopie erfordert jedes Mal die Zustimmung des Dateneigentümers. Unsere ließ beim ersten Mal einen Tag auf sich warten, da Priya zuerst das Wissensmodell lesen wollte. Beginnen Sie mit synthetischen Daten und fragen Sie frühzeitig an.
  2. Der Autor kann sein eigenes Release nicht genehmigen, und Anfragen verfallen nach 3 Tagen. Wenn Ihre Prüfer beschäftigt sind, muss Ihr Release warten.
  3. Ein Release, das mehr Berechtigungen als das vorherige anfordert, wie etwa das Senden von E-Mails oder eine externe Adresse, wird zurückgehalten, bis zwei Prüfer das erweiterte Manifest akzeptieren. Kapitel 2.28, „Veröffentlichen Ihrer Erweiterung“ (Releasing your extension), zeigt die Seite „Manifest und Berechtigungen“ (Manifest and permissions), die Sie informiert, bevor Sie die Anfrage stellen.
  4. Eine Ansicht kann nicht anzeigen, was ihre Basisansicht ausblendet. Wenn eine Rolle wirklich mehr benötigt, erfordert dies ein Gespräch mit dem Organisationsadministrator, keine bloße Einstellung.

Keiner dieser Punkte stand uns zweimal im Weg. Das zweite Release von „Kühlkette“ (Cold chain) dauerte vom ersten Commit bis zum Pilotprojekt in Rotterdam eine Woche – der Großteil davon entfiel auf die 66 Tests, die über drei Branches liefen, sowie auf zwei Personen, die die Nachweise prüften.