diff --git a/backend/operators/builtin/package/operator.py b/backend/operators/builtin/package/operator.py
index 53cdb3a1..55cc8510 100644
--- a/backend/operators/builtin/package/operator.py
+++ b/backend/operators/builtin/package/operator.py
@@ -2,6 +2,8 @@
from __future__ import annotations
import hashlib
+import bisect
+import csv
import json
import pathlib
import re
@@ -188,6 +190,8 @@ def _camera_collection_id(value: Any) -> str:
def _right_video_artifacts(inputs: list[dict[str, Any]]) -> list[dict[str, Any]]:
artifacts: list[dict[str, Any]] = []
for artifact in inputs:
+ if str(artifact.get("type", "")).strip().lower() != "video":
+ continue
port = str(artifact.get("portId") or artifact.get("portName") or "").strip()
data = artifact.get("data") if isinstance(artifact.get("data"), dict) else {}
transform_chain = data.get("transformChain") if isinstance(data.get("transformChain"), list) else []
@@ -246,6 +250,149 @@ def _materialize_input_video(
return resolved
+def _materialize_input_file(artifact: dict[str, Any], output: pathlib.Path, helpers: HelperMap) -> pathlib.Path:
+ materialize = helpers.get("source_path_from_item")
+ if not callable(materialize):
+ raise RuntimeError("synchronized delivery cannot materialize a sidecar file")
+ source_ref = helpers.get("source_ref_from_artifact")
+ source = source_ref(artifact) if callable(source_ref) else artifact.get("source", {})
+ name = str(artifact.get("name") or "sidecar.bin").strip()
+ resolved = pathlib.Path(materialize({"source": source if isinstance(source, dict) else {}, "path": str(artifact.get("path", ""))}, name, output, {}))
+ if not resolved.is_file() or resolved.stat().st_size <= 0:
+ raise RuntimeError(f"synchronized delivery sidecar is unavailable: {name}")
+ return resolved
+
+
+def _sidecar_artifacts(inputs: list[dict[str, Any]], ports: set[str]) -> list[dict[str, Any]]:
+ return [artifact for artifact in inputs if str(artifact.get("portId") or artifact.get("portName") or "").strip() in ports]
+
+
+def _matching_sidecar(collection_id: str, candidates: list[dict[str, Any]], marker: str = "") -> dict[str, Any]:
+ filtered = [item for item in candidates if not marker or marker in str(item.get("name") or "").lower()]
+ matches = [item for item in filtered if _camera_collection_id(item) == collection_id]
+ if len(matches) == 1:
+ return matches[0]
+ if len(filtered) == 1:
+ return filtered[0]
+ if not matches:
+ raise RuntimeError(f"no {marker or 'sidecar'} file matches collection {collection_id}")
+ raise RuntimeError(f"multiple {marker or 'sidecar'} files match collection {collection_id}")
+
+
+def _clean_csv_cell(value: Any) -> str:
+ return str(value or "").strip().strip("\ufeff").strip("\t").strip()
+
+
+def _read_rows(path: pathlib.Path) -> tuple[list[str], list[list[str]]]:
+ lines = path.read_text(encoding="utf-8-sig").splitlines()
+ if not lines:
+ raise RuntimeError(f"sidecar CSV is empty: {path.name}")
+ delimiter = "," if "," in lines[0] else "\t"
+ parsed = list(csv.reader(lines, delimiter=delimiter))
+ header = [_clean_csv_cell(value) for value in parsed[0]]
+ rows = [[_clean_csv_cell(value) for value in row] for row in parsed[1:] if any(_clean_csv_cell(value) for value in row)]
+ return header, rows
+
+
+def _read_pts(path: pathlib.Path) -> list[int]:
+ header, rows = _read_rows(path)
+ normalized = {name.lower(): index for index, name in enumerate(header)}
+ if "timestamp_us" not in normalized:
+ raise RuntimeError(f"PTS CSV must contain timestamp_us: {path.name}")
+ column = normalized["timestamp_us"]
+ values: list[int] = []
+ for row in rows:
+ try:
+ value = int(row[column])
+ except (IndexError, ValueError) as exc:
+ raise RuntimeError(f"PTS CSV contains an invalid timestamp_us: {path.name}") from exc
+ if values and value <= values[-1]:
+ raise RuntimeError(f"PTS CSV timestamp_us must be strictly increasing: {path.name}")
+ values.append(value)
+ if not values:
+ raise RuntimeError(f"PTS CSV has no frame timestamps: {path.name}")
+ return values
+
+
+def _read_imu(path: pathlib.Path) -> list[dict[str, Any]]:
+ header, rows = _read_rows(path)
+ indexes = {name.lower(): index for index, name in enumerate(header)}
+ required = {"timestamp_us", "x", "y", "z", "type"}
+ if not required.issubset(indexes):
+ raise RuntimeError(f"IMU CSV must contain timestamp_us,x,y,z,type: {path.name}")
+ result: list[dict[str, Any]] = []
+ previous = -1
+ for row in rows:
+ try:
+ timestamp = int(row[indexes["timestamp_us"]])
+ kind = row[indexes["type"]].lower()
+ values = [float(row[indexes[key]]) for key in ("x", "y", "z")]
+ except (IndexError, ValueError) as exc:
+ raise RuntimeError(f"IMU CSV contains an invalid row: {path.name}") from exc
+ if kind not in {"accel", "gyro"} or timestamp < previous:
+ raise RuntimeError(f"IMU CSV type/timestamp ordering is invalid: {path.name}")
+ previous = timestamp
+ result.append({"timestamp_us": timestamp, "x": values[0], "y": values[1], "z": values[2], "type": kind})
+ if not result:
+ raise RuntimeError(f"IMU CSV has no samples: {path.name}")
+ return result
+
+
+def _ffprobe_frame_count(path: pathlib.Path) -> int:
+ completed = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_frames", "-show_entries", "stream=nb_read_frames", "-of", "default=nokey=1:noprint_wrappers=1", str(path)], capture_output=True, text=True, check=False)
+ try:
+ count = int(completed.stdout.strip())
+ except ValueError as exc:
+ raise RuntimeError(f"cannot determine decoded video frame count: {path.name}") from exc
+ if completed.returncode != 0 or count <= 0:
+ raise RuntimeError(f"cannot determine decoded video frame count: {path.name}")
+ return count
+
+
+def _write_frame_segment(source: pathlib.Path, destination: pathlib.Path, start_frame: int, end_frame: int) -> None:
+ if shutil.which("ffmpeg") is None or shutil.which("ffprobe") is None:
+ raise RuntimeError("synchronized delivery requires ffmpeg and ffprobe")
+ if start_frame < 0 or end_frame <= start_frame:
+ raise RuntimeError("synchronized video frame range is empty")
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ expression = f"trim=start_frame={start_frame}:end_frame={end_frame},setpts=PTS-STARTPTS"
+ completed = subprocess.run(["ffmpeg", "-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-i", str(source), "-an", "-vf", expression, "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-pix_fmt", "yuv420p", "-movflags", "+faststart", str(destination)], capture_output=True, text=True, check=False)
+ if completed.returncode != 0 or not destination.is_file() or destination.stat().st_size <= 0:
+ raise RuntimeError(f"synchronized frame-accurate cut failed: {(completed.stderr or completed.stdout).strip()[:800]}")
+
+
+def _write_pts_slice(path: pathlib.Path, timestamps: list[int], start_index: int, end_index: int) -> dict[str, Any]:
+ selected = timestamps[start_index:end_index]
+ if not selected:
+ raise RuntimeError("synchronized PTS slice is empty")
+ with path.open("w", encoding="utf-8", newline="") as handle:
+ writer = csv.writer(handle)
+ writer.writerow(["frame_index", "timestamp_ms", "clip_time_ms"])
+ origin = selected[0]
+ for index, value in enumerate(selected):
+ writer.writerow([index, round(value / 1000), round((value - origin) / 1000)])
+ return {"name": path.name, "sha256": _sha256_file(path), "bytes": path.stat().st_size, "rowCount": len(selected), "firstTimestampUs": selected[0], "lastTimestampUs": selected[-1]}
+
+
+def _write_imu_slice(path: pathlib.Path, rows: list[dict[str, Any]], start_us: int, end_us: int) -> dict[str, Any]:
+ selected = [row for row in rows if start_us <= int(row["timestamp_us"]) < end_us]
+ if not selected:
+ raise RuntimeError("synchronized IMU slice is empty")
+ by_timestamp: dict[int, set[str]] = {}
+ for row in selected:
+ by_timestamp.setdefault(int(row["timestamp_us"]), set()).add(str(row["type"]))
+ if any(types != {"accel", "gyro"} for types in by_timestamp.values()):
+ raise RuntimeError("synchronized IMU slice contains an unpaired accel/gyro timestamp")
+ with path.open("w", encoding="utf-8", newline="") as handle:
+ writer = csv.writer(handle)
+ writer.writerow(["timestamp_ms", "clip_time_ms", "x", "y", "z", "type"])
+ origin = int(selected[0]["timestamp_us"])
+ for row in selected:
+ timestamp = int(row["timestamp_us"])
+ writer.writerow([round(timestamp / 1000), round((timestamp - origin) / 1000), row["x"], row["y"], row["z"], row["type"]])
+ return {"name": path.name, "sha256": _sha256_file(path), "bytes": path.stat().st_size, "sampleCount": len(selected), "timestampCount": len(by_timestamp), "firstTimestampUs": int(selected[0]["timestamp_us"]), "lastTimestampUs": int(selected[-1]["timestamp_us"])}
+
+
def _write_verified_segment(
source: pathlib.Path,
destination: pathlib.Path,
@@ -269,7 +416,7 @@ def _write_verified_segment(
}
-def _validate_final_acceptance(item: dict[str, Any]) -> None:
+def _validate_final_acceptance(item: dict[str, Any]) -> dict[str, Any]:
evidence = item.get("finalAcceptance") if isinstance(item.get("finalAcceptance"), dict) else {}
canonical = str(evidence.get("canonical", ""))
digest = str(evidence.get("sha256", "")).lower()
@@ -279,6 +426,7 @@ def _validate_final_acceptance(item: dict[str, Any]) -> None:
raise RuntimeError("pre-package acceptance evidence SHA-256 does not verify")
if not str(evidence.get("confirmedByUserId", "")).strip():
raise RuntimeError("pre-package acceptance evidence has no confirmer identity")
+ return evidence
def _write_precise_final_segment(source: pathlib.Path, destination: pathlib.Path, start: float, end: float) -> None:
@@ -357,6 +505,23 @@ def _materialize_final_mp4(item: dict[str, Any], package_dir: pathlib.Path, help
return destination
+def _materialize_left_source(item: dict[str, Any], directory: pathlib.Path, helpers: HelperMap) -> pathlib.Path:
+ source_path = pathlib.Path(str(item.get("clipPath", "")).strip())
+ if source_path.is_file() and source_path.stat().st_size > 0:
+ return source_path
+ source = item.get("source") if isinstance(item.get("source"), dict) else {}
+ resolved = pathlib.Path(
+ helpers["source_path_from_item"](
+ {"source": source or {"path": str(item.get("clipPath", "")).strip()}},
+ str(item.get("sourceVideo") or pathlib.PurePosixPath(str(item.get("clipPath", ""))).name or "left-camera.mp4"),
+ directory,
+ )
+ )
+ if not resolved.is_file() or resolved.stat().st_size <= 0:
+ raise RuntimeError("left-camera video is unavailable for synchronized cropping")
+ return resolved
+
+
def _collect_unique_package_artifacts(
run_id: str,
node_id: str,
@@ -382,6 +547,90 @@ def _collect_unique_package_artifacts(
return artifacts
+def _copy_calibrations(inputs: list[dict[str, Any]], packages_root: pathlib.Path, output: pathlib.Path, helpers: HelperMap) -> list[dict[str, Any]]:
+ destination = packages_root / "calibration"
+ result: list[dict[str, Any]] = []
+ seen: set[str] = set()
+ for artifact in _sidecar_artifacts(inputs, {"calibrations"}):
+ name = str(artifact.get("name") or "").strip()
+ if not name or name in seen:
+ continue
+ seen.add(name)
+ source = _materialize_input_file(artifact, output / "_inputs", helpers)
+ destination.mkdir(parents=True, exist_ok=True)
+ target = destination / name
+ shutil.copy2(source, target)
+ result.append({"name": name, "path": f"calibration/{name}", "sha256": _sha256_file(target), "bytes": target.stat().st_size})
+ if not result:
+ raise RuntimeError("synchronized delivery requires camera/IMU calibration files")
+ return result
+
+
+def _synchronized_segment(
+ item: dict[str, Any],
+ clip_id: str,
+ package_dir: pathlib.Path,
+ output: pathlib.Path,
+ start: float,
+ end: float,
+ inputs: list[dict[str, Any]],
+ right_videos: list[dict[str, Any]],
+ helpers: HelperMap,
+) -> tuple[pathlib.Path, dict[str, Any], dict[str, Any]]:
+ collection_id = str(item.get("collectionId") or "").strip() or _camera_collection_id(_source_video_name(item))
+ left_pts_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"leftTimestamps"}), "left")
+ right_pts_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"rightTimestamps"}), "right")
+ imu_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"imu"}), "imu")
+ left_pts_path = _materialize_input_file(left_pts_artifact, output / "_inputs", helpers)
+ right_pts_path = _materialize_input_file(right_pts_artifact, output / "_inputs", helpers)
+ imu_path = _materialize_input_file(imu_artifact, output / "_inputs", helpers)
+ left_pts = _read_pts(left_pts_path)
+ right_pts = _read_pts(right_pts_path)
+ imu_rows = _read_imu(imu_path)
+ left_source = _materialize_left_source(item, output / "_inputs", helpers)
+ right_artifact = _matching_right_video(item, right_videos)
+ if right_artifact is None:
+ raise RuntimeError(f"accepted segment {clip_id} has no matching right-camera video")
+ right_source = _materialize_input_video(right_artifact, output / "_inputs", helpers)
+ if _ffprobe_frame_count(left_source) != len(left_pts):
+ raise RuntimeError("left-camera decoded frame count does not match left PTS rows")
+ if _ffprobe_frame_count(right_source) != len(right_pts):
+ raise RuntimeError("right-camera decoded frame count does not match right PTS rows")
+ target_start_us = left_pts[0] + round(start * 1_000_000)
+ target_end_us = left_pts[0] + round(end * 1_000_000)
+ imu_first, imu_last = int(imu_rows[0]["timestamp_us"]), int(imu_rows[-1]["timestamp_us"])
+ common_start = max(left_pts[0], right_pts[0], imu_first)
+ common_end = min(left_pts[-1], right_pts[-1], imu_last)
+ if target_start_us < common_start or target_end_us > common_end or target_end_us <= target_start_us:
+ raise RuntimeError("final segment is outside the common left/right/IMU hardware timestamp range")
+ left_start, left_end = bisect.bisect_left(left_pts, target_start_us), bisect.bisect_left(left_pts, target_end_us)
+ right_start, right_end = bisect.bisect_left(right_pts, target_start_us), bisect.bisect_left(right_pts, target_end_us)
+ left_destination = package_dir / str(item.get("clipName") or f"{clip_id}_left.mp4")
+ right_destination = package_dir / f"{clip_id}_right.mp4"
+ _write_frame_segment(left_source, left_destination, left_start, left_end)
+ _write_frame_segment(right_source, right_destination, right_start, right_end)
+ if _ffprobe_frame_count(left_destination) != left_end - left_start or _ffprobe_frame_count(right_destination) != right_end - right_start:
+ raise RuntimeError("synchronized output frame count does not match sliced PTS rows")
+ left_pts_manifest = _write_pts_slice(package_dir / f"{clip_id}_left_pts.csv", left_pts, left_start, left_end)
+ right_pts_manifest = _write_pts_slice(package_dir / f"{clip_id}_right_pts.csv", right_pts, right_start, right_end)
+ imu_manifest = _write_imu_slice(package_dir / f"{clip_id}_imu.csv", imu_rows, target_start_us, target_end_us)
+ left_video = {"name": left_destination.name, "sha256": _sha256_file(left_destination), "bytes": left_destination.stat().st_size, "cameraSide": "left", "frameCount": left_end - left_start}
+ right_video = {"name": right_destination.name, "sha256": _sha256_file(right_destination), "bytes": right_destination.stat().st_size, "cameraSide": "right", "frameCount": right_end - right_start, "sourceVideo": str(right_artifact.get("name") or right_source.name)}
+ alignment_values = [left_pts[left_start], right_pts[right_start], int(imu_manifest["firstTimestampUs"]), left_pts[left_end - 1], right_pts[right_end - 1], int(imu_manifest["lastTimestampUs"])]
+ max_alignment_error_us = max(abs(value - target_start_us) for value in alignment_values[:3])
+ synchronized = {
+ "schemaVersion": "droboticflow.synchronized-slice/v1",
+ "collectionId": collection_id,
+ "window": {"startTimestampUs": target_start_us, "endTimestampUs": target_end_us, "semantics": "half-open"},
+ "commonRange": {"startTimestampUs": common_start, "endTimestampUs": common_end},
+ "left": {"video": left_video, "pts": left_pts_manifest},
+ "right": {"video": right_video, "pts": right_pts_manifest},
+ "imu": imu_manifest,
+ "maxStartAlignmentErrorUs": max_alignment_error_us,
+ }
+ return left_destination, right_video, synchronized
+
+
def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[str, Any], inputs: list[dict[str, Any]], helpers: HelperMap) -> list[dict[str, Any]]:
output = pathlib.Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
@@ -392,14 +641,16 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
pose_free = _bool(params, "POSE_FREE", False)
require_final_acceptance = _bool(params, "REQUIRE_FINAL_ACCEPTANCE", False)
generate_segment_mp4 = _bool(params, "GENERATE_SEGMENT_MP4", False)
+ synchronized_sidecars = _bool(params, "SYNCHRONIZED_SIDECARS", False)
+ allow_pose_exclusion = _bool(params, "ALLOW_POSE_EXCLUSION", False)
payloads = _payload_tree(_payloads_with_full_pose_manifests(inputs, output, helpers))
headpose = _first_payload(payloads, "droboticflow.headpose/v1")
handpose = _first_payload(payloads, "droboticflow.wilor.hand_pose_result/v1")
if pose_free and (headpose is not None or handpose is not None):
raise RuntimeError("pose-free v5 package rejects HeadPose and HandPose payloads")
- if require_headpose and (headpose is None or not headpose.get("enabled") or not isinstance(headpose.get("frames"), list)):
+ if require_headpose and not allow_pose_exclusion and (headpose is None or not headpose.get("enabled") or not isinstance(headpose.get("frames"), list)):
raise RuntimeError("package requires a real Headpose manifest with frames")
- if require_handpose and (
+ if require_handpose and not allow_pose_exclusion and (
handpose is None
or handpose.get("enabled") is False
or not _pose_frames(handpose, "handpose")
@@ -427,9 +678,22 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
raise RuntimeError("stereo delivery has no accepted Qwen clip with a camera collection")
package_items: list[dict[str, Any]] = []
binding = helpers["output_binding"](node_data)
+ calibration_refs = _copy_calibrations(inputs, output / "packages", output, helpers) if synchronized_sidecars else []
+ package_pose_policy: dict[str, Any] | None = None
for index, item in enumerate(accepted_items):
+ acceptance_evidence: dict[str, Any] = {}
if require_final_acceptance:
- _validate_final_acceptance(item)
+ acceptance_evidence = _validate_final_acceptance(item)
+ pose_policy = acceptance_evidence.get("poseDelivery") if isinstance(acceptance_evidence.get("poseDelivery"), dict) else {}
+ if allow_pose_exclusion:
+ if pose_policy.get("headpose") not in {"include", "exclude"} or pose_policy.get("handpose") not in {"include", "exclude"}:
+ raise RuntimeError("v5.8 final acceptance must decide HeadPose and HandPose inclusion")
+ if package_pose_policy is None:
+ package_pose_policy = pose_policy
+ elif package_pose_policy != pose_policy:
+ raise RuntimeError("v5.8 package items contain conflicting aggregate pose delivery decisions")
+ include_headpose = not allow_pose_exclusion or pose_policy.get("headpose") == "include"
+ include_handpose = not allow_pose_exclusion or pose_policy.get("handpose") == "include"
clip_id = str(item.get("clipId") or f"segment-{index + 1:04d}").strip()
package_dir = output / "packages" / f"{clip_id}_package"
package_dir.mkdir(parents=True, exist_ok=True)
@@ -439,7 +703,11 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
raise RuntimeError("accepted package item has invalid final source boundaries")
# 虚拟切片条目没有物理中间片段:无论是否显式要求 MP4,
# 都必须按源视频区间在打包阶段精确物化最终交付 MP4。
- if generate_segment_mp4 or item.get("finalSegment") is True or item.get("virtualCut") is True:
+ synchronized_manifest = None
+ right_video_manifest = None
+ if synchronized_sidecars:
+ video_path, right_video_manifest, synchronized_manifest = _synchronized_segment(item, clip_id, package_dir, output, start, end, inputs, right_videos, helpers)
+ elif generate_segment_mp4 or item.get("finalSegment") is True or item.get("virtualCut") is True:
video_path = _materialize_final_mp4(item, package_dir, helpers)
else:
source = pathlib.Path(str(item.get("clipPath", "")).strip())
@@ -448,15 +716,14 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
video_path = package_dir / (str(item.get("clipName") or source.name))
shutil.copy2(source, video_path)
annotation = item.get("annotation") if isinstance(item.get("annotation"), dict) else {}
- headpose_segment = _crop_pose(headpose, start, end, "headpose") if headpose else None
- handpose_segment = _crop_pose(handpose, start, end, "handpose") if handpose and handpose.get("enabled", True) else None
- if require_headpose and (headpose_segment is None or headpose_segment["frameCount"] <= 0):
+ headpose_segment = _crop_pose(headpose, start, end, "headpose") if include_headpose and headpose else None
+ handpose_segment = _crop_pose(handpose, start, end, "handpose") if include_handpose and handpose and handpose.get("enabled", True) else None
+ if require_headpose and include_headpose and (headpose_segment is None or headpose_segment["frameCount"] <= 0):
raise RuntimeError("required Headpose has no frame inside the final half-open segment interval")
- if require_handpose and (handpose_segment is None or handpose_segment["frameCount"] <= 0):
+ if require_handpose and include_handpose and (handpose_segment is None or handpose_segment["frameCount"] <= 0):
raise RuntimeError("required HandPose has no frame inside the final half-open segment interval")
- right_video = _matching_right_video(item, right_videos)
- right_video_manifest = None
- if right_video is not None:
+ right_video = None if synchronized_sidecars else _matching_right_video(item, right_videos)
+ if not synchronized_sidecars and right_video is not None:
right_source = _materialize_input_video(right_video, output, helpers)
right_destination = package_dir / f"{clip_id}_right.mp4"
right_video_manifest = _write_verified_segment(right_source, right_destination, start, end, helpers)
@@ -466,9 +733,12 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
right_video_manifest["transformChain"] = (
right_data.get("transformChain") if isinstance(right_data.get("transformChain"), list) else []
)
- elif require_stereo_delivery:
+ elif not synchronized_sidecars and require_stereo_delivery:
raise RuntimeError(f"accepted segment {clip_id} has no matching right-camera video")
helpers["write_json_artifact"](run_id, node_id, package_dir, "semantic.json", annotation, output=binding)
+ if synchronized_manifest is not None:
+ synchronized_manifest["calibration"] = calibration_refs
+ helpers["write_json_artifact"](run_id, node_id, package_dir, "synchronized-slice.json", synchronized_manifest, output=binding)
segment_manifest = {
"schemaVersion": "droboticflow.delivery.segment/v2",
"clipId": clip_id,
@@ -478,6 +748,9 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
"semantic": {"file": "semantic.json", "actionCount": len(annotation.get("actions", []))},
"transformChain": item.get("transformChain", []) if isinstance(item.get("transformChain"), list) else [],
"finalAcceptance": item.get("finalAcceptance") if require_final_acceptance else None,
+ "poseDelivery": pose_policy if allow_pose_exclusion else None,
+ "synchronizedSlice": {"file": "synchronized-slice.json", "schemaVersion": "droboticflow.synchronized-slice/v1"} if synchronized_manifest is not None else None,
+ "calibration": calibration_refs,
}
segment_manifest["videos"] = {
"left": {**segment_manifest["video"], "cameraSide": "left"},
@@ -495,7 +768,7 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
package_items.append({"packageName": package_dir.name, "clipId": clip_id, "clipName": video_path.name, "rightClipName": right_video_manifest["name"] if right_video_manifest else "", "sourceVideo": source_video, "sourceRightVideo": right_video_manifest["sourceVideo"] if right_video_manifest else "", "stereo": right_video_manifest is not None, "storagePath": str(package_dir), "startSecond": start, "endSecond": end, "clipDuration": end - start, "duration": end - start, "fileCount": len([path for path in package_dir.iterdir() if path.is_file()]), "quality": quality, "annotation": annotation, "segmentManifest": segment_manifest})
if not package_items:
raise RuntimeError("package produced zero final segment packages")
- manifest = {"schemaVersion": "droboticflow.delivery.manifest/v3", "datasetType": "fanyu-v5-final-segments", "packageCount": len(package_items), "stereoDelivery": all(item["stereo"] for item in package_items), "headposeIncluded": headpose is not None, "handposeIncluded": handpose is not None and handpose.get("enabled", True), "items": package_items, "trainingEnabled": False}
+ manifest = {"schemaVersion": "droboticflow.delivery.manifest/v4" if synchronized_sidecars else "droboticflow.delivery.manifest/v3", "datasetType": "fanyu-v5-final-segments", "packageCount": len(package_items), "stereoDelivery": all(item["stereo"] for item in package_items), "headposeIncluded": headpose is not None and (not allow_pose_exclusion or (package_pose_policy or {}).get("headpose") == "include"), "handposeIncluded": handpose is not None and handpose.get("enabled", True) and (not allow_pose_exclusion or (package_pose_policy or {}).get("handpose") == "include"), "poseDelivery": package_pose_policy, "audioIncluded": False if synchronized_sidecars else None, "calibration": calibration_refs, "items": package_items, "trainingEnabled": False}
artifacts = [helpers["write_json_artifact"](run_id, node_id, output, "packages-manifest.json", manifest, output=binding)]
artifacts.extend(_collect_unique_package_artifacts(run_id, node_id, output / "packages", node_data, binding, helpers))
return artifacts
diff --git a/docs/annotation-operations.md b/docs/annotation-operations.md
index 1f714968..dd206660 100644
--- a/docs/annotation-operations.md
+++ b/docs/annotation-operations.md
@@ -2,12 +2,12 @@
> 插件化重构后的通用状态机、API、分区释放和深链约定见 [Human Loop Core 与 Annotation QA 插件](./human-loop-plugin.md)。本页保留 Annotation QA 领域对象和兼容接口说明。
-`/annotation-operations` 提供项目级语义模板、供应商分组、逐段标注、审核、验收、返工和工时统计。平台全局角色负责登录后的工作台边界,项目成员关系进一步限定项目、供应商和工作组。生产角色固定为三类:
+`/annotation-operations` 提供项目级语义模板、供应商分组、真实切分、逐段标注、审核、验收、返工和工时统计。平台全局角色负责登录后的工作台边界,项目成员关系进一步限定项目、供应商和工作组。v5.8 生产角色固定为三类:
-- `cutter`(人工剪切员):从剪切池领取自动粗切结果,调整边界、拆分、合并或重做切片。
-- `annotator`(标注员):从剪切审核池和语义标注池领取任务;剪切不可用时打回人工剪切池,可用时继续领取同一片段的语义标注任务。
-- `quality_reviewer`(审核员):从标注审核池和最终验收池领取任务;同一审核角色负责逐片段标注质量结论和聚合包前/成品包最终验收。
-- `acceptance_reviewer`:仅保留为历史兼容角色,权限按 `quality_reviewer` 解释,不再作为新流程的独立岗位。
+- `annotator`(标注员):在同一个原子提交中完成真实切分校正和语义标注;既可先切完再标,也可边切边标。
+- `quality_reviewer`(审核员):独立审核切分边界、左右目对应关系和语义标注,拒绝时把整条源任务退回标注员。
+- `acceptance_reviewer`(最终验收员):在自动打包前独立执行整包全量验收;拒绝时整包退回审核员,不得参与该批次标注审核。
+- `cutter`:只保留历史 v5.7 任务兼容,新建 v5.8 项目不再分配该角色。
- `vendor_manager`:只聚合查看所管供应商/工作组的工作量和质量,不能读取任务媒体或执行审核。
每个成员关系同时绑定 `projectId`、`workgroupId` 和 `vendorId`。除管理员、流程工程师和兼容管理员外,后端只返回当前用户所在分组的任务、模板、分组和工时事件;前端隐藏不是安全边界。
@@ -41,7 +41,11 @@
- `ANNOTATION_WORKGROUP_ID`:目标供应商分组。
- 新任务不接受 `ANNOTATION_ASSIGNED_USER_ID` 预分配;成员从 HumanItem 待领取池主动领取。
-Worker 到达该节点后不会启动 Kubernetes Job,也不会创建通用 AuditTask。它会从上游 `clips-manifest.json`、视频 artifact 和预标 JSON 自动按片段创建 AnnotationTask,并写入 `projectId`、`dataTaskId`、`workflowId`、`runId`、`nodeId`、`artifactId`。Run 保持 `waiting_for_audit`,直到该节点下所有任务依次完成:人工剪切员调整切片 → 标注员审核剪切 → 标注员语义标注 → 审核员标注审核。审核员随后领取聚合包前或成品包最终验收任务。
+Worker 到达该节点后不会启动 Kubernetes Job,也不会创建通用 AuditTask。它会从上游真实视频与 Qwen 边界创建 AnnotationTask,并写入 `projectId`、`dataTaskId`、`workflowId`、`runId`、`nodeId`、`artifactId`。Run 保持 `waiting_for_audit`,直到该节点下所有任务依次完成:标注员真实切分与语义标注 → 审核员统一审核 → 最终验收员整包验收。验收通过后系统自动释放 Package child Run。
+
+v5.8 不预先把长视频拆成多个人工 Task;同一个源任务可提交多个最终切片。无法局部调整的丢帧、流缺失或时间轴异常必须整条任务退回自动重处理,不允许用 FFmpeg 拼接近似修复。
+
+v5.8 打包以绝对 `timestamp_us` 为权威时钟,按同一个半开窗口同步裁切左右视频、左右 PTS CSV 和 IMU accel/gyro;输出侧车统一为毫秒并保留 clip-relative 时间。Audio 与 audio PTS 不处理、不交付,camera/IMU calibration 原文件在批次根目录保留且不做内参差异管理。
标注审核通过后,Worker 生成 `droboticflow.annotation.accepted/v1` 的 `annotations-manifest.json`,记录模板版本、人工 revision、片段、artifact 和 Run lineage,然后从节点 `approved` 输出创建分区子 Run。成品打包完成后创建未分配的 Acceptance HumanItem;审核员领取并通过后才记录幂等最终导出快照,拒绝则进入拒绝区。
diff --git a/docs/fanyu-v5-8-workflow.md b/docs/fanyu-v5-8-workflow.md
new file mode 100644
index 00000000..77af85a1
--- /dev/null
+++ b/docs/fanyu-v5-8-workflow.md
@@ -0,0 +1,23 @@
+# 泛宇双目/PTS/IMU 同步切分交付 v5.8
+
+v5.8 是 v5.7 的不可变后继版本。历史 v5.7 Run 和产物继续可读,新项目默认采用以下流程:
+
+`目录读取 → 双目标准化 → 双目去畸变 → 双目人脸脱敏 → Qwen 粗切 → 标注员真实切分与语义标注 → 审核员统一审核 → 最终验收员整包验收 → 自动打包`
+
+## 人工契约
+
+- 标注员在一个任务中原子提交最终切分与语义标签。
+- 审核员审核切分、左右目关系和语义;拒绝时整条任务回到合并标注环节。
+- 最终验收员独立完成整包全量验收;拒绝时所有条目回到审核池。
+- 验收员分别决定 HeadPose、HandPose 是 `include` 还是 `exclude`;排除 Pose 不阻断基础数据交付。
+
+## 同步切分契约
+
+- 不预拆长视频 Task,一个源任务可产生多个最终片段。
+- 左右视频、左右 PTS、IMU 以绝对硬件微秒时钟求共同有效区间。
+- 每个片段使用 `[start_us, end_us)`;左右视频按帧号重新编码,PTS 行数必须等于输出解码帧数。
+- IMU 仅保留窗口内成对 accel/gyro 数据。
+- 输出 PTS 为 `frame_index,timestamp_ms,clip_time_ms`,IMU 为 `timestamp_ms,clip_time_ms,x,y,z,type`。
+- Audio/audio PTS 不处理、不交付;calibration 原样保留一份,不做去畸变内参差异管理。
+
+每个片段生成 `droboticflow.synchronized-slice/v1`,记录窗口、左右帧数、PTS、IMU 样本、最大对齐误差、SHA 和 calibration 引用。任一必需流缺失、时间戳乱序、IMU 不成对或覆盖不足时 fail-closed。
diff --git a/internal/api/annotation_operations.go b/internal/api/annotation_operations.go
index 58088441..3cbb85e0 100644
--- a/internal/api/annotation_operations.go
+++ b/internal/api/annotation_operations.go
@@ -101,9 +101,7 @@ func membershipAllowsTaskRead(memberships []domain.ProjectAnnotationMembershipRe
func membershipHasRole(memberships []domain.ProjectAnnotationMembershipRecord, task domain.AnnotationTaskRecord, role domain.AnnotationAssignmentRole) bool {
for _, membership := range memberships {
- compatible := membership.AssignmentRole == role ||
- (role == domain.AnnotationRoleQualityReviewer && membership.AssignmentRole == domain.AnnotationRoleAcceptanceReviewer) ||
- (role == domain.AnnotationRoleAcceptanceReviewer && membership.AssignmentRole == domain.AnnotationRoleQualityReviewer)
+ compatible := membership.AssignmentRole == role
if compatible && membershipAllowsTask([]domain.ProjectAnnotationMembershipRecord{membership}, task) {
return true
}
diff --git a/internal/api/annotation_operations_test.go b/internal/api/annotation_operations_test.go
index 33abcf4e..e679bc3e 100644
--- a/internal/api/annotation_operations_test.go
+++ b/internal/api/annotation_operations_test.go
@@ -91,14 +91,32 @@ func TestAnnotationProductionRolesMatchTheThreePoolModel(t *testing.T) {
}
}
-func TestQualityReviewerMembershipAlsoCoversLegacyAcceptanceRole(t *testing.T) {
+func TestQualityReviewerMembershipDoesNotCoverIndependentAcceptanceRole(t *testing.T) {
task := domain.AnnotationTaskRecord{ProjectID: "project-a", WorkgroupID: "group-a", VendorID: "vendor-a"}
memberships := []domain.ProjectAnnotationMembershipRecord{{
ProjectID: task.ProjectID, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID,
AssignmentRole: domain.AnnotationRoleQualityReviewer,
}}
+ if membershipHasRole(memberships, task, domain.AnnotationRoleAcceptanceReviewer) {
+ t.Fatal("quality reviewer must not cover independent final-acceptance membership checks")
+ }
+ memberships = append(memberships, domain.ProjectAnnotationMembershipRecord{ProjectID: task.ProjectID, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID, AssignmentRole: domain.AnnotationRoleAcceptanceReviewer})
if !membershipHasRole(memberships, task, domain.AnnotationRoleAcceptanceReviewer) {
- t.Fatal("quality reviewer must cover legacy final-acceptance membership checks")
+ t.Fatal("explicit acceptance reviewer membership must grant final acceptance")
+ }
+}
+
+func TestFanyuV58UsesCombinedAnnotationAndIndependentReview(t *testing.T) {
+ stages := domain.DefaultFanyuV58HumanStages()
+ if !domain.IsFanyuV58ThreeRoleHumanLoop(stages) {
+ t.Fatalf("unexpected v5.8 stages: %#v", stages)
+ }
+ if annotationRoleForHumanStage(stages[0]) != domain.AnnotationRoleAnnotator || annotationRoleForHumanStage(stages[1]) != domain.AnnotationRoleQualityReviewer {
+ t.Fatalf("unexpected v5.8 stage role routing: %#v", stages)
+ }
+ acceptance := domain.HumanStageDefinition{ID: fanyuV5PrePackageAcceptanceStageID, Kind: domain.HumanStageAcceptance, RequiredRole: "acceptance_reviewer"}
+ if annotationRoleForHumanStage(acceptance) != domain.AnnotationRoleAcceptanceReviewer {
+ t.Fatal("v5.8 aggregate acceptance must require an independent acceptance reviewer")
}
}
diff --git a/internal/api/builtin_operators_catalog.json b/internal/api/builtin_operators_catalog.json
index 5abf7997..4d73d72d 100644
--- a/internal/api/builtin_operators_catalog.json
+++ b/internal/api/builtin_operators_catalog.json
@@ -7710,6 +7710,18 @@
"key": "GENERATE_SEGMENT_MP4",
"type": "boolean",
"value": "false"
+ },
+ {
+ "description": "是否按绝对硬件时间窗口同步裁切左右视频、PTS 和 IMU,并排除音频",
+ "key": "SYNCHRONIZED_SIDECARS",
+ "type": "boolean",
+ "value": "false"
+ },
+ {
+ "description": "是否允许最终验收决定排除 HeadPose 或 HandPose 而继续交付基础数据",
+ "key": "ALLOW_POSE_EXCLUSION",
+ "type": "boolean",
+ "value": "false"
}
],
"id": "operator-builtin-package",
@@ -7758,16 +7770,56 @@
"transmission": "oss",
"type": "json"
},
- {
- "container": "single",
- "description": "自动生成的 WiLoR 3D HandPose 逐帧结果",
- "id": "handpose",
+ {
+ "container": "single",
+ "description": "自动生成的 WiLoR 3D HandPose 逐帧结果",
+ "id": "handpose",
"name": "handpose",
"payloadMode": "ref",
"role": "annotation",
- "transmission": "oss",
- "type": "json"
- }
+ "transmission": "oss",
+ "type": "json"
+ },
+ {
+ "container": "collection",
+ "description": "左相机逐帧硬件 PTS CSV;v5.8 按绝对时间窗口同步裁切",
+ "id": "leftTimestamps",
+ "name": "leftTimestamps",
+ "payloadMode": "ref",
+ "role": "pts",
+ "transmission": "oss",
+ "type": "file"
+ },
+ {
+ "container": "collection",
+ "description": "右相机逐帧硬件 PTS CSV;v5.8 按绝对时间窗口同步裁切",
+ "id": "rightTimestamps",
+ "name": "rightTimestamps",
+ "payloadMode": "ref",
+ "role": "pts",
+ "transmission": "oss",
+ "type": "file"
+ },
+ {
+ "container": "collection",
+ "description": "与双目视频同硬件时钟的 accel/gyro IMU CSV",
+ "id": "imu",
+ "name": "imu",
+ "payloadMode": "ref",
+ "role": "imu",
+ "transmission": "oss",
+ "type": "file"
+ },
+ {
+ "container": "collection",
+ "description": "原始相机与 IMU calibration 文件;不切分、不改写",
+ "id": "calibrations",
+ "name": "calibrations",
+ "payloadMode": "ref",
+ "role": "calibration",
+ "transmission": "oss",
+ "type": "file"
+ }
],
"name": "成品打包",
"outputs": [
diff --git a/internal/api/fanyu_template.go b/internal/api/fanyu_template.go
index 47808012..0cbb8192 100644
--- a/internal/api/fanyu_template.go
+++ b/internal/api/fanyu_template.go
@@ -20,6 +20,7 @@ const fanyuDeliveryTemplateV54ID = "template-fanyu-left-camera-delivery-v5-4"
const fanyuDeliveryTemplateV55ID = "template-fanyu-left-camera-delivery-v5-5"
const fanyuDeliveryTemplateV56ID = "template-fanyu-stereo-pose-delivery-v5-6"
const fanyuDeliveryTemplateV57ID = "template-fanyu-stereo-prelabel-delivery-v5-7"
+const fanyuDeliveryTemplateV58ID = "template-fanyu-stereo-synchronized-delivery-v5-8"
func fanyuLegacyPorts(operatorID string, inputs []domain.PortDefinition, outputs []domain.PortDefinition) ([]domain.PortDefinition, []domain.PortDefinition) {
legacy := func(id, name string, typ domain.PortType, required bool) domain.PortDefinition {
@@ -167,6 +168,17 @@ func fanyuEdge(id string, source string, sourceHandle string, target string, tar
return domain.WorkflowEdge{ID: id, Source: source, SourceHandle: sourceHandle, Target: target, TargetHandle: targetHandle, Animated: true}
}
+func fanyuUpsertHyperparam(items []domain.HyperParam, key string, value string) []domain.HyperParam {
+ updated := append([]domain.HyperParam(nil), items...)
+ for index := range updated {
+ if updated[index].Key == key {
+ updated[index].Value = value
+ return updated
+ }
+ }
+ return append(updated, domain.HyperParam{Key: key, Value: value, Type: "string"})
+}
+
func (server *server) ensureFanyuDeliveryTemplate(ctx context.Context, organizationID string) error {
organizationID = normalizedOrganizationID(organizationID)
if err := server.ensureFanyuDeliveryTemplateV1(ctx, organizationID); err != nil {
@@ -196,12 +208,15 @@ func (server *server) ensureFanyuDeliveryTemplate(ctx context.Context, organizat
if err := server.ensureFanyuDeliveryTemplateV57(ctx, organizationID); err != nil {
return err
}
+ if err := server.ensureFanyuDeliveryTemplateV58(ctx, organizationID); err != nil {
+ return err
+ }
return server.ensureFanyuConvenienceStoreAnnotationTemplates(ctx, organizationID)
}
func (server *server) ensureFanyuConvenienceStoreAnnotationTemplates(ctx context.Context, organizationID string) error {
organizationID = normalizedOrganizationID(organizationID)
- for version := 1; version <= 5; version++ {
+ for version := 1; version <= 6; version++ {
templateID := fmt.Sprintf("tpl-fanyu-convenience-store-v%d-%s", version, organizationID)
existing, err := server.store.GetAnnotationTemplate(ctx, templateID)
if err != nil {
@@ -209,6 +224,9 @@ func (server *server) ensureFanyuConvenienceStoreAnnotationTemplates(ctx context
}
if existing == nil {
template := domain.DefaultConvenienceStoreAnnotationTemplate(organizationID, "", version)
+ if version == 6 {
+ template.HumanStages = domain.DefaultFanyuV58HumanStages()
+ }
now := nowISO()
template.CreatedAt = now
template.UpdatedAt = now
@@ -219,6 +237,15 @@ func (server *server) ensureFanyuConvenienceStoreAnnotationTemplates(ctx context
}
continue
}
+ if version == 6 && !domain.IsFanyuV58ThreeRoleHumanLoop(existing.HumanStages) {
+ updated := *existing
+ updated.HumanStages = domain.DefaultFanyuV58HumanStages()
+ updated.UpdatedAt = nowISO()
+ if err := server.store.UpsertAnnotationTemplate(ctx, updated); err != nil {
+ return err
+ }
+ continue
+ }
// Early v5 POC deployments persisted a two-stage combined template
// under this system-owned ID. Upgrade only that stale stage topology;
// preserve its labels, phrases, project binding, and publication record.
@@ -234,6 +261,93 @@ func (server *server) ensureFanyuConvenienceStoreAnnotationTemplates(ctx context
return nil
}
+// ensureFanyuDeliveryTemplateV58 publishes the confirmed three-role workflow
+// and carries stereo PTS, IMU, and calibration sidecars into the final package.
+// v5.7 remains immutable and readable for historical runs.
+func (server *server) ensureFanyuDeliveryTemplateV58(ctx context.Context, organizationID string) error {
+ organizationID = normalizedOrganizationID(organizationID)
+ base, err := server.store.GetTemplate(ctx, fanyuDeliveryTemplateV57ID+"-"+organizationID)
+ if err != nil || base == nil {
+ return err
+ }
+ templateID := fanyuDeliveryTemplateV58ID + "-" + organizationID
+ releaseID := "workflow-release-fanyu-v5-8-" + organizationID
+ nodes := append([]domain.WorkflowNode(nil), base.Nodes...)
+ annotationTemplateID := fmt.Sprintf("tpl-fanyu-convenience-store-v6-%s", organizationID)
+ for index := range nodes {
+ node := &nodes[index]
+ switch node.ID {
+ case "fanyu-v56-human":
+ node.Data.Label = "真实切分与语义标注→切分/标注审核→整包验收"
+ node.Data.Description = "标注员在一个合并环节完成真实切分和语义标注;审核员统一审核,独立验收员完成整包验收。"
+ node.Data.Hyperparams = fanyuUpsertHyperparam(node.Data.Hyperparams, "ANNOTATION_TEMPLATE_ID", annotationTemplateID)
+ node.Data.Hyperparams = fanyuUpsertHyperparam(node.Data.Hyperparams, "RELEASE_POLICY", "all_accepted")
+ node.Data.Hyperparams = fanyuUpsertHyperparam(node.Data.Hyperparams, "REQUIRE_PREPACKAGE_ACCEPTANCE", "true")
+ case "fanyu-v56-package":
+ node.Data.Label = "双目/PTS/IMU 同步切分与自动交付打包"
+ node.Data.Description = "按统一绝对硬件时间窗口裁切左右视频、PTS 和 IMU;排除音频,原样携带 calibration,并按验收决定包含或排除 Pose。"
+ node.Data.Hyperparams = fanyuUpsertHyperparam(node.Data.Hyperparams, "SYNCHRONIZED_SIDECARS", "true")
+ node.Data.Hyperparams = fanyuUpsertHyperparam(node.Data.Hyperparams, "ALLOW_POSE_EXCLUSION", "true")
+ }
+ }
+ edges := append([]domain.WorkflowEdge(nil), base.Edges...)
+ edges = append(edges,
+ fanyuEdge("fanyu-v58-e23", "fanyu-v56-undistort", "leftRectifiedTimestamps", "fanyu-v56-package", "leftTimestamps"),
+ fanyuEdge("fanyu-v58-e24", "fanyu-v56-undistort", "rightRectifiedTimestamps", "fanyu-v56-package", "rightTimestamps"),
+ fanyuEdge("fanyu-v58-e25", "fanyu-v56-normalize", "imu", "fanyu-v56-package", "imu"),
+ fanyuEdge("fanyu-v58-e26", "fanyu-v56-normalize", "calibrations", "fanyu-v56-package", "calibrations"),
+ )
+ now := nowISO()
+ createdAt := now
+ if existing, existingErr := server.store.GetTemplate(ctx, templateID); existingErr != nil {
+ return existingErr
+ } else if existing != nil && strings.TrimSpace(existing.CreatedAt) != "" {
+ createdAt = existing.CreatedAt
+ }
+ template := domain.TemplateRecord{
+ ID: templateID, OrganizationID: organizationID, Name: "01-双目/PTS/IMU 同步切分交付-v5.8",
+ Description: "双目去畸变与脱敏、Qwen 粗切、三角色合并人工处理、独立整包验收,以及左右视频/PTS/IMU 同步切分自动打包;音频不处理不交付,calibration 原样保留。",
+ Type: domain.WorkflowTypeBatch, Kind: domain.WorkflowKindStandard, ExecutionScope: domain.WorkflowExecutionScopeProduction,
+ DefinitionState: domain.WorkflowDefinitionStateDraft, DefinitionVersion: 8, DefinitionFamilyID: fanyuDeliveryTemplateV5ID + "-" + organizationID, SupersedesTemplateID: fanyuDeliveryTemplateV57ID + "-" + organizationID,
+ MaxConcurrentRuns: 1, WorkflowInputs: append([]domain.WorkflowInputDefinition(nil), base.WorkflowInputs...), Nodes: nodes, Edges: edges, CreatedAt: createdAt, UpdatedAt: now,
+ }
+ if issues := validateWorkflowTopology(nodes, edges); len(issues) > 0 {
+ return fmt.Errorf("invalid fanyu v5.8 template: %s", strings.TrimSpace(issues[0].Message))
+ }
+ if issues := validateWorkflowInputContract(nodes, edges, template.WorkflowInputs, true); len(issues) > 0 {
+ return fmt.Errorf("invalid fanyu v5.8 input contract: %s", strings.TrimSpace(issues[0].Message))
+ }
+ if err := server.store.UpsertTemplate(ctx, template); err != nil {
+ return err
+ }
+ if existingRelease, releaseErr := server.store.GetWorkflowRelease(ctx, releaseID); releaseErr != nil || existingRelease != nil {
+ return releaseErr
+ }
+ if len(server.validateWorkflowOperatorPublication(ctx, nodes, domain.WorkflowExecutionScopeProduction)) > 0 {
+ return nil
+ }
+ for _, node := range nodes {
+ if node.ID != "fanyu-v56-human" {
+ continue
+ }
+ for _, parameter := range node.Data.Hyperparams {
+ if parameter.Key == "ANNOTATION_WORKGROUP_ID" && strings.TrimSpace(fmt.Sprint(parameter.Value)) == "" {
+ return nil
+ }
+ }
+ }
+ release := domain.WorkflowReleaseRecord{
+ ID: releaseID, OrganizationID: organizationID, TemplateID: template.ID, Version: 8, Name: template.Name, Description: template.Description,
+ Type: template.Type, Kind: template.Kind, ExecutionScope: template.ExecutionScope, MaxConcurrentRuns: template.MaxConcurrentRuns,
+ WorkflowInputs: template.WorkflowInputs, Nodes: nodes, Edges: edges,
+ Capabilities: []string{"directory_input", "stereo_opencv_undistort", "stereo_yunet_face_anonymization", "qwen3vl_behavior_rough_cut", "combined_cut_semantic_annotation", "combined_quality_review", "independent_full_acceptance", "stereo_pts_imu_synchronized_crop", "automatic_package"},
+ RequiredPluginIDs: []string{pluginregistry.HumanLoopCoreID, pluginregistry.AnnotationQAID}, ContentDigest: workflowReleaseDigest(template),
+ ReleaseNotes: "v5.8 three-role human loop and absolute-timestamp synchronized stereo/PTS/IMU package",
+ PublishedByUserID: "system", PublishedAt: now, CreatedAt: now,
+ }
+ return server.store.UpsertWorkflowRelease(ctx, release)
+}
+
// ensureFanyuDeliveryTemplateV5 adds a new immutable left-camera route and
// intentionally never mutates v1-v4. It is saved as an editable template
// until independently built images, a verified Qwen3-VL cache, and the real
diff --git a/internal/api/fanyu_template_test.go b/internal/api/fanyu_template_test.go
index d6f3e2e9..98201853 100644
--- a/internal/api/fanyu_template_test.go
+++ b/internal/api/fanyu_template_test.go
@@ -531,4 +531,44 @@ func TestEnsureFanyuDeliveryTemplateV56BuildsStereoCropAndPoseTopology(t *testin
if !reviewEdges["head"] || reviewEdges["hand"] {
t.Fatalf("v5.7 must review HeadPose but bypass human review for HandPose: %#v", reviewEdges)
}
+ v58, v58Err := dataStore.GetTemplate(ctx, fanyuDeliveryTemplateV58ID+"-org-v56")
+ if v58Err != nil || v58 == nil {
+ t.Fatalf("v5.8 template=%#v err=%v", v58, v58Err)
+ }
+ if v58.DefinitionVersion != 8 || v58.SupersedesTemplateID != fanyuDeliveryTemplateV57ID+"-org-v56" || len(v58.Nodes) != 10 || len(v58.Edges) != 26 {
+ t.Fatalf("unexpected v5.8 synchronized topology: %#v", v58)
+ }
+ v58Package := fanyuTestNode(v58.Nodes, "fanyu-v56-package")
+ v58Human := fanyuTestNode(v58.Nodes, "fanyu-v56-human")
+ if v58Package == nil || fanyuTestHyperparam(v58Package, "SYNCHRONIZED_SIDECARS") != "true" || fanyuTestHyperparam(v58Package, "ALLOW_POSE_EXCLUSION") != "true" {
+ t.Fatalf("v5.8 package must enable synchronized sidecars and pose exclusion: %#v", v58Package)
+ }
+ if v58Human == nil || fanyuTestHyperparam(v58Human, "ANNOTATION_TEMPLATE_ID") != "tpl-fanyu-convenience-store-v6-org-v56" {
+ t.Fatalf("v5.8 human node must use the three-role annotation template: %#v", v58Human)
+ }
+ requiredV58Edges := map[string]bool{"leftPts": false, "rightPts": false, "imu": false, "calibrations": false}
+ for _, edge := range v58.Edges {
+ if edge.Target != "fanyu-v56-package" {
+ continue
+ }
+ switch edge.TargetHandle {
+ case "leftTimestamps":
+ requiredV58Edges["leftPts"] = true
+ case "rightTimestamps":
+ requiredV58Edges["rightPts"] = true
+ case "imu":
+ requiredV58Edges["imu"] = true
+ case "calibrations":
+ requiredV58Edges["calibrations"] = true
+ }
+ }
+ for name, found := range requiredV58Edges {
+ if !found {
+ t.Fatalf("v5.8 missing synchronized package edge %s", name)
+ }
+ }
+ v6Annotation, annotationErr := dataStore.GetAnnotationTemplate(ctx, "tpl-fanyu-convenience-store-v6-org-v56")
+ if annotationErr != nil || v6Annotation == nil || !domain.IsFanyuV58ThreeRoleHumanLoop(v6Annotation.HumanStages) {
+ t.Fatalf("v5.8 annotation template=%#v err=%v", v6Annotation, annotationErr)
+ }
}
diff --git a/internal/api/fanyu_v5_four_stage_human_loop_test.go b/internal/api/fanyu_v5_four_stage_human_loop_test.go
index 4f331b5f..f1a358c3 100644
--- a/internal/api/fanyu_v5_four_stage_human_loop_test.go
+++ b/internal/api/fanyu_v5_four_stage_human_loop_test.go
@@ -322,3 +322,82 @@ func TestFanyuV5FourStageProgressesToConfirmOnlyAggregateAcceptance(t *testing.T
t.Fatalf("aggregate acceptance must remain confirm-only for quality_reviewer: batch=%#v err=%v", aggregateBatch, err)
}
}
+
+func TestFanyuV58AggregateAcceptanceUsesIndependentRoleAndWholeBatchRejection(t *testing.T) {
+ ctx := context.Background()
+ dataStore := store.NewMemoryStore()
+ now := nowISO()
+ quality := domain.UserRecord{ID: "quality-v58", OrganizationID: domain.DefaultOrganizationID, Role: domain.UserRoleQualityReviewer, Status: domain.UserStatusActive}
+ acceptance := domain.UserRecord{ID: "acceptance-v58", OrganizationID: domain.DefaultOrganizationID, Role: domain.UserRoleAcceptanceReviewer, Status: domain.UserStatusActive}
+ for _, user := range []domain.UserRecord{quality, acceptance} {
+ if err := dataStore.UpsertUser(ctx, user); err != nil {
+ t.Fatal(err)
+ }
+ }
+ for _, membership := range []domain.ProjectAnnotationMembershipRecord{
+ {ID: "quality-membership-v58", OrganizationID: domain.DefaultOrganizationID, ProjectID: "project-v58", UserID: quality.ID, WorkgroupID: "workgroup-v58", VendorID: "vendor-v58", AssignmentRole: domain.AnnotationRoleQualityReviewer, CreatedAt: now, UpdatedAt: now},
+ {ID: "acceptance-membership-v58", OrganizationID: domain.DefaultOrganizationID, ProjectID: "project-v58", UserID: acceptance.ID, WorkgroupID: "workgroup-v58", VendorID: "vendor-v58", AssignmentRole: domain.AnnotationRoleAcceptanceReviewer, CreatedAt: now, UpdatedAt: now},
+ } {
+ if err := dataStore.UpsertProjectAnnotationMembership(ctx, membership); err != nil {
+ t.Fatal(err)
+ }
+ }
+ batch := domain.HumanBatchRecord{ID: "batch-v58", OrganizationID: domain.DefaultOrganizationID, PluginID: "annotation-qa", ProjectID: "project-v58", WorkflowID: "workflow-v58", RunID: "run-v58", GateNodeID: "human-v58", Status: domain.HumanBatchActive, Stages: domain.DefaultFanyuV58HumanStages(), ReleasePolicy: domain.HumanReleaseAllAccepted, MaxReworkRounds: 5, RequirePrePackageAcceptance: true, CreatedAt: now, UpdatedAt: now}
+ if err := dataStore.UpsertHumanBatch(ctx, batch); err != nil {
+ t.Fatal(err)
+ }
+ task := domain.AnnotationTaskRecord{ID: "task-v58", OrganizationID: domain.DefaultOrganizationID, ProjectID: batch.ProjectID, WorkflowID: batch.WorkflowID, RunID: batch.RunID, NodeID: batch.GateNodeID, ArtifactID: "artifact-v58", SourceVideo: "bos://fixture/video.mp4", ClipStart: 0, ClipEnd: 20, TemplateID: "template-v58", TemplateVersion: 6, WorkgroupID: "workgroup-v58", VendorID: "vendor-v58", Status: domain.AnnotationTaskStatusAccepted, CurrentRevision: 1, CreatedAt: now, UpdatedAt: now}
+ if err := dataStore.UpsertAnnotationTask(ctx, task); err != nil {
+ t.Fatal(err)
+ }
+ if err := dataStore.UpsertSliceRevision(ctx, domain.SliceRevisionRecord{ID: "slice-v58", OrganizationID: domain.DefaultOrganizationID, TaskID: task.ID, Revision: 1, Segments: []domain.SliceSegment{{ID: "slice", Start: 0, End: 20}}, AuthorUserID: "annotator-v58", CreatedAt: now}); err != nil {
+ t.Fatal(err)
+ }
+ if err := dataStore.UpsertAnnotationRevision(ctx, domain.AnnotationRevisionRecord{ID: "revision-v58", OrganizationID: domain.DefaultOrganizationID, TaskID: task.ID, Revision: 1, TemplateVersion: 6, Segments: []domain.AnnotationSegment{{ID: "semantic", LabelID: "01", Label: "测试", Start: 0, End: 20}}, AuthorUserID: "annotator-v58", CreatedAt: now}); err != nil {
+ t.Fatal(err)
+ }
+ item := domain.HumanItemRecord{ID: "item-v58", OrganizationID: domain.DefaultOrganizationID, PluginID: "annotation-qa", BatchID: batch.ID, ProjectID: batch.ProjectID, WorkflowID: batch.WorkflowID, RunID: batch.RunID, GateNodeID: batch.GateNodeID, LegacyTaskID: task.ID, Subject: domain.HumanSubjectRef{ArtifactID: task.ArtifactID, ItemKey: "clip-v58"}, CurrentStageID: domain.FanyuV58StageQualityReview, Status: domain.HumanItemAccepted, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID, CurrentRevision: 1, MaxReworkRounds: 5, Version: 2, AcceptedAt: now, AcceptedByUserID: quality.ID, CreatedAt: now, UpdatedAt: now}
+ if err := dataStore.UpsertHumanItem(ctx, item); err != nil {
+ t.Fatal(err)
+ }
+ server := &server{store: dataStore}
+ confirmed, err := server.ensureFanyuV5PrePackageAcceptance(ctx, &batch)
+ if err != nil || confirmed {
+ t.Fatalf("create v5.8 acceptance confirmed=%v err=%v", confirmed, err)
+ }
+ aggregate, _ := dataStore.GetHumanItem(ctx, fanyuV5PrePackageAcceptanceItemID(batch.ID))
+ aggregateBatch, _ := dataStore.GetHumanBatch(ctx, aggregate.BatchID)
+ if aggregate == nil || aggregateBatch == nil || aggregateBatch.Stages[0].RequiredRole != "acceptance_reviewer" || aggregateBatch.Stages[0].ConfirmOnly {
+ t.Fatalf("unexpected v5.8 aggregate acceptance: item=%#v batch=%#v", aggregate, aggregateBatch)
+ }
+ handler := NewHandler(dataStore, nil)
+ request := func(method, path string, user domain.UserRecord, body any) *httptest.ResponseRecorder {
+ encoded, _ := json.Marshal(body)
+ req := httptest.NewRequest(method, path, bytes.NewReader(encoded))
+ req.Header.Set("Content-Type", "application/json")
+ csrf := "v58-csrf"
+ req.AddCookie(&http.Cookie{Name: csrfCookieName, Value: csrf})
+ req.Header.Set(csrfHeaderName, csrf)
+ req = req.WithContext(context.WithValue(req.Context(), authContextKey{}, &authenticatedPrincipal{User: user, Organization: domain.OrganizationRecord{ID: domain.DefaultOrganizationID, Status: domain.OrganizationStatusActive}}))
+ recorder := httptest.NewRecorder()
+ handler.ServeHTTP(recorder, req)
+ return recorder
+ }
+ qualityClaim := request(http.MethodPost, "/api/human-items/"+aggregate.ID+"/claim", quality, map[string]any{"version": aggregate.Version})
+ if qualityClaim.Code != http.StatusForbidden {
+ t.Fatalf("quality reviewer must not claim v5.8 acceptance: status=%d body=%s", qualityClaim.Code, qualityClaim.Body.String())
+ }
+ claim := request(http.MethodPost, "/api/human-items/"+aggregate.ID+"/claim", acceptance, map[string]any{"version": aggregate.Version})
+ if claim.Code != http.StatusOK {
+ t.Fatalf("acceptance claim status=%d body=%s", claim.Code, claim.Body.String())
+ }
+ claimed, _ := dataStore.GetHumanItem(ctx, aggregate.ID)
+ reject := request(http.MethodPost, "/api/human-items/"+aggregate.ID+"/decisions", acceptance, map[string]any{"version": claimed.Version, "decision": "rejected", "reasonCodes": []string{"batch_problem"}, "comment": "整包退回审核"})
+ if reject.Code != http.StatusOK {
+ t.Fatalf("acceptance reject status=%d body=%s", reject.Code, reject.Body.String())
+ }
+ routed, _ := dataStore.GetHumanItem(ctx, item.ID)
+ if routed.CurrentStageID != domain.FanyuV58StageQualityReview || routed.Status != domain.HumanItemSubmitted || routed.AcceptedAt != "" {
+ t.Fatalf("whole-batch rejection must route source item to quality review: %#v", routed)
+ }
+}
diff --git a/internal/api/human_loop.go b/internal/api/human_loop.go
index bd195fda..02e45dac 100644
--- a/internal/api/human_loop.go
+++ b/internal/api/human_loop.go
@@ -32,16 +32,17 @@ type humanSubmissionRequest struct {
}
type humanDecisionRequest struct {
- Version int `json:"version"`
- Decision domain.HumanDecision `json:"decision"`
- ReviewedRevision int `json:"reviewedRevision"`
- RejectTargets []string `json:"rejectTargets"`
- ReasonCodes []string `json:"reasonCodes"`
- Comment string `json:"comment"`
- VideoQuality string `json:"videoQuality,omitempty"`
- AnnotationAccuracy float64 `json:"annotationAccuracy,omitempty"`
- AnnotationCompleteness float64 `json:"annotationCompleteness,omitempty"`
- OverallGrade string `json:"overallGrade,omitempty"`
+ Version int `json:"version"`
+ Decision domain.HumanDecision `json:"decision"`
+ ReviewedRevision int `json:"reviewedRevision"`
+ RejectTargets []string `json:"rejectTargets"`
+ ReasonCodes []string `json:"reasonCodes"`
+ Comment string `json:"comment"`
+ VideoQuality string `json:"videoQuality,omitempty"`
+ AnnotationAccuracy float64 `json:"annotationAccuracy,omitempty"`
+ AnnotationCompleteness float64 `json:"annotationCompleteness,omitempty"`
+ OverallGrade string `json:"overallGrade,omitempty"`
+ PoseDelivery domain.PoseDeliveryPolicy `json:"poseDelivery,omitempty"`
}
type humanReopenRequest struct {
@@ -293,13 +294,22 @@ func isFanyuV5FourStageBatch(batch *domain.HumanBatchRecord) bool {
return batch != nil && domain.IsFanyuV5FourStageHumanLoop(batch.Stages)
}
+func isFanyuV58ThreeRoleBatch(batch *domain.HumanBatchRecord) bool {
+ return batch != nil && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages)
+}
+
func annotationRoleForHumanStage(stage domain.HumanStageDefinition) domain.AnnotationAssignmentRole {
switch stage.ID {
case "split_annotation", domain.FanyuV5StageCutAdjustment:
return domain.AnnotationRoleCutter
case "split_quality_review", domain.FanyuV5StageCutReview, domain.FanyuV5StageSemanticAnnotation:
return domain.AnnotationRoleAnnotator
- case "quality_review", domain.FanyuV5StageSemanticReview, "acceptance", fanyuV5PrePackageAcceptanceStageID:
+ case "quality_review", domain.FanyuV5StageSemanticReview:
+ return domain.AnnotationRoleQualityReviewer
+ case "acceptance", fanyuV5PrePackageAcceptanceStageID:
+ if stage.RequiredRole == "acceptance_reviewer" {
+ return domain.AnnotationRoleAcceptanceReviewer
+ }
return domain.AnnotationRoleQualityReviewer
}
switch stage.RequiredRole {
@@ -308,7 +318,7 @@ func annotationRoleForHumanStage(stage domain.HumanStageDefinition) domain.Annot
case "quality_reviewer":
return domain.AnnotationRoleQualityReviewer
case "acceptance_reviewer":
- return domain.AnnotationRoleQualityReviewer
+ return domain.AnnotationRoleAcceptanceReviewer
default:
return domain.AnnotationRoleAnnotator
}
@@ -726,9 +736,10 @@ func userRoleSupportsAnnotationAssignment(role domain.UserRole, assignmentRole d
return role == domain.UserRoleCutter
case domain.AnnotationRoleAnnotator:
return role == domain.UserRoleAnnotator || role == domain.UserRoleDataOperator
- case domain.AnnotationRoleQualityReviewer, domain.AnnotationRoleAcceptanceReviewer:
- return role == domain.UserRoleQualityReviewer || role == domain.UserRoleAcceptanceReviewer ||
- role == domain.UserRoleQAReviewer || role == domain.UserRoleAuditor || role == domain.UserRoleComplianceAuditor
+ case domain.AnnotationRoleQualityReviewer:
+ return role == domain.UserRoleQualityReviewer || role == domain.UserRoleQAReviewer || role == domain.UserRoleAuditor || role == domain.UserRoleComplianceAuditor
+ case domain.AnnotationRoleAcceptanceReviewer:
+ return role == domain.UserRoleAcceptanceReviewer
default:
return false
}
@@ -973,6 +984,11 @@ func (server *server) handleHumanItemDecision(writer http.ResponseWriter, reques
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human batch not found"})
return
}
+ strictSourceBatch, v58AggregateAcceptance, sourceErr := v58AggregateSourceBatch(request.Context(), server, batch)
+ if sourceErr != nil {
+ renderError(writer, http.StatusInternalServerError, sourceErr)
+ return
+ }
stage, stageIndex, found := humanStage(batch, item.CurrentStageID)
if !found || (stage.Kind != domain.HumanStageReview && stage.Kind != domain.HumanStageAcceptance && stage.Kind != domain.HumanStageApproval) {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Current human stage does not accept decisions"})
@@ -1003,6 +1019,16 @@ func (server *server) handleHumanItemDecision(writer http.ResponseWriter, reques
renderValidationError(writer, validationIssue{Field: "decision", Message: "this acceptance stage is confirm-only and does not allow reject or rework"})
return
}
+ if v58AggregateAcceptance && payload.Decision == domain.HumanDecisionApproved {
+ if !validPoseDeliveryDecision(payload.PoseDelivery.Headpose) || !validPoseDeliveryDecision(payload.PoseDelivery.Handpose) {
+ renderValidationError(writer, validationIssue{Field: "poseDelivery", Message: "headpose and handpose must be include or exclude"})
+ return
+ }
+ if (payload.PoseDelivery.Headpose == domain.PoseDeliveryExclude || payload.PoseDelivery.Handpose == domain.PoseDeliveryExclude) && len(payload.PoseDelivery.ReasonCodes) == 0 {
+ renderValidationError(writer, validationIssue{Field: "poseDelivery.reasonCodes", Message: "pose exclusion requires at least one reason code"})
+ return
+ }
+ }
if stage.ConfirmOnly && (strings.TrimSpace(payload.VideoQuality) == "" || strings.TrimSpace(payload.OverallGrade) == "" || payload.AnnotationAccuracy < 0 || payload.AnnotationAccuracy > 100 || payload.AnnotationCompleteness < 0 || payload.AnnotationCompleteness > 100) {
renderValidationError(writer, validationIssue{Field: "statistics", Message: "confirm-only acceptance requires videoQuality, overallGrade and annotation accuracy/completeness in [0,100]"})
return
@@ -1023,6 +1049,12 @@ func (server *server) handleHumanItemDecision(writer http.ResponseWriter, reques
statistics["overallGrade"] = strings.TrimSpace(payload.OverallGrade)
item.Subject.Payload["statistics"] = statistics
}
+ if v58AggregateAcceptance {
+ if item.Subject.Payload == nil {
+ item.Subject.Payload = map[string]any{}
+ }
+ item.Subject.Payload["poseDelivery"] = payload.PoseDelivery
+ }
eventType := string(payload.Decision)
automaticReworkTarget := ""
rejectAllowedStages := []string(nil)
@@ -1044,6 +1076,10 @@ func (server *server) handleHumanItemDecision(writer http.ResponseWriter, reques
return
}
rejectAllowedStages = allowedHumanReopenStages(batch, previousStage)
+ if v58AggregateAcceptance {
+ rejectAllowedStages = []string{domain.FanyuV58StageQualityReview}
+ payload.RejectTargets = []string{domain.FanyuV58StageQualityReview}
+ }
if isFanyuV5FourStageBatch(batch) {
if len(stage.RejectTargets) == 0 {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "v5 review stage has no configured rework target", "code": "human_item_stage_contract"})
@@ -1121,6 +1157,14 @@ func (server *server) handleHumanItemDecision(writer http.ResponseWriter, reques
return
}
}
+ if v58AggregateAcceptance && payload.Decision == domain.HumanDecisionRejected {
+ if err := server.routeV58AcceptanceRejection(request.Context(), strictSourceBatch, principal.User.ID, payload.ReasonCodes, payload.Comment); err != nil {
+ renderError(writer, http.StatusInternalServerError, err)
+ return
+ }
+ batch.Status = domain.HumanBatchBlocked
+ _ = server.store.UpsertHumanBatch(request.Context(), *batch)
+ }
_ = server.appendHumanEvent(request.Context(), *item, eventType, principal.User.ID, map[string]any{
"decision": payload.Decision, "reviewedRevision": payload.ReviewedRevision, "rejectTargets": payload.RejectTargets,
"reasonCodes": payload.ReasonCodes, "comment": strings.TrimSpace(payload.Comment), "routedToStage": automaticReworkTarget, "videoQuality": payload.VideoQuality, "annotationAccuracy": payload.AnnotationAccuracy, "annotationCompleteness": payload.AnnotationCompleteness, "overallGrade": payload.OverallGrade,
@@ -1156,6 +1200,59 @@ func (server *server) handleHumanItemDecision(writer http.ResponseWriter, reques
renderJSON(writer, http.StatusOK, item)
}
+func (server *server) routeV58AcceptanceRejection(ctx context.Context, source *domain.HumanBatchRecord, actorUserID string, reasonCodes []string, comment string) error {
+ if source == nil || !domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
+ return fmt.Errorf("v5.8 aggregate acceptance source batch is unavailable")
+ }
+ items, err := server.store.ListHumanItems(ctx, source.OrganizationID, domain.HumanItemQuery{BatchID: source.ID})
+ if err != nil {
+ return err
+ }
+ for index := range items {
+ item := items[index]
+ if strings.TrimSpace(item.ReleasePartitionID) != "" {
+ return fmt.Errorf("v5.8 accepted item %s was already released before final acceptance", item.ID)
+ }
+ previousVersion := item.Version
+ item.CurrentStageID = domain.FanyuV58StageQualityReview
+ item.Status = domain.HumanItemSubmitted
+ item.AssignedUserID = ""
+ item.ClaimedAt = ""
+ item.AcceptedAt = ""
+ item.AcceptedByUserID = ""
+ item.RejectedAt = ""
+ item.ReviewRound++
+ item.Version++
+ item.UpdatedAt = nowISO()
+ updated, updateErr := server.store.UpdateHumanItemVersioned(ctx, item, previousVersion)
+ if updateErr != nil || !updated {
+ if updateErr != nil {
+ return updateErr
+ }
+ return fmt.Errorf("v5.8 item %s version conflict during whole-batch rejection", item.ID)
+ }
+ if strings.TrimSpace(item.LegacyTaskID) != "" {
+ task, taskErr := server.store.GetAnnotationTask(ctx, item.LegacyTaskID)
+ if taskErr != nil {
+ return taskErr
+ }
+ if task != nil {
+ task.Status = domain.AnnotationTaskStatusPendingQuality
+ task.AssignedUserID = ""
+ if taskErr = server.store.UpsertAnnotationTask(ctx, *task); taskErr != nil {
+ return taskErr
+ }
+ }
+ }
+ _ = server.store.UpsertHumanStageAttempt(ctx, domain.HumanStageAttemptRecord{OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: item.CurrentStageID, Round: item.ReviewRound, Status: item.Status})
+ _ = server.appendHumanEvent(ctx, item, "aggregate_acceptance_rejected", actorUserID, map[string]any{"reasonCodes": reasonCodes, "comment": strings.TrimSpace(comment), "routedToStage": domain.FanyuV58StageQualityReview})
+ }
+ source.Status = domain.HumanBatchActive
+ source.AcceptedCount = 0
+ source.UpdatedAt = nowISO()
+ return server.store.UpsertHumanBatch(ctx, *source)
+}
+
func (server *server) handleHumanRejectsList(writer http.ResponseWriter, request *http.Request) {
items, err := server.store.ListHumanRejects(request.Context(), server.requestOrganizationID(request), parseHumanRejectQuery(request))
if err != nil {
@@ -1462,6 +1559,21 @@ func acceptanceArtifactRefs(value any) []map[string]any {
return refs
}
+func validPoseDeliveryDecision(value domain.PoseDeliveryDecision) bool {
+ return value == domain.PoseDeliveryInclude || value == domain.PoseDeliveryExclude
+}
+
+func v58AggregateSourceBatch(ctx context.Context, server *server, batch *domain.HumanBatchRecord) (*domain.HumanBatchRecord, bool, error) {
+ if batch == nil || strings.TrimSpace(batch.SourceBatchID) == "" {
+ return nil, false, nil
+ }
+ source, err := server.store.GetHumanBatch(ctx, batch.SourceBatchID)
+ if err != nil || source == nil {
+ return source, false, err
+ }
+ return source, domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages), nil
+}
+
// ensureFanyuV5PrePackageAcceptance creates exactly one vendor-scoped,
// partition-level acceptance item after every source item has passed the cut
// and semantic-review loop. Optional hand/head prelabels and their rendered
@@ -1486,12 +1598,16 @@ func (server *server) ensureFanyuV5PrePackageAcceptance(ctx context.Context, sou
}
if acceptanceBatch == nil {
now := nowISO()
+ stage := domain.HumanStageDefinition{ID: fanyuV5PrePackageAcceptanceStageID, Label: "包前最终验收(仅确认)", Kind: domain.HumanStageAcceptance, RequiredRole: "quality_reviewer", EditorSchema: "acceptance-statistics/v1", ConfirmOnly: true}
+ if domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
+ stage = domain.HumanStageDefinition{ID: fanyuV5PrePackageAcceptanceStageID, Label: "整包最终验收", Kind: domain.HumanStageAcceptance, RequiredRole: "acceptance_reviewer", EditorSchema: "acceptance-package/v2", RejectTargets: []string{domain.FanyuV58StageQualityReview}}
+ }
acceptanceBatch = &domain.HumanBatchRecord{
ID: batchID, OrganizationID: source.OrganizationID, PluginID: source.PluginID,
ProjectID: source.ProjectID, WorkflowID: source.WorkflowID, RunID: source.RunID,
GateNodeID: source.GateNodeID + "-prepackage-acceptance", SourceBatchID: source.ID,
Status: domain.HumanBatchActive, ItemCount: 1, MaxReworkRounds: 0,
- Stages: []domain.HumanStageDefinition{{ID: fanyuV5PrePackageAcceptanceStageID, Label: "包前最终验收(仅确认)", Kind: domain.HumanStageAcceptance, RequiredRole: "quality_reviewer", EditorSchema: "acceptance-statistics/v1", ConfirmOnly: true}},
+ Stages: []domain.HumanStageDefinition{stage},
CreatedAt: now, UpdatedAt: now,
}
if err := server.store.UpsertHumanBatch(ctx, *acceptanceBatch); err != nil {
@@ -1503,8 +1619,11 @@ func (server *server) ensureFanyuV5PrePackageAcceptance(ctx context.Context, sou
if err != nil {
return false, err
}
- if acceptanceItem != nil {
- return acceptanceItem.Status == domain.HumanItemAccepted, nil
+ if acceptanceItem != nil && acceptanceItem.Status == domain.HumanItemAccepted {
+ return true, nil
+ }
+ if acceptanceItem != nil && acceptanceItem.Status != domain.HumanItemRejected {
+ return false, nil
}
aggregate := make([]map[string]any, 0, len(items))
statistics := map[string]any{
@@ -1584,12 +1703,26 @@ func (server *server) ensureFanyuV5PrePackageAcceptance(ctx context.Context, sou
aggregate = append(aggregate, map[string]any{"taskId": task.ID, "runId": task.RunID, "clipArtifactId": task.ArtifactID, "sourceVideo": task.SourceVideo, "clipStart": task.ClipStart, "clipEnd": task.ClipEnd, "finalSlices": latestSlices.Segments, "annotation": latestRevision.Segments, "poseSummary": poseSummary})
}
now := nowISO()
- acceptanceItem = &domain.HumanItemRecord{
- ID: acceptanceID, OrganizationID: source.OrganizationID, PluginID: source.PluginID, BatchID: batchID,
- ProjectID: source.ProjectID, WorkflowID: source.WorkflowID, RunID: source.RunID, GateNodeID: acceptanceBatch.GateNodeID,
- Subject: domain.HumanSubjectRef{ItemKey: source.ID, MediaType: "application/json", Payload: map[string]any{"sourceBatchId": source.ID, "items": aggregate, "statistics": statistics}},
- CurrentStageID: fanyuV5PrePackageAcceptanceStageID, Status: domain.HumanItemReady,
- WorkgroupID: items[0].WorkgroupID, VendorID: items[0].VendorID, MaxReworkRounds: 0, Version: 1, CreatedAt: now, UpdatedAt: now,
+ if acceptanceItem == nil {
+ acceptanceItem = &domain.HumanItemRecord{
+ ID: acceptanceID, OrganizationID: source.OrganizationID, PluginID: source.PluginID, BatchID: batchID,
+ ProjectID: source.ProjectID, WorkflowID: source.WorkflowID, RunID: source.RunID, GateNodeID: acceptanceBatch.GateNodeID,
+ Subject: domain.HumanSubjectRef{ItemKey: source.ID, MediaType: "application/json", Payload: map[string]any{"sourceBatchId": source.ID, "items": aggregate, "statistics": statistics, "strictThreeRole": domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages)}},
+ CurrentStageID: fanyuV5PrePackageAcceptanceStageID, Status: domain.HumanItemReady,
+ WorkgroupID: items[0].WorkgroupID, VendorID: items[0].VendorID, MaxReworkRounds: source.MaxReworkRounds, Version: 1, CreatedAt: now, UpdatedAt: now,
+ }
+ } else {
+ acceptanceItem.Subject.Payload = map[string]any{"sourceBatchId": source.ID, "items": aggregate, "statistics": statistics, "strictThreeRole": domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages)}
+ acceptanceItem.Status = domain.HumanItemReady
+ acceptanceItem.AssignedUserID = ""
+ acceptanceItem.ClaimedAt = ""
+ acceptanceItem.AcceptedAt = ""
+ acceptanceItem.AcceptedByUserID = ""
+ acceptanceItem.RejectedAt = ""
+ acceptanceItem.Version++
+ acceptanceItem.UpdatedAt = now
+ acceptanceBatch.Status = domain.HumanBatchActive
+ _ = server.store.UpsertHumanBatch(ctx, *acceptanceBatch)
}
if err := server.store.UpsertHumanItem(ctx, *acceptanceItem); err != nil {
return false, err
diff --git a/internal/domain/human_loop.go b/internal/domain/human_loop.go
index db55ba31..00adaefb 100644
--- a/internal/domain/human_loop.go
+++ b/internal/domain/human_loop.go
@@ -55,6 +55,28 @@ const (
FanyuV5StageSemanticReview = "semantic_review"
)
+// Fanyu v5.8 restores the confirmed three-role production loop. The
+// annotator owns one atomic cut+semantic submission, the quality reviewer
+// reviews that complete submission, and a distinct acceptance reviewer owns
+// the aggregate pre-package decision.
+const (
+ FanyuV58StageAnnotationCombined = "annotation_combined"
+ FanyuV58StageQualityReview = "quality_review"
+)
+
+type PoseDeliveryDecision string
+
+const (
+ PoseDeliveryInclude PoseDeliveryDecision = "include"
+ PoseDeliveryExclude PoseDeliveryDecision = "exclude"
+)
+
+type PoseDeliveryPolicy struct {
+ Headpose PoseDeliveryDecision `json:"headpose" bson:"headpose"`
+ Handpose PoseDeliveryDecision `json:"handpose" bson:"handpose"`
+ ReasonCodes []string `json:"reasonCodes,omitempty" bson:"reasonCodes,omitempty"`
+}
+
type HumanStageDefinition struct {
ID string `json:"id" bson:"id"`
Label string `json:"label" bson:"label"`
@@ -280,6 +302,20 @@ func DefaultFanyuV5HumanStages() []HumanStageDefinition {
}
}
+func DefaultFanyuV58HumanStages() []HumanStageDefinition {
+ return []HumanStageDefinition{
+ {ID: FanyuV58StageAnnotationCombined, Label: "真实切分与语义标注", Kind: HumanStageAnnotation, RequiredRole: "annotator", EditorSchema: "temporal-semantic-annotation/v2"},
+ {ID: FanyuV58StageQualityReview, Label: "切分与标注审核", Kind: HumanStageReview, RequiredRole: "quality_reviewer", RejectTargets: []string{FanyuV58StageAnnotationCombined}},
+ }
+}
+
+func IsFanyuV58ThreeRoleHumanLoop(stages []HumanStageDefinition) bool {
+ return len(stages) == 2 &&
+ stages[0].ID == FanyuV58StageAnnotationCombined && stages[0].Kind == HumanStageAnnotation && stages[0].RequiredRole == "annotator" &&
+ stages[1].ID == FanyuV58StageQualityReview && stages[1].Kind == HumanStageReview && stages[1].RequiredRole == "quality_reviewer" &&
+ len(stages[1].RejectTargets) == 1 && stages[1].RejectTargets[0] == FanyuV58StageAnnotationCombined
+}
+
// IsFanyuV5FourStageHumanLoop is deliberately strict: historical v5 combined
// batches stay readable through their legacy adapter while newly created v5
// work uses the independent cut and semantic review loop.
diff --git a/internal/plugins/registry.go b/internal/plugins/registry.go
index a443fa7c..bacad11c 100644
--- a/internal/plugins/registry.go
+++ b/internal/plugins/registry.go
@@ -24,17 +24,15 @@ var builtin = map[string]domain.PluginManifest{
Routes: []domain.PluginRouteContribution{
{ID: "clip", Path: "/plugins/annotation-qa/workflows/:workflowId/clip", Label: "人工调切", RequiredRoles: []string{"admin", "cutter"}},
{ID: "clip-quality", Path: "/plugins/annotation-qa/workflows/:workflowId/clip-quality", Label: "剪切审核", RequiredRoles: []string{"admin", "annotator"}},
- {ID: "annotate", Path: "/plugins/annotation-qa/workflows/:workflowId/annotate", Label: "语义标注", RequiredRoles: []string{"admin", "annotator"}},
- {ID: "quality", Path: "/plugins/annotation-qa/workflows/:workflowId/quality", Label: "标注审核", RequiredRoles: []string{"admin", "quality_reviewer"}},
- {ID: "acceptance", Path: "/plugins/annotation-qa/workflows/:workflowId/acceptance", Label: "最终验收", RequiredRoles: []string{"admin", "quality_reviewer", "acceptance_reviewer"}},
+ {ID: "annotate", Path: "/plugins/annotation-qa/workflows/:workflowId/annotate", Label: "真实切分与语义标注", RequiredRoles: []string{"admin", "annotator"}},
+ {ID: "quality", Path: "/plugins/annotation-qa/workflows/:workflowId/quality", Label: "切分与标注审核", RequiredRoles: []string{"admin", "quality_reviewer"}},
+ {ID: "acceptance", Path: "/plugins/annotation-qa/workflows/:workflowId/acceptance", Label: "最终验收", RequiredRoles: []string{"admin", "acceptance_reviewer"}},
{ID: "item", Path: "/plugins/annotation-qa/items/:itemId", Label: "标注任务详情"},
},
Navigation: []domain.PluginNavigationContribution{
- {ID: "annotate", Label: "语义标注", Path: "/plugins/annotation-qa/workflows/all/annotate", Icon: "tags", Order: 10, GroupID: "annotation-center", GroupLabel: "标注中心", GroupIcon: "tags", RequiredRoles: []string{"admin", "annotator"}},
- {ID: "quality", Label: "标注审核", Path: "/plugins/annotation-qa/workflows/all/quality", Icon: "clipboard-check", Order: 20, GroupID: "annotation-center", GroupLabel: "标注中心", GroupIcon: "tags", RequiredRoles: []string{"admin", "quality_reviewer"}},
- {ID: "clip", Label: "人工剪切", Path: "/plugins/annotation-qa/workflows/all/clip", Icon: "scissors", Order: 30, GroupID: "annotation-center", GroupLabel: "标注中心", GroupIcon: "tags", RequiredRoles: []string{"admin", "cutter"}},
- {ID: "clip-quality", Label: "剪切审核", Path: "/plugins/annotation-qa/workflows/all/clip-quality", Icon: "shield-check", Order: 40, GroupID: "annotation-center", GroupLabel: "标注中心", GroupIcon: "tags", RequiredRoles: []string{"admin", "annotator"}},
- {ID: "acceptance", Label: "最终验收", Path: "/plugins/annotation-qa/workflows/all/acceptance", Icon: "shield-check", Order: 50, GroupID: "annotation-center", GroupLabel: "标注中心", GroupIcon: "tags", RequiredRoles: []string{"admin", "quality_reviewer", "acceptance_reviewer"}},
+ {ID: "annotate", Label: "切分与语义标注", Path: "/plugins/annotation-qa/workflows/all/annotate", Icon: "tags", Order: 10, GroupID: "annotation-center", GroupLabel: "标注中心", GroupIcon: "tags", RequiredRoles: []string{"admin", "annotator"}},
+ {ID: "quality", Label: "切分与标注审核", Path: "/plugins/annotation-qa/workflows/all/quality", Icon: "clipboard-check", Order: 20, GroupID: "annotation-center", GroupLabel: "标注中心", GroupIcon: "tags", RequiredRoles: []string{"admin", "quality_reviewer"}},
+ {ID: "acceptance", Label: "最终验收", Path: "/plugins/annotation-qa/workflows/all/acceptance", Icon: "shield-check", Order: 50, GroupID: "annotation-center", GroupLabel: "标注中心", GroupIcon: "tags", RequiredRoles: []string{"admin", "acceptance_reviewer"}},
},
WorkflowCapabilities: []string{"human_cut_adjustment", "human_cut_review", "human_annotation", "human_quality_review", "human_acceptance"},
OperatorIDs: []string{
diff --git a/internal/plugins/registry_test.go b/internal/plugins/registry_test.go
index f28cba51..ec13dc32 100644
--- a/internal/plugins/registry_test.go
+++ b/internal/plugins/registry_test.go
@@ -28,10 +28,10 @@ func TestAnnotationManifestContributesWorkbenchesAndOperators(t *testing.T) {
if !ok {
t.Fatal("annotation plugin manifest is missing")
}
- if len(manifest.Navigation) != 5 {
- t.Fatalf("expected five navigation contributions, got %#v", manifest.Navigation)
+ if len(manifest.Navigation) != 3 {
+ t.Fatalf("expected three-role navigation contributions, got %#v", manifest.Navigation)
}
- if manifest.Navigation[0].ID != "annotate" || manifest.Navigation[4].ID != "acceptance" {
+ if manifest.Navigation[0].ID != "annotate" || manifest.Navigation[2].ID != "acceptance" {
t.Fatalf("unexpected navigation order: %#v", manifest.Navigation)
}
for _, item := range manifest.Navigation {
@@ -43,14 +43,8 @@ func TestAnnotationManifestContributesWorkbenchesAndOperators(t *testing.T) {
for _, item := range manifest.Navigation {
rolesByID[item.ID] = item.RequiredRoles
}
- if len(rolesByID["clip"]) != 2 || rolesByID["clip"][1] != "cutter" {
- t.Fatalf("cut pool must belong to cutter: %#v", rolesByID["clip"])
- }
- if len(rolesByID["clip-quality"]) != 2 || rolesByID["clip-quality"][1] != "annotator" {
- t.Fatalf("cut review must belong to annotator: %#v", rolesByID["clip-quality"])
- }
- if len(rolesByID["acceptance"]) < 2 || rolesByID["acceptance"][1] != "quality_reviewer" {
- t.Fatalf("final acceptance must belong to reviewer: %#v", rolesByID["acceptance"])
+ if len(rolesByID["acceptance"]) != 2 || rolesByID["acceptance"][1] != "acceptance_reviewer" {
+ t.Fatalf("final acceptance must belong only to the independent acceptance reviewer: %#v", rolesByID["acceptance"])
}
wanted := map[string]bool{
"operator-builtin-annotation-gate": true,
diff --git a/internal/worker/annotation_gate.go b/internal/worker/annotation_gate.go
index 9bf0db00..76b9a152 100644
--- a/internal/worker/annotation_gate.go
+++ b/internal/worker/annotation_gate.go
@@ -732,12 +732,12 @@ func fanyuV5PrePackageAcceptanceEvidence(ctx context.Context, runtime *Runtime,
if strings.TrimSpace(item.AcceptedByUserID) == "" {
return nil, fmt.Errorf("v5 pre-package acceptance has no confirmer identity")
}
- canonical, marshalErr := json.Marshal(map[string]any{"batchId": acceptanceBatch.ID, "itemId": item.ID, "version": item.Version, "acceptedAt": item.AcceptedAt, "confirmedByUserId": item.AcceptedByUserID, "statistics": payload["statistics"], "sourceBatchId": sourceBatch.ID})
+ canonical, marshalErr := json.Marshal(map[string]any{"batchId": acceptanceBatch.ID, "itemId": item.ID, "version": item.Version, "acceptedAt": item.AcceptedAt, "confirmedByUserId": item.AcceptedByUserID, "statistics": payload["statistics"], "poseDelivery": payload["poseDelivery"], "sourceBatchId": sourceBatch.ID})
if marshalErr != nil {
return nil, marshalErr
}
digest := sha256.Sum256(canonical)
- return map[string]any{"confirmed": true, "humanBatchId": acceptanceBatch.ID, "humanItemId": item.ID, "humanItemVersion": item.Version, "acceptedAt": item.AcceptedAt, "confirmedByUserId": item.AcceptedByUserID, "statistics": payload["statistics"], "canonical": string(canonical), "sha256": hex.EncodeToString(digest[:])}, nil
+ return map[string]any{"confirmed": true, "humanBatchId": acceptanceBatch.ID, "humanItemId": item.ID, "humanItemVersion": item.Version, "acceptedAt": item.AcceptedAt, "confirmedByUserId": item.AcceptedByUserID, "statistics": payload["statistics"], "poseDelivery": payload["poseDelivery"], "canonical": string(canonical), "sha256": hex.EncodeToString(digest[:])}, nil
}
func annotationArtifactSize(size int64) string {
diff --git a/operator-repos/builtin/package/src/operator.py b/operator-repos/builtin/package/src/operator.py
index 53cdb3a1..55cc8510 100644
--- a/operator-repos/builtin/package/src/operator.py
+++ b/operator-repos/builtin/package/src/operator.py
@@ -2,6 +2,8 @@
from __future__ import annotations
import hashlib
+import bisect
+import csv
import json
import pathlib
import re
@@ -188,6 +190,8 @@ def _camera_collection_id(value: Any) -> str:
def _right_video_artifacts(inputs: list[dict[str, Any]]) -> list[dict[str, Any]]:
artifacts: list[dict[str, Any]] = []
for artifact in inputs:
+ if str(artifact.get("type", "")).strip().lower() != "video":
+ continue
port = str(artifact.get("portId") or artifact.get("portName") or "").strip()
data = artifact.get("data") if isinstance(artifact.get("data"), dict) else {}
transform_chain = data.get("transformChain") if isinstance(data.get("transformChain"), list) else []
@@ -246,6 +250,149 @@ def _materialize_input_video(
return resolved
+def _materialize_input_file(artifact: dict[str, Any], output: pathlib.Path, helpers: HelperMap) -> pathlib.Path:
+ materialize = helpers.get("source_path_from_item")
+ if not callable(materialize):
+ raise RuntimeError("synchronized delivery cannot materialize a sidecar file")
+ source_ref = helpers.get("source_ref_from_artifact")
+ source = source_ref(artifact) if callable(source_ref) else artifact.get("source", {})
+ name = str(artifact.get("name") or "sidecar.bin").strip()
+ resolved = pathlib.Path(materialize({"source": source if isinstance(source, dict) else {}, "path": str(artifact.get("path", ""))}, name, output, {}))
+ if not resolved.is_file() or resolved.stat().st_size <= 0:
+ raise RuntimeError(f"synchronized delivery sidecar is unavailable: {name}")
+ return resolved
+
+
+def _sidecar_artifacts(inputs: list[dict[str, Any]], ports: set[str]) -> list[dict[str, Any]]:
+ return [artifact for artifact in inputs if str(artifact.get("portId") or artifact.get("portName") or "").strip() in ports]
+
+
+def _matching_sidecar(collection_id: str, candidates: list[dict[str, Any]], marker: str = "") -> dict[str, Any]:
+ filtered = [item for item in candidates if not marker or marker in str(item.get("name") or "").lower()]
+ matches = [item for item in filtered if _camera_collection_id(item) == collection_id]
+ if len(matches) == 1:
+ return matches[0]
+ if len(filtered) == 1:
+ return filtered[0]
+ if not matches:
+ raise RuntimeError(f"no {marker or 'sidecar'} file matches collection {collection_id}")
+ raise RuntimeError(f"multiple {marker or 'sidecar'} files match collection {collection_id}")
+
+
+def _clean_csv_cell(value: Any) -> str:
+ return str(value or "").strip().strip("\ufeff").strip("\t").strip()
+
+
+def _read_rows(path: pathlib.Path) -> tuple[list[str], list[list[str]]]:
+ lines = path.read_text(encoding="utf-8-sig").splitlines()
+ if not lines:
+ raise RuntimeError(f"sidecar CSV is empty: {path.name}")
+ delimiter = "," if "," in lines[0] else "\t"
+ parsed = list(csv.reader(lines, delimiter=delimiter))
+ header = [_clean_csv_cell(value) for value in parsed[0]]
+ rows = [[_clean_csv_cell(value) for value in row] for row in parsed[1:] if any(_clean_csv_cell(value) for value in row)]
+ return header, rows
+
+
+def _read_pts(path: pathlib.Path) -> list[int]:
+ header, rows = _read_rows(path)
+ normalized = {name.lower(): index for index, name in enumerate(header)}
+ if "timestamp_us" not in normalized:
+ raise RuntimeError(f"PTS CSV must contain timestamp_us: {path.name}")
+ column = normalized["timestamp_us"]
+ values: list[int] = []
+ for row in rows:
+ try:
+ value = int(row[column])
+ except (IndexError, ValueError) as exc:
+ raise RuntimeError(f"PTS CSV contains an invalid timestamp_us: {path.name}") from exc
+ if values and value <= values[-1]:
+ raise RuntimeError(f"PTS CSV timestamp_us must be strictly increasing: {path.name}")
+ values.append(value)
+ if not values:
+ raise RuntimeError(f"PTS CSV has no frame timestamps: {path.name}")
+ return values
+
+
+def _read_imu(path: pathlib.Path) -> list[dict[str, Any]]:
+ header, rows = _read_rows(path)
+ indexes = {name.lower(): index for index, name in enumerate(header)}
+ required = {"timestamp_us", "x", "y", "z", "type"}
+ if not required.issubset(indexes):
+ raise RuntimeError(f"IMU CSV must contain timestamp_us,x,y,z,type: {path.name}")
+ result: list[dict[str, Any]] = []
+ previous = -1
+ for row in rows:
+ try:
+ timestamp = int(row[indexes["timestamp_us"]])
+ kind = row[indexes["type"]].lower()
+ values = [float(row[indexes[key]]) for key in ("x", "y", "z")]
+ except (IndexError, ValueError) as exc:
+ raise RuntimeError(f"IMU CSV contains an invalid row: {path.name}") from exc
+ if kind not in {"accel", "gyro"} or timestamp < previous:
+ raise RuntimeError(f"IMU CSV type/timestamp ordering is invalid: {path.name}")
+ previous = timestamp
+ result.append({"timestamp_us": timestamp, "x": values[0], "y": values[1], "z": values[2], "type": kind})
+ if not result:
+ raise RuntimeError(f"IMU CSV has no samples: {path.name}")
+ return result
+
+
+def _ffprobe_frame_count(path: pathlib.Path) -> int:
+ completed = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_frames", "-show_entries", "stream=nb_read_frames", "-of", "default=nokey=1:noprint_wrappers=1", str(path)], capture_output=True, text=True, check=False)
+ try:
+ count = int(completed.stdout.strip())
+ except ValueError as exc:
+ raise RuntimeError(f"cannot determine decoded video frame count: {path.name}") from exc
+ if completed.returncode != 0 or count <= 0:
+ raise RuntimeError(f"cannot determine decoded video frame count: {path.name}")
+ return count
+
+
+def _write_frame_segment(source: pathlib.Path, destination: pathlib.Path, start_frame: int, end_frame: int) -> None:
+ if shutil.which("ffmpeg") is None or shutil.which("ffprobe") is None:
+ raise RuntimeError("synchronized delivery requires ffmpeg and ffprobe")
+ if start_frame < 0 or end_frame <= start_frame:
+ raise RuntimeError("synchronized video frame range is empty")
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ expression = f"trim=start_frame={start_frame}:end_frame={end_frame},setpts=PTS-STARTPTS"
+ completed = subprocess.run(["ffmpeg", "-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-i", str(source), "-an", "-vf", expression, "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-pix_fmt", "yuv420p", "-movflags", "+faststart", str(destination)], capture_output=True, text=True, check=False)
+ if completed.returncode != 0 or not destination.is_file() or destination.stat().st_size <= 0:
+ raise RuntimeError(f"synchronized frame-accurate cut failed: {(completed.stderr or completed.stdout).strip()[:800]}")
+
+
+def _write_pts_slice(path: pathlib.Path, timestamps: list[int], start_index: int, end_index: int) -> dict[str, Any]:
+ selected = timestamps[start_index:end_index]
+ if not selected:
+ raise RuntimeError("synchronized PTS slice is empty")
+ with path.open("w", encoding="utf-8", newline="") as handle:
+ writer = csv.writer(handle)
+ writer.writerow(["frame_index", "timestamp_ms", "clip_time_ms"])
+ origin = selected[0]
+ for index, value in enumerate(selected):
+ writer.writerow([index, round(value / 1000), round((value - origin) / 1000)])
+ return {"name": path.name, "sha256": _sha256_file(path), "bytes": path.stat().st_size, "rowCount": len(selected), "firstTimestampUs": selected[0], "lastTimestampUs": selected[-1]}
+
+
+def _write_imu_slice(path: pathlib.Path, rows: list[dict[str, Any]], start_us: int, end_us: int) -> dict[str, Any]:
+ selected = [row for row in rows if start_us <= int(row["timestamp_us"]) < end_us]
+ if not selected:
+ raise RuntimeError("synchronized IMU slice is empty")
+ by_timestamp: dict[int, set[str]] = {}
+ for row in selected:
+ by_timestamp.setdefault(int(row["timestamp_us"]), set()).add(str(row["type"]))
+ if any(types != {"accel", "gyro"} for types in by_timestamp.values()):
+ raise RuntimeError("synchronized IMU slice contains an unpaired accel/gyro timestamp")
+ with path.open("w", encoding="utf-8", newline="") as handle:
+ writer = csv.writer(handle)
+ writer.writerow(["timestamp_ms", "clip_time_ms", "x", "y", "z", "type"])
+ origin = int(selected[0]["timestamp_us"])
+ for row in selected:
+ timestamp = int(row["timestamp_us"])
+ writer.writerow([round(timestamp / 1000), round((timestamp - origin) / 1000), row["x"], row["y"], row["z"], row["type"]])
+ return {"name": path.name, "sha256": _sha256_file(path), "bytes": path.stat().st_size, "sampleCount": len(selected), "timestampCount": len(by_timestamp), "firstTimestampUs": int(selected[0]["timestamp_us"]), "lastTimestampUs": int(selected[-1]["timestamp_us"])}
+
+
def _write_verified_segment(
source: pathlib.Path,
destination: pathlib.Path,
@@ -269,7 +416,7 @@ def _write_verified_segment(
}
-def _validate_final_acceptance(item: dict[str, Any]) -> None:
+def _validate_final_acceptance(item: dict[str, Any]) -> dict[str, Any]:
evidence = item.get("finalAcceptance") if isinstance(item.get("finalAcceptance"), dict) else {}
canonical = str(evidence.get("canonical", ""))
digest = str(evidence.get("sha256", "")).lower()
@@ -279,6 +426,7 @@ def _validate_final_acceptance(item: dict[str, Any]) -> None:
raise RuntimeError("pre-package acceptance evidence SHA-256 does not verify")
if not str(evidence.get("confirmedByUserId", "")).strip():
raise RuntimeError("pre-package acceptance evidence has no confirmer identity")
+ return evidence
def _write_precise_final_segment(source: pathlib.Path, destination: pathlib.Path, start: float, end: float) -> None:
@@ -357,6 +505,23 @@ def _materialize_final_mp4(item: dict[str, Any], package_dir: pathlib.Path, help
return destination
+def _materialize_left_source(item: dict[str, Any], directory: pathlib.Path, helpers: HelperMap) -> pathlib.Path:
+ source_path = pathlib.Path(str(item.get("clipPath", "")).strip())
+ if source_path.is_file() and source_path.stat().st_size > 0:
+ return source_path
+ source = item.get("source") if isinstance(item.get("source"), dict) else {}
+ resolved = pathlib.Path(
+ helpers["source_path_from_item"](
+ {"source": source or {"path": str(item.get("clipPath", "")).strip()}},
+ str(item.get("sourceVideo") or pathlib.PurePosixPath(str(item.get("clipPath", ""))).name or "left-camera.mp4"),
+ directory,
+ )
+ )
+ if not resolved.is_file() or resolved.stat().st_size <= 0:
+ raise RuntimeError("left-camera video is unavailable for synchronized cropping")
+ return resolved
+
+
def _collect_unique_package_artifacts(
run_id: str,
node_id: str,
@@ -382,6 +547,90 @@ def _collect_unique_package_artifacts(
return artifacts
+def _copy_calibrations(inputs: list[dict[str, Any]], packages_root: pathlib.Path, output: pathlib.Path, helpers: HelperMap) -> list[dict[str, Any]]:
+ destination = packages_root / "calibration"
+ result: list[dict[str, Any]] = []
+ seen: set[str] = set()
+ for artifact in _sidecar_artifacts(inputs, {"calibrations"}):
+ name = str(artifact.get("name") or "").strip()
+ if not name or name in seen:
+ continue
+ seen.add(name)
+ source = _materialize_input_file(artifact, output / "_inputs", helpers)
+ destination.mkdir(parents=True, exist_ok=True)
+ target = destination / name
+ shutil.copy2(source, target)
+ result.append({"name": name, "path": f"calibration/{name}", "sha256": _sha256_file(target), "bytes": target.stat().st_size})
+ if not result:
+ raise RuntimeError("synchronized delivery requires camera/IMU calibration files")
+ return result
+
+
+def _synchronized_segment(
+ item: dict[str, Any],
+ clip_id: str,
+ package_dir: pathlib.Path,
+ output: pathlib.Path,
+ start: float,
+ end: float,
+ inputs: list[dict[str, Any]],
+ right_videos: list[dict[str, Any]],
+ helpers: HelperMap,
+) -> tuple[pathlib.Path, dict[str, Any], dict[str, Any]]:
+ collection_id = str(item.get("collectionId") or "").strip() or _camera_collection_id(_source_video_name(item))
+ left_pts_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"leftTimestamps"}), "left")
+ right_pts_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"rightTimestamps"}), "right")
+ imu_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"imu"}), "imu")
+ left_pts_path = _materialize_input_file(left_pts_artifact, output / "_inputs", helpers)
+ right_pts_path = _materialize_input_file(right_pts_artifact, output / "_inputs", helpers)
+ imu_path = _materialize_input_file(imu_artifact, output / "_inputs", helpers)
+ left_pts = _read_pts(left_pts_path)
+ right_pts = _read_pts(right_pts_path)
+ imu_rows = _read_imu(imu_path)
+ left_source = _materialize_left_source(item, output / "_inputs", helpers)
+ right_artifact = _matching_right_video(item, right_videos)
+ if right_artifact is None:
+ raise RuntimeError(f"accepted segment {clip_id} has no matching right-camera video")
+ right_source = _materialize_input_video(right_artifact, output / "_inputs", helpers)
+ if _ffprobe_frame_count(left_source) != len(left_pts):
+ raise RuntimeError("left-camera decoded frame count does not match left PTS rows")
+ if _ffprobe_frame_count(right_source) != len(right_pts):
+ raise RuntimeError("right-camera decoded frame count does not match right PTS rows")
+ target_start_us = left_pts[0] + round(start * 1_000_000)
+ target_end_us = left_pts[0] + round(end * 1_000_000)
+ imu_first, imu_last = int(imu_rows[0]["timestamp_us"]), int(imu_rows[-1]["timestamp_us"])
+ common_start = max(left_pts[0], right_pts[0], imu_first)
+ common_end = min(left_pts[-1], right_pts[-1], imu_last)
+ if target_start_us < common_start or target_end_us > common_end or target_end_us <= target_start_us:
+ raise RuntimeError("final segment is outside the common left/right/IMU hardware timestamp range")
+ left_start, left_end = bisect.bisect_left(left_pts, target_start_us), bisect.bisect_left(left_pts, target_end_us)
+ right_start, right_end = bisect.bisect_left(right_pts, target_start_us), bisect.bisect_left(right_pts, target_end_us)
+ left_destination = package_dir / str(item.get("clipName") or f"{clip_id}_left.mp4")
+ right_destination = package_dir / f"{clip_id}_right.mp4"
+ _write_frame_segment(left_source, left_destination, left_start, left_end)
+ _write_frame_segment(right_source, right_destination, right_start, right_end)
+ if _ffprobe_frame_count(left_destination) != left_end - left_start or _ffprobe_frame_count(right_destination) != right_end - right_start:
+ raise RuntimeError("synchronized output frame count does not match sliced PTS rows")
+ left_pts_manifest = _write_pts_slice(package_dir / f"{clip_id}_left_pts.csv", left_pts, left_start, left_end)
+ right_pts_manifest = _write_pts_slice(package_dir / f"{clip_id}_right_pts.csv", right_pts, right_start, right_end)
+ imu_manifest = _write_imu_slice(package_dir / f"{clip_id}_imu.csv", imu_rows, target_start_us, target_end_us)
+ left_video = {"name": left_destination.name, "sha256": _sha256_file(left_destination), "bytes": left_destination.stat().st_size, "cameraSide": "left", "frameCount": left_end - left_start}
+ right_video = {"name": right_destination.name, "sha256": _sha256_file(right_destination), "bytes": right_destination.stat().st_size, "cameraSide": "right", "frameCount": right_end - right_start, "sourceVideo": str(right_artifact.get("name") or right_source.name)}
+ alignment_values = [left_pts[left_start], right_pts[right_start], int(imu_manifest["firstTimestampUs"]), left_pts[left_end - 1], right_pts[right_end - 1], int(imu_manifest["lastTimestampUs"])]
+ max_alignment_error_us = max(abs(value - target_start_us) for value in alignment_values[:3])
+ synchronized = {
+ "schemaVersion": "droboticflow.synchronized-slice/v1",
+ "collectionId": collection_id,
+ "window": {"startTimestampUs": target_start_us, "endTimestampUs": target_end_us, "semantics": "half-open"},
+ "commonRange": {"startTimestampUs": common_start, "endTimestampUs": common_end},
+ "left": {"video": left_video, "pts": left_pts_manifest},
+ "right": {"video": right_video, "pts": right_pts_manifest},
+ "imu": imu_manifest,
+ "maxStartAlignmentErrorUs": max_alignment_error_us,
+ }
+ return left_destination, right_video, synchronized
+
+
def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[str, Any], inputs: list[dict[str, Any]], helpers: HelperMap) -> list[dict[str, Any]]:
output = pathlib.Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
@@ -392,14 +641,16 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
pose_free = _bool(params, "POSE_FREE", False)
require_final_acceptance = _bool(params, "REQUIRE_FINAL_ACCEPTANCE", False)
generate_segment_mp4 = _bool(params, "GENERATE_SEGMENT_MP4", False)
+ synchronized_sidecars = _bool(params, "SYNCHRONIZED_SIDECARS", False)
+ allow_pose_exclusion = _bool(params, "ALLOW_POSE_EXCLUSION", False)
payloads = _payload_tree(_payloads_with_full_pose_manifests(inputs, output, helpers))
headpose = _first_payload(payloads, "droboticflow.headpose/v1")
handpose = _first_payload(payloads, "droboticflow.wilor.hand_pose_result/v1")
if pose_free and (headpose is not None or handpose is not None):
raise RuntimeError("pose-free v5 package rejects HeadPose and HandPose payloads")
- if require_headpose and (headpose is None or not headpose.get("enabled") or not isinstance(headpose.get("frames"), list)):
+ if require_headpose and not allow_pose_exclusion and (headpose is None or not headpose.get("enabled") or not isinstance(headpose.get("frames"), list)):
raise RuntimeError("package requires a real Headpose manifest with frames")
- if require_handpose and (
+ if require_handpose and not allow_pose_exclusion and (
handpose is None
or handpose.get("enabled") is False
or not _pose_frames(handpose, "handpose")
@@ -427,9 +678,22 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
raise RuntimeError("stereo delivery has no accepted Qwen clip with a camera collection")
package_items: list[dict[str, Any]] = []
binding = helpers["output_binding"](node_data)
+ calibration_refs = _copy_calibrations(inputs, output / "packages", output, helpers) if synchronized_sidecars else []
+ package_pose_policy: dict[str, Any] | None = None
for index, item in enumerate(accepted_items):
+ acceptance_evidence: dict[str, Any] = {}
if require_final_acceptance:
- _validate_final_acceptance(item)
+ acceptance_evidence = _validate_final_acceptance(item)
+ pose_policy = acceptance_evidence.get("poseDelivery") if isinstance(acceptance_evidence.get("poseDelivery"), dict) else {}
+ if allow_pose_exclusion:
+ if pose_policy.get("headpose") not in {"include", "exclude"} or pose_policy.get("handpose") not in {"include", "exclude"}:
+ raise RuntimeError("v5.8 final acceptance must decide HeadPose and HandPose inclusion")
+ if package_pose_policy is None:
+ package_pose_policy = pose_policy
+ elif package_pose_policy != pose_policy:
+ raise RuntimeError("v5.8 package items contain conflicting aggregate pose delivery decisions")
+ include_headpose = not allow_pose_exclusion or pose_policy.get("headpose") == "include"
+ include_handpose = not allow_pose_exclusion or pose_policy.get("handpose") == "include"
clip_id = str(item.get("clipId") or f"segment-{index + 1:04d}").strip()
package_dir = output / "packages" / f"{clip_id}_package"
package_dir.mkdir(parents=True, exist_ok=True)
@@ -439,7 +703,11 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
raise RuntimeError("accepted package item has invalid final source boundaries")
# 虚拟切片条目没有物理中间片段:无论是否显式要求 MP4,
# 都必须按源视频区间在打包阶段精确物化最终交付 MP4。
- if generate_segment_mp4 or item.get("finalSegment") is True or item.get("virtualCut") is True:
+ synchronized_manifest = None
+ right_video_manifest = None
+ if synchronized_sidecars:
+ video_path, right_video_manifest, synchronized_manifest = _synchronized_segment(item, clip_id, package_dir, output, start, end, inputs, right_videos, helpers)
+ elif generate_segment_mp4 or item.get("finalSegment") is True or item.get("virtualCut") is True:
video_path = _materialize_final_mp4(item, package_dir, helpers)
else:
source = pathlib.Path(str(item.get("clipPath", "")).strip())
@@ -448,15 +716,14 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
video_path = package_dir / (str(item.get("clipName") or source.name))
shutil.copy2(source, video_path)
annotation = item.get("annotation") if isinstance(item.get("annotation"), dict) else {}
- headpose_segment = _crop_pose(headpose, start, end, "headpose") if headpose else None
- handpose_segment = _crop_pose(handpose, start, end, "handpose") if handpose and handpose.get("enabled", True) else None
- if require_headpose and (headpose_segment is None or headpose_segment["frameCount"] <= 0):
+ headpose_segment = _crop_pose(headpose, start, end, "headpose") if include_headpose and headpose else None
+ handpose_segment = _crop_pose(handpose, start, end, "handpose") if include_handpose and handpose and handpose.get("enabled", True) else None
+ if require_headpose and include_headpose and (headpose_segment is None or headpose_segment["frameCount"] <= 0):
raise RuntimeError("required Headpose has no frame inside the final half-open segment interval")
- if require_handpose and (handpose_segment is None or handpose_segment["frameCount"] <= 0):
+ if require_handpose and include_handpose and (handpose_segment is None or handpose_segment["frameCount"] <= 0):
raise RuntimeError("required HandPose has no frame inside the final half-open segment interval")
- right_video = _matching_right_video(item, right_videos)
- right_video_manifest = None
- if right_video is not None:
+ right_video = None if synchronized_sidecars else _matching_right_video(item, right_videos)
+ if not synchronized_sidecars and right_video is not None:
right_source = _materialize_input_video(right_video, output, helpers)
right_destination = package_dir / f"{clip_id}_right.mp4"
right_video_manifest = _write_verified_segment(right_source, right_destination, start, end, helpers)
@@ -466,9 +733,12 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
right_video_manifest["transformChain"] = (
right_data.get("transformChain") if isinstance(right_data.get("transformChain"), list) else []
)
- elif require_stereo_delivery:
+ elif not synchronized_sidecars and require_stereo_delivery:
raise RuntimeError(f"accepted segment {clip_id} has no matching right-camera video")
helpers["write_json_artifact"](run_id, node_id, package_dir, "semantic.json", annotation, output=binding)
+ if synchronized_manifest is not None:
+ synchronized_manifest["calibration"] = calibration_refs
+ helpers["write_json_artifact"](run_id, node_id, package_dir, "synchronized-slice.json", synchronized_manifest, output=binding)
segment_manifest = {
"schemaVersion": "droboticflow.delivery.segment/v2",
"clipId": clip_id,
@@ -478,6 +748,9 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
"semantic": {"file": "semantic.json", "actionCount": len(annotation.get("actions", []))},
"transformChain": item.get("transformChain", []) if isinstance(item.get("transformChain"), list) else [],
"finalAcceptance": item.get("finalAcceptance") if require_final_acceptance else None,
+ "poseDelivery": pose_policy if allow_pose_exclusion else None,
+ "synchronizedSlice": {"file": "synchronized-slice.json", "schemaVersion": "droboticflow.synchronized-slice/v1"} if synchronized_manifest is not None else None,
+ "calibration": calibration_refs,
}
segment_manifest["videos"] = {
"left": {**segment_manifest["video"], "cameraSide": "left"},
@@ -495,7 +768,7 @@ def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[st
package_items.append({"packageName": package_dir.name, "clipId": clip_id, "clipName": video_path.name, "rightClipName": right_video_manifest["name"] if right_video_manifest else "", "sourceVideo": source_video, "sourceRightVideo": right_video_manifest["sourceVideo"] if right_video_manifest else "", "stereo": right_video_manifest is not None, "storagePath": str(package_dir), "startSecond": start, "endSecond": end, "clipDuration": end - start, "duration": end - start, "fileCount": len([path for path in package_dir.iterdir() if path.is_file()]), "quality": quality, "annotation": annotation, "segmentManifest": segment_manifest})
if not package_items:
raise RuntimeError("package produced zero final segment packages")
- manifest = {"schemaVersion": "droboticflow.delivery.manifest/v3", "datasetType": "fanyu-v5-final-segments", "packageCount": len(package_items), "stereoDelivery": all(item["stereo"] for item in package_items), "headposeIncluded": headpose is not None, "handposeIncluded": handpose is not None and handpose.get("enabled", True), "items": package_items, "trainingEnabled": False}
+ manifest = {"schemaVersion": "droboticflow.delivery.manifest/v4" if synchronized_sidecars else "droboticflow.delivery.manifest/v3", "datasetType": "fanyu-v5-final-segments", "packageCount": len(package_items), "stereoDelivery": all(item["stereo"] for item in package_items), "headposeIncluded": headpose is not None and (not allow_pose_exclusion or (package_pose_policy or {}).get("headpose") == "include"), "handposeIncluded": handpose is not None and handpose.get("enabled", True) and (not allow_pose_exclusion or (package_pose_policy or {}).get("handpose") == "include"), "poseDelivery": package_pose_policy, "audioIncluded": False if synchronized_sidecars else None, "calibration": calibration_refs, "items": package_items, "trainingEnabled": False}
artifacts = [helpers["write_json_artifact"](run_id, node_id, output, "packages-manifest.json", manifest, output=binding)]
artifacts.extend(_collect_unique_package_artifacts(run_id, node_id, output / "packages", node_data, binding, helpers))
return artifacts
diff --git a/src/App.tsx b/src/App.tsx
index c4cf552a..ce7e45f6 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -111,7 +111,7 @@ function RoleRouteGuard({ children }: { children: React.ReactNode }) {
currentUser?.role === "data_operator"
? "annotator"
: currentUser?.role === "acceptance_reviewer"
- ? "quality_reviewer"
+ ? "acceptance_reviewer"
: currentUser?.role === "qa_reviewer" ||
currentUser?.role === "auditor" ||
currentUser?.role === "compliance_auditor"
@@ -144,6 +144,13 @@ function RoleRouteGuard({ children }: { children: React.ReactNode }) {
if (effectiveRole === "quality_reviewer" && !qualityPath && !itemPath) {
return