Formatos de arquivo — Docs · CommandAGI Developers

As regras

Só arquivos simples. O máximo que um arquivo faz é crescer enquanto registra — o records.jsonl de um fluxo, o arquivo de mídia dele, o members.jsonl de uma execução. Não há bancos de dados ocultos, arquivos de ponteiro nem pacotes.
Referências são caminhos e ids. Uma execução usa o ativo que está no seu caminho agora; nada fixa um hash.
A pasta é o projeto. Nada sobre o layout de um projeto fica fixo na bancada de trabalho.
Níveis. Toda definição, todo mundo e toda configuração podem existir na nuvem ou localmente, nos níveis global, do usuário e do projeto, e se fundem do mais amplo para o mais específico.

Dispositivos

devices/<id>/definition.tsx, com os seus ativos ao lado, em devices/<id>/assets/ (por exemplo model.glb). Uma definição é código: a bancada de trabalho o executa e lê o <device> que ele declara.

Uma definição nomeia a máquina (name, manufacturer, model_number, product_url …), o seu modelo 3D (model) e os seus canais (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 é in, out ou duplex; medium é records, video, audio ou bytes. Uma unidade em um mundo pode substituir um canal.

Mundos

worlds/<id>/world.tsx, código que declara um <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 edição feita na bancada de trabalho é gravada de volta no código como a menor mudança possível.

kind é physical ou simulation. Um mundo pode citar uma cena 3D (model, um .3d.tsx) e, se for uma simulação, um arquivo de simulação (sim, um .sim.json). Um mundo não é um modelo 3D, e uma execução não é um mundo.

Execuções e fluxos

runs/<run>/ é uma execução em um mundo:

arquivo	guarda
`run.json`	`id`, `world`, `kind` (`session`, `recipe` ou `thread`), `started`, `ended`, `from` (a execução e o momento de onde ela foi bifurcada)
`members.jsonl`	quem e o que participou, acrescentado conforme entra
`steps.jsonl`	os passos de uma receita
`streams/<uid>.<channel>@<replica>/`	um fluxo: `stream.json` mais os seus dados — `records.jsonl`, ou um `video.webm`/`.mp4`, `audio.webm`/`.mp4` ou `data.bin`
`streams/chat@<replica>/`	a conversa de uma conversa
`streams/sim@<replica>/`, `streams/sim-input@<replica>/`	os quadros de uma simulação e as entradas aplicadas a ela
`evidence/`	arquivos guardados como evidência

Um registro é uma linha 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 é device, sim ou operator; kind é command, event, ack, reply, state, evidence ou note; seq aumenta estritamente. Um estado desconhecido é gravado como { "kind": "state", "status": "unknown" }.

Documentos

Cada documento do editor é um arquivo JSON — { "format": "commandagi-document", "kind", "title", "meta", "body" } — com os ativos grandes em uma pasta <name>.assets/ ao lado dele.

extensão	abre em
`.3d.tsx`	design 3D (peças, montagens, cenas)
`.cam.tsx`, `.slice.tsx`	design 3D nos modos CAM e fatiamento; os programas são salvos ao lado como `.gcode`
`.nest.tsx`	o modo de encaixe do app vetorial (trabalhos de laser e de chapa), em código
`.draw.tsx`, `.paint.tsx`, `.img.tsx`	desenho, pintura e edição de imagem, em código; os pixels continuam como arquivos de imagem ao lado
`.vid.tsx`	o editor de vídeo, em código; as mídias continuam como arquivos ao lado dele
`.mus.tsx`	música, em código
`.geo.tsx`	espaços de trabalho de geoeconomia

Outros formatos

arquivo	o que é
`<name>.sch.tsx` + `<name>.pcb.tsx`	um circuito em código: o esquemático, e a placa que ele nomeia
`<name>.sheet.tsx`, `<name>.page.tsx`, `<name>.deck.tsx`	uma planilha, uma página e uma apresentação de slides, escritas como código: os editores de planilhas, documentos e apresentações gravam cada edição no arquivo
`<name>.sim.json`	uma simulação
`<name>.trials.json`	um experimento: muitas execuções simuladas em uma varredura de parâmetros
`<name>.graph.json`	um grafo (conhecimento, memória)
`<name>.dashboard.tsx`	um painel em código: os painéis e os arquivos que eles mostram
`<name>.geo.tsx`	um projeto de geoeconomia em código
`<name>.opgraph.tsx`	um grafo de nós em código
`<name>.task.tsx`, `<name>.project.tsx`	uma tarefa e um projeto, em código
`<name>.market.jsonl`	a fita, o livro de ofertas, as ordens e as posições de um mercado
`calendar/<calendar>/<event>.ics`, `contacts/<email>.vcf`	calendários e contatos
`.xlsx`, `.md`, `.pdf`, `.ipynb`, `.gcode`, `.step`, `.stl`, `.glb` …	abertos como estão, no editor do seu tipo

Configurações

Configurações são arquivos settings.json no estilo VS Code (comentários são permitidos), um por nível, fundidos do mais amplo para o mais específico: os níveis global da nuvem e local, as suas organizações, a sua conta, depois este computador (~/.commandagi/settings.json) e este projeto (.commandagi/settings.json).