调整 Autocal 标定记录格式与目录命名

将人工参考载荷按档位区间保存，重排帧字段并明确界面操作。已通过相关测试、代码和文档检查。

shared/src/orisys_app_shared/record/experiment.py

@@ -46,7 +46,7 @@ from orisys_app_shared.record.video_writer import VideoSegments
 
 logger = logging.getLogger(__name__)
 
-RECORD_FORMAT_VERSION = "1.3"
+RECORD_FORMAT_VERSION = "1.4"
 
 # Lifecycle states. ``failed`` and ``stopped`` are terminal; a recorder that has
 # not reached a terminal state must not be reused.
@@ -80,17 +80,17 @@ FORCES_HEADER = (
 )
 FRAMES_HEADER = (
     "frame_id",
+    "source_frame_id",
     "t_rel_s",
+    "t_host_mono_ns",
+    "t_host_utc_ns",
     "acquired_at",
+    "time_basis",
+    "media_time_ms",
     "segment",
     "segment_frame",
     "in_video",
     "dropped",
-    "t_host_mono_ns",
-    "t_host_utc_ns",
-    "source_frame_id",
-    "time_basis",
-    "media_time_ms",
     "capture_dropped",
 )
 #: ``frame_id`` was added so an operator action can be tied to a frame position.
@@ -345,8 +345,14 @@ class ExperimentRecorder:
         calibration_id: str = "",
         calibration_version: str = "",
         preroll=(),
+        directory_label: str = "",
     ) -> Path:
         """Create the experiment directory and start the writer thread."""
+        if directory_label and (
+            directory_label in {".", ".."}
+            or not all(char.isalnum() or char in "-_" for char in directory_label)
+        ):
+            raise ValueError("directory label must contain only letters, numbers, - or _")
         # A previous writer that has not reached a terminal state still owns the
         # files and the statistics; reusing it would silently mix two sessions.
         if self._thread is not None and self._thread.is_alive():
@@ -363,7 +369,8 @@ class ExperimentRecorder:
             # lifecycle checks, so caller mutations cannot change this run.
             self.config = replace(config if config is not None else self.config)
         stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-        directory = Path(root) / f"{stamp}_session{session_id:04d}_{uuid4().hex}"
+        label = f"_{directory_label}" if directory_label else ""
+        directory = Path(root) / f"{stamp}{label}_session{session_id:04d}_{uuid4().hex}"
         try:
             directory.mkdir(parents=True, exist_ok=False)
         except Exception as exc:  # noqa: BLE001 - reported to the caller
@@ -1141,17 +1148,17 @@ class _SessionWriter:
         self._frames[1].writerow(
             (
                 sample.frame_id,
+                sample.source_frame_id if sample.source_frame_id is not None else "",
                 repr(t_rel),
+                sample.capture_mono_ns or "",
+                sample.capture_utc_ns or "",
                 acquired,
+                sample.time_basis,
+                format_value(sample.media_time_ms),
                 segment,
                 segment_frame,
                 1 if segment else 0,
                 0,
-                sample.capture_mono_ns or "",
-                sample.capture_utc_ns or "",
-                sample.source_frame_id if sample.source_frame_id is not None else "",
-                sample.time_basis,
-                format_value(sample.media_time_ms),
                 sample.capture_dropped,
             )
         )
@@ -1170,7 +1177,7 @@ class _SessionWriter:
             wall_t or time.time(), timezone.utc
         ).isoformat(timespec="milliseconds")
         self._frames[1].writerow(
-            (frame_id, repr(t_rel), acquired, 0, 0, 0, 1, "", "", "", "", "", "")
+            (frame_id, "", repr(t_rel), "", "", acquired, "", "", 0, 0, 0, 1, "")
         )
         self.gap_rows += 1