规则
- 只用普通文件。 文件最多只会在记录过程中不断增长——数据流的
records.jsonl、它的媒体文件、运行的members.jsonl。没有隐藏的数据库、指针文件或打包文件。 - 引用就是路径和 id。 运行使用其路径上当前的资源；不固定任何哈希。
- 文件夹就是项目。 工作台中没有硬编码任何项目布局。
- 层级。 每个定义、世界和设置都可以存在于云端或本地，处于全局、用户和项目层级，并按从宽泛到具体的顺序合并。
设备
devices/<id>/definition.tsx，其资源放在旁边的 devices/<id>/assets/ 中（例如 model.glb）。定义就是代码：工作台运行它，读取它声明的 <device>。
定义写明机器信息（name、manufacturer、model_number、product_url …）、它的 3D model，以及它的 channels：
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 或 duplex；medium 取 records、video、audio 或 bytes。世界中的单元可以覆盖某个通道的设置。
世界
worlds/<id>/world.tsx，一段声明一个 <world> 的代码：
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>
);在工作台中的每次编辑都会以最小的改动写回代码。
kind 取 physical 或 simulation。世界可以指定一个 3D 场景（model，一个 .3d.tsx）；如果是仿真世界，还可以指定一个仿真文件（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：
{ "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/ 文件夹中。
| 扩展名 | 打开方式 |
|---|---|
.3d.tsx | 3D 设计（零件、装配体、场景） |
.cam.tsx、.slice.tsx | 3D 设计的 CAM 与切片模式；程序以 .gcode 保存在旁边 |
.nest.tsx | 矢量应用的排样模式（激光和板材作业），以代码表示 |
.draw.tsx、.paint.tsx、.img.tsx | 绘图、绘画和图像编辑，以代码表示；像素仍是旁边的图像文件 |
.vid.tsx | 视频编辑器，以代码表示；素材仍是旁边的文件 |
.mus.tsx | 音乐，以代码表示 |
.geo.tsx | 地缘经济工作区 |
其他格式
| 文件 | 是什么 |
|---|---|
<name>.sch.tsx + <name>.pcb.tsx | 代码形式的电路：原理图，以及引用它的电路板 |
<name>.sheet.tsx、<name>.page.tsx、<name>.deck.tsx | 以代码编写的工作簿、页面和幻灯片：表格、文档和幻灯片编辑器把每次编辑写入该文件 |
<name>.sim.json | 一个仿真 |
<name>.trials.json | 一个实验：在参数扫描上进行的多次仿真运行 |
<name>.graph.json | 一张图谱（知识、记忆） |
<name>.dashboard.tsx | 代码形式的仪表盘：窗格及其显示的文件 |
<name>.geo.tsx | 代码形式的地缘经济项目 |
<name>.opgraph.tsx | 代码形式的节点图 |
<name>.task.tsx、<name>.project.tsx | 任务和项目（代码） |
<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）。
{
"workbench.theme": "dark",
"threads.agentControl": false,
"devices.lanListener": true,
"[.gcode]": { "editor.default": "gcode" }
}"[.ext]" 块用于覆盖某一种文件扩展名的设置。