OKF-Export & -Import · Aiqbee Hive

Brains als portable Markdown-Bundles verschieben: was verlustfrei übertragen wird und was gemeldet wird.

OKF (Open Knowledge Format, Version 0.2) ist ein Klartextdatei-Format für Wissen: ein Ordnerbaum aus Markdown-Dateien, jeweils mit einem kleinen YAML-Header. Hive kann jedes Brain als OKF-.zip-Bundle exportieren und ein Bundle als neues Brain importieren. Da es nur Markdown ist, lässt sich ein Bundle in jedem Editor lesen, in Git vergleichen und von anderen Tools verstehen, die OKF beherrschen.

Brain-Eigentümer können ihre eigenen Brains exportieren (Einstellungen → Als OKF exportieren), und jeder angemeldete Benutzer kann ein Bundle als neues eigenes Brain importieren (Brains → Neues Brain → OKF-Bundle importieren). Administratoren können jedes Brain auf der Admin-Seite Brains exportieren und importieren. Der JSON-Export und -Import (kompatibel mit der Aiqbee-SaaS-Plattform) bleibt Administratoren vorbehalten (JSON importieren fragt wie der OKF-Import nach einem Eigentümer). Der OKF-Export wird über MCP nicht angeboten.

Export und Import in Eigenregie

Der Export steht dem Eigentümer des Brains (einschließlich Miteigentümern) zur Verfügung. Er enthält jedes Neuron, das der Eigentümer lesen kann, auch Neuronen unter Typen mit erweiterter Sicherheit. Bibliotheks-Brains kann niemand exportieren; exportieren Sie stattdessen das Quell-Brain (siehe Marktplatz & Bibliothek).
Der Import erstellt ein neues Brain, das Ihnen gehört. Er wird wie jedes andere Brain auf die Lizenz angerechnet, und das Upload-Limit von 50 MiB gilt. Auf der Hive können höchstens zwei Importe gleichzeitig laufen, und jeder Benutzer kann einen Import gleichzeitig ausführen; wird der Import als ausgelastet gemeldet, versuchen Sie es in Kürze erneut.

Ein Brain exportieren

Klicken Sie als Administrator unter Admin → Brains in der Zeile eines Brains auf das Zip-Symbol (OKF exportieren (.zip)) oder öffnen Sie das Brain und klicken Sie auf OKF exportieren. Der Download heißt <brain-name>-okf.zip.

Das Bundle hat einen Ordner auf oberster Ebene mit folgendem Inhalt:

Pfad	Was es enthält
`index.md`	Inhaltsseite. Ihr einziger Header-Schlüssel ist `okf_version: "0.2"`.
`log.md`	Ein datiertes Protokoll: zuerst der Export selbst, dann eine Zeile pro Erstellungsdatum.
`<type>/index.md`	Ein Ordner pro Neuronentyp — auch für einen Typ ohne Neuronen — mit der Auflistung seiner Neuronen.
`<type>/<neuron>.md`	Eine Datei pro Neuron: der Header, Ihr Inhalt genau wie gespeichert und eine Verwandt-Liste seiner ausgehenden Synapsen.
`_aiqbee/brain.md`	Das Brain-Manifest: Name, Beschreibung, das MCP-Bearbeitungs-Flag, Neuronentypen und die Metadatenfeld-Registrierung.

Datei- und Ordnernamen sind kleingeschriebene, ASCII-only-Versionen der Typ- und Neuronennamen (bei einem Konflikt folgt -2, -3…). Sie dienen nur der Darstellung: Die IDs in den Dateien, nicht die Dateinamen, steuern einen erneuten Import.

Ein Bundle importieren

Sie können auch ein ganz neues Brain in einem Schritt aus einem Bundle anlegen: Mit Neues Brain auf derselben Seite wählen Sie den Eigentümer, benennen das Brain und hängen optional einen .json-Export oder ein OKF-.zip an. Zuerst wird das Brain-Kontingent der Lizenz geprüft, und Sie erfahren, ob zusätzliche Lizenzen erworben werden müssen.

