两级时间：会话起点 + 相对偏移 Two-level time: session origin plus relative offset

每个采集会话在元数据中记录一个绝对起始时间（UTC，毫秒精度），每帧只携带相对该起点的毫秒偏移。这样做的原因有两个： Each acquisition session records one absolute start time (UTC, millisecond precision) in its metadata, and every frame carries only a millisecond offset relative to that origin. There are two reasons:

• 省空间：帧内只放 4 字节偏移，而不是 8 字节绝对时间——对上百万帧的会话是显著节省。 Space: a 4-byte offset per frame rather than an 8-byte absolute timestamp — a substantial saving across sessions of millions of frames.
• 抗漂移：设备 RTC 的绝对精度有限（技术要求允许 24 h 内误差 ≤5 min），但相对偏移由高稳定时钟源产生，精度远高于绝对时间。数据内部的时间关系因此始终可靠。 Drift immunity: the device RTC has limited absolute accuracy (the technical requirement permits ≤5 min drift per 24 h), but relative offsets come from a high-stability clock and are far more precise. Internal timing relationships therefore remain reliable throughout.

采样间隔的表达方式 How the sampling interval is expressed

元数据中同时给出浮点间隔与精确分数形式（分子 / 分母）。分数形式的分母取 2 的整数次幂，便于用移位与整数运算精确重建每一帧的时间，完全避免浮点累积误差。 Metadata provides both a floating-point interval and an exact fractional form (numerator / denominator). The denominator is a power of two so frame times can be reconstructed exactly with shifts and integer arithmetic, eliminating floating-point accumulation error.

U 盘目录结构USB-drive directory structure

/
├── sub-S005/                  # subject ID (subject-level)
│   ├── ses-20260927/          # session (session-level)
│   │   ├── META.BIN           # metadata snapshot
│   │   ├── F1_ecg.bin         # 16 B frames @512/1024 Hz
│   │   ├── F2a_bioz.bin       # 16 B frames @16 Hz
│   │   ├── F2b_ppg_imu.bin    # 64 B frames @128 Hz
│   │   ├── F3_slow.bin        # 16 B frames @1 Hz / events
│   │   └── session.log         # human-readable event log
│   └── ses-20260928/
│       └── …
└── sub-UNKNOWN/               # when no subject ID was set

目录层级采用"受试者 → 会话"两段式，命名规则与主流科研数据组织的习惯一致，便于批量导入与脚本遍历。未设置受试者编号时落入 sub-UNKNOWN，事后可重命名而无需改动文件内容。 The two-level subject → session hierarchy follows common research data organisation conventions, easing bulk import and scripted traversal. When no subject ID is set, data lands in sub-UNKNOWN and can be renamed later without touching file contents.

META.BIN 元数据快照META.BIN metadata snapshot

科研可复现的关键：把"当时设备处于什么状态"完整记录下来。 Reproducibility hinges on recording exactly what state the device was in.

核心抽象Core abstractions

# SampleFrame — the single truth source on the PC side
class SampleFrame:
    t_utc_ms:  int          # absolute UTC time (ms)
    t_ms:      int          # offset from session origin
    channels:  dict[int, float]   # ChID -> value
    quality:   int          # quality bitmap (0x70)
    marker:    int          # event marker (0x60)

# FrameSource — abstract, two concrete implementations
class FrameSource:            # iterable of SampleFrame
    ...

class BluetoothSource(FrameSource):   # live / .ftraw
    ...

class UDiskSource(FrameSource):       # .bin files
    ...

用法：换数据源，不改算法 Usage: swap the source, keep the algorithm

from ft_core import UDiskSource, BluetoothSource

# Option A — read from a USB drive dump
src = UDiskSource("E:/sub-S005/ses-20260927")

# Option B — read from a BLE session capture
# src = BluetoothSource("capture.ftraw")

# Downstream is identical for both
for frame in src:
    ecg   = frame.channels[0x01]
    eda   = frame.channels[0x10]
    ppg   = frame.channels[0x20]
    # ... your algorithm here, unchanged