Formatos de archivo — Documentación

Las reglas

Solo archivos simples. Lo máximo que hace un archivo es crecer mientras registra — el records.jsonl de un flujo, su archivo multimedia, el members.jsonl de una ejecución. No hay bases de datos ocultas, archivos puntero ni paquetes.
Las referencias son rutas e ids. Una ejecución usa el recurso que hay ahora en su ruta; nada fija un hash.
La carpeta es el proyecto. Nada de la estructura de un proyecto está codificado en el workbench.
Niveles. Cada definición, mundo y ajuste puede existir en la nube o en local, a nivel global, de usuario y de proyecto, y se combinan de lo general a lo específico.

Dispositivos

devices/<id>/definition.json, con sus recursos al lado en devices/<id>/assets/ (por ejemplo, model.glb).

Una definición nombra la máquina (name, manufacturer, model_number, product_url …), su model 3D y sus channels:

json

{ "id": "gcode", "dir": "duplex", "medium": "records",
  "format": "gcode-chat", "dialect": "grbl", "transport": "serial", "baud": 115200 }

dir es in, out o duplex; medium es records, video, audio o bytes. Una unidad de un mundo puede sobrescribir un canal.

Mundos

worlds/<id>/world.json:

json

{ "id": "shop", "name": "Shop floor", "kind": "physical",
  "space": { "origin_mm": [0, 0, 0], "size_mm": [6000, 4000, 3000] },
  "units": [ { "uid": "mill-1", "name": "Mill", "device": "cnc-3018-montaj",
               "position": [1200, 800, 0], "rotation": [0, 0, 90] } ] }

kind es physical o simulation. Un mundo puede nombrar una escena 3D (model, un .3dx) y, si es de simulación, un archivo de simulación (sim, un .sim.json). Un mundo no es un modelo 3D, y una ejecución no es un mundo.

Ejecuciones y flujos

runs/<run>/ es una ejecución en un mundo:

archivo	contiene
`run.json`	`id`, `world`, `kind` (`session`, `recipe` o `thread`), `started`, `ended`, `from` (la ejecución y el momento desde los que se bifurcó)
`members.jsonl`	quién y qué participó, añadido a medida que se unen
`steps.jsonl`	los pasos de una receta
`streams/<uid>.<channel>/`	un flujo: `stream.json` más sus datos — `records.jsonl`, o un único `video.webm`/`.mp4`, `audio.webm`/`.mp4` o `data.bin`
`streams/chat/`	la conversación de un hilo
`streams/sim/`, `streams/sim-input/`	los fotogramas de una simulación y las entradas que se le aplicaron
`evidence/`	archivos guardados como evidencia

Un registro es una línea de JSON:

json

{ "t": 7.180, "seq": 41, "src": "operator", "kind": "note", "text": "agent:night-shift: run_program", "by": "agent:night-shift" }

src es device, sim u operator; kind es command, event, ack, reply, state, evidence o note; seq crece estrictamente. Un estado desconocido se escribe { "kind": "state", "status": "unknown" }.

Documentos

Cada documento de un editor es un archivo JSON — { "format": "commandagi-document", "kind", "title", "meta", "body" } — con los recursos grandes en una carpeta <name>.assets/ a su lado.

extensión	se abre en
`.3dx`	diseño 3D (piezas, ensamblajes, escenas)
`.camx`, `.slicex`	diseño 3D en modo CAM y laminado; los programas se guardan a su lado como `.gcode`
`.nestx`	el modo de anidado de la app vectorial (trabajos de láser y de lámina)
`.drawx`, `.paintx`, `.imgx`	dibujo, pintura y edición de imágenes
`.deckx`	presentaciones
`.vidx`	el editor de video
`.musx`	música
`.geox`	espacios de trabajo de geoeconomía
`.task`, `.project`	tareas y proyectos

Otros formatos

archivo	qué es
`<name>.sch.json` + `<name>.pcb.json`	un circuito: el esquemático y su placa, dos archivos que se nombran mutuamente
`<name>.sim.json`	una simulación
`<name>.trials.json`	un experimento: muchas ejecuciones simuladas sobre un barrido de parámetros
`<name>.graph.json`	un grafo (conocimiento, memoria)
`<name>.dashboard.json`	un panel: paneles de vista y los archivos que muestran
`<name>.market.jsonl`	la cinta, el libro, las órdenes y las posiciones de un mercado
`calendar/<calendar>/<event>.ics`, `contacts/<email>.vcf`	calendarios y contactos
`.xlsx`, `.md`, `.pdf`, `.ipynb`, `.gcode`, `.step`, `.stl`, `.glb` …	se abren tal cual, en el editor de su tipo

Ajustes

Los ajustes son archivos settings.json al estilo de VS Code (se permiten comentarios), uno por nivel, combinados de lo general a lo específico: los niveles globales en la nube y en local, tus organizaciones, tu cuenta, luego esta computadora (~/.commandagi/settings.json) y este proyecto (.commandagi/settings.json).

json

{
  "workbench.theme": "dark",
  "threads.agentControl": false,
  "devices.lanListener": true,
  "[.gcode]": { "editor.default": "gcode" }
}

Un bloque "[.ext]" sobrescribe los ajustes para una extensión de archivo.