Formats de fichiers — Docs

Les règles

Uniquement des fichiers simples. Un fichier fait au plus une chose : grossir pendant qu'il enregistre — le records.jsonl d'un flux, son fichier média, le members.jsonl d'une exécution. Il n'existe pas de base de données cachée, de fichier pointeur ni de paquet.
Les références sont des chemins et des identifiants. Une exécution utilise le fichier présent à son chemin ; rien n'épingle un hachage.
Le dossier est le projet. Rien dans la mise en page d'un projet n'est codé en dur dans l'atelier.
Niveaux. Chaque définition, monde et paramètre peut exister dans le cloud ou en local, aux niveaux global, utilisateur et projet, et ils se fusionnent du plus large au plus précis.

Appareils

Un appareil est défini dans devices/<id>/definition.tsx, et ses ressources se trouvent à côté, dans devices/<id>/assets/ (par exemple model.glb). Une définition est du code : l'atelier l'exécute et lit le <device> qu'elle déclare.

Une définition nomme la machine (name, manufacturer, model_number, product_url …), son modèle 3D (model) et ses 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 vaut in, out ou duplex ; medium vaut records, video, audio ou bytes. Une unité dans un monde peut remplacer un canal.

Mondes

Un monde est défini dans worlds/<id>/world.tsx, du code qui déclare un seul <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>
);

Chaque modification faite dans l'atelier est réécrite dans le code, sous la forme du plus petit changement.

kind vaut physical ou simulation. Un monde peut nommer une scène 3D (model, un .3d.tsx) et, s'il est une simulation, un fichier de simulation (sim, un .sim.json). Un monde n'est pas un modèle 3D, et une exécution n'est pas un monde.

Exécutions et flux

runs/<run>/ est une exécution dans un monde :

fichier	contient
`run.json`	`id`, `world`, `kind` (`session`, `recipe` ou `thread`), `started`, `ended`, `from` (l'exécution et l'heure dont elle est issue)
`members.jsonl`	qui et quoi a participé, ajouté au fil des arrivées
`steps.jsonl`	les étapes d'une recette
`streams/<uid>.<channel>@<replica>/`	un flux : `stream.json` et ses données — `records.jsonl`, ou un seul `video.webm`/`.mp4`, `audio.webm`/`.mp4`, ou `data.bin`
`streams/chat@<replica>/`	la conversation
`streams/sim@<replica>/`, `streams/sim-input@<replica>/`	les images d'une simulation et les entrées qui lui sont appliquées
`evidence/`	fichiers conservés comme preuves

Un enregistrement est une ligne de JSON :

json

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

src vaut device, sim ou operator ; kind vaut command, event, ack, reply, state, evidence ou note ; seq augmente strictement. Un état inconnu s'écrit { "kind": "state", "status": "unknown" }.

Documents

Chaque document d'éditeur est un fichier JSON — { "format": "commandagi-document", "kind", "title", "meta", "body" } — dont les grandes ressources se trouvent dans un dossier <name>.assets/ à côté de lui.

extension	s'ouvre dans
`.3d.tsx`	conception 3D (pièces, assemblages, scènes)
`.cam.tsx`, `.slice.tsx`	conception 3D en mode CAM et tranchage ; les programmes sont enregistrés à côté sous forme de `.gcode`
`.nest.tsx`	le mode d'imbrication de l'application vectorielle (travaux laser et de tôle), en code
`.draw.tsx`, `.paint.tsx`, `.img.tsx`	dessin, peinture et retouche d'image, en code ; les pixels restent des fichiers image à côté
`.vid.tsx`	l'éditeur vidéo, en code ; les médias restent des fichiers à côté
`.mus.tsx`	musique, en code
`.geo.tsx`	espaces de travail de géoéconomie

Autres formats

fichier	ce que c'est
`<name>.sch.tsx` + `<name>.pcb.tsx`	un circuit en code : le schéma, et la carte qui le nomme
`<name>.sheet.tsx`, `<name>.page.tsx`, `<name>.deck.tsx`	un classeur, une page et une présentation, écrits en code : les éditeurs de feuilles, de documents et de présentations écrivent chaque modification dans le fichier
`<name>.sim.json`	une simulation
`<name>.trials.json`	une expérience : de nombreuses exécutions simulées sur un balayage de paramètres
`<name>.graph.json`	un graphe (savoir, mémoire)
`<name>.dashboard.tsx`	un tableau de bord en code : volets et fichiers qu'ils affichent
`<name>.geo.tsx`	un projet de géoéconomie en code
`<name>.opgraph.tsx`	un graphe de nœuds en code
`<name>.task.tsx`, `<name>.project.tsx`	une tâche et un projet, en code
`<name>.market.jsonl`	le ruban, le carnet, les ordres et les positions d'un marché
`calendar/<calendar>/<event>.ics`, `contacts/<email>.vcf`	agendas et contacts
`.xlsx`, `.md`, `.pdf`, `.ipynb`, `.gcode`, `.step`, `.stl`, `.glb` …	ouverts tels quels, dans l'éditeur de leur type

Paramètres

Les paramètres sont des fichiers settings.json de style VS Code (commentaires permis), un par niveau, fusionnés du plus large au plus précis : les niveaux globaux du cloud et du local, vos organisations, votre compte, puis cet ordinateur (~/.commandagi/settings.json) et ce projet (.commandagi/settings.json).