数据集与分析范围

普通分析只需用dataset.name给这组输入取名；不需要再填写entity、session或时间范围。省略时两个身份沿用name，时间范围取实际输入。它不读取文件；文件由sources提供。一次分析配置描述一个对象的一次共同会话，多次独立试验使用批量任务。这些标识会出现在结果中，用于区分和追溯计算。

配置位置与示例

下面是根级片段，应与sources、signals等并列；完整文件见快速开始。

应用位置：以analysis.yaml为基础，找到现有根级 dataset: 并用下面整段替换；其他段保持原样。dataset 是映射，不是列表，前面不加 -，也不要追加第二个同名父字段。

yaml

dataset:              # 设置本次分析名称及可选的对象、会话和时间范围
  name: bench_run_01  # 命名本次分析数据集；名称写入结果身份字段

只有要区分设备与采集批次时才填写entity和session。例如一个设备有多次采集，可以另设设备名和采集批次名；这些是结果标签，不决定读取哪份文件，也不证明多来源已同步。只分析部分时间时才增加 domain，见下面示例。字段表供特殊需求查询，不是需要逐项填写的清单。

只分析2到5秒

将 analysis.yaml 的原 dataset 段替换为：

yaml

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

字段表把这两个位置写作 dataset.domain.start 和 dataset.domain.end：先找到 dataset，再找它下面的 domain，最后找 start 或 end。实际键只有 dataset、domain、start、end，不要把点号连写进字段名。多行写法与 domain: {start: 2s, end: 5s} 含义相同；完整对照及缩进规则见配置文件语法。

随手册提供的 ASC 输入在 0、1、3、4 秒记录功率 2、4、8、10W，6 秒还有一条无关报文，说明文件观测到6秒。选择 2–5 秒后：2–3 秒使用此前1秒更新的4W，3–4 秒为8W，4–5 秒为10W，因此能量为 4×1＋8×1＋10×1＝22J。范围内真实样本只有3秒的8W和4秒的10W，样本均值为9W；时间均值为22/3W。2秒的保持值参与积分，不算新增样本。这些数字对应该合成ASC文件，不是任意输入的预期。

字段参考

完整路径	类型、必填与默认	用途及约束
`dataset.name`	字符串，必填	给本组输入及结果设置名称。由项目自行命名，例如两次试验分别填`run_01`和`run_02`；格式见下方标识规则。程序保存这个值，不从文件名生成。
`dataset.entity`	字符串，可省略，默认同name	标明正在分析哪个设备或样品。取自设备台账或试验记录，例如`motor_01`；程序不会根据这个名字选择DBC或换算单位。
`dataset.session`	字符串，可省略，默认同name	标明本次共同采集会话。取自采集记录或由项目命名，例如`warmup`；同一次联合分析使用一个会话，但仍需另外校准各来源时间。
`dataset.domain`	映射，可省略	控制本次请求分析哪段时间。按希望检查的试验范围填写`start`和`end`两项；省略时使用本次输入实际观测范围。`null`和`{}`都不能表示分析整个文件。
`dataset.domain.start`	时间字符串，domain存在时必填	设置请求起点，包含该时刻。按校准后的来源时间填写：相对时间例如`0s`，绝对时间例如`2026-01-01T08:00:00+08:00`；不要填未经来源offset修正的另一个时钟读数。
`dataset.domain.end`	时间字符串，domain存在时必填	设置请求终点，连续计算不包含这个端点。按分析目标填写不早于start的时间；0s到6s请求6秒，相等表示零时长。恰好末端的真实点可用于边界判断，不增加持续时间。
`dataset.metadata`	映射，可省略，默认`{}`	保存这一组数据的附加说明。键和值由项目定义，例如`{operator: tester_01}`；省略不记录备注，不改变输入、时间或计算。

前三个标识使用英文字母或下划线开头，后接字母、数字或下划线；不能使用Python关键字以及表达式保留名abs、isclose等。空字符串、空值和数字均不能替代标识。

0s是带单位的时间字符串，0是数字，null是空值，三者不同。输入CSV时间列可以是裸数字，由sources[].time.unit解释；分析范围端点必须明确时间表示。来源time.offset先修正输入时间，再与这里的范围比较。

请求范围与实际观测范围

请求[0,12)秒，但输入只观测到8秒，并不意味着8～12秒也有有效数据。程序保留请求范围和缺失信息，valid_for也不能扩展实际观测范围。结果是否接受部分数据由执行设置及计算设置控制。

省略分析范围

普通分析和逐消息累计都可省略domain。程序在同一次读取中确定实际首末时间，不先扫描一遍文件，也不为了求范围保存整份历史。规则、序列、窗口、普通计算和按需导出都使用这一范围。

例如来源A记录到8秒、来源B记录到5秒，会话保留到8秒，B的缺测独立处理。所有输入为空时不生成事件，会话统计返回空值并注明no_observation；不会凭空生成“始终成立”的事件。只有一条记录、没有更晚观测时，首末时间相同，半开范围内没有样本，也没有可累计时长；不会人为延长到其有效期结束。

需要只分析某段时再填domain；null和空对象都不是省略。跨来源时间是否已对齐仍由来源时间声明和实际同步依据决定，不能靠默认范围自动校时。