Exportación e importación OKF

Mueva Brains como paquetes markdown portables: qué se conserva en el viaje de ida y vuelta y qué se notifica.

OKF (Open Knowledge Format, versión 0.2) es un formato de archivos planos para el conocimiento: un árbol de carpetas con archivos markdown, cada uno con una pequeña cabecera YAML. Hive puede exportar cualquier Brain como un paquete .zip OKF e importar un paquete como un Brain nuevo. Al ser solo markdown, un paquete se puede leer en cualquier editor, comparar en git y lo entienden otras herramientas compatibles con OKF.

Los propietarios de brains pueden exportar sus propios brains (Configuración → Exportar como OKF), y cualquier usuario con sesión iniciada puede importar un paquete como un brain nuevo propio (Brains → Nuevo brain → Importar paquete OKF). Los administradores pueden exportar e importar cualquier brain desde la página Brains de administración. La exportación e importación JSON (compatibles con la plataforma SaaS de Aiqbee) siguen siendo solo para administradores (Importar JSON pide un propietario, igual que la importación OKF). La exportación OKF no se ofrece por MCP.

Exportación e importación de autoservicio

La exportación es para el propietario del brain (incluidos los copropietarios). Incluye todas las neuronas que el propietario puede leer, también las de tipos con seguridad avanzada. Nadie puede exportar los brains de la biblioteca; exporte en su lugar el brain de origen (consulte Mercado & biblioteca).
La importación crea un brain nuevo del que usted es propietario. Cuenta para la licencia como cualquier otro brain y se aplica el límite de subida de 50 MiB. Solo pueden ejecutarse dos importaciones a la vez en la Hive y cada usuario puede tener una en curso; si se indica que la importación está ocupada, vuelva a intentarlo en breve.

Exportar un Brain

Como administrador, en Admin → Brains, haga clic en el icono zip (Exportar OKF (.zip)) en la fila de un brain, o abra el brain y haga clic en Exportar OKF. La descarga se llama <brain-name>-okf.zip.

El paquete tiene una carpeta de nivel superior que contiene:

Ruta	Qué contiene
`index.md`	Página de contenidos. Su única clave de cabecera es `okf_version: "0.2"`.
`log.md`	Un registro fechado: primero la propia exportación y luego una línea por cada fecha de creación.
`<type>/index.md`	Una carpeta por tipo de neurona — incluso un tipo sin neuronas — con la lista de sus neuronas.
`<type>/<neuron>.md`	Un archivo por neurona: el encabezado, su contenido exactamente como está almacenado y una lista Relacionadas con sus sinapsis salientes.
`_aiqbee/brain.md`	El manifiesto del Brain: nombre, descripción, el indicador de edición MCP, los tipos de neurona y el registro de campos de metadatos.

Los nombres de archivos y carpetas son versiones en minúsculas y solo ASCII de los nombres de tipos y neuronas (un conflicto añade -2, -3…). Son solo de presentación: en una reimportación mandan los identificadores dentro de los archivos, no los nombres de archivo.

Importar un paquete

También puede sembrar un Brain nuevo desde un paquete en un solo paso: Nuevo Brain en la misma página le permite elegir el propietario, poner nombre al Brain y adjuntar opcionalmente una exportación .json o un .zip OKF. Primero comprueba la asignación de Brains de la licencia y le indica si es necesario adquirir licencias adicionales.

Como administrador, en Admin → Brains, haga clic en Importar paquete OKF y complete el cuadro de diálogo (los usuarios que importan para sí mismos usan Brains → Nuevo brain y no necesitan el campo de propietario):

Paquete OKF (.zip) — el archivo que se va a importar.
Nombre del Brain (opcional) — por defecto, el nombre del manifiesto del paquete; si no, el nombre del archivo zip. Si el nombre ya existe, Hive lo hace único.
Propietario (obligatorio) — el usuario activo que será propietario del nuevo Brain. La sesión de administración no es un usuario, por lo que debe elegir uno.

Una importación siempre crea un Brain nuevo. Nunca se fusiona con uno existente ni lo actualiza. Es todo o nada: si se detecta algo fatal, no se escribe nada y recibirá un único mensaje con el motivo. Las incrustaciones no forman parte del paquete; Hive empieza a generarlas en cuanto termina la importación, igual que con la importación JSON, por lo que la búsqueda semántica del nuevo Brain puede retrasarse un poco con un paquete grande.

Paquetes de otras herramientas

Un paquete OKF genérico (sin claves de Aiqbee) también se importa:

Cada archivo .md se convierte en una neurona. Su tipo de neurona procede de la cabecera type; si no, del nombre de la carpeta; si no, Concept.
El nombre de la neurona es el title; si no existe, el primer encabezado #; y si tampoco, el nombre del archivo. Se permiten títulos duplicados.
Los enlaces Markdown entre archivos se convierten en sinapsis; el texto que sigue a un elemento de lista * [Title](link) - description pasa a ser la descripción de la sinapsis. Los enlaces dentro de bloques de código, a sitios web o que no se resuelven no son sinapsis (los no resueltos se notifican como enlaces rotos).
index.md y log.md se ignoran.

