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.tsx, con sus recursos al lado en devices/<id>/assets/ (por ejemplo, model.glb). Una definición es código: el workbench lo ejecuta y lee el <device> que declara.

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

tsx

export default () => (
  <device name="CNC 3018" manufacturer="…">
    <channel id="gcode" dir="duplex" medium="records" format="gcode-chat" dialect="grbl" transport="serial" baud={115200} />
  </device>
);

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.tsx, código que declara un <world>:

tsx

export default () => (
  <world name="Shop floor" kind="physical">
    <space origin_mm={[0, 0, 0]} size_mm={[6000, 4000, 3000]} />
    <unit uid="mill-1" name="Mill" device="../../devices/cnc-3018/definition.tsx" position={[1200, 800, 0]} rotation={0} />
  </world>
);

Cada edición en el workbench se escribe en el código como el cambio más pequeño.

kind es physical o simulation. Un mundo puede nombrar una escena 3D (model, un .3d.tsx) 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
`.3d.tsx`	diseño 3D (piezas, ensamblajes, escenas)
`.cam.tsx`, `.slice.tsx`	diseño 3D en modo CAM y laminado; los programas se guardan a su lado como `.gcode`
`.nest.tsx`	el modo de anidado de la app vectorial (trabajos de láser y de lámina), en código
`.draw.tsx`, `.paint.tsx`, `.img.tsx`	dibujo, pintura y edición de imágenes, en código; los píxeles quedan como archivos de imagen al lado
`.vid.tsx`	el editor de video, en código; los medios quedan como archivos al lado
`.mus.tsx`	música, en código
`.geo.tsx`	espacios de trabajo de geoeconomía

Otros formatos

archivo	qué es
`<name>.sch.tsx` + `<name>.pcb.tsx`	un circuito en código: el esquemático, y su placa, que lo nombra
`<name>.sheet.tsx`, `<name>.page.tsx`, `<name>.deck.tsx`	un libro de cálculo, una página y una presentación, escritos como código: los editores de hojas, documentos y presentaciones escriben cada cambio en el archivo
`<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.tsx`	un panel en código: paneles de vista y los archivos que muestran
`<name>.geo.tsx`	un proyecto de geoeconomía en código
`<name>.opgraph.tsx`	un grafo de nodos en código
`<name>.task.tsx`, `<name>.project.tsx`	una tarea y un proyecto, en código
`<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).