配置文件语法

分析配置推荐保存为 UTF-8 的 .yaml 或 .yml 文件。先从快速开始下载完整的 analysis.yaml，再修改需要的部分。下面说明怎样读懂它的层级；JSON 使用同一套字段，表示方法不同。

先认识字段、映射和列表

本手册每深入一层缩进 2 个空格。同一层对齐，用空格，不要使用 Tab 制表符。# 后面是说明文字，不参与计算。编辑器可以开启“显示空白字符”，并把 Tab 键设为插入空格。

点号路径怎样变成实际配置

字段表中的 dataset.domain.start 是查阅位置，意思是“dataset 里面的 domain 里面的 start”。它不是需要原样填写的字段名。实际文件依靠缩进表达这三层关系。

要把现有 analysis.yaml 改为只分析 2–5 秒，找到原来的 dataset:，用下面整段替换；其他根级内容保留。不要在文件末尾再追加第二个 dataset:。

dataset:        # 设置本次分析名称及可选的对象、会话和时间范围
  name: energy  # 命名本次分析数据集；名称写入结果身份字段
  domain:       # 限定本次分析请求的起止时间；应与来源采用相同时间基准
    start: 2s   # 设置分析起点，包含该时刻；按希望分析的范围填写
    end: 5s     # 设置分析终点；连续时长不包含该端点，按希望分析的范围填写

这里 name 和 domain 都属于 dataset，所以缩进相同；start 和 end 属于 domain，再多缩进 2 个空格。只写 start: 2s 到文件根级，或写成 dataset.domain.start: 2s，都会因字段位置错误被拒绝。

下面是同一段配置的等价内联写法，用于认识花括号；初次编辑优先使用上面的多行写法。两种写法选一种替换原段，不要同时粘贴。

dataset:                        # 设置本次分析名称及可选的对象、会话和时间范围
  name: energy                  # 命名本次分析数据集；名称写入结果身份字段
  domain: {start: 2s, end: 5s}  # start：起点；end：终点（不含）；与上面的多行写法等价

{} 把一个映射写在一行，字段之间用逗号分开；它没有改变层级。这个范围在随手册提供的 ASC 数据上得到 22J，计算过程见分析范围示例。

列表中的每一项怎样写

以现有 analysis.yaml 为基础，用下段替换整个 calculations: 段。这会保留能量和样本均值两项计算；power 已在该文件的 signals 中声明。

calculations:               # 列出希望获得的统计或积分结果，每项独立选择范围和算法
  - name: energy            # 为这项计算结果取唯一名称；结果表用它区分计算项
    operation: integral     # 选择计算方法；本例将有效数值乘持续时间后累计，例如功率乘秒得到能量
    expr: power             # 指定参与计算的数值或信号表达式；引用前面已定义的信号
  - name: sample_average    # 为这项计算结果取唯一名称；结果表用它区分计算项
    operation: sample_mean  # 选择计算方法；本例对范围内有效真实样本等权求平均，每个样本计一次
    expr: power             # 指定参与计算的数值或信号表达式；引用前面已定义的信号

每个 - 开始一个计算项。项内的 name、operation、expr 对齐；operation 前不能再加 -，否则会被理解成另一个列表项。

字段表中的 sources[] 表示“来源列表中的每一项”，sources[0] 表示第一项（编号从 0 开始）；这些方括号也属于查阅路径，不是实际字段名。例如 sources[].time.unit 是每个来源下面 time 的 unit。另一方面，写在值的位置的 [power] 是 YAML 的单行列表，与换行后写 - power 等价。

值、引号与表达式

true、false 是布尔值；yes、no 是字符串。0 是数字，0s 是带单位的时间文本，null 是空值。省略字段、填写 null、空列表和 0 的含义不同，不能互相替换。

包含“冒号后接空格”、以特殊字符开头或需要保留数字文本时，加引号。例如 DBC 通道键 '1'、预设版本 '1'。日期和 500ms、2s 这样的时长保留为文本；具体字段接受哪种值，仍由字段规则决定。

表达式另有语法。例如 condition: enabled == True 中，整段 enabled == True 是表达式文本，True 是表达式中的布尔文字。它与 YAML 本身的 true 分开解释。表达式不会执行任意 Python 代码，支持内容见表达式。

配置、API与Schema要分开读

支持的YAML范围

“YAML 1.2 受限子集”指支持常用数据结构，但拒绝会产生歧义或执行额外操作的写法。

若使用版本指令，只能声明 YAML 1.2。日期不会自动变成 Python 日期对象。数字键要写成加引号的字符串。

各种版本字段

公共定义文件只放允许导入的 sources、signals、derived，不填写 config_version，详见公共定义。