Qué se conserva en el viaje de ida y vuelta

Al exportar un Brain de Aiqbee e importar el paquete se recrea exactamente lo siguiente:

Nombre del Brain (antes de cualquier sufijo de unicidad), descripción y ajuste de edición MCP.
Tipos de neurona — nombres, descripciones, el indicador de tipo de archivo, tipos vacíos y tipos con nombres duplicados.
Neuronas — nombre, contenido byte a byte (incluida la diferencia entre vacío y ninguno), fecha del contenido, metadatos y hora de creación.
Sinapsis — dirección, descripción y enlaces duplicados o a sí mismas.
El registro de campos de metadatos.

Deliberadamente no se trasladan:

Control de acceso — permisos de Brain, usuario, grupo y cuenta de servicio, acceso por tipo de neurona, seguridad avanzada y ajustes de auditoría. Los usuarios y grupos pertenecen a un solo Hive; el nuevo Brain recibe valores predeterminados y el propietario elegido.
Ids de fila (se generan nuevos), contadores de versión y embeddings.
Archivos adjuntos. Hive no almacena blobs de archivos, por lo que solo se exporta el contenido de texto; cualquier archivo que no sea markdown en un paquete importado (imágenes, HTML) se omite y se lista.

El informe de importación y las advertencias

Una importación correcta muestra una página de resultados con un enlace al nuevo Brain, el recuento de tipos de neurona, neuronas, sinapsis, campos de metadatos y archivos ignorados, y advertencias agrupadas. Las advertencias nunca bloquean la importación; le indican qué se ajustó:

Grupo	Significado
Archivos omitidos	Archivos no importados: codificación de texto no válida, cabecera YAML ilegible o demasiado grande, o una cabecera que no es un bloque de clave/valor.
Valores de reserva aplicados	Un valor no era válido o faltaba y se usó uno predeterminado — un tipo tomado de la carpeta, un nombre truncado a 255 caracteres, una fecha ilegible.
Enlaces rotos	Enlaces que no apuntan a ningún archivo del paquete. Se muestran los primeros 20, más el total.
Claves de frontmatter sin asignar	Claves OKF estándar como `tags`, `sources`, `status` y cualquier clave desconocida. Hive aún no tiene dónde guardarlas, por lo que se descartan y se contabilizan.
Metadatos descartados o ajustados	Valores de metadatos que no superaron la validación de su campo declarado.
Archivos que no son .md ignorados	Toda entrada que no sea markdown, con su tamaño declarado. Nunca se descomprimen.

Límites y paquetes rechazados

Estas comprobaciones se ejecutan antes de escribir nada. Un paquete que incumpla alguna se rechaza por completo:

Cargue hasta 50 MiB; como máximo 25 000 entradas zip y 20 000 archivos de conceptos; cada archivo .md de hasta 8 MiB y 256 MiB de markdown en total. El frontmatter se limita a 512 KiB por archivo y 32 MiB en conjunto, y un paquete puede definir como máximo 500 000 sinapsis.
Rutas que se salen del paquete (../), rutas absolutas, enlaces simbólicos, entradas cifradas, rutas demasiado largas o demasiado profundas, y dos entradas cuyos nombres solo difieren en mayúsculas y minúsculas.
Archivos que no son archivos zip.
Un paquete sin conceptos que importar.

La exportación aplica los mismos límites: un Brain demasiado grande para volver a importarse no se exporta a OKF (se le informa y se le remite a la exportación JSON), de modo que un paquete que descargue siempre se pueda reimportar. Cada formulario de importación solo puede enviarse una vez, por lo que recargar la página de resultados nunca crea un segundo Brain.

No se extrae nada al disco y los encabezados YAML se analizan de forma segura (sin etiquetas, anclas ni alias), por lo que un paquete hostil no puede ejecutar código ni escribir archivos.

La importación también cuenta para su licencia: el límite de Brains y el tope combinado de neuronas se comprueban con el tamaño del paquete, y una licencia caducada (modo de solo lectura) rechaza la importación. El mensaje indica el límite alcanzado. Consulte Licencias & niveles.

Metadatos y la licencia

Declarar un campo de metadatos es una función de pago (consulte Metadatos de neurona). Lo que hace una importación depende de la licencia del Hive que la recibe:

Con el derecho de metadatos — se crea el registro de campos y los metadatos de cada neurona se validan contra él.
Sin él — el registro no se crea, pero los valores de metadatos de las neuronas se siguen almacenando. Están inactivos (visibles, pero no utilizables como filtros) hasta que se declaren los campos, exactamente como tras el vencimiento de una licencia. El informe incluye una advertencia que lo indica.

Como siempre, los metadatos son etiquetado, no control de acceso. Viajan con el paquete a cualquiera que pueda abrir el zip.