CLI 与输出参考

命令族

自动化与 CI 应优先使用各命令的 --json 结果，并根据进程退出码判断成功。面向人的彩色文本不应被正则解析为协议。

fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml scenario.scene.robots.arm.use
fastsim config lock run.yaml --output run.lock --json

plugins list 与 plugins inspect 读取编译元数据而不导入插件代码；plugins diagnose 只导入 Run 选中的 factory，用于定位安装、entry point 或契约错误。

输出操作始终限制在解析后的可信根中。清理前先 inspect；不要把用户主目录、项目根或未解析环境变量作为递归删除目标。输出完整性由 staging、校验、原子发布与失败清理共同保证。

更细的输出行为见录制、回放与输出，字段见配置参考。

建议的自动化门禁

CI 在无后端阶段依次执行配置 validate、关键值 explain、Lock 生成/校验和插件元数据 inspect；通过后才进入安装 wheel 与真实 Provider 的运行门禁。保存 JSON、退出码、Plan/Lock digest 和安装发行版本。

面向人的 rich/plain 输出可能随展示改进而变化，脚本不应对颜色或句子做正则。机器调用使用 --json 和稳定 code；破坏性命令仍需要显式确认参数。

有界读取与安全清理

普通 outputs list 只读取有界文件元数据；--verify 校验当前结果页；inspect、verify 与 open 按需调用独立 Viewer。未使用这些操作时，Core 不引入 FSR 解析、相机解码或 Viewer cache 开销。

目标可以是输出根内相对路径或明确的绝对 .fsr。相对路径不能逃逸输出根，符号链接和特殊文件被拒绝，只写文件名时必须唯一匹配。

安全清理流程。 先 outputs root 确认解析后的可信根，再 list/inspect 核对目标，最后执行带 --yes 的准确 remove/clean。remove 只删除明确命名的普通文件；clean 只处理超过阈值的 .incomplete，不会把完整 FSR 当临时文件清理。

不要通过 shell 通配符绕过 CLI 的边界，也不要把用户目录或项目根设置成宽泛输出根。自动保留策略应在运维层明确，而不是定期递归删除未知目录。

退出码与错误记录

命令失败时保留完整命令、Core/插件版本、JSON body 与退出码。对于 run，额外保存最终 Application state、failures 与输出 finalizer；对于 plugin diagnose，记录 distribution、entry point 与 factory 错误；对于 verify-lock 或 output verify，保留预期与实际摘要/结构错误。

需要精确参数时以 fastsim <command> --help 和当前版本源码为准，本页解释命令族的稳定用途与安全边界。