用户级设置是当前工作站上的可选部署偏好。它不是 Run 配置，不会编译进
ExecutionPlan，也不会写进 Lock 文件。
默认状态
规范默认状态是不存在用户级配置文件。读取设置不会创建文件。只要文件不存在，且
没有对应的 FASTSIM_* 环境变量覆盖，FastSim 就保持该功能加入前的行为：
- Run 与 Project 配置仍是仿真语义的唯一输入；
- 只有启用的插件请求
run.output时，CLI 才默认使用./outputs； - Project Cache、Registry、网络、GPU 和 CLI 展示的原默认值均不改变。
只有用户明确执行 settings set 或 settings import 时才会创建文件。删除最后一项已存
设置后，文件也会被删除，重新回到零配置状态。
路径与优先级
默认路径如下：
| 平台 | 路径 |
|---|---|
| Linux | $XDG_CONFIG_HOME/fastsim/config.toml，未设置时为 ~/.config/fastsim/config.toml |
| macOS | ~/Library/Application Support/FastSim/config.toml |
| Windows | %APPDATA%\FastSim\config.toml |
托管部署或测试可用 FASTSIM_SETTINGS_FILE 选择其他文件；单次设置命令可使用
fastsim settings --file PATH ...。
有效值的优先级是：
- 当前命令显式传入的参数；
- 该设置对应的环境变量；
- 用户级配置文件；
- FastSim 原有默认值。
Project 显式字段仍优先于用户级回退值。例如 Project 已经声明 cache_dir 时，
paths.cache_root 不会替换它。
支持的设置项
| 设置项 | 环境变量 | 实际使用位置 |
|---|---|---|
outputs.root |
FASTSIM_OUTPUT_ROOT |
fastsim run 与 fastsim outputs |
paths.cache_root |
FASTSIM_CACHE_ROOT |
Project 未声明 Cache 时的资源缓存根目录 |
paths.temp_root |
FASTSIM_TEMP_ROOT |
CLI 进程产生的临时文件 |
registries.sources |
FASTSIM_REGISTRIES |
附加本地或固定摘要的 HTTPS Registry Index |
network.offline |
FASTSIM_OFFLINE |
资源解析器的离线策略 |
network.timeout_s |
FASTSIM_NETWORK_TIMEOUT_S |
资源下载超时 |
cli.language |
FASTSIM_LANGUAGE |
面向操作者的语言偏好 |
cli.color |
FASTSIM_COLOR |
auto、always 或 never 配色策略 |
cli.output_format |
FASTSIM_OUTPUT_FORMAT |
rich、plain 或 json 输出格式 |
cli.log_level |
FASTSIM_LOG_LEVEL |
CLI 日志级别 |
compute.gpu_ids |
FASTSIM_GPU_IDS |
fastsim run 默认使用的 CUDA_VISIBLE_DEVICES |
compute.max_workers |
FASTSIM_MAX_WORKERS |
输出校验、Viewer 缓存准备等显式并行任务 |
server.default_url |
FASTSIM_SERVER_URL |
fastsim server status |
viewer.cache_root |
FASTSIM_VIEWER_CACHE_ROOT |
fastsim outputs open 的预解析帧缓存 |
viewer.cache_limit_gb |
FASTSIM_VIEWER_CACHE_LIMIT_GB |
Viewer Cache 容量上限 |
credentials.registry_token_env |
— | 保存 Registry Bearer Token 的环境变量名称 |
配置文件永远不保存 Token 本身。Authorization 只会发给已配置的 HTTPS Registry Origin； 重定向改变 Origin 时会自动移除。
本地 Registry 会规范化成绝对路径。远程 Registry 必须固定内容摘要：
fastsim settings set registries.sources \
'https://registry.example/index.yaml#sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
fastsim settings set credentials.registry_token_env FASTSIM_PRIVATE_REGISTRY_TOKEN
通过环境变量提供多个 Registry 时，请把 FASTSIM_REGISTRIES 写成字符串 JSON 数组；
单个固定摘要的 HTTPS URL 可以直接填写。
Backend、Physics Rate、Seed、实体、相机、插件、录制流和 Codec 等仿真语义不能写在这里。 它们应继续写在 Run、Scenario、组件或插件配置中，保证 Lock 可复现。
命令
fastsim settings path
fastsim settings list
fastsim settings list --effective
fastsim settings get outputs.root
fastsim settings describe
fastsim settings describe compute.gpu_ids
fastsim settings set outputs.root /data/fastsim/outputs
fastsim settings unset outputs.root
fastsim settings validate
fastsim settings export --to yaml --output fastsim-settings.yaml
fastsim settings import fastsim-settings.yaml
fastsim settings import fastsim-settings.yaml --replace
fastsim settings reset --yes
每条命令均可在子命令后添加 --json。path、list、get、describe、validate
和 export 是只读操作。reset 与输出删除命令必须明确传入 --yes，不会把破坏性确认
隐藏在交互式提示里。
写入采用同目录临时文件、fsync 与原子替换，文件权限为 0600。FastSim 新建的设置
目录使用 0700，但绝不会修改已有父目录的权限。