你的设备
在代码中操作设备
每一台设备都是一个实时文件夹。用一次文件读取来读取它的屏幕、摄像头或姿态；通过写入一个文件在它的屏幕上绘图；用一套统一的动作驱动它——无论硬件是什么，方式都一样。
设备就是文件夹
当一台设备接入一个会话时，它会投射进一个 .commandagi/ 目录树，按它是什么类型的东西分组。这些文件是实时的：读取一个就能拿到最新的数据，无需任何轮询仪式。
.commandagi/
computers/<id>/
screen.mjpeg # the screen AS VIDEO — Motion JPEG, its frames concatenated
screen.latest.jpg # the latest screen frame
screen.structure.jsonl # the UI accessibility tree, as a log
display.jsonl # WRITE here to draw on the screen
details.json # what this embodiment is: model, capabilities, location
cameras/<id>/
camera.mjpeg # the camera as video
camera.latest.jpg # latest camera frame
robots/<id>/
camera.mjpeg pose.jsonl joints.jsonl force.jsonl流就是文件
一个流的文件就是它的字节本身，这条规则对每一种设备都一样：
- 屏幕或摄像头是视频流，所以它的文件是
<stream>.mjpeg——Motion JPEG，ffmpeg和 VLC 都能打开。若有采集脚本生成，<stream>.latest.jpg会并列存在，表示这一帧。 - 结构化流——
pose.jsonl、界面树——是只追加的日志，保存整个累积的流。像跟踪任何日志一样跟踪它以获取每次更新，或读取.latest.json获取当前值。
这里没有任何发明：视频流就是视频文件，事件流就是日志，所以 ffmpeg、tail -f 和 jq 都可以原样使用。
读取一台设备的三种方式
同样的数据，选择适合你代码的那个入口。
1. SDK——用于一个循环的最快路径。
from commandagi import CommandAGI
cagi = CommandAGI(api_key="cagi_…")
with cagi.launch("computer/software-engineer") as pc:
frame = pc.observe() # bytes of the latest screen frame
pc.step("click", x=640, y=400) # drive it
pc.step("type", text="hello")2. 作为文件——通过 WebDAV 挂载你的工作区。
你的 Drive（包含 .commandagi/ 目录树）会通过 WebDAV 挂载，所以任何能读文件的工具都能用——shell、rclone、你所用语言的文件 API。非常适合写脚本和粘合逻辑。
# mount your workspace over WebDAV, then it's just files
cat .commandagi/computers/<id>/screen.latest.jpg # latest screen frame (image bytes)
ffmpeg -i .commandagi/computers/<id>/screen.mjpeg out.mp4 # the screen, as video
tail -f .commandagi/robots/<id>/pose.jsonl # follow a robot's pose, live
jq . .commandagi/computers/<id>/screen.structure.latest.json # the current UI tree3. 实时线路——推送，追求低延迟。
// realtime: wss://api.commandagi.com/rt/thread/{threadId}?role=owner&token={cagi_key}
← { "t": "frame", "embodimentId": "…", "channelId": "screen",
"url": "data:image/png;base64,…" } // frames stream in
→ { "t": "control", "embodimentId": "…", "action": "type", "payload": { "text": "hello" } }驾驶它
一套统一的动作词汇会映射到设备物理上能做的任何事——一台笔记本电脑、一台云端虚拟机、一部手机、一台机器人。通过 SDK（step/act）或 WebSocket（control）发送动作。
- 计算机 / 手机：
click、double_click、right_click、move、drag、scroll、type、key（坐标空间为 1280×800）。 - 机器人 / 仿真：
move、back、turn、stop、reset、joint、pose、gripper。
在屏幕上绘图——那个可写的文件
一台计算机或手机还会暴露一个可写的文件，display.jsonl。其他文件是你读取的东西，而这一个你要写入——每一行都是一次在设备上绘图的操作：在实时界面上叠加一条提示、呈现一个 HTML/白板场景，或者说话。这就是一个智能体展示它的工作，或向一个人问候的方式。
# a computer/phone screen is a WRITABLE file — write an op, it draws
echo '{ "op": "say", "text": "Hi — I can help with that." }' >> display.jsonl
echo '{ "op": "scene", "scene": { "kind": "html", "html": "<h1>Welcome</h1>" } }' >> display.jsonl其他一切也都是文件
这个模式还在延续：一台机器自己的端口（一个串口设备、一个 USB 外设、一个本地 TCP 端口）会以读写文件的形式出现在 dev/ 下，每台设备的 details.json 会告诉你它是什么、物理上位于何处。对其中任何一个的访问都只是对该文件的一次权限授予——没有任何定制的特殊逻辑。