文件格式 — 文档

规则

只用普通文件。 文件最多只会在记录过程中不断增长——数据流的 records.jsonl、它的媒体文件、运行的 members.jsonl。没有隐藏的数据库、指针文件或打包文件。
引用就是路径和 id。 运行使用其路径上当前的资源；不固定任何哈希。
文件夹就是项目。 工作台中没有硬编码任何项目布局。
层级。 每个定义、世界和设置都可以存在于云端或本地，处于全局、用户和项目层级，并按从宽泛到具体的顺序合并。

设备

devices/<id>/definition.json，其资源放在旁边的 devices/<id>/assets/ 中（例如 model.glb）。

定义写明机器信息（name、manufacturer、model_number、product_url …）、它的 3D model，以及它的 channels：

json

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

dir 取 in、out 或 duplex；medium 取 records、video、audio 或 bytes。世界中的单元可以覆盖某个通道的设置。

世界

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 取 physical 或 simulation。世界可以指定一个 3D 场景（model，一个 .3dx）；如果是仿真世界，还可以指定一个仿真文件（sim，一个 .sim.json）。世界不是 3D 模型，运行也不是世界。

运行与数据流

runs/<run>/ 是某个世界中的一次运行：

文件	内容
`run.json`	`id`、`world`、`kind`（`session`、`recipe` 或 `thread`）、`started`、`ended`、`from`（分叉来源的运行和时间点）
`members.jsonl`	谁和什么参与了运行，在加入时追加
`steps.jsonl`	配方（recipe）的步骤
`streams/<uid>.<channel>/`	一条数据流：`stream.json` 加上它的数据——`records.jsonl`，或者一个 `video.webm`/`.mp4`、`audio.webm`/`.mp4`，或 `data.bin`
`streams/chat/`	线程的对话
`streams/sim/`、`streams/sim-input/`	仿真的帧，以及施加给它的输入
`evidence/`	作为证据保存的文件

一条记录就是一行 JSON：

json

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

src 取 device、sim 或 operator；kind 取 command、event、ack、reply、state、evidence 或 note；seq 严格递增。未知状态写作 { "kind": "state", "status": "unknown" }。

文档

每个编辑器文档都是一个 JSON 文件——{ "format": "commandagi-document", "kind", "title", "meta", "body" }——大型资源放在旁边的 <name>.assets/ 文件夹中。

扩展名	打开方式
`.3dx`	3D 设计（零件、装配体、场景）
`.camx`、`.slicex`	3D 设计的 CAM 与切片模式；程序以 `.gcode` 保存在旁边
`.nestx`	矢量应用的排样模式（激光和板材作业）
`.drawx`、`.paintx`、`.imgx`	绘图、绘画和图像编辑
`.deckx`	幻灯片
`.vidx`	视频编辑器
`.musx`	音乐
`.geox`	地缘经济工作区
`.task`、`.project`	任务和项目

其他格式

文件	是什么
`<name>.sch.json` + `<name>.pcb.json`	一个电路：原理图及其电路板，两个互相引用的文件
`<name>.sim.json`	一个仿真
`<name>.trials.json`	一个实验：在参数扫描上进行的多次仿真运行
`<name>.graph.json`	一张图谱（知识、记忆）
`<name>.dashboard.json`	一个仪表盘：窗格及其显示的文件
`<name>.market.jsonl`	一个市场的成交记录、订单簿、委托和持仓
`calendar/<calendar>/<event>.ics`、`contacts/<email>.vcf`	日历和联系人
`.xlsx`、`.md`、`.pdf`、`.ipynb`、`.gcode`、`.step`、`.stl`、`.glb` …	按原样打开，使用对应类型的编辑器

设置

设置是 VS Code 风格的 settings.json 文件（允许注释），每个层级一个，按从宽泛到具体的顺序合并：云端和本地的全局层级、你的组织、你的账户，然后是这台电脑（~/.commandagi/settings.json）和这个项目（.commandagi/settings.json）。

json

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

"[.ext]" 块用于覆盖某一种文件扩展名的设置。