Klicken Sie als Administrator unter Admin → Brains auf OKF-Bundle importieren und füllen Sie den Dialog aus (Benutzer, die für sich selbst importieren, verwenden Brains → Neues Brain und brauchen kein Eigentümerfeld):

OKF-Bundle (.zip) — die zu importierende Datei.
Brain-Name (optional) — standardmäßig der Name aus dem Manifest des Bundles, sonst der Name der Zip-Datei. Ist der Name vergeben, macht Hive ihn eindeutig.
Eigentümer (erforderlich) — der aktive Benutzer, dem das neue Brain gehören wird. Die Admin-Sitzung ist kein Benutzer, daher wählen Sie einen aus.

Ein Import erstellt immer ein neues Brain. Er führt nie mit einem vorhandenen zusammen und aktualisiert es nicht. Es gilt alles oder nichts: Wird etwas Schwerwiegendes gefunden, wird nichts geschrieben, und Sie erhalten eine einzelne Meldung mit dem Grund. Embeddings sind nicht Teil des Bundles; Hive beginnt mit ihrer Erzeugung, sobald der Import abgeschlossen ist, wie beim JSON-Import, sodass die semantische Suche für das neue Brain bei einem großen Bundle kurzzeitig verzögert sein kann.

Bundles aus anderen Tools

Ein generisches OKF-Bundle (ohne Aiqbee-Schlüssel) lässt sich ebenfalls importieren:

Jede .md-Datei wird zu einem Neuron. Ihr Neuronentyp stammt aus dem type-Header, sonst aus dem Ordnernamen, sonst Concept.
Der Neuronenname ist der title, sonst die erste #-Überschrift, sonst der Dateiname. Doppelte Titel sind erlaubt.
Markdown-Links zwischen Dateien werden zu Synapsen; der Text nach einem Listeneintrag * [Title](link) - description wird zur Synapsenbeschreibung. Links in Codeblöcken, zu Websites oder solche, die sich nicht auflösen lassen, sind keine Synapsen (nicht auflösbare werden als defekte Links gemeldet).
index.md und log.md werden ignoriert.

Was verlustfrei übertragen wird

Wenn Sie ein Aiqbee-Brain exportieren und das Bundle importieren, wird Folgendes exakt wiederhergestellt:

Brain-Name (vor einem Eindeutigkeitssuffix), Beschreibung und die MCP-Bearbeitungseinstellung.
Neuronentypen — Namen, Beschreibungen, das Dateityp-Flag, leere Typen und Typen mit doppelten Namen.
Neuronen — Name, Inhalt Byte für Byte (einschließlich leer vs. keiner), Inhaltsdatum, Metadaten und Erstellungszeit.
Synapsen — Richtung, Beschreibung sowie doppelte oder Selbstverknüpfungen.
Die Metadatenfeld-Registrierung.

Bewusst nicht übernommen:

Zugriffskontrolle — Berechtigungen für Brains, Benutzer, Gruppen und Dienstkonten, Neuronentyp-Zugriff, erweiterte Sicherheit und Prüfeinstellungen. Benutzer und Gruppen gehören zu einem Hive; das neue Brain erhält Standardwerte und den gewählten Eigentümer.
Zeilen-IDs (neue werden generiert), Versionszähler und Embeddings.
Anhänge. Hive speichert keine Datei-Blobs, daher wird nur Textinhalt exportiert; jede Nicht-Markdown-Datei in einem importierten Bundle (Bilder, HTML) wird übersprungen und aufgelistet.

Der Importbericht und die Warnungen

Ein erfolgreicher Import zeigt eine Ergebnisseite mit einem Link zum neuen Brain, den Anzahlen von Neuronentypen, Neuronen, Synapsen, Metadatenfeldern und ignorierten Dateien sowie gruppierten Warnungen. Warnungen blockieren den Import nie; sie zeigen, was angepasst wurde:

Gruppe	Bedeutung
Übersprungene Dateien	Nicht importierte Dateien: ungültige Textkodierung, nicht lesbarer oder zu großer YAML-Header oder ein Header, der kein Schlüssel-Wert-Block ist.
Angewandte Ersatzwerte	Ein Wert war ungültig oder fehlte, und es wurde ein Standardwert verwendet — ein aus dem Ordner übernommener Typ, ein auf 255 Zeichen gekürzter Name, ein nicht lesbares Datum.
Defekte Links	Links, die auf keine Datei im Bundle zeigen. Die ersten 20 werden angezeigt, dazu die Gesamtzahl.
Nicht zugeordnete Frontmatter-Schlüssel	Standard-OKF-Schlüssel wie `tags`, `sources`, `status` und jeder unbekannte Schlüssel. Hive hat dafür noch keinen Platz, daher werden sie verworfen und gezählt.
Metadaten verworfen oder angepasst	Metadatenwerte, die die Validierung für ihr deklariertes Feld nicht bestanden haben.
Ignorierte Nicht-.md-Dateien	Jeder Nicht-Markdown-Eintrag mit seiner deklarierten Größe. Diese werden nie entpackt.

Limits und abgelehnte Bundles

Diese Prüfungen laufen, bevor etwas geschrieben wird. Ein Bundle, das gegen eine davon verstößt, wird sofort abgelehnt:

Laden Sie bis zu 50 MiB hoch; höchstens 25.000 Zip-Einträge und 20.000 Konzeptdateien; jede .md-Datei höchstens 8 MiB und insgesamt 256 MiB Markdown. Frontmatter ist auf 512 KiB pro Datei und 32 MiB insgesamt begrenzt, und ein Bundle darf höchstens 500.000 Synapsen definieren.
Pfade, die aus dem Bundle ausbrechen (../), absolute Pfade, Symlinks, verschlüsselte Einträge, zu lange oder zu tief verschachtelte Pfade sowie zwei Einträge, deren Namen sich nur in der Groß-/Kleinschreibung unterscheiden.
Dateien, die keine Zip-Archive sind.
Ein Bundle ohne zu importierende Konzepte.

Der Export wendet dieselben Grenzen an: Ein Brain, das zu groß ist, um erneut importiert zu werden, wird nicht nach OKF exportiert (Sie werden darauf hingewiesen und auf den JSON-Export verwiesen), sodass sich ein heruntergeladenes Bundle immer wieder importieren lässt. Jedes Importformular kann nur einmal abgesendet werden, daher erzeugt ein erneutes Laden der Ergebnisseite nie ein zweites Brain.

Es wird nichts auf die Festplatte extrahiert, und YAML-Header werden sicher geparst (keine Tags, Anker oder Aliase), sodass ein bösartiges Bundle weder Code ausführen noch Dateien schreiben kann.

Der Import zählt auch gegen Ihre Lizenz: Das Brain-Limit und die gemeinsame Neuronenobergrenze werden anhand der Größe des Bundles geprüft, und eine abgelaufene Lizenz (schreibgeschützter Modus) lehnt den Import ab. Die Meldung nennt das erreichte Limit. Siehe Lizenzierung & Stufen.

Metadaten und die Lizenz

Das Deklarieren eines Metadatenfelds ist eine kostenpflichtige Funktion (siehe Neuron-Metadaten). Was ein Import bewirkt, hängt von der Lizenz des Hive ab, der ihn empfängt:

Mit der Metadaten-Berechtigung — das Feldregister wird angelegt, und die Metadaten jedes Neurons werden dagegen geprüft.
Ohne sie — das Register wird nicht angelegt, aber Neuron-Metadatenwerte werden dennoch gespeichert. Sie sind inaktiv (sichtbar, aber nicht als Filter nutzbar), bis die Felder deklariert werden, genau wie nach dem Ablauf einer Lizenz. Der Bericht enthält eine entsprechende Warnung.

Wie immer gilt: Metadaten dienen der Kennzeichnung, nicht der Zugriffskontrolle. Sie reisen mit dem Bundle zu jedem, der die Zip-Datei öffnen kann.