命令行启动

fastsim 是 FastSim 的命令行入口，提供仿真启动、配置校验、配置检查、录制分析与调试等操作。支持 YAML、JSON 和 .sim 三种配置格式。

bash

fastsim <command> [--arg value ...]
fastsim --help         # 查看所有命令
fastsim <command> --help  # 查看单个命令的参数说明

命令分组一览

命令按用途分为四组，与 TUI 侧边栏分组一致：

Simulation — 仿真启动

`launch_simulation`

启动仿真。配置文件中声明的所有扩展（录制、Benchmark、遥操作、管线等）将在启动时自动 enable。

bash

# 启动仿真
fastsim launch_simulation --config path/to/config.yaml

# 使用 .sim 格式配置
fastsim launch_simulation --config path/to/config.sim

# 通过 --set 覆盖配置字段
fastsim launch_simulation --config path/to/config.yaml --set simulation.dt=0.01

# 禁用状态监控面板
fastsim launch_simulation --config path/to/config.yaml --monitor no

参数	说明
`--config`	配置文件路径（YAML / JSON / `.sim`）
`--set`	覆盖配置字段（格式 `key.path=value`），可多次使用
`--monitor`	是否启用 TUI 状态监控面板（默认 `yes`）

任务执行已迁移到 task_executor 扩展，不再使用 --run_task 参数。在配置中启用 task_executor 扩展即可自动执行任务。

Config Tools — 配置工具

`validate_configuration`

校验配置文件的合法性，包括字段类型、必填项、路径存在性与 stereotype 注册情况。校验结果以格式化表格输出，按配置块分组显示每个字段的状态（通过/警告/错误）。

bash

fastsim validate_configuration --config path/to/config.yaml

`show_config`

将配置文件展开为完整结构并打印，包含所有默认值与继承字段。适合排查"配置写了但没生效"的问题。

bash

fastsim show_config --config path/to/config.yaml

`diff_config`

对比两个配置文件的差异，以表格形式显示字段的修改、新增和删除。如果配置使用了 FROM 继承，会先解析继承后再进行对比。

bash

fastsim diff_config config_a.yaml config_b.yaml

输出包含三列：字段路径、配置 A 的值和配置 B 的值，并用颜色标识变更类型。

`inspect_scene`

以格式化表格检查配置文件中的场景实体：机器人、物体、传感器、光源，显示每个实体的 stereotype、asset_path、position 等关键字段。

bash

fastsim inspect_scene --config path/to/config.yaml

`inspect_task`

检查任务配置的详情：按顺序列出所有 action（动作类型、目标物体、机械臂等）和最终 goal 列表。

bash

fastsim inspect_task --config path/to/config.yaml

`inspect_extension`

检查扩展配置：列出所有启用的扩展实例及其参数（observer 列表、recorder 配置等）。

bash

fastsim inspect_extension --config path/to/config.yaml

Recording — 录制分析

`inspect_recording`

检查并校验录制目录或 HDF5 文件。显示 observer 分组、帧数、数据类型、文件大小，并检测缺失帧和不完整帧。可选预览某一帧的 JSON 摘要和 numpy 数组维度信息。

bash

# 检查录制目录
fastsim inspect_recording --recording_path path/to/recording/

# 检查 HDF5 文件
fastsim inspect_recording --recording_path path/to/record.h5

# 预览第 10 帧
fastsim inspect_recording --recording_path path/to/record.h5 --frame 10

参数	说明
`--recording_path`	录制目录或 `.h5` 文件路径
`--frame`	预览指定帧索引（可选）

`plot_trajectory`

从 HDF5 录制文件中绘制轨迹曲线，直接在终端中渲染（基于 plotext）。支持预置模式和自定义列/时间范围筛选。

bash

# 使用预置模式绘制关节位置
fastsim plot_trajectory --query "record.h5 joint_pos"

# 指定 observer 和列范围
fastsim plot_trajectory --query "record.h5 joint_pos @Franka cols:0,1,2"

# 指定时间范围（秒）
fastsim plot_trajectory --query "record.h5 ee_pos t:2-5"

参数	说明
`--query`	查询字符串：`<h5_file> [preset] [@observer] [cols:0,1,2] [t:start-end]`

内置预置模式（preset）：

预置	数据含义
`joint_pos`	关节位置
`joint_vel`	关节速度
`joint_acc`	关节加速度
`joint_target`	关节目标位置
`ee_pos`	末端执行器位置
`ee_quat`	末端执行器四元数
`ee_euler`	末端执行器欧拉角
`obj_pos`	物体位置
`obj_rot`	物体旋转
`gripper`	夹爪状态

Registry — 注册表查看

`show_registery`

打印当前已注册的所有 stereotype（Config 类与 Model 类的映射表）。

bash

fastsim show_registery

注意：结果依赖 general.scan_project 是否启用。若自定义 stereotype 未出现，检查配置中 scan_project: true 是否已设置。

`show_static_api`

打印所有通过 @apiclass 注册的 HTTP 路由列表（即启用 server 扩展后可访问的所有 REST API 端点）。

bash

fastsim show_static_api

`show_stereotype_params`

打印指定 stereotype 对应配置类的所有字段与默认值。

bash

fastsim show_stereotype_params --stereotype_name camera
fastsim show_stereotype_params --stereotype_name record
fastsim show_stereotype_params --stereotype_name benchmark

典型工作流

bash

# 1. 校验配置
fastsim validate_configuration --config my_config.yaml

# 2. 查看展开后的完整配置（含默认值）
fastsim show_config --config my_config.yaml

# 3. 检查场景/任务/扩展细节
fastsim inspect_scene --config my_config.yaml
fastsim inspect_task --config my_config.yaml

# 4. 对比两个配置的差异
fastsim diff_config base_config.yaml override_config.yaml

# 5. 启动仿真
fastsim launch_simulation --config my_config.yaml

# 6. 仿真结束后分析录制数据
fastsim inspect_recording --recording_path datasets://runs/run001/
fastsim plot_trajectory --query "datasets://runs/run001/record.h5 joint_pos"