sync processor from GitLab c697b6e: 版本 1.19.4 / 前端 1.12.4 —— 服务端 i18n(首屏不再闪英文)、推理模块并入模型页、前端抽出 shared/、缓存键改用前端号

顺带:.gitattributes 补 processor/**/*.task 走 LFS(MediaPipe 手部模型 7.5MB,
HF 不收非 LFS 二进制;与 collector 侧同一条规则)。

Co-Authored-By: Claude <noreply@anthropic.com>

.gitattributes

@@ -44,3 +44,5 @@ collector/**/*.task filter=lfs diff=lfs merge=lfs -text
 
 # processor 文档截图走 LFS(HF 拒绝非 LFS 二进制)
 processor/**/*.png filter=lfs diff=lfs merge=lfs -text
+# MediaPipe 手部模型(7.5MB 二进制)—— 与 collector 侧同一条规则,HF 不收非 LFS 二进制
+processor/**/*.task filter=lfs diff=lfs merge=lfs -text

processor/.env.example

@@ -13,8 +13,8 @@ SFTP_CONNECT_TIMEOUT=15
 API_KEY=change-me
 WORKER_API_KEY=change-me-worker-key
 JWT_SECRET=change-me-jwt-secret
-EGODATA_BOOTSTRAP_USERNAME=demo-admin
-EGODATA_BOOTSTRAP_PASSWORD=change-me-bootstrap-password
+EGODATA_BOOTSTRAP_USERNAME=Root
+EGODATA_BOOTSTRAP_PASSWORD=Root
 EGODATA_BOOTSTRAP_EMAIL=root@egodata.local
 DEFAULT_WORKFLOW_ID=
 WORKER_LEASE_SECONDS=90

processor/.gitignore

@@ -33,6 +33,14 @@ web/workflow-studio/*.tsbuildinfo
 *.db
 *.log
 
+# 编辑器/工具留下的备份与冲突残留文件 —— 一律不入库。
+# 起因:`web/static/plyr.js.bak`(改 plyr.js 时留下的备份)被误提交进了版本库,
+# 而仓库里没有任何规则拦它。改 JS 时留的 .bak 尤其容易混进来。
+*.bak
+*.orig
+*.rej
+*~
+
 # Local model assets and scratch (large binaries, never in git).
 models/
 *.deb

processor/README.md

@@ -4,7 +4,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-> Documentation: 2026-09-02  ·  Backend: `1.6.8`  ·  Web frontend: `1.5.6`
+> Documentation: 2026-09-28  ·  Backend: `1.19.4`  ·  Frontend: `1.12.3`
 
 processor is EgoData's service for data capture, processing, review, and export. It is
 designed for embodied AI and robot manipulation data. The system consists of a FastAPI backend,
@@ -523,12 +523,22 @@ Troubleshooting order:
 <details>
 <summary>Click to expand: version maintenance rules</summary>
 
-- The backend version is maintained in `app/version.py`;
-- the Web frontend version is maintained in `web/workflow-studio/package.json`;
+- The backend version is maintained in `app/version.py` and covers the backend **only**;
+- **the frontend version is maintained in `web/VERSION`**. It covers every piece of frontend
+  code under `processor/web/` (`templates/`, `static/`, `workflow-studio/`) — **not just the
+  React SPA**. The version inside `web/workflow-studio/package.json` only represents the SPA
+  itself; all three numbers are independent and do not need to stay in sync.
+- **Bump `web/VERSION` — that one file — whenever you change the frontend.** A single number
+  serves two purposes: ① the `?v={{ asset_version }}` cache key on static assets (so browsers
+  re-fetch changed JS/CSS), ② the "frontend X" part of commit messages. Sharing one number
+  means the commit message can never disagree with what the browser actually loaded.
+  You do **not** need to touch the backend version for a frontend change.
+- `web/VERSION` is read once at startup and cached (`app/web_version.py`), so **restart the
+  service** after bumping it.
 - increment the patch version for fixes and small adjustments, the minor version for new features,
   and the major version for architectural changes;
 - before release, record the software version, data format, and API changes together.
 
-Current versions: backend `1.6.8`, Web frontend `1.5.6`.
+Current versions: backend `1.19.4`, frontend `1.12.3`.
 
 </details>

processor/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [中文](README.zh-CN.md) | [English](README.md)
 
-> 文档版本：2026-09-02  ·  后端版本：`1.6.8`  ·  WEB 前端版本：`1.5.6`
+> 文档版本：2026-09-28  ·  后端版本：`1.19.4`  ·  前端版本：`1.12.3`
 
 processor 是 EgoData 的数据采集、处理、审核和导出服务，面向具身智能与机器人
 操作数据。系统由 FastAPI 后端、异步 Worker、Web 审核页面和 Workflow Studio 组成。
@@ -506,11 +506,19 @@ npm run build
 <details>
 <summary>点击展开：版本维护规则</summary>
 
-- 后端版本在 `app/version.py` 中维护；
-- Web 前端版本在 `web/workflow-studio/package.json` 中维护；
+- 后端版本在 `app/version.py` 中维护，**只管后端**；
+- **前端版本在 `web/VERSION` 中维护**。它覆盖 `processor/web/` 下的全部前端代码
+  （`templates/`、`static/`、`workflow-studio/`），**不只是那个 React SPA**。
+  `web/workflow-studio/package.json` 里的 version 只代表 SPA 自己，三者互相独立、不必同步。
+- **改了前端就只 bump `web/VERSION` 这一个文件**。它一个号管两件事：
+  ① 模板里的 `?v={{ asset_version }}` 缓存键（读了它浏览器才会重新拉 JS/CSS）
+  ② 提交信息里的「前端 X」。
+  两个用途共用一个数，不会出现"提交信息写 1.12.3、浏览器却拿 1.12.2"这种对不上的情况。
+  改前端**不需要**动后端版本号。
+- 改完 `web/VERSION` 要**重启服务**才生效（`app/web_version.py` 启动时读一次就缓存）。
 - 修复和小调整增加修订号；新增功能增加次版本号；重大架构变更增加主版本号；
 - 发布前应同步记录软件版本、数据格式和 API 变化。
 
-当前版本：后端 `1.6.8`，WEB 前端 `1.5.6`。
+当前版本：后端 `1.19.4`，前端 `1.12.3`。
 
 </details>

processor/app/ai_annotation.py

@@ -41,7 +41,6 @@ from app.localstore import (
     read_episode_state,
     write_episode_state,
 )
-from app.routes.annotations import notify_annotations_changed
 from app.video_quality import check_video_quality_async
 from app.workflow_types import HAND_PROCESS_TYPES, canonical_node_type
 
@@ -612,23 +611,36 @@ def _set_ai_quality_state(episode_id: str, report: dict, *,
 
     The web UI continues to use only Reviewing/Approved.  The detailed report
     is kept in episode state for diagnostics and future review tooling.
+
+    ★ ``auto_approve`` 会被【数据质检】否决 —— 判 FAIL/ERROR 的批次在
+      ``cleaning_summary.blocking`` 上留了粘性标记。AI 标注覆盖率合格不代表
+      数据本身没问题；只看自己那份报告的话，坏数据会被一路自动批准放行
+      （质检与视频门禁是并发跑的，谁先写没有保证，所以必须查标记而不是
+      比谁写得晚）。
     """
-    state = read_episode_state(episode_id)
-    state["ai_quality_status"] = "passed" if report.get("passed") else "failed"
-    state["ai_quality_report"] = report
-    state["updated_at"] = _utcnow()
-    current = str(state.get("status") or "")
-    if report.get("passed") and auto_approve:
-        if current in {"processing", "to_review", "completed", "failed"}:
-            state["status"] = "reviewed"
-            if not state.get("approved_at"):
-                state["approved_at"] = _utcnow()
-    elif not report.get("passed"):
-        # Fail closed: an incomplete/failed AI result remains in Reviewing.
-        if current in {"processing", "completed", "reviewed", "approved", "failed"}:
-            state["status"] = "to_review"
-            state["approved_at"] = None
-    write_episode_state(episode_id, state)
+    from app.localstore import mutate_episode_state
+    from app.processing.cleaning.store import is_approval_blocked
+
+    def _apply(state: dict) -> None:
+        state["ai_quality_status"] = "passed" if report.get("passed") else "failed"
+        state["ai_quality_report"] = report
+        state["updated_at"] = _utcnow()
+        current = str(state.get("status") or "")
+        if report.get("passed") and auto_approve:
+            if (current in {"processing", "to_review", "completed", "failed"}
+                    and not is_approval_blocked(state)):
+                state["status"] = "reviewed"
+                if not state.get("approved_at"):
+                    state["approved_at"] = _utcnow()
+        elif not report.get("passed"):
+            # Fail closed: an incomplete/failed AI result remains in Reviewing.
+            if current in {"processing", "completed", "reviewed", "approved", "failed"}:
+                state["status"] = "to_review"
+                state["approved_at"] = None
+
+    # 锁内 RMW：数据质检 / 视频门禁在同一次 run 后并发写同一份 state。分开
+    # read→write 的话，后写的会用旧快照把先写的 ``status`` 冲掉。
+    mutate_episode_state(episode_id, _apply)
 
 
 def _set_ai_quality_pending(episode_id: str) -> None:
@@ -2697,6 +2709,11 @@ def _persist_ai_segment(episode_id: str, generation: int, candidate: dict,
                         index: int, media_sources: list[str], *,
                         pending: bool = False, error: str = "") -> dict:
     """Atomically insert/update one segment without waiting for its siblings."""
+    # 惰性导入 —— 不要提到模块顶层。本模块在路由层**之下**,而 routes.annotations
+    # 反过来惰性引用 ai_annotation(_schedule_dataset_sync)。模块级导入会形成
+    # import 环:谁先被导入,谁就拿不到对方完整的模块对象。放进调用点后方向保持
+    # 单向(路由 → 本模块),将来搬文件也不会因顺序踩坑。
+    from app.routes.annotations import notify_annotations_changed
     record = _ai_annotation_record(
         episode_id, candidate, index, media_sources,
         pending=pending, error=error)
@@ -2823,6 +2840,8 @@ def run_ai_annotation(episode_id: str, mode: str, min_confidence: float,
     走本地 vLLM 抽帧图;provider=api 走 Kimi 原生视频 —— 两模式严格
     分离,配置缺失/请求失败显式报错(任务 detail 可见),绝不互回退。
     """
+    # 同 _persist_ai_segment:惰性导入,避免与 routes.annotations 形成 import 环。
+    from app.routes.annotations import notify_annotations_changed
     episode_id = str(episode_id)
     quality_review_enabled = bool(quality_gate or video_quality_gate)
     if quality_review_enabled:
@@ -3538,7 +3557,7 @@ def _connected_quality_node_config(graph: dict, node_configs: dict,
     }
     quality_nodes = {
         str(node.get("id")): node for node in nodes
-        if canonical_node_type((node.get("data") or {}).get("nodeType")) == "ai_quality_review"
+        if canonical_node_type((node.get("data") or {}).get("nodeType")) == "data_quality"
         and node.get("id") is not None
     }
     if not source_ids or not quality_nodes:
@@ -3570,25 +3589,32 @@ def _connected_quality_node_config(graph: dict, node_configs: dict,
     return None
 
 
-def ai_quality_review_node_config(graph: dict, node_configs: dict) -> dict | None:
-    """Return the quality card only when it is connected to AI Annotation.
+def annotation_coverage_gate_config(graph: dict, node_configs: dict) -> dict | None:
+    """Return the Data Quality card only when it is connected to AI Annotation.
 
     A card sitting alone in the canvas is configuration only.  The gate is
-    enabled for a directed path ``AI Annotation -> ... -> AI Quality Review``;
+    enabled for a directed path ``AI Annotation -> ... -> Data Quality``;
     allowing pass-through nodes in the middle keeps existing workflow layouts
     compatible while making a dangling quality card inert.
+
+    以前叫 ``ai_quality_review_node_config`` —— 当时节点叫 AI Quality Review。
+    节点合并为 Data Quality 后按"它能开启哪项检查"重命名，函数名不再绑定
+    已废弃的 slug。
     """
     return _connected_quality_node_config(
         graph, node_configs, {"ai_annotation"})
 
 
-def video_quality_review_node_config(graph: dict, node_configs: dict) -> dict | None:
-    """Return the quality card when it is connected to a media/data source.
+def video_quality_gate_config(graph: dict, node_configs: dict) -> dict | None:
+    """Return the Data Quality card when it is connected to a media/data source.
 
     This enables a video-only workflow to run the post-processing media gate,
-    while an unconnected ``AI Quality Review`` card remains inert.  The list
+    while an unconnected ``Data Quality`` card remains inert.  The list
     intentionally contains existing input/process node types only; export
     nodes cannot accidentally activate a review gate.
+
+    历史上这段逻辑属于 ``AI Quality Review`` 卡片 —— 视频检查当时"寄居"在
+    标注节点里，好让没有 AI 标注的纯视频工作流也有质量门禁。
     """
     return _connected_quality_node_config(
         graph,
@@ -3656,7 +3682,7 @@ def _workflow_ai_quality_enabled(episode_id: str) -> bool:
         wf = get_workflow(wf_id)
         if wf is None:
             continue
-        if ai_quality_review_node_config(
+        if annotation_coverage_gate_config(
                 wf.get("graph") or {}, wf.get("node_configs") or {}) is not None:
             return True
     return False
@@ -3683,7 +3709,7 @@ def _workflow_video_quality_enabled(episode_id: str) -> bool:
         wf = get_workflow(wf_id)
         if wf is None:
             continue
-        if video_quality_review_node_config(
+        if video_quality_gate_config(
                 wf.get("graph") or {}, wf.get("node_configs") or {}) is not None:
             return True
     return False

processor/app/api/quality.py

@@ -0,0 +1,172 @@
+"""数据质检 API —— 检查项目录、报告查询、手动触发。
+
+给前端两件事：
+* 设置面板的**数据源** —— ``/checks`` 返回检查项目录 + 按设备卡片的分组，
+  面板按它渲染 tab 和每一项的阈值输入框。新增检查项前端零改动。
+* 报告的**读取入口** —— 列表页和详情页。
+
+写端点少而克制：只有"重跑某集"。质检本身不做任何数据修改，
+所以没有删除/清理类的接口。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Query
+
+router = APIRouter(prefix="/api/v1/quality", tags=["quality"])
+
+
+def _check_catalog() -> dict:
+    """检查项目录 + 按设备卡片分组 —— 前端设置面板的渲染数据。
+
+    ``checks`` 是平铺清单（每项带 ``device_cards`` / ``default_params``）；
+    ``by_device`` 是按设备卡片分好组的视图，前端 tab 直接用。
+    两者给同一份数据，前端按方便取用。
+    """
+    from app.processing.cleaning.checks import all_checks, all_check_specs
+    from app.processing.cleaning.contract import (
+        DEVICE_MODALITIES, MODALITY_CHANNELS,
+    )
+    from app.processing.cleaning.engine import ruleset_revision
+
+    specs = all_check_specs()
+    by_device: dict[str, list[str]] = {}
+    for modality in DEVICE_MODALITIES:
+        by_device[modality] = [
+            spec["slug"] for spec in specs
+            if modality in (spec.get("device_cards") or [])
+        ]
+
+    return {
+        "ruleset_revision": ruleset_revision(),
+        "checks": specs,
+        "by_device": by_device,
+        "device_labels": _device_labels(),
+        "device_channels": {
+            modality: list(channels)
+            for modality, channels in MODALITY_CHANNELS.items()
+        },
+        "severity_labels": _severity_labels(),
+        "total": len(all_checks()),
+    }
+
+
+def _device_labels() -> dict[str, str]:
+    """设备卡片的显示名 —— 复用 device_naming，不另起一套。"""
+    try:
+        from app.device_naming import DEVICE_LABELS
+        return dict(DEVICE_LABELS)
+    except Exception:
+        return {}
+
+
+def _severity_labels() -> dict[str, str]:
+    from app.processing.cleaning.contract import SEVERITY_LABELS
+    return dict(SEVERITY_LABELS)
+
+
+@router.get("/checks")
+def list_checks() -> dict:
+    """检查项目录（含按设备卡片分组）—— 设置面板用。"""
+    return _check_catalog()
+
+
+@router.get("/summary")
+def list_summaries(project: str | None = Query(None),
+                   status: str | None = Query(None),
+                   limit: int = Query(200, ge=1, le=2000)) -> dict:
+    """质检报告列表（摘要），按时间倒序。
+
+    ``status`` 过滤按 episode 结论（pass / warn / fail / pending_review / error）。
+    """
+    from app.processing.cleaning.store import list_reports
+
+    items = list_reports()
+    if project:
+        items = [item for item in items if str(item.get("project")) == project]
+    if status:
+        items = [item for item in items if item.get("status") == status]
+
+    counts: dict[str, int] = {}
+    for item in items:
+        key = str(item.get("status") or "unknown")
+        counts[key] = counts.get(key, 0) + 1
+
+    return {"reports": items[:limit], "total": len(items), "counts": counts}
+
+
+@router.get("/episodes/{episode_id}")
+def get_report(episode_id: str) -> dict:
+    """某一集的完整质检报告（四层结果）。"""
+    from app.processing.cleaning.store import load_report, load_summary
+
+    report = load_report(episode_id)
+    if report is not None:
+        return report
+    summary = load_summary(episode_id)
+    if summary is not None:
+        # 完整报告被清掉了但摘要还在（state 里）—— 至少把摘要给出去
+        return {"episode_id": episode_id, "summary_only": True, **summary}
+    raise HTTPException(status_code=404, detail="No quality report for this episode")
+
+
+@router.post("/episodes/{episode_id}/run")
+async def run_episode_checks(
+    episode_id: str,
+    probe_video: bool = Query(False, description="是否跑视频检查（慢）"),
+    persist: bool = Query(True, description="是否把报告写进 episode state"),
+) -> dict:
+    """重跑某一集的质检。
+
+    跑在**线程池**里 —— 读 parquet/视频是阻塞 IO，直接放事件循环上会把
+    页面请求卡住（仓库里 ``routes/devices.py`` 有同样的处理）。
+    """
+    episode = await asyncio.to_thread(_find_episode, episode_id)
+    if episode is None:
+        raise HTTPException(status_code=404, detail="Episode not found")
+
+    report = await asyncio.to_thread(_run_checks_for, episode, probe_video)
+    saved = False
+    if persist:
+        from app.processing.cleaning.store import save_report
+        saved = await asyncio.to_thread(save_report, episode_id, report)
+    return {"episode_id": episode_id, "saved": saved, "report": report}
+
+
+def _find_episode(episode_id: str) -> dict | None:
+    """在会话索引里找这一集（含 ``path``，质检要用它读数据）。"""
+    from app.localstore import scan_sessions
+
+    for episode in scan_sessions():
+        if str(episode.get("id")) == episode_id:
+            return episode
+    return None
+
+
+def _run_checks_for(episode: dict, probe_video: bool) -> dict:
+    from app.processing.cleaning.engine import run_checks
+
+    path = Path(str(episode.get("path") or ""))
+    if not path.is_dir():
+        raise HTTPException(status_code=409, detail="Episode data directory missing")
+
+    # 设备卡片取自 episode 的设备信息 —— 与工作流派发用的是同一套口径
+    modality = None
+    try:
+        from app.workflow_dispatch import _episode_input_groups
+        groups = _episode_input_groups(episode) or []
+        if groups:
+            modality = str(groups[0].get("input_type") or "") or None
+    except Exception:
+        modality = None
+
+    return run_checks(
+        path,
+        episode_id=str(episode.get("id") or ""),
+        project=str(episode.get("project") or ""),
+        probe_video=probe_video,
+        modality_hint=modality,
+    )

processor/app/api/worker.py

@@ -520,14 +520,14 @@ async def complete_job(
         from app.ai_annotation import (
             run_ai_annotation,
             ai_annotation_node_config,
-            ai_quality_review_node_config,
-            video_quality_review_node_config,
+            annotation_coverage_gate_config,
+            video_quality_gate_config,
         )
         graph = run.get("graph") or {}
         node_configs = run.get("node_configs") or {}
         cfg = ai_annotation_node_config(graph, node_configs)
-        quality_cfg = ai_quality_review_node_config(graph, node_configs)
-        video_quality_cfg = video_quality_review_node_config(graph, node_configs)
+        quality_cfg = annotation_coverage_gate_config(graph, node_configs)
+        video_quality_cfg = video_quality_gate_config(graph, node_configs)
         if cfg is not None and not run.get("ai_suggest_triggered"):
             run["ai_suggest_triggered"] = True
             save_run(run)
@@ -572,6 +572,26 @@ async def complete_job(
     except Exception as exc:
         print(f"[Worker] AI annotation trigger skipped: {exc}")
 
+    # 数据质检联动:工作流里 Data Quality 卡片**接了数据链路**就跑一次检查。
+    #
+    # 与上面两条是两套东西:ai_annotation / video_quality 会改 episode 状态
+    # (通过→reviewed、失败→卡到 to_review),而质检**只把结论记进**
+    # state 的 cleaning_report,不参与状态流转。
+    #
+    # 两者会同时触发(相机类工作流就同时命中 video_quality_gate 和这里),而且
+    # 都各要解码一遍视频 —— 所以它们几乎同时结束、同时写状态,状态写入一律走
+    # localstore.mutate_episode_state(锁内 RMW),否则后写的会用旧快照把先写的
+    # 冲掉(尤其 status)。
+    #
+    # 必须放后台任务:probe_video 要解码视频(实测约 4.8s/集),不能拖住完成响应。
+    try:
+        from app.processing.cleaning.trigger import spawn_cleaning_for_run
+        if ep is not None and spawn_cleaning_for_run(run, ep):
+            print(f"[Worker] Data quality checks triggered "
+                  f"for {run['episode_id']}")
+    except Exception as exc:
+        print(f"[Worker] Data quality trigger skipped: {exc}")
+
     # 归档联动:处理完成后后台把该批次增量推送到 NAS(只推不删;rsync
     # 逐块校验+断点续传,失败仅记日志不阻塞响应;每晚 cron 兜底补传)。
     # 脚本不存在(如 Windows 环境)时静默跳过。

processor/app/cleaning.py

@@ -281,20 +281,41 @@ def _check_frame_alignment_fs(batch_dir: Path) -> dict:
                 except Exception:
                     continue
         parquet_frames = len(seen)
+        if parquet_frames == 0:
+            return {"name": "frame_alignment", "passed": True, "detail": "No parquet data"}
+
+        # 2026-09-23 修:此处此前直接用 cv2 却没 import,异常被下方 except 吞掉,
+        # 整个帧对齐检查在文件级路径下**永远静默通过**(detail 里写的是
+        # "Check error (skipped)" 但 passed=True,不会引起任何人注意)。
+        try:
+            import cv2
+        except ImportError:
+            return {"name": "frame_alignment", "passed": True,
+                    "detail": "OpenCV not available — video frame count skipped"}
+
+        mp4s = sorted(batch_dir.rglob("*.mp4"))
+        if not mp4s:
+            # 与 _check_video_decode_fs 同款处理:没有视频就没有可比对的对象,
+            # 判"未适用"而不是"不匹配"——只有传感器的批次(如纯手套)是合法的。
+            # 修复 cv2 漏 import 后,这里若不给守卫会退化成 dev=10000% 的误报。
+            return {"name": "frame_alignment", "passed": True,
+                    "detail": "No video to compare against"}
+
         video_frames = 0
-        for mp4 in batch_dir.rglob("*.mp4"):
+        for mp4 in mp4s:
             cap = cv2.VideoCapture(str(mp4))
             try:
                 video_frames = max(video_frames, int(cap.get(cv2.CAP_PROP_FRAME_COUNT)) or 0)
             finally:
                 cap.release()
-        if parquet_frames == 0:
-            return {"name": "frame_alignment", "passed": True, "detail": "No parquet data"}
         ratio = abs(parquet_frames - video_frames) / max(video_frames, 1)
         return {"name": "frame_alignment", "passed": ratio < 0.10,
                 "detail": f"parquet={parquet_frames}, video={video_frames}, dev={ratio:.1%}"}
     except Exception as e:
-        return {"name": "frame_alignment", "passed": True, "detail": f"Check error (skipped): {e}"}
+        # 保持 passed=True(不改变既有行为),但 detail 必须说清是"降级通过",
+        # 免得再出现"看起来全过了其实根本没检查"的情况。
+        return {"name": "frame_alignment", "passed": True,
+                "detail": f"Degraded pass — check errored: {e}"}
 
 
 def _check_sensor_completeness_fs(batch_dir: Path) -> dict:

processor/app/config.py

@@ -56,6 +56,27 @@ class Settings(BaseSettings):
     EXPORT_SHARD_SIZE: int = 100000
     VIDEO_SHARD_FRAMES: int = 5000
 
+    # Training. Checkpoints are produced *outside* the platform by the official
+    # ``lerobot-train`` CLI (conda env ``lerobot052_base_piper``), so this points
+    # at an existing directory we only ever read. Empty = use the default below.
+    TRAIN_OUTPUT_ROOT: str = ""
+
+    @property
+    def train_root(self) -> Path:
+        """Trained-model directory — **read-only**, never created here.
+
+        Defaults to ``<repo>/文件测试/umi_act_model``, i.e. beside ``processor/``.
+        The directory is git-ignored and may legitimately be absent (fresh
+        clone, or training never run on this host): callers must treat a
+        missing path as "no runs" rather than creating it.  Creating it would
+        make an empty training dir appear out of nowhere on every boot.
+        """
+        raw = str(self.TRAIN_OUTPUT_ROOT or "").strip()
+        if raw:
+            return Path(raw).expanduser()
+        return (Path(__file__).resolve().parent.parent.parent
+                / "文件测试" / "umi_act_model")
+
     model_config = {
         "env_prefix": "",
         "case_sensitive": False,

processor/app/hdf5_export.py

@@ -34,6 +34,7 @@ from app.localstore import get_episode
 from app.lerobot_export import (
     _annotation_maps,
     _calibration_docs,
+    _depth_video_paths,
     _hand_columns,
     _infer_hand_3d_unit,
     _key_matches_any,
@@ -288,6 +289,66 @@ def build_hdf5_dataset(dataset_name: str, episode_ids: list[str], output_dir: Pa
                     "video_info": {"video.fps": vfps, "video.is_depth_map": False},
                 }
 
+            # 1b) 深度流 → 逐帧 uint16 毫米(单独一组,不和 RGB 混在 images/ 下)
+            #
+            # 深度**不在** camera_streams 里 —— 它单独放在 depth/<source>/,
+            # 所以上面的 RGB 循环根本看不到它,必须用 lerobot_export 的发现函数。
+            #
+            # 解码必须走 DepthVideoReader(ffmpeg 解 gray12le):OpenCV 会把
+            # 12-bit 深度当普通显示图转成 8-bit,真实毫米值全丢。
+            #
+            # **0 表示"没测到深度"的无效像素,不是 0 毫米** —— 与采集端语义一致,
+            # 原样保留,不要当数值去算均值。
+            for source_key, depth_path in _depth_video_paths(session_dir, episode_id):
+                if include_video_keys is not None and not _key_matches_any(
+                        source_key, include_video_keys):
+                    continue
+                reader = None
+                try:
+                    from app.lerobot_v21 import DEPTH_VIDEO_ENCODING, DepthVideoReader
+                    reader = DepthVideoReader(depth_path)
+                    dheight, dwidth = reader.height, reader.width
+                    if dheight <= 0 or dwidth <= 0 or T <= 0:
+                        continue
+                    dfps = float(reader.fps or episode_fps)
+                    ds = obs.create_dataset(
+                        f"depth/{source_key}", shape=(T, dheight, dwidth),
+                        dtype="uint16", chunks=(1, dheight, dwidth),
+                        compression=compression, compression_opts=level)
+                    ds.attrs["unit"] = "millimetre"
+                    ds.attrs["invalid_value"] = 0
+                    ds.attrs["fps"] = dfps
+                    ds.attrs["source_key"] = source_key
+                    ds.attrs["source_episode"] = episode_id
+                    ds.attrs["encoding"] = DEPTH_VIDEO_ENCODING
+                    i = 0
+                    while i < T:
+                        frame = reader.read_mm()
+                        if frame is None:
+                            break
+                        ds[i] = frame
+                        i += 1
+                    features[f"observation.depth.{source_key}"] = {
+                        "dtype": "uint16", "shape": [T, dheight, dwidth],
+                        "unit": "millimetre",
+                        "note": "0 = 无效像素(该点未测到深度),不是 0 毫米",
+                        "video_info": {
+                            "video.fps": dfps,
+                            "video.is_depth_map": True,
+                            "video.height": dheight,
+                            "video.width": dwidth,
+                        },
+                    }
+                except Exception as exc:
+                    print(f"[hdf5_export] depth stream {source_key} "
+                          f"skipped: {exc}")
+                finally:
+                    if reader is not None:
+                        try:
+                            reader.close()
+                        except Exception:
+                            pass
+
             # 2) 表列:传感器 + 手部骨骼 + 标注(与 LeRobot 列同构,按帧号对齐)
             columns: dict[str, dict[int, Any]] = {}
             str_columns: set[str] = set()
@@ -406,11 +467,11 @@ def build_hdf5_dataset(dataset_name: str, episode_ids: list[str], output_dir: Pa
                     annotation_defs, ensure_ascii=False)
 
             # 6) 标定 → /meta/calibration/<episode>/<name> attrs(JSON 字符串)
-            # 与 stereo_triangulate 一致:批次标定缺失/全零 → 回退内置默认标定
-            # (否则 meta 里声明的是未生效的标定,3D 数据无法复现)。
-            # 回退逻辑统一在 lerobot_export._calibration_docs(单点维护)。
+            # 每集一份,所以把 episode_id 一起传进去 —— 批次内各集标定可以不同,
+            # 不传就只会看到批次级的 calibration/ 目录。
+            # 缺失/全零时的默认标定回退统一在 lerobot_export._calibration_docs。
             cal_group = meta.create_group(f"calibration/{episode_id}")
-            cal_docs = _calibration_docs(session_dir)
+            cal_docs = _calibration_docs(session_dir, episode_id)
             for name, value in cal_docs.items():
                 cal_group.attrs[name] = json.dumps(value, ensure_ascii=False)
 
@@ -506,7 +567,16 @@ def _build_readme(dataset_name: str, h5: Any) -> str:
     img_keys = sorted(n for n in all_names
                       if n.startswith(f"{root}/observation/images/"))
     if img_keys:
-        rows.append(f"| **原视频** | {len(img_keys)} 路原始帧 | ✅ 全量 |")
+        # 不写"全量" —— 视频可能被工作流的 include_video_keys 过滤过,而且
+        # 深度流走 depth_sources、不经 camera_streams,本文件**从来不导**。
+        # 声称"全量"会让客户以为拿到的是全部视频。
+        rows.append(f"| **原视频** | {len(img_keys)} 路原始帧(逐帧 uint8 RGB)"
+                    " | ✅ 已导出,清单见上方结构树 |")
+    depth_keys = sorted(n for n in all_names
+                        if n.startswith(f"{root}/observation/depth/"))
+    if depth_keys:
+        rows.append(f"| **深度图** | {len(depth_keys)} 路,uint16 **毫米**"
+                    " | ✅ 0 = 无效像素(未测到),不是 0 毫米 |")
     hand_coordinate = next(
         (coord for coord in ("world", "3d", "2d")
          if f"{root}/observation/state/hand_left_{coord}" in all_names),
@@ -558,6 +628,27 @@ with open("hand_skeleton.mp4", "wb") as f:
 ```
 """
 
+    # 读取示例:只给文件里**确实存在**的路径。原来是左目写死 stereo_left、
+    # 手部无数据时仍回落到 hand_right_3d —— 客户照抄都是 KeyError;而且
+    # `import h5py` 在 0 列、`with` 却缩进了 4 格,示例本身就不是合法 Python。
+    first_img = img_keys[0].split("/")[-1] if img_keys else None
+    example = ["import h5py", "", 'with h5py.File("dataset.h5", "r") as h5:']
+    if first_img:
+        example.append(f"    # 读一帧图像({first_img})")
+        example.append(f'    img = h5["{root}/observation/images/{first_img}"][0]')
+    if depth_keys:
+        first_depth = depth_keys[0].split("/")[-1]
+        example.append(f"    # 读一帧深度({first_depth};uint16 毫米,0 = 无效像素)")
+        example.append(f'    depth = h5["{root}/observation/depth/{first_depth}"][0]')
+    if hand_coordinate:
+        example.append("    # 读第一帧右手骨骼(字段可能是 world / 3d / 2d)")
+        example.append(f'    hand3d = h5["{root}/observation/state/'
+                       f'hand_right_{hand_coordinate}"][0]')
+    if f"{root}/observation/annotation" in all_names:
+        example.append("    # 读全部标注")
+        example.append(f'    labels = h5["{root}/observation/annotation"][:]')
+    read_example = "\n".join(example)
+
     readme = f"""# {dataset_name} 数据文件说明(HDF5 格式)
 
 > 本文件由 EgoData 数据采集系统工作流自动生成
@@ -588,15 +679,7 @@ with open("hand_skeleton.mp4", "wb") as f:
 ## 四、如何读取
 
 ```python
-import h5py
-
-    with h5py.File("dataset.h5", "r") as h5:
-        # 读一帧左目图像
-        img = h5["episode_000000/observation/images/stereo_left"][0]
-    # 读第一帧右手骨骼(字段可能是 world / 3d / 2d)
-    hand3d = h5["episode_000000/observation/state/hand_right_{hand_coordinate or '3d'}"][0]
-    # 读全部标注
-    labels = h5["episode_000000/observation/annotation"][:]
+{read_example}
 ```
 {video_extract}
 其他工具:HDFView、Panoply、MATLAB(h5read)等支持 HDF5 的软件均可打开。

processor/app/i18n.py

@@ -0,0 +1,89 @@
+"""服务端 i18n —— 让首屏 HTML 直接是正确语言,消掉"先英文后中文"的闪烁。
+
+**问题**:语言原本只存在浏览器的 ``localStorage`` 里,服务端不知道。所以渲染出来
+的 ``data-i18n`` 元素只能填**默认语言(英文)**,再由 ``DOMContentLoaded`` 里的 JS
+改成中文 —— 改的时机在首屏之后,于是每次整页导航都闪一下。
+
+**做法**:语言同时写进 cookie,服务端渲染时就用它取词。首屏直接是对的语言,
+不需要任何"先渲染再纠正"。
+
+**词典的真源**是 ``web/static/js/i18n-data.js`` —— 一个合法 JSON 载荷外面包一行
+``window.__I18N__ = …``:
+
+    * 浏览器把它当**普通脚本**同步加载(带 ``?v=`` 缓存,不会每页重下)
+    * 这里剥掉包装后 ``json.loads``,拿到的就是同一份数据
+
+两边读同一份文件,所以**不会分叉**。改词条只改那一个文件。
+"""
+
+from __future__ import annotations
+
+import json
+from contextvars import ContextVar
+from pathlib import Path
+
+from starlette.middleware.base import BaseHTTPMiddleware
+
+# cookie 名与前端 localStorage 的键保持一致,便于两边对照排查。
+LANG_COOKIE = "lang"
+LANGUAGES = ("zh", "en")
+# 没选过语言时用哪个。刻意保持 **en** —— 与前端原来的行为一致(切语言前的默认),
+# 不借这次改动偷偷改变默认观感。要改成 zh 的话两边一起改(i18n.js 的 currentLang)。
+DEFAULT_LANG = "en"
+
+_DICT_PATH = (Path(__file__).resolve().parent.parent
+              / "web" / "static" / "js" / "i18n-data.js")
+
+
+def _load() -> dict[str, dict[str, str]]:
+    """读 ``i18n-data.js`` 并把 JSON 载荷解析出来。
+
+    解析失败**不抛异常**:页面照常起得来,只是文案退回 key 本身 —— 比整个服务
+    因为一个词典文件挂掉好。真要查的话看 ``data`` 是不是空的。
+    """
+    try:
+        raw = _DICT_PATH.read_text(encoding="utf-8")
+        payload = raw[raw.index("{"):raw.rindex("}") + 1]
+        data = json.loads(payload)
+    except (OSError, ValueError, IndexError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+DATA: dict[str, dict[str, str]] = _load()
+
+
+def normalize(lang: str | None) -> str:
+    """把任意输入收敛成一个可用语言码。认不出来就回默认。"""
+    value = str(lang or "").strip().lower()
+    return value if value in DATA else DEFAULT_LANG
+
+
+_current: ContextVar[str] = ContextVar("egodata_lang", default=DEFAULT_LANG)
+
+
+def get_current_lang() -> str:
+    return _current.get()
+
+
+def t(key: str, lang: str | None = None) -> str:
+    """取词。**取不到就返回 key 本身** —— 页面上会显示出一个明显的
+    ``nav_foo`` 而不是空白,一眼看得出是漏翻,比静默空着好排查。"""
+    use = normalize(lang) if lang is not None else _current.get()
+    table = DATA.get(use) or DATA.get(DEFAULT_LANG) or {}
+    return table.get(key) or key
+
+
+class LanguageMiddleware(BaseHTTPMiddleware):
+    """从 cookie 读语言,放进 ContextVar —— Jinja 里注册的 ``t`` 直接用。
+
+    用 ContextVar 而不是往每个 ``TemplateResponse`` 的 context 里塞:后者要改
+    20 多处调用点,而 ``t`` 是**每个模板都要用**的东西,漏一个就是一片英文。
+    """
+
+    async def dispatch(self, request, call_next):
+        token = _current.set(normalize(request.cookies.get(LANG_COOKIE)))
+        try:
+            return await call_next(request)
+        finally:
+            _current.reset(token)

processor/app/lerobot_export.py

@@ -1806,6 +1806,82 @@ def _depth_assets(session_dir: Path, frame_count: int,
     return assets
 
 
+# 内置默认双目标定 —— 批次标定缺失或整份全零时的兜底。键名取自该文件的
+# ``name`` 字段(head_stereo),与会话里真有一份 head_stereo.json 时算出的键一致。
+_DEFAULT_CALIBRATION_PATH = (Path(__file__).resolve().parent
+                             / "processing" / "modules"
+                             / "calibration_default_head_stereo.json")
+
+
+def _calibration_is_blank(doc: Any) -> bool:
+    """整份标定里找不出任何非零数值 —— 视为未生效的空白标定。
+
+    只递归看数值叶子(标定本质上就是嵌套的数值结构);字符串等非数值字段
+    不构成"有效标定"的证据。所以 ``{"depth_scale": 0.001}`` 不算空白,
+    而全零的 intrinsic/rotation/translation 算。
+    """
+    if isinstance(doc, bool):
+        return True                    # bool 是 int 子类,必须先挡掉
+    if isinstance(doc, (int, float)):
+        return doc == 0
+    if isinstance(doc, dict):
+        return all(_calibration_is_blank(v) for v in doc.values())
+    if isinstance(doc, (list, tuple)):
+        return all(_calibration_is_blank(v) for v in doc)
+    return True
+
+
+def _default_calibration_docs() -> dict[str, Any]:
+    """读内置默认标定;文件缺失/损坏时返回 {} (调用方自行回落到空)。"""
+    try:
+        doc = json.loads(_DEFAULT_CALIBRATION_PATH.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(doc, dict):
+        return {}
+    return {str(doc.get("name") or _DEFAULT_CALIBRATION_PATH.stem): doc}
+
+
+def _calibration_docs(session_dir: str | Path,
+                      episode_id: str | None = None) -> dict[str, Any]:
+    """会话标定 → ``{名称: 标定内容}``,供导出侧写进数据集 meta。
+
+    目录口径与其余读取点一致(media_groups / depth_hand_3d / lerobot_v21 /
+    本文件的深度标定段):先看 ``calibration/``;给了 ``episode_id`` 时优先
+    ``meta/calibration/<episode_id>/``,再回退 ``meta/calibration/``。键名优先
+    取 JSON 里的 ``name`` 字段,否则用文件名 stem。
+
+    **批次标定缺失、或整份全零时回退内置默认标定**
+    (``processing/modules/calibration_default_head_stereo.json``)。不这么做的话,
+    导出的 meta 会声明一个从未生效的标定,下游照它复现 3D 全是错的。
+
+    只有**每一份**都空白才回退 —— 只要有一份像样的就用会话里的。
+    """
+    session_dir = Path(session_dir)
+    calib_dir = session_dir / "calibration"
+    if episode_id:
+        namespaced = session_dir / "meta" / "calibration" / str(episode_id)
+        if namespaced.is_dir():
+            calib_dir = namespaced
+    if not calib_dir.is_dir():
+        calib_dir = session_dir / "meta" / "calibration"
+
+    docs: dict[str, Any] = {}
+    if calib_dir.is_dir():
+        for path in sorted(calib_dir.glob("*.json")):
+            try:
+                value = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, ValueError, TypeError):
+                continue
+            if not isinstance(value, dict):
+                continue
+            docs[str(value.get("name") or path.stem)] = value
+
+    if docs and not all(_calibration_is_blank(v) for v in docs.values()):
+        return docs
+    return _default_calibration_docs() or docs
+
+
 def _device_metadata(session_dir: Path) -> list[dict]:
     """Return physical-device declarations for export-side pairing metadata."""
     for name in ("metadata.json", "meta/info.json"):

processor/app/localstore.py

@@ -704,6 +704,36 @@ def write_episode_state(episode_id: str, state: dict) -> None:
     invalidate_session_cache()
 
 
+def mutate_episode_state(
+    episode_id: str,
+    mutator: Callable[[dict], _MutationResult],
+) -> _MutationResult | None:
+    """Atomically read, mutate, and persist one episode's state.
+
+    ``read_episode_state`` / ``write_episode_state`` each take ``_lock`` on
+    their own, so a read-modify-write *across* them is not atomic.  Two writers
+    that overlap lose one side's fields — and when the lost field is ``status``,
+    a batch already pushed back to ``to_review`` can be silently restored to
+    ``reviewed``.
+
+    That window is not theoretical: the post-run quality tasks (the video gate
+    and data quality) both decode the same episode's video and therefore finish
+    within milliseconds of each other, which is exactly when they overlap.
+
+    Mutate the ``state`` dict in place inside ``mutator``; the return value is
+    passed straight through.  Returns ``None`` (and writes nothing) when the
+    episode has no state — callers must not invent one.
+    """
+    key = str(episode_id)
+    with _lock:
+        state = read_episode_state(key)
+        if not state:
+            return None
+        result = mutator(state)
+        write_episode_state(key, state)
+        return result
+
+
 def set_episode_status(episode_id: str, status: str) -> dict:
     with _lock:
         state = read_episode_state(episode_id)

processor/app/main.py

@@ -12,8 +12,10 @@ from starlette.middleware.gzip import GZipMiddleware
 
 from app.config import settings
 from app.routes import ingestion, video, export, pages, session, annotations, dashboard, devices, auth
-from app.api import workflows, worker, projects, exceptions
+from app.routes import training
+from app.api import workflows, worker, projects, exceptions, quality
 from app.api import users
+from app.i18n import LanguageMiddleware
 from app.middleware import AuthMiddleware
 from app.paths import STATIC_DIR
 from app.version import __version__
@@ -75,7 +77,10 @@ app = FastAPI(
 app.add_middleware(GZipMiddleware, minimum_size=500)
 
 # Auth middleware — protect routes (after gzip, before everything else)
+# 语言中间件要在 Auth 之外(先于它)跑:鉴权失败跳登录页时,那个页面本身也要
+# 按 cookie 里的语言渲染。add_middleware 是**后加的先跑**,所以放在 Auth 之后加。
 app.add_middleware(AuthMiddleware)
+app.add_middleware(LanguageMiddleware)
 
 # 媒体/压缩文件下载不走 gzip:zip/mp4/parquet/hdf5 本身已是压缩格式,
 # 再压一遍只是烧 CPU(zlib level 9 压缩 180MB ≈ 10s),而且流式压缩会
@@ -109,6 +114,15 @@ async def static_cache_headers(request, call_next):
             response.headers["Cache-Control"] = "public, max-age=31536000, immutable"
         elif request.url.query:
             response.headers["Cache-Control"] = "public, max-age=86400"
+        elif path.startswith("/static/js/"):
+            # ES module 的相对 import 解析出来的 URL **不带查询串** —— 就算入口
+            # script 写了 ?v=,`import './api.js'` 也永远是同一个地址。给它任何
+            # 正数的 max-age,升级后都会出现「新入口 + 旧子模块」混用,直接抛
+            # TypeError。这类文件必须每次回源校验(未变则 304,开销可忽略)。
+            #
+            # 范围刻意收窄到 /static/js/:带 ?v= 的老脚本走上面那支不受影响;
+            # /static/ 顶层的第三方库(plyr.js、iconify-*)也不在范围里。
+            response.headers["Cache-Control"] = "no-cache"
         else:
             response.headers["Cache-Control"] = "public, max-age=3600"
     return response
@@ -139,4 +153,6 @@ app.include_router(workflows.router)
 app.include_router(worker.router)
 app.include_router(projects.router)
 app.include_router(exceptions.router)
+app.include_router(quality.router)
 app.include_router(users.router)
+app.include_router(training.router)

processor/app/processing/black_glove/hand_landmarker.task

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fbc2a30080c3c557093b5ddfc334698132eb341044ccee322ccf8bcf3607cde1
+size 7819105

processor/app/processing/cleaning/__init__.py

@@ -0,0 +1,40 @@
+"""数据清洗 —— 按数据类型检查 episode 质量，异常退回人工审核。
+
+对应《以 Episode 为单位的数据清洗方案》(PDF)。核心设计:
+
+* **按信道声明需求**，不按"这是 UMI 还是 EGO" —— 检查项自己声明需要哪些信道，
+  实际有哪些信道由数据决定，两者匹配上才跑（见 ``checks.applicable_checks``）。
+* **四层结果** —— 数据流 / 时间区间 / episode / 训练用途（见 ``report.build_report``）。
+* **只出结论，不产出数据** —— 原始数据一字不改，也不生成 clean_v1 之类的副本。
+  区间信息完整保留在报告里，下游按 ``training_use`` 过滤即可。
+* **可插拔** —— 新增检查项 = 在 ``checks/`` 下放一个 .py（与 processing/modules 同款）。
+
+这个包的算法实现与工作流适配器是分开的，与 ``app/processing/black_glove`` 同构:
+
+    app/processing/cleaning/               ← 本包：契约 + 检查项 + 报告组装
+    app/processing/modules/data_cleaning.py ← 工作流节点（artifact 契约 + 端口 + 配置）
+"""
+
+from app.processing.cleaning.contract import (
+    DEVICE_MODALITIES, CAMERA_MODALITIES, CHANNELS, MODALITY_CHANNELS,
+    PASS, WARN, FAIL, PENDING, ERROR,
+    SEVERITY_ORDER, SEVERITY_LABELS,
+    Finding, Range, StreamResult,
+    channels_for, normalize_device_modality, worst, is_blocking,
+)
+from app.processing.cleaning.report import (
+    SCHEMA_VERSION, TRAINING_USE_RULES,
+    build_report, build_timeline, rollup_episode, rollup_training_use,
+    empty_report, passed_for,
+)
+
+__all__ = [
+    "DEVICE_MODALITIES", "CAMERA_MODALITIES", "CHANNELS", "MODALITY_CHANNELS",
+    "PASS", "WARN", "FAIL", "PENDING", "ERROR",
+    "SEVERITY_ORDER", "SEVERITY_LABELS",
+    "Finding", "Range", "StreamResult",
+    "channels_for", "normalize_device_modality", "worst", "is_blocking",
+    "SCHEMA_VERSION", "TRAINING_USE_RULES",
+    "build_report", "build_timeline", "rollup_episode", "rollup_training_use",
+    "empty_report", "passed_for",
+]

processor/app/processing/cleaning/checks/__init__.py

@@ -0,0 +1,294 @@
+"""清洗检查项注册表 —— 一个文件 = 一个检查项，自动发现。
+
+与 app/processing/modules/ 同一套思路（见那里的 __init__.py）:
+
+    for _m in pkgutil.iter_modules(__path__):
+        importlib.import_module(...)
+
+新增检查项只需在 checks/ 下放一个 .py，内部用 @register_check 装饰类定义。
+
+检查项**按信道/模态声明需求**，不按"这个 episode 是 UMI 还是 EGO"。
+所以同一份检查项集合能自动适配任何数据组合:
+    UMI 夹爪来了 → 只跑需要 slam/force/gripper_state 的那些
+    触觉手套来了 → 只跑需要 tactile 的那些
+    EGO 来了     → 只跑需要 rgb/keypoints 的那些
+这就是 PDF §2「用采集模板决定跑哪些清洗规则」的落地方式。
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from dataclasses import dataclass, field as dc_field
+from pathlib import Path
+from typing import Any, Callable, Iterable
+
+from app.processing.cleaning.contract import (
+    Finding, Range, PASS, WARN, FAIL, PENDING, ERROR,
+    SEVERITY_LABELS, worst, is_blocking,
+)
+
+__all__ = [
+    "CheckContext", "StreamEvidence", "CleaningCheck", "register_check",
+    "get_check", "all_checks", "all_check_specs", "applicable_checks",
+    "checks_for_device_cards",
+    "Finding", "Range", "PASS", "WARN", "FAIL", "PENDING", "ERROR",
+    "SEVERITY_LABELS", "worst", "is_blocking",
+]
+
+_registry: dict[str, "CleaningCheck"] = {}
+
+
+@dataclass(frozen=True)
+class StreamEvidence:
+    """一条数据流的证据 —— 由 evidence.py 采集，检查项**只读不采**。
+
+    把"读磁盘"和"做判断"分开，是让检查项可纯测的关键：测试直接构造本对象，
+    不需要真的 mp4 / parquet / cv2。
+    """
+
+    key: str                             # 流标识，如 "umi_rgb" / "slam_trajectory"
+    channel: str = ""                    # rgb | depth | slam | tactile | ...
+    path: str = ""                       # 相对批次目录的路径（仅用于报错定位）
+    # video_quality 的报告（黑屏/冻结/丢帧/解码）。非视频流为空 dict。
+    # 结构见 app/video_quality.py::_check_stream 的返回。
+    video: dict[str, Any] = dc_field(default_factory=dict)
+    # parquet 概览
+    columns: tuple[str, ...] = ()
+    rows: int = 0
+    fps: float = 0.0
+    # 逐帧数值序列（按帧对齐）。evidence.py 采集时**派生好的**，检查项不自己算。
+    # 例：SLAM 流 → {"pose": ((x,y,z,qx,qy,qz,qw), ...), "t": (...)}
+    #     夹爪流 → {"gripper_state": ((open, gripped, raw), ...),
+    #               "force": ((fx,fy,fz), ...)}
+    # ★ 派生复用 app/umi_slam_action.py 的函数，保证与 action 口径同源。
+    series: dict[str, tuple] = dc_field(default_factory=dict)
+
+
+@dataclass
+class CheckContext:
+    """检查项执行上下文。
+
+    IO 走注入（``read_columns`` / ``probe_video`` …），这样检查项本体是纯逻辑，
+    测试可以喂假数据而不需要真的 mp4 或 cv2。
+    """
+
+    batch_dir: Path                      # 批次目录（含 data/ videos/ meta/）
+    episode_id: str = ""
+    channels: frozenset[str] = frozenset()      # 实际存在的信道
+    modalities: tuple[str, ...] = ()            # 实际存在的设备模态
+    params: dict[str, Any] = dc_field(default_factory=dict)   # 节点配置里的阈值
+    duration_sec: float = 0.0
+    fps: float = 0.0
+    progress: Callable[[float], None] = lambda _value: None
+
+    # ── 证据包（evidence.py 采集好，检查项只读）────────────────
+    streams: tuple["StreamEvidence", ...] = ()
+    # parquet 侧的汇总：行数 / 时间戳列等，跨流共用的信息
+    data_rows: int = 0
+    data_columns: tuple[str, ...] = ()
+
+    # ── 注入式 IO ────────────────────────────────────────────
+    read_columns: Callable[[Path], list[str]] = lambda _p: []
+    read_head: Callable[[Path, int], list[dict]] = lambda _p, _n: []
+    probe_video: Callable[[Path], dict] = lambda _p: {}
+
+    # ── 证据查询便捷方法 ──────────────────────────────────────
+    def streams_of(self, channel: str) -> tuple["StreamEvidence", ...]:
+        """取某信道的全部流。检查项用它筛选自己要看的流。"""
+        return tuple(item for item in self.streams if item.channel == channel)
+
+    def param(self, name: str, default: Any = None) -> Any:
+        """取阈值配置；节点未配置时回落到检查项声明的默认值。"""
+        value = self.params.get(name)
+        return default if value is None else value
+
+
+class CleaningCheck:
+    """清洗检查项基类。
+
+    子类填元数据 + 实现 ``run()``，用 ``@register_check`` 装饰即可被自动发现。
+    """
+
+    slug: str = ""                       # "video.frame_drop"
+    label: str = ""
+    version: str = "1.0"                 # 改了要 bump —— 进 ruleset_revision
+    description: str = ""
+
+    # 必需的信道/设备模态；全部满足才跑
+    requires_channels: tuple[str, ...] = ()
+    requires_modality: tuple[str, ...] = ()
+    # 需要 ≥2 类设备模态同时存在（PDF 的"跨模态联合检查"）
+    cross_modal: bool = False
+
+    # ★ 本项属于哪些【设备卡片】—— 前端按它把检查项分到设置面板的各 tab。
+    #
+    # 取值来自 contract.DEVICE_MODALITIES，空元组 = 不绑定单个设备
+    # （跨设备检查用，它们只在"跨设备" tab 里出现）。
+    #
+    # 为什么用声明而不是靠目录分：同一个检查项往往多张卡片都要用 ——
+    # ``video.frame_drop`` 对 RGB Camera、RGB-D Camera、UMI Gripper 都成立，
+    # 按目录分只能放一处。声明式的话它能同时出现在多个 tab 里，
+    # 且各自的阈值配置互不影响（见 node.data.config.devices.<卡片>.params）。
+    device_cards: tuple[str, ...] = ()
+
+    default_severity: str = FAIL
+    # 阈值默认值 —— 节点配置可覆盖。PDF 明确要求"阈值不要照搬"，
+    # 所以这里给的是**平台初始值**，必须在真实数据上验证后再固化。
+    default_params: dict[str, Any] = dc_field(default_factory=dict)
+
+    def param(self, ctx: "CheckContext", name: str, fallback: Any = None) -> Any:
+        """取阈值。顺序：节点配置 → 本项声明的 default_params → fallback。
+
+        检查项一律用这个方法读阈值，不要写 ``ctx.params.get(..., 字面量)`` ——
+        那样声明的 default_params 就成了死代码，改它不生效。
+        """
+        value = (ctx.params or {}).get(name)
+        if value is not None:
+            return value
+        if name in self.default_params:
+            return self.default_params[name]
+        return fallback
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        raise NotImplementedError
+
+    # ── 便捷构造 ─────────────────────────────────────────────
+    def finding(self, ctx: CheckContext, status: str, *,
+                stream: str = "", message: str = "",
+                metrics: dict | None = None,
+                ranges: Iterable[Range] = ()) -> Finding:
+        return Finding(
+            rule=self.slug, version=self.version, status=status,
+            scope="cross_modal" if self.cross_modal else "stream",
+            stream=stream, message=message, metrics=dict(metrics or {}),
+            ranges=tuple(ranges),
+        )
+
+
+def checks_for_device_cards(cards: Iterable[str]) -> dict[str, list[CleaningCheck]]:
+    """按【设备卡片】把检查项分组 —— 前端设置面板的 tab 就按这个渲染。
+
+    只返回传进来的卡片（= 工作流里实际连接的设备），未连接的不会出现。
+    一个检查项可能落在多个卡片下（如 ``video.frame_drop`` 对每种带摄像头的
+    设备都成立），各 tab 里的阈值配置互不影响。
+
+    例::
+
+        checks_for_device_cards(["rgbd_camera", "glove_sensor"])
+        → {"rgbd_camera": [video.frame_drop, video.black_screen, ...],
+           "glove_sensor": [glove.tactile_health, ...]}
+    """
+    wanted = [str(card) for card in cards]
+    grouped: dict[str, list[CleaningCheck]] = {card: [] for card in wanted}
+    for check in all_checks():
+        for card in check.device_cards:
+            if card in grouped:
+                grouped[card].append(check)
+    return grouped
+
+
+def register_check(cls):
+    """按 slug 注册检查项（装饰器）。"""
+    if not cls.slug:
+        raise ValueError(f"Check {cls.__name__} has no slug")
+    if cls.slug in _registry:
+        raise ValueError(f"Duplicate check slug: {cls.slug}")
+    _registry[cls.slug] = cls()
+    return cls
+
+
+def get_check(slug: str) -> CleaningCheck | None:
+    return _registry.get(slug)
+
+
+def all_checks() -> list[CleaningCheck]:
+    """全部已注册检查项（按 slug 排序，保证 ruleset_revision 稳定）。"""
+    return [_registry[key] for key in sorted(_registry)]
+
+
+def all_check_specs() -> list[dict]:
+    """检查项目录 —— 给 API / UI 用。
+
+    前端配置面板直接渲染这个：按 ``category`` 分组，每个检查项一行开关，
+    下面按 ``default_params`` 动态生成输入框。新增检查项前端零改动。
+    """
+    return [
+        {
+            "slug": check.slug,
+            # 分类取自 slug 前缀（video.frame_drop → video），与 checks/ 下的
+            # 目录名一致。前端按它分组。
+            "category": check.slug.split(".", 1)[0] if "." in check.slug else "other",
+            "label": check.label,
+            "version": check.version,
+            "description": check.description,
+            "requires_channels": list(check.requires_channels),
+            "requires_modality": list(check.requires_modality),
+            "cross_modal": check.cross_modal,
+            "device_cards": list(check.device_cards),
+            "default_severity": check.default_severity,
+            "default_params": dict(check.default_params),
+        }
+        for check in all_checks()
+    ]
+
+
+def applicable_checks(channels: Iterable[str],
+                      modalities: Iterable[str],
+                      *,
+                      cross_modal_active: bool = False,
+                      enabled: Iterable[str] | None = None,
+                      disabled: Iterable[str] | None = None) -> list[CleaningCheck]:
+    """筛出该跑哪些检查项。纯函数。
+
+    - ``requires_channels`` / ``requires_modality`` 必须**全部**具备
+    - ``cross_modal`` 的额外要求至少两类模态同时存在
+    - ``enabled`` / ``disabled`` 是节点配置里的按类型开关
+    """
+    have_channels = {str(item) for item in channels}
+    have_modalities = {str(item) for item in modalities}
+    allow = {str(item) for item in enabled} if enabled is not None else None
+    deny = {str(item) for item in disabled or ()}
+
+    result: list[CleaningCheck] = []
+    for check in all_checks():
+        if not set(check.requires_channels) <= have_channels:
+            continue
+        if not set(check.requires_modality) <= have_modalities:
+            continue
+        # ★ 设备卡片闸门 —— 声明了归属的检查项只在【对应设备】上跑。
+        #
+        # 光按信道筛不够：`umi.action_present` 只要"有 action 列"就满足，
+        # 而手套项目同样有一列（采集端写的全零占位）—— 结果 UMI 的检查跑到了
+        # 手套项目上、报出一个对方根本不关心的失败。
+        # 空 device_cards = 跨设备检查，不设闸门。
+        if check.device_cards and not (set(check.device_cards) & have_modalities):
+            continue
+        if check.cross_modal and not cross_modal_active:
+            continue
+        if allow is not None and check.slug not in allow:
+            continue
+        if check.slug in deny:
+            continue
+        result.append(check)
+    return result
+
+
+# 自动发现检查项。
+#
+# 用 walk_packages 而非 iter_modules —— 前者递归进子包，后者只认平铺的 .py。
+# 检查项按数据类型分类放在子包里，目录即分类，便于定位:
+#
+#     checks/video/frame_drop.py      视频
+#     checks/umi/slam_continuity.py   UMI 夹爪
+#     checks/glove/baseline_drift.py  触觉手套
+#     checks/ego/hand_side.py         EGO 头戴
+#     checks/depth/presence.py        深度
+#     checks/cross/video_data_sync.py 跨模态
+#
+# 子包不需要写任何注册代码 —— 空 __init__.py 即可，里面的模块会被自动导入。
+# 新增一项检查 = 在对应目录放一个 .py，注册表/节点/前端都不用改。
+for _info in pkgutil.walk_packages(__path__, prefix=f"{__name__}."):
+    if _info.name.rsplit(".", 1)[-1].startswith("_"):
+        continue
+    importlib.import_module(_info.name)

processor/app/processing/cleaning/checks/cross/__init__.py

@@ -0,0 +1,5 @@
+"""跨模态检查 —— 需要 ≥2 类设备模态同时存在。
+
+本目录下一个 .py = 一个检查项（用 @register_check 注册）。
+新增检查项只需在此放文件，注册表会自动发现（见上级 __init__.py 的 walk_packages）。
+"""

processor/app/processing/cleaning/checks/depth/__init__.py

@@ -0,0 +1,5 @@
+"""深度类检查 —— 是否存在/有效占比。
+
+本目录下一个 .py = 一个检查项（用 @register_check 注册）。
+新增检查项只需在此放文件，注册表会自动发现（见上级 __init__.py 的 walk_packages）。
+"""

processor/app/processing/cleaning/checks/ego/__init__.py

@@ -0,0 +1,5 @@
+"""EGO 头戴检查 —— 关键点/左右手/曝光。
+
+本目录下一个 .py = 一个检查项（用 @register_check 注册）。
+新增检查项只需在此放文件，注册表会自动发现（见上级 __init__.py 的 walk_packages）。
+"""

processor/app/processing/cleaning/checks/glove/__init__.py

@@ -0,0 +1,5 @@
+"""触觉手套检查 —— 阵列健康/基线漂移/缺帧。
+
+本目录下一个 .py = 一个检查项（用 @register_check 注册）。
+新增检查项只需在此放文件，注册表会自动发现（见上级 __init__.py 的 walk_packages）。
+"""

processor/app/processing/cleaning/checks/glove/array_shape.py

@@ -0,0 +1,82 @@
+"""触觉阵列形状 —— 每帧必须是一整块 16×16。
+
+为什么值得单列一项
+------------------
+看着像废话，但它是**静默截断的哨兵**：采集层曾经因为宽度表里没有 ``tactile``
+而落到 3 的兜底值，256 个感应点被悄悄截成 3 个 —— 有列、有值、能加载，检查项
+只看得到 1% 的阵列，而且不报任何错。同一类问题还会再来（换手套、换固件、改列
+宽），所以这里明确把"整块阵列"写成契约。
+
+判据
+----
+每帧长度必须等于 ``expected_size``（默认 256 = 16×16）。空元组（``None`` 帧）
+也算不合格 —— 它意味着这一帧根本没读到。
+
+超出 ``max_bad_ratio`` 判 FAIL，否则 WARN：单帧缺失多半是偶发，系统性截断会是
+接近 100% 的比例。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN, FAIL,
+)
+
+
+@register_check
+class GloveArrayShapeCheck(CleaningCheck):
+    slug = "glove.array_shape"
+    label = "Tactile Array Integrity"
+    version = "1.0"
+    description = "Every frame must be a complete 16×16 array (catches silent truncation)"
+
+    requires_channels = ("tactile",)
+    device_cards = ("glove_sensor",)
+    default_params = {
+        "expected_size": 256,     # 16×16
+        "max_bad_ratio": 0.01,    # 不合格帧超过 1% 判 FAIL
+    }
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        expected = int(self.param(ctx, "expected_size", 256))
+        max_ratio = float(self.param(ctx, "max_bad_ratio", 0.01))
+
+        for stream in ctx.streams_of("tactile"):
+            values = tuple(stream.series.get("tactile") or ())
+            total = len(values)
+            if not total:
+                # 列在但一行都没有 —— 与"列不存在"同义，交给别的检查去报
+                continue
+
+            bad = [len(item) for item in values if len(item) != expected]
+            ratio = len(bad) / total
+            # 出现过的长度 —— 一眼看出是被截断(如 3)还是别的形状
+            observed = sorted({len(item) for item in values})
+
+            if not bad:
+                findings.append(self.finding(
+                    ctx, PASS, stream=stream.key,
+                    message=f"{stream.key}: {expected}-wide for the whole episode",
+                    metrics={"frames": total, "expected_size": expected},
+                ))
+                continue
+
+            status = FAIL if ratio > max_ratio else WARN
+            findings.append(self.finding(
+                ctx, status, stream=stream.key,
+                message=(f"{stream.key}: {len(bad)}/{total} frames are not "
+                         f"{expected}-wide (observed lengths {observed[:5]})"),
+                metrics={
+                    "frames": total, "bad_frames": len(bad),
+                    "bad_ratio": round(ratio, 4),
+                    "expected_size": expected,
+                    "observed_sizes": observed[:10],
+                    "first_bad_frame": next(
+                        (i for i, item in enumerate(values) if len(item) != expected), None),
+                },
+            ))
+
+        return findings

processor/app/processing/cleaning/checks/glove/device_status.py

@@ -0,0 +1,107 @@
+"""手套连接状态 —— 录制途中掉线。
+
+为什么重要
+----------
+手套掉线时阵列读数会**静默保持最后一个值**，看起来完全正常：有列、有 16×16、
+数值也在合理范围。只有状态列说实话。所以这一项是唯一能看见"设备其实没了"
+的检查。
+
+判定口径（分两种，因为状态词表只见过一个值）
+------------------------------------------
+``connected`` 是实测见到的**唯一**取值（S80C / D435 两个项目、全部集、全部帧）。
+其余词表未知，所以：
+
+  录制中途**状态发生变化**  → **FAIL**
+      无论变成什么，从"连着"变成别的就是掉线，这个判断不依赖词表。
+
+  全程恒定但不是 ``connected`` → **WARN**
+      可能是掉线，也可能是我们没见过的正常状态词（如 "ok"/"active"）。
+      词表未证实之前不拦批次 —— 拦错了用户会开始无脑点通过，比不拦更糟。
+
+  空字符串 → **WARN**（这一帧没读到状态）
+
+★ 阈值不放进 ``default_params``：词表是字符串，而前端设置面板把所有参数都渲染
+  成数字输入框。硬塞会把面板显示成 NaN。真需要可配时先改面板的类型支持。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN, FAIL,
+)
+
+# 实测唯一见过的取值。其余一律按"词表未知"处理，不直接判失败。
+_HEALTHY = "connected"
+
+
+@register_check
+class GloveDeviceStatusCheck(CleaningCheck):
+    slug = "glove.device_status"
+    label = "Glove Connection"
+    version = "1.0"
+    description = "Device dropped out mid-recording (from status.*_glove)"
+
+    requires_channels = ("device_status",)
+    device_cards = ("glove_sensor",)
+    default_params: dict = {}
+    default_severity = FAIL
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+
+        for stream in ctx.streams_of("device_status"):
+            values = tuple(stream.series.get("device_status") or ())
+            # 流名就是那一列的最后一段（left_glove / right_glove），用它报位置
+            hand = stream.key
+            if not values:
+                findings.append(self.finding(
+                    ctx, WARN, stream=hand,
+                    message=f"{hand}: no status column data",
+                    metrics={"frames": 0},
+                ))
+                continue
+
+            blanks = sum(1 for item in values if not item)
+            distinct: list[str] = []
+            for item in values:
+                if item and item not in distinct:
+                    distinct.append(item)
+
+            # ① 中途变过 —— 与词表无关，见到即掉线
+            if len(distinct) > 1:
+                changes = [i for i in range(1, len(values)) if values[i] != values[i - 1]]
+                findings.append(self.finding(
+                    ctx, FAIL, stream=hand,
+                    message=(f"{hand}: status changed {len(changes)} times "
+                             f"during recording: {' -> '.join(distinct)}"),
+                    metrics={"frames": len(values), "distinct": distinct,
+                             "first_change_frame": changes[0] if changes else None,
+                             "blank_frames": blanks},
+                ))
+                continue
+
+            status = distinct[0] if distinct else ""
+            # ② 恒定但词表未知 / ③ 全空
+            if not status:
+                findings.append(self.finding(
+                    ctx, WARN, stream=hand,
+                    message=f"{hand}: status column is entirely blank",
+                    metrics={"frames": len(values), "blank_frames": blanks},
+                ))
+            elif status != _HEALTHY:
+                findings.append(self.finding(
+                    ctx, WARN, stream=hand,
+                    message=(f"{hand}: status is constantly {status!r} (only "
+                             f"{_HEALTHY!r} has ever been observed; vocabulary "
+                             f"unconfirmed - please verify manually)"),
+                    metrics={"frames": len(values), "status": status},
+                ))
+            else:
+                findings.append(self.finding(
+                    ctx, PASS, stream=hand,
+                    message=f"{hand}: {_HEALTHY} for the whole episode",
+                    metrics={"frames": len(values), "status": status},
+                ))
+
+        return findings

processor/app/processing/cleaning/checks/glove/frozen_array.py

@@ -0,0 +1,132 @@
+"""触觉阵列卡死 —— 设备停止更新，录制端却继续写。
+
+为什么重要
+----------
+这是最难发现的一类：**录制链路完全正常**。帧数对得上、时间戳连续、阵列是完整
+的 16×16、数值也在合理区间 —— 只是内容是**很久以前的那一帧**，一直没变。
+事后看数据一切正常，只有对比相邻帧才发现它静止了。
+
+判定口径（阈值有实测依据）
+--------------------------
+**静止本身不是问题**。实测设备更新率约 7.5Hz，而录制是 30fps，所以同一个值会
+**连续保持 4 帧** —— 这是正常的，不是卡死。
+
+  S80C 全部集：受压时的保持段长度**只有 4**（`{4}`，无其他取值）
+  D435 全部集：没有受压保持段
+
+（本文件统计的是"保持帧数"= 一个取值连续占了多少帧。同一现象另一种常见记法是
+"相邻帧相等的对数"，那个数是 3 —— 4 帧有 3 个间隔。两个数不矛盾，别混。）
+
+所以阈值有充足余量：``warn_frames=40``（约 1.3 秒）已经远超正常值。取 40 而不是
+"比 4 大一点"，是给将来换更新率更低的设备留空间 —— 卡死检测宁可慢一点发现，
+也不该把正常的低更新率设备全报一遍。
+
+★ 只在**受压时**才判。全零段天然"完全相同"（都是零），把它算进去的话，一集里
+  88% 都是全零帧的批次会报出几百帧的假静止（实测踩过：最长静止段 575 帧，全部
+  来自全零段）。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN, FAIL,
+)
+from app.processing.cleaning.contract import Range
+
+# 报告的区间数上限 —— 真卡死时可能几百段，全塞进报告没意义
+_MAX_RANGES = 20
+
+
+def _static_runs(values: tuple, min_length: int) -> list[tuple[int, int]]:
+    """受压时完全相同的连续帧段 ``[(起始帧, 长度), ...]``。
+
+    只统计**非空且有压力**的帧：全零段天然完全相同，算进来会造出大片假区间。
+    """
+    runs: list[tuple[int, int]] = []
+    total = len(values)
+    index = 0
+    while index < total:
+        # 向后找同一取值的最长延伸
+        end = index
+        while end + 1 < total and values[end + 1] == values[index]:
+            end += 1
+        length = end - index + 1
+        frame = values[index]
+        pressed = bool(frame) and any(value > 0.0 for value in frame)
+        if length >= min_length and pressed:
+            runs.append((index, length))
+        index = end + 1
+    return runs
+
+
+@register_check
+class GloveFrozenArrayCheck(CleaningCheck):
+    slug = "glove.frozen_array"
+    label = "Tactile Array Frozen"
+    version = "1.0"
+    description = "Array unchanged for a long stretch while pressed (device stopped updating)"
+
+    requires_channels = ("tactile",)
+    device_cards = ("glove_sensor",)
+    default_params = {
+        "warn_frames": 40,        # 约 1.3 秒 @30fps；实测正常值 3 帧
+        "fail_frames": 300,       # 约 10 秒
+    }
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        fps = float(ctx.fps or 0.0) or 30.0
+        warn_frames = int(self.param(ctx, "warn_frames", 40))
+        fail_frames = int(self.param(ctx, "fail_frames", 300))
+
+        for stream in ctx.streams_of("tactile"):
+            values = tuple(stream.series.get("tactile") or ())
+            if not values:
+                continue
+
+            runs = _static_runs(values, warn_frames)
+            if not runs:
+                findings.append(self.finding(
+                    ctx, PASS, stream=stream.key,
+                    message=f"{stream.key}: no abnormal frozen stretch",
+                    metrics={"frames": len(values), "warn_frames": warn_frames},
+                ))
+                continue
+
+            longest = max(length for _, length in runs)
+            status = FAIL if longest >= fail_frames else WARN
+            ranges = tuple(
+                Range(
+                    start_sec=start / fps,
+                    end_sec=(start + length - 1) / fps,
+                    code=self.slug,
+                    severity=FAIL if length >= fail_frames else WARN,
+                    stream=stream.key,
+                    channel="tactile",
+                    start_frame=start,
+                    end_frame=start + length - 1,
+                    rule=self.slug,
+                    message=f"array unchanged for {length} frames",
+                    evidence={"frozen_frames": length},
+                )
+                for start, length in runs[:_MAX_RANGES]
+            )
+
+            findings.append(self.finding(
+                ctx, status, stream=stream.key,
+                message=(f"{stream.key}: {len(runs)} frozen stretches while "
+                         f"pressed (longest {longest} frames ~= {longest / fps:.1f}s)"),
+                metrics={
+                    "frames": len(values),
+                    "static_runs": len(runs),
+                    "longest_run_frames": longest,
+                    "longest_run_sec": round(longest / fps, 3),
+                    "warn_frames": warn_frames,
+                    "fail_frames": fail_frames,
+                },
+                ranges=ranges,
+            ))
+
+        return findings

processor/app/processing/cleaning/checks/glove/gate_floor.py

@@ -0,0 +1,87 @@
+"""触觉阵列取值下限 —— 检测**编码/量纲漂移**。
+
+为什么需要它
+------------
+实测这份手套数据有个硬门限：取值**要么是 0，要么 ≥ 500.02**，0 到 500 之间
+一个值都没有（从 0 直接跳到 508.09，没有过渡）。所以
+
+    ``0`` 的含义是"未接触"，**不是"力为零"**
+
+这个门限是固件行为，也是所有下游解读的前提。它一旦变了，**别的一切看起来都还
+正常**：列还在、还是 16×16、数还在合理区间 —— 但含义已经不同了。典型触发：
+
+  * 固件改版，直接输出原始 ADC（0–4095）而不是门限后的值
+  * 标定系数 ``scale`` 被应用了两次（或该应用而没应用）
+  * 换了另一款手套
+
+判据
+----
+非零值里低于 ``min_contact_value``（默认 500）的**占比**。
+超出 ``fail_ratio`` 判 FAIL，否则 WARN。实测两个项目全部集都是 0 个越界值，
+所以正常数据有充足余量。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN, FAIL,
+)
+
+
+@register_check
+class GloveGateFloorCheck(CleaningCheck):
+    slug = "glove.gate_floor"
+    label = "Contact Threshold"
+    version = "1.0"
+    description = "Non-zero values must exceed the contact floor (catches silent encoding changes)"
+
+    requires_channels = ("tactile",)
+    device_cards = ("glove_sensor",)
+    default_params = {
+        # 实测最小非零值 500.02。留一点余量给固件微调，但远低于它就没有意义了
+        # —— 那正是"编码变了"的样子。
+        "min_contact_value": 500.0,
+        "fail_ratio": 0.05,       # 非零值里超过 5% 低于门限 → FAIL
+    }
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        floor = float(self.param(ctx, "min_contact_value", 500.0))
+        fail_ratio = float(self.param(ctx, "fail_ratio", 0.05))
+
+        for stream in ctx.streams_of("tactile"):
+            values = tuple(stream.series.get("tactile") or ())
+            flat = [float(v) for item in values if item for v in item]
+            nonzero = [v for v in flat if v > 0.0]
+            if not nonzero:
+                # 整集没有非零值 —— 那是 glove.no_contact 的事，这里不重复报
+                continue
+
+            below = [v for v in nonzero if v < floor]
+            ratio = len(below) / len(nonzero)
+
+            if not below:
+                findings.append(self.finding(
+                    ctx, PASS, stream=stream.key,
+                    message=f"{stream.key}: all non-zero values above the floor",
+                    metrics={"nonzero": len(nonzero), "min_value": round(min(nonzero), 3)},
+                ))
+                continue
+
+            status = FAIL if ratio > fail_ratio else WARN
+            findings.append(self.finding(
+                ctx, status, stream=stream.key,
+                message=(f"{stream.key}: {len(below)}/{len(nonzero)} non-zero values"
+                         f" are below the contact floor {floor:g} (min {min(below):.3f})"
+                         f" - the array encoding may have changed"),
+                metrics={
+                    "nonzero": len(nonzero), "below_floor": len(below),
+                    "below_ratio": round(ratio, 4),
+                    "min_contact_value": floor,
+                    "min_value": round(min(nonzero), 3),
+                },
+            ))
+
+        return findings

processor/app/processing/cleaning/checks/glove/no_contact.py

@@ -0,0 +1,70 @@
+"""整集无接触 —— 手套没戴上、没开机，或阵列整体失效。
+
+为什么单列一项
+--------------
+它和"某一根手指没碰"完全不同量级：后者是正常的（实测单集里 30–86% 的感应点
+全程为 0，因为只压到阵列的一部分）。**整只手套一帧都没有值**才是设备层面的问题。
+
+判据保守是故意的
+----------------
+实测最低的一集也有 **11.4%** 的帧存在压力，所以"全零"离正常值有极大余量，
+不需要为它编阈值。``min_active_ratio`` 默认 0.0 = 只在**整集恒为 0** 时才报，
+用户想更严可以往上调。
+
+只报 WARN：手套没戴上也可能是**操作员故意的**（这一段就是不给触觉），
+没到判失败的程度。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN,
+)
+
+
+@register_check
+class GloveNoContactCheck(CleaningCheck):
+    slug = "glove.no_contact"
+    label = "No Contact"
+    version = "1.0"
+    description = "No pressure readings at all in this episode (not worn / not working)"
+
+    requires_channels = ("tactile",)
+    device_cards = ("glove_sensor",)
+    default_params = {
+        # 0.0 = 只在整集恒为 0 时报。实测最低 11.4%，余量充足。
+        "min_active_ratio": 0.0,
+    }
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        min_ratio = float(self.param(ctx, "min_active_ratio", 0.0))
+
+        for stream in ctx.streams_of("tactile"):
+            values = tuple(stream.series.get("tactile") or ())
+            if not values:
+                continue
+
+            active = sum(1 for frame in values
+                         if frame and any(value > 0.0 for value in frame))
+            ratio = active / len(values)
+
+            if ratio > min_ratio:
+                findings.append(self.finding(
+                    ctx, PASS, stream=stream.key,
+                    message=f"{stream.key}: has contact frames",
+                    metrics={"frames": len(values), "active_frames": active,
+                             "active_ratio": round(ratio, 4)},
+                ))
+            else:
+                findings.append(self.finding(
+                    ctx, WARN, stream=stream.key,
+                    message=(f"{stream.key}: no pressure readings in any of the "
+                             f"{len(values)} frames (not worn, or the array failed)"),
+                    metrics={"frames": len(values), "active_frames": active,
+                             "active_ratio": round(ratio, 4)},
+                ))
+
+        return findings

processor/app/processing/cleaning/checks/umi/__init__.py

@@ -0,0 +1,5 @@
+"""UMI 夹爪检查 —— SLAM 连续性/帧同步/夹爪量程。
+
+本目录下一个 .py = 一个检查项（用 @register_check 注册）。
+新增检查项只需在此放文件，注册表会自动发现（见上级 __init__.py 的 walk_packages）。
+"""

processor/app/processing/cleaning/checks/umi/action_present.py

@@ -0,0 +1,118 @@
+"""action 有效性 —— 监督信号是否真的存在、是否可用。
+
+为什么重要
+----------
+**action 是 ACT 的监督信号**（``L1(预测, action)``）。没有它就算不出 loss。
+而它是**派生**出来的，不是采出来的，所以有四种失效方式：
+
+  ① 工作流没跑 / 跑失败 → action 还是采集端的**全零占位**
+     ★ 最阴险：有列、有 7 维、能加载，全是 0 —— 不报任何错
+  ② 整集派生失败（位姿样本不足）→ 列根本不写 → 导出时缺失
+     ★ 训练直接 KeyError（2026-09-11 踩过）
+  ③ 部分帧派生失败 → 那些帧的 action 是 null
+  ④ 派生成功但数值离群 → 归一化统计量被撑大（交给 umi.slam_continuity 解释）
+
+严重度
+------
+① ② 判 **FAIL** —— 没有监督信号，这一集对训练毫无价值。
+③ 判 **WARN** —— 部分帧缺失，剩余帧仍可训练。
+
+关于"全零"
+----------
+采集端在 UMI 硬件上写的就是全零（硬件不录 action），所以**必须区分**
+"还没派生"和"派生了但动作真的是零"。判据是**整列方差**：
+派生的 action 即使动作很小，帧间也会有变化；全零占位则方差严格为 0。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN, FAIL,
+)
+
+
+@register_check
+class UmiActionPresentCheck(CleaningCheck):
+    slug = "umi.action_present"
+    label = "Action Validity"
+    version = "1.0"
+    description = "Missing supervision signal, all-zero placeholder, or frames never derived"
+
+    requires_channels = ("action",)
+
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+
+    device_cards = ("gripper_device",)
+
+    default_params = {
+        "min_coverage": 0.95,     # 有 action 的帧占比下限
+        "zero_epsilon": 1e-9,     # 判定"全零"的容差
+    }
+    default_severity = FAIL
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        min_coverage = float(self.param(ctx, "min_coverage", 0.95))
+        epsilon = float(self.param(ctx, "zero_epsilon", 1e-9))
+
+        for stream in ctx.streams_of("action"):
+            rows = int(stream.rows or 0)
+            if not rows:
+                # 列存在但一行都没有 —— 与"列不存在"同义
+                findings.append(self.finding(
+                    ctx, FAIL, stream=stream.key,
+                    message="the action column has no data at all (derivation failed for the whole episode)",
+                    metrics={"rows": 0},
+                ))
+                continue
+
+            values = stream.series.get("action") or ()
+            usable = [item for item in values if item]
+            coverage = len(usable) / rows if rows else 0.0
+
+            # 整列方差 —— 区分"全零占位"和"动作真的很小"
+            flat: list[float] = []
+            for item in usable[:5000]:          # 抽样即可，全零占位必然处处为零
+                try:
+                    flat.extend(float(value) for value in item)
+                except (TypeError, ValueError):
+                    continue
+            spread = (max(flat) - min(flat)) if flat else 0.0
+            all_zero = spread <= epsilon
+
+            metrics = {
+                "rows": rows,
+                "usable": len(usable),
+                "coverage": round(coverage, 4),
+                "value_spread": spread,
+            }
+
+            if all_zero and usable:
+                findings.append(self.finding(
+                    ctx, FAIL, stream=stream.key,
+                    message="action is all zeros - likely still the recorder placeholder (workflow never ran, or derivation failed)",
+                    metrics=metrics,
+                ))
+                continue
+
+            if not usable:
+                findings.append(self.finding(
+                    ctx, FAIL, stream=stream.key,
+                    message="the action column exists but every value is empty (derivation produced no frames)",
+                    metrics=metrics,
+                ))
+                continue
+
+            if coverage < min_coverage:
+                findings.append(self.finding(
+                    ctx, WARN, stream=stream.key,
+                    message=f"only {len(usable)}/{rows} frames have action"
+                            f"（{coverage:.1%}），其余帧无监督信号",
+                    metrics=metrics,
+                ))
+                continue
+
+            findings.append(self.finding(ctx, PASS, stream=stream.key,
+                                         metrics=metrics))
+        return findings

processor/app/processing/cleaning/checks/umi/av_sync.py

@@ -0,0 +1,84 @@
+"""视频 ↔ 数据 帧同步 —— 各数据流的帧数与 RGB 视频是否一致。
+
+为什么重要
+----------
+UMI 的 action 按帧号对齐：第 i 行动作对应第 i 帧画面。任何一路数据与视频
+帧数不一致，都会让"看这一帧、预测下一步"的监督信号整体错位。
+
+与 ``video.frame_drop`` 的分工
+-----------------------------
+``video.frame_drop`` 比的是 **视频帧数 vs parquet 总行数**（整体量）。
+本项比的是 **每一路数据流各自的帧数**（结构性）——
+UMI 特有：Slam / gripper_state / force 是三条独立写入的列，
+采集端丢帧时可能只有其中一路短了，总数却对得上。
+
+这也是用户提的"整个的数据有没有根据 RGB 视频进行帧同步"。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN, FAIL,
+)
+
+
+@register_check
+class UmiAvSyncCheck(CleaningCheck):
+    slug = "umi.av_sync"
+    label = "Video ↔ Data Frame Sync"
+    version = "1.0"
+    description = "Frame counts differ between data streams"
+
+    # 需要视频和至少一路数据同时存在才有意义。
+    # ★ 不加 cross_modal —— 它比的是【同一个 UMI 设备内部】的视频与各数据列，
+    #   不是两张设备卡片之间。requires_channels 已经把"必须有 rgb"表达清楚了，
+    #   再加 cross_modal 会把它错误地挤进"跨设备" tab。
+    requires_channels = ("rgb", "time")
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+    device_cards = ("gripper_device",)
+
+    default_params = {"tolerance": 2}
+    default_severity = FAIL
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        # 视频侧：取第一路 RGB 的帧数作为基准
+        rgb_streams = ctx.streams_of("rgb")
+        if not rgb_streams:
+            return []
+        reference = None
+        reference_key = ""
+        for stream in rgb_streams:
+            frames = int((stream.video or {}).get("frame_count") or stream.rows or 0)
+            if frames:
+                reference, reference_key = frames, stream.key
+                break
+        if not reference:
+            return []
+
+        tolerance = int(self.param(ctx, "tolerance", 2))
+        drifted: dict[str, int] = {}
+        for stream in ctx.streams:
+            if stream.channel in ("rgb", "depth") or not stream.rows:
+                continue
+            if stream.key == reference_key:
+                continue
+            diff = abs(int(stream.rows) - reference)
+            if diff > tolerance:
+                drifted[stream.key] = int(stream.rows)
+
+        metrics = {"reference_stream": reference_key,
+                   "reference_frames": reference,
+                   "tolerance": tolerance,
+                   "drifted": drifted}
+
+        if not drifted:
+            return [self.finding(ctx, PASS, metrics=metrics)]
+
+        detail = "，".join(f"{key}={rows}" for key, rows in sorted(drifted.items()))
+        return [self.finding(
+            ctx,
+            FAIL,
+            message=f"these streams do not match the video frame count ({reference}): {detail}",
+            metrics=metrics,
+        )]

processor/app/processing/cleaning/checks/umi/gripper_range.py

@@ -0,0 +1,157 @@
+"""夹爪量程与力基线 —— 开合度越界、力读数漂移。
+
+为什么重要
+----------
+**开合度越界**：``umi_slam_action._gripper_fraction()`` 会把开合度
+``np.clip(0, 1)``。也就是说越界值在派生 action 时被**静默夹掉**了 ——
+标定异常的集看起来"正常"，但动作里的夹爪维度是失真的。本项就是在
+clip 之前把它抓出来（原始列 ``observation.gripper_state[0]`` 是 0–100）。
+
+**力基线漂移**：夹爪没接触物体时力读数应在零附近。若整集的静息基线缓慢
+上移，说明传感器漂移/温漂，用力做阈值判断的模型会失真。
+
+判定口径
+--------
+开合度越界默认判 **WARN**（数据还能用，但要知道标定有问题）；
+力漂移默认判 **WARN**（同上）。两者都不拦数据，只报告。
+"""
+
+from __future__ import annotations
+
+import math
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, Range, PASS, WARN,
+)
+
+# 原始列里开合度的量程（采集端契约：[open_pct, gripped, fz_mn]）
+OPEN_PCT_MIN = 0.0
+OPEN_PCT_MAX = 100.0
+
+
+def _median(values: list[float]) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    middle = len(ordered) // 2
+    if len(ordered) % 2:
+        return ordered[middle]
+    return (ordered[middle - 1] + ordered[middle]) / 2.0
+
+
+@register_check
+class UmiGripperRangeCheck(CleaningCheck):
+    slug = "umi.gripper_range"
+    label = "Gripper Range / Force Baseline"
+    version = "1.0"
+    description = "Gripper opening out of range, or force baseline drift"
+
+    requires_channels = ("gripper_state",)
+
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+
+    device_cards = ("gripper_device",)
+
+    default_params = {
+        "max_out_of_range_ratio": 0.01,   # 越界帧占比上限
+        "max_force_drift": 200.0,          # 前后半段基线差（mN）
+    }
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        max_ratio = float(self.param(ctx, "max_out_of_range_ratio", 0.01))
+        max_drift = float(self.param(ctx, "max_force_drift", 200.0))
+
+        for stream in ctx.streams_of("gripper_state"):
+            samples = stream.series.get("gripper_state") or ()
+            if not samples:
+                continue
+            fps = float(stream.fps or ctx.fps or 30.0)
+
+            out_of_range: list[Range] = []
+            values: list[float] = []
+            for index, sample in enumerate(samples):
+                if not sample:
+                    continue
+                try:
+                    pct = float(sample[0])
+                except (TypeError, ValueError, IndexError):
+                    continue
+                values.append(pct)
+                if OPEN_PCT_MIN <= pct <= OPEN_PCT_MAX:
+                    continue
+                out_of_range.append(Range(
+                    start_sec=index / fps, end_sec=(index + 1) / fps,
+                    code=self.slug, severity=WARN,
+                    stream=stream.key, channel="gripper_state",
+                    start_frame=index, end_frame=index,
+                    rule=self.slug,
+                    message=f"opening {pct:.1f} is outside the 0-100 range"
+                            f"（派生 action 时会被静默夹掉）",
+                    evidence={"open_pct": round(pct, 2)},
+                ))
+
+            if not values:
+                continue
+
+            ratio = len(out_of_range) / len(values)
+            metrics: dict = {
+                "samples": len(values),
+                "out_of_range": len(out_of_range),
+                "out_of_range_ratio": round(ratio, 4),
+                "min": round(min(values), 2),
+                "max": round(max(values), 2),
+            }
+
+            if ratio > max_ratio:
+                findings.append(self.finding(
+                    ctx, WARN, stream=stream.key,
+                    message=f"{len(out_of_range)}/{len(values)} frames out of range"
+                            f"（{ratio:.1%}），标定可能异常",
+                    metrics=metrics,
+                    ranges=out_of_range[:50],
+                ))
+            else:
+                findings.append(self.finding(ctx, PASS, stream=stream.key,
+                                             metrics=metrics))
+
+        # 力基线漂移 —— 独立的信道，单独一轮
+        for stream in ctx.streams_of("force"):
+            forces = stream.series.get("force") or ()
+            if len(forces) < 20:
+                continue
+            magnitudes = []
+            for sample in forces:
+                if not sample:
+                    continue
+                try:
+                    magnitudes.append(_norm3(sample))
+                except (TypeError, ValueError):
+                    continue
+            if len(magnitudes) < 20:
+                continue
+
+            half = len(magnitudes) // 2
+            first, second = _median(magnitudes[:half]), _median(magnitudes[half:])
+            drift = abs(second - first)
+            metrics = {"baseline_first_half": round(first, 2),
+                       "baseline_second_half": round(second, 2),
+                       "drift_mN": round(drift, 2)}
+
+            if drift <= max_drift:
+                findings.append(self.finding(ctx, PASS, stream=stream.key,
+                                             metrics=metrics))
+                continue
+            findings.append(self.finding(
+                ctx, WARN, stream=stream.key,
+                message=f"force baseline drift {drift:.0f} mN"
+                        f"（前半 {first:.0f} → 后半 {second:.0f}），疑似传感器漂移",
+                metrics=metrics,
+            ))
+        return findings
+
+
+def _norm3(sample) -> float:
+    return math.sqrt(sum(float(value) ** 2 for value in sample[:3]))

processor/app/processing/cleaning/checks/umi/slam_continuity.py

@@ -0,0 +1,158 @@
+"""SLAM 轨迹连续性 —— 相邻位姿之间出现不可能的速度/角速度跳变。
+
+为什么重要
+----------
+UMI 的 action 是从 SLAM 位姿**差分**出来的（见 ``app/umi_slam_action.py``）。
+位姿一旦跳变，差分出来的动作就是一个巨大的假位移；模型会学到"突然瞬移"。
+官方也承认 ORB_SLAM3 是整条流水线"最脆弱的部分"。
+
+常见来源：视觉跟踪丢失后重定位、弱纹理/暗光、快速转手腕导致运动模糊。
+
+判定分两档（这正是本项的设计，不是"只报告不判定"）
+--------------------------------------------------
+方案明确警告：「SLAM 单帧跳了 113.9 毫米可以作为问题线索，但不能马上定成
+全平台红线」。113.9mm 来自本平台实测（`umi_slam_action.py` 的 docstring 记录了
+插值方案会横跨重定位跳变），它是**观测线索**不是阈值来源。
+
+所以**单次跳变只判 WARN** —— 一次重定位不该废掉一整集（实测
+UMIGripper_Action_AI_000001 就有一次真实的 6.8 m/s 跳变，属"该警告、不该拦"）。
+
+但跳变**达到 ``fail_jumps``（默认 10 处）判 FAIL**：那已经不是偶发重定位，而是
+SLAM 全程没跟住，差分出来的动作整段都是假的 —— 这种数据确实不能训，按"数据不对
+就拦回人工审核"处理。
+
+★ 本文件的旧注释曾写成"默认判 WARN 而非 FAIL……只报告"，与实现不符（实现一直
+  是分档的）。以本段为准。阈值本身仍须用人工确认过的好/坏数据校准后才固化。
+"""
+
+from __future__ import annotations
+
+import math
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, Range, PASS, WARN, FAIL,
+)
+from app.processing.cleaning.contract import pose_is_valid
+
+
+def _norm3(vector) -> float:
+    return math.sqrt(sum(float(value) ** 2 for value in vector[:3]))
+
+
+@register_check
+class UmiSlamContinuityCheck(CleaningCheck):
+    slug = "umi.slam_continuity"
+    label = "SLAM Trajectory Continuity"
+    version = "1.0"
+    description = "Impossible linear or angular velocity between adjacent poses"
+
+    requires_channels = ("slam",)
+
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+
+    device_cards = ("gripper_device",)
+
+    # 单位：米/秒、弧度/秒。人手快速挥动约 2 m/s、6 rad/s 量级，
+    # 这里给的是"明显超出人类可达"的起点值。
+    #
+    # 判级用两个计数阈值，而不是"速度超过多少倍"—— 后者在默认值下会退化成
+    # "任何一次跳变都判失败"（一次跳变就废掉一整集太重了）。实测 episode 1
+    # 帧 293 有一次 6.8 m/s 的真实重定位跳变，属"该警告、但不该直接拦"。
+    default_params = {
+        "max_linear_mps": 5.0,
+        "max_angular_rps": 20.0,
+        "warn_jumps": 1,      # 达到此数即警告
+        "fail_jumps": 10,     # 达到此数判失败（说明 SLAM 全程不稳）
+    }
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        max_linear = float(self.param(ctx, "max_linear_mps", 5.0))
+        max_angular = float(self.param(ctx, "max_angular_rps", 20.0))
+        fail_jumps = int(self.param(ctx, "fail_jumps", 10))
+
+        for stream in ctx.streams_of("slam"):
+            poses = stream.series.get("pose") or ()
+            stamps = stream.series.get("t") or ()
+            if len(poses) < 2:
+                continue
+            fps = float(stream.fps or ctx.fps or 30.0)
+            dt_default = 1.0 / fps if fps > 0 else 1.0 / 30.0
+
+            jumps: list[Range] = []
+            peak_linear = 0.0
+            peak_angular = 0.0
+
+            for index in range(1, len(poses)):
+                prev, cur = poses[index - 1], poses[index]
+                # ★ 必须用 pose_is_valid，不能只判长度。
+                #
+                # 全零占位位姿长度也是 7，能过 len 检查，但四元数模为 0 ——
+                # 两个零四元数点积为 0，acos(0)=π/2 ⇒ 夹角 180° ⇒ 每帧
+                # 94.25 rad/s。实测 Test94 的 slam_pose 有 437/599 行是全零，
+                # 于是 599 帧报出 465 处"跳变"，整集被假判 FAIL 并拦住批次。
+                if not pose_is_valid(prev) or not pose_is_valid(cur):
+                    continue
+                try:
+                    delta = [float(cur[i]) - float(prev[i]) for i in range(3)]
+                except (TypeError, ValueError):
+                    continue
+
+                # 时间间隔取真实时间戳；缺失时回落到 fps
+                dt = dt_default
+                if len(stamps) > index and stamps[index] and stamps[index - 1]:
+                    try:
+                        span = float(stamps[index]) - float(stamps[index - 1])
+                        if 0 < span < 1.0:      # 超过 1 秒说明中间丢了整段
+                            dt = span
+                    except (TypeError, ValueError):
+                        pass
+
+                linear = _norm3(delta) / dt
+                # 姿态差：四元数点积 → 夹角。|dot| 接近 1 表示几乎没转。
+                dot = sum(float(prev[3 + i]) * float(cur[3 + i]) for i in range(4))
+                angle = 2.0 * math.acos(max(-1.0, min(1.0, abs(dot))))
+                angular = angle / dt
+
+                peak_linear = max(peak_linear, linear)
+                peak_angular = max(peak_angular, angular)
+
+                if linear <= max_linear and angular <= max_angular:
+                    continue
+                jumps.append(Range(
+                    start_sec=index / fps, end_sec=(index + 1) / fps,
+                    code=self.slug, severity=WARN,
+                    stream=stream.key, channel="slam",
+                    start_frame=index - 1, end_frame=index,
+                    rule=self.slug,
+                    message=f"pose jump at frame {index}: "
+                            f"{_norm3(delta) * 1000:.1f}mm / {math.degrees(angle):.1f}°",
+                    evidence={"linear_mps": round(linear, 3),
+                              "angular_rps": round(angular, 3)},
+                ))
+
+            metrics = {
+                "frames": len(poses),
+                "jumps": len(jumps),
+                "peak_linear_mps": round(peak_linear, 3),
+                "peak_angular_rps": round(peak_angular, 3),
+            }
+            if not jumps:
+                findings.append(self.finding(ctx, PASS, stream=stream.key,
+                                             metrics=metrics))
+                continue
+
+            findings.append(self.finding(
+                ctx,
+                FAIL if len(jumps) >= fail_jumps else WARN,
+                stream=stream.key,
+                message=f"{len(jumps)} pose jumps, peak "
+                        f"{peak_linear:.1f} m/s / "
+                        f"{math.degrees(peak_angular):.0f} deg/s "
+                        f"(verify against the video)",
+                metrics=metrics,
+                ranges=jumps[:50],       # 报告里最多带 50 个，避免 JSON 过大
+            ))
+        return findings

processor/app/processing/cleaning/checks/umi/slam_coverage.py

@@ -0,0 +1,105 @@
+"""SLAM 位姿覆盖率 —— 多少帧的位姿是**插值补出来的**。
+
+★ 别把"自己格子为空"当成问题
+--------------------------------
+采集端的位姿流是 20/20/60ms **突发**，而数据帧是 1/30s 均匀网格。某个
+33ms 窗口里一个位姿都没到，这一格的缓冲就是空的 —— **这是设计使然**。
+
+实测（52 集训练集）：**28.2% 的帧自己格子为空**（p90 32.8%）。
+第一版检查项拿这个当指标，结果 52/52 集全部报警 —— 典型的阈值照搬。
+
+真正该关心的是：既没有本地样本、**相邻格子也没有**，只能靠插值硬补的帧。
+``poses_from_trajectory`` 汇总所有格子按时间取最近样本，实测能救回绝大多数
+空帧，只有剩下的才插值。
+
+实测（同上，4 集抽样）：
+    集 0: 插值  2/326 = 0.6%
+    集 1: 插值 17/313 = 5.4%   ← ★ 明显高于其他集
+    集 2: 插值  4/384 = 1.0%
+    集 7: 插值  0/308 = 0.0%
+
+★ 集 1 正是 ``umi.slam_continuity`` 报出 6.8 m/s 跳变的那一集 ——
+两个独立指标指向同一件事：那一集 SLAM 跟丢过。
+所以这两项要**一起看**：插值率高 + 有跳变 = 基本可以确定是跟踪丢失。
+
+判定口径
+--------
+默认 **WARN**：插值帧本身不代表数据不可用（插值的是平滑轨迹），
+它是"这段 SLAM 不稳"的信号。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN, FAIL,
+)
+
+
+@register_check
+class UmiSlamCoverageCheck(CleaningCheck):
+    slug = "umi.slam_coverage"
+    label = "SLAM Pose Coverage"
+    version = "2.0"
+    description = "Poses only recoverable by interpolation (no real sample in nearby slots)"
+
+    requires_channels = ("slam",)
+
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+
+    device_cards = ("gripper_device",)
+
+    # 实测正常集 0~1%，异常集 5.4%。起点值取 2% / 10%：
+    # 低于 2% 属正常抖动，超过 10% 说明这一段基本没有真实位姿。
+    # ★ 这两个数是拿 52 集训练集跑出来的，不是拍脑袋 —— 但样本只有 52 集，
+    #   上生产前应拿更多数据复核。
+    default_params = {
+        "warn_ratio": 0.02,
+        "fail_ratio": 0.10,
+    }
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        warn_ratio = float(self.param(ctx, "warn_ratio", 0.02))
+        fail_ratio = float(self.param(ctx, "fail_ratio", 0.10))
+
+        for stream in ctx.streams_of("slam"):
+            # evidence 提供两种粒度：
+            #   "interpolated" —— 逐帧布尔（本检查项用这个，能出区间）
+            #   "coverage"     —— 直接给汇总数字（{"frames","direct","interpolated"}）
+            flags = stream.series.get("interpolated")
+            summary = stream.series.get("coverage") or {}
+            if flags:
+                total = len(flags)
+                count = sum(1 for item in flags if item)
+            elif summary:
+                total = int(summary.get("frames") or 0)
+                count = int(summary.get("interpolated") or 0)
+            else:
+                continue
+            if not total:
+                continue
+            ratio = count / total
+
+            metrics = {
+                "frames": total,
+                "interpolated_frames": count,
+                "interpolated_ratio": round(ratio, 4),
+            }
+
+            if ratio < warn_ratio:
+                findings.append(self.finding(ctx, PASS, stream=stream.key,
+                                             metrics=metrics))
+                continue
+            findings.append(self.finding(
+                ctx,
+                FAIL if ratio >= fail_ratio else WARN,
+                stream=stream.key,
+                message=f"{count}/{total} poses ({ratio:.1%}) are interpolation-"
+                        f"only - no real sample in the local or neighbouring slots,"
+                        f" which suggests SLAM lost tracking (review together with"
+                        f" SLAM Trajectory Continuity)",
+                metrics=metrics,
+            ))
+        return findings

processor/app/processing/cleaning/checks/video/__init__.py

@@ -0,0 +1,5 @@
+"""视频类检查 —— 解码/黑屏/冻结/丢帧。
+
+本目录下一个 .py = 一个检查项（用 @register_check 注册）。
+新增检查项只需在此放文件，注册表会自动发现（见上级 __init__.py 的 walk_packages）。
+"""

processor/app/processing/cleaning/checks/video/black_screen.py

@@ -0,0 +1,86 @@
+"""黑屏 —— 镜头被挡、补光灯没开、或采集程序写了空帧。
+
+为什么重要
+----------
+黑屏段里的视觉信息为零。模型在这些帧上学到的是"画面全黑时该做什么"，
+通常是噪声；若黑屏占比高，还会把图像归一化统计量带偏。
+
+判定口径
+----------
+检测本身由 ``app/video_quality.py`` 完成（按灰度均值 + 暗像素占比双阈值）。
+本检查项只负责把它的区间翻成统一的 Finding/Range 并套用节点配置的阈值 ——
+**不重复实现检测算法**，避免两处口径漂移。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.contract import VIDEO_CAPABLE_MODALITIES
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, Range, PASS, WARN, FAIL,
+)
+
+
+@register_check
+class VideoBlackScreenCheck(CleaningCheck):
+    slug = "video.black_screen"
+    label = "Black Screen"
+    version = "1.0"
+    description = "Frame is fully or nearly black"
+
+    requires_channels = ("rgb",)
+
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+
+    device_cards = VIDEO_CAPABLE_MODALITIES
+
+    default_params = {"min_sec": 0.5, "fail_ratio": 0.05}
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        for stream in ctx.streams_of("rgb"):
+            report = stream.video or {}
+            ranges = report.get("black_ranges") or []
+            if not ranges:
+                continue
+
+            fps = float(report.get("fps") or stream.fps or ctx.fps or 30.0)
+            min_sec = float(self.param(ctx, "min_sec", 0.5))
+            converted: list[Range] = []
+            total_sec = 0.0
+            for item in ranges:
+                try:
+                    start, end = float(item[0]), float(item[1])
+                except (TypeError, ValueError, IndexError):
+                    continue
+                if end - start < min_sec:
+                    continue
+                total_sec += end - start
+                converted.append(Range(
+                    start_sec=start, end_sec=end,
+                    code=self.slug, severity=WARN,
+                    stream=stream.key, channel="rgb",
+                    start_frame=int(start * fps), end_frame=int(end * fps),
+                    rule=self.slug,
+                    message=f"black screen for {end - start:.1f}s",
+                ))
+
+            if not converted:
+                continue
+
+            duration = float(ctx.duration_sec or 0.0)
+            ratio = (total_sec / duration) if duration > 0 else 0.0
+            fail_ratio = float(self.param(ctx, "fail_ratio", 0.05))
+            status = FAIL if ratio >= fail_ratio else WARN
+
+            findings.append(self.finding(
+                ctx, status, stream=stream.key,
+                message=f"{len(converted)} black-screen stretches, {total_sec:.1f}s total"
+                        + (f"（占 {ratio:.1%}）" if duration else ""),
+                metrics={"segments": len(converted),
+                         "total_sec": round(total_sec, 3),
+                         "ratio": round(ratio, 4)},
+                ranges=converted,
+            ))
+        return findings

processor/app/processing/cleaning/checks/video/decode_error.py

@@ -0,0 +1,99 @@
+"""解码失败 / 文件打不开 —— 最硬的一类问题。
+
+为什么重要
+----------
+解码失败意味着这段视频在任何下游都无法使用：训练读取会抛异常、浏览器预览
+会黑屏、导出会失败。而且它常常是文件损坏的前兆 —— 与其等到训练时才发现，
+不如在入库后就标出来。
+
+严重度
+------
+本项默认 **FAIL**（其余视频检查默认 WARN）：能解码是"数据可用"的最低门槛，
+不存在"阈值调松就能接受"的余地。
+
+opencv 不可用是**环境问题不是数据问题** —— 判 ERROR（处理失败）而不是 FAIL，
+避免把环境缺依赖记成数据质量事故。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.contract import VIDEO_CAPABLE_MODALITIES
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, Range, PASS, FAIL, ERROR,
+)
+
+# 这些 reason 说明"没检查成"，不是"数据坏了"
+_ENV_REASONS = {"opencv_unavailable"}
+
+
+@register_check
+class VideoDecodeErrorCheck(CleaningCheck):
+    slug = "video.decode_error"
+    label = "Decode Errors"
+    version = "1.0"
+    description = "Video won't open, or contains undecodable frames"
+
+    requires_channels = ("rgb",)
+
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+
+    device_cards = VIDEO_CAPABLE_MODALITIES
+
+    default_params = {"max_errors": 0}
+    default_severity = FAIL
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        for stream in ctx.streams_of("rgb"):
+            report = stream.video or {}
+            if not report:
+                continue
+
+            reason = str(report.get("reason") or "")
+            if reason in _ENV_REASONS:
+                findings.append(self.finding(
+                    ctx, ERROR, stream=stream.key,
+                    message="OpenCV unavailable, could not check (environment issue, not a data issue)",
+                    metrics={"reason": reason},
+                ))
+                continue
+
+            # 整条流打不开 —— 比丢几帧严重得多
+            if reason in ("video_open_failed", "video_metadata_invalid"):
+                findings.append(self.finding(
+                    ctx, FAIL, stream=stream.key,
+                    message=f"video cannot be opened or has invalid metadata ({reason})",
+                    metrics={"reason": reason,
+                             "error": str(report.get("error") or "")[:200]},
+                ))
+                continue
+
+            count = int(report.get("decode_error_count") or 0)
+            max_errors = int(self.param(ctx, "max_errors", 0))
+            if count <= max_errors:
+                findings.append(self.finding(ctx, PASS, stream=stream.key,
+                                             metrics={"decode_error_count": count}))
+                continue
+
+            fps = float(report.get("fps") or stream.fps or ctx.fps or 30.0)
+            frames = [int(item) for item in (report.get("decode_errors") or [])
+                      if isinstance(item, (int, float))]
+            # 每个失败帧给一个零长度区间 —— 时间轴上就是一个可点击的红点
+            marks = tuple(
+                Range(start_sec=frame / fps, end_sec=frame / fps,
+                      code=self.slug, severity=FAIL,
+                      stream=stream.key, channel="rgb",
+                      start_frame=frame, end_frame=frame,
+                      rule=self.slug, message=f"frame {frame} failed to decode")
+                for frame in frames[:20]
+            )
+            findings.append(self.finding(
+                ctx, FAIL, stream=stream.key,
+                message=f"{count} frames failed to decode"
+                        + (f"（示例：{frames[:5]}）" if frames else ""),
+                metrics={"decode_error_count": count,
+                         "sample_frames": frames[:20]},
+                ranges=marks,
+            ))
+        return findings

processor/app/processing/cleaning/checks/video/frame_drop.py

@@ -0,0 +1,82 @@
+"""丢帧 / 帧数对齐 —— 视频帧数与 parquet 行数不一致。
+
+为什么重要
+----------
+两者不一致时，按帧号取动作会整体错位；漏帧则会让模型学到"同一帧对应两个
+动作"。真实的采集侧表现是视频比数据少几帧（编码器丢帧）或多几帧（尾部多录）。
+
+判定口径
+--------
+容差取 ``max(tolerance_min, data_rows × tolerance_ratio)``：
+小批次按绝对帧数兜底（默认 2 帧），大批次按比例（默认 0.5%）。
+超出容差 5 倍判 FAIL，否则 WARN —— 差几帧和差几百帧不是一回事。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.contract import VIDEO_CAPABLE_MODALITIES
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, PASS, WARN, FAIL,
+)
+
+
+@register_check
+class VideoFrameDropCheck(CleaningCheck):
+    slug = "video.frame_drop"
+    label = "Frame Drop / Count Alignment"
+    version = "1.0"
+    description = "Video frame count differs from data row count"
+
+    requires_channels = ("rgb",)
+
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+
+    device_cards = VIDEO_CAPABLE_MODALITIES
+
+    # 阈值默认值 —— 节点配置可覆盖。
+    # 方案要求「阈值不要照搬」：这是平台起点值，必须用人工确认过的好/坏数据验证。
+    default_params = {"tolerance_ratio": 0.005, "tolerance_min": 2}
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        for stream in ctx.streams_of("rgb"):
+            report = stream.video or {}
+            if not report:
+                continue
+            # 打不开/读不了元数据的流不算"丢帧问题"，交给 video.decode_error
+            if report.get("reason") in ("video_open_failed", "video_metadata_invalid"):
+                continue
+
+            video_frames = int(report.get("frame_count") or 0)
+            data_rows = int(stream.rows or ctx.data_rows or 0)
+            if not video_frames or not data_rows:
+                continue
+
+            diff = abs(video_frames - data_rows)
+            tolerance = max(
+                int(self.param(ctx, "tolerance_min", 2)),
+                int(data_rows * float(self.param(ctx, "tolerance_ratio", 0.005))),
+            )
+            metrics = {
+                "video_frames": video_frames,
+                "data_rows": data_rows,
+                "diff": diff,
+                "tolerance": tolerance,
+            }
+
+            if diff <= tolerance:
+                findings.append(self.finding(ctx, PASS, stream=stream.key,
+                                             metrics=metrics))
+                continue
+
+            findings.append(self.finding(
+                ctx,
+                FAIL if diff > tolerance * 5 else WARN,
+                stream=stream.key,
+                message=f"video has {video_frames} frames / data has {data_rows} rows"
+                        f"，差 {diff} 帧（容差 {tolerance}）",
+                metrics=metrics,
+            ))
+        return findings

processor/app/processing/cleaning/checks/video/freeze.py

@@ -0,0 +1,86 @@
+"""冻结 —— 画面连续多帧几乎不变。
+
+为什么重要
+----------
+冻结段通常是采集程序卡住、编码器 stall、或 USB 带宽不足导致丢帧后补重复帧。
+它和黑屏不同：画面是"正常的样子"，但时间已经不动了。模型会以为任务停滞。
+
+注意与"合理的静止"区分
+----------------------
+人拿着夹爪停在物体上方思考时，画面也接近静止。所以本项默认判 **WARN 而非
+FAIL**，并在 metrics 里带上每段时长供人工/AI 复核 —— 方案明确要求
+「阈值不要照搬」，静止多久算异常要按任务节奏定。
+"""
+
+from __future__ import annotations
+
+from app.processing.cleaning.contract import VIDEO_CAPABLE_MODALITIES
+from app.processing.cleaning.checks import (
+    CheckContext, CleaningCheck, register_check,
+    Finding, Range, WARN, FAIL,
+)
+
+
+@register_check
+class VideoFreezeCheck(CleaningCheck):
+    slug = "video.freeze"
+    label = "Frozen Frame"
+    version = "1.0"
+    description = "Frame nearly unchanged across consecutive frames"
+
+    requires_channels = ("rgb",)
+
+    # 属于哪些设备卡片 —— 前端设置面板按它分 tab
+
+    device_cards = VIDEO_CAPABLE_MODALITIES
+
+    default_params = {"min_sec": 2.0, "fail_sec": 10.0}
+    default_severity = WARN
+
+    def run(self, ctx: CheckContext) -> list[Finding]:
+        findings: list[Finding] = []
+        for stream in ctx.streams_of("rgb"):
+            report = stream.video or {}
+            ranges = report.get("freeze_ranges") or []
+            if not ranges:
+                continue
+
+            fps = float(report.get("fps") or stream.fps or ctx.fps or 30.0)
+            min_sec = float(self.param(ctx, "min_sec", 2.0))
+            fail_sec = float(self.param(ctx, "fail_sec", 10.0))
+
+            converted: list[Range] = []
+            longest = 0.0
+            worst_status = WARN
+            for item in ranges:
+                try:
+                    start, end = float(item[0]), float(item[1])
+                except (TypeError, ValueError, IndexError):
+                    continue
+                span = end - start
+                if span < min_sec:
+                    continue
+                longest = max(longest, span)
+                status = FAIL if span >= fail_sec else WARN
+                if status == FAIL:
+                    worst_status = FAIL
+                converted.append(Range(
+                    start_sec=start, end_sec=end,
+                    code=self.slug, severity=status,
+                    stream=stream.key, channel="rgb",
+                    start_frame=int(start * fps), end_frame=int(end * fps),
+                    rule=self.slug,
+                    message=f"frozen for {span:.1f}s",
+                ))
+
+            if not converted:
+                continue
+
+            findings.append(self.finding(
+                ctx, worst_status, stream=stream.key,
+                message=f"{len(converted)} frozen stretches, longest {longest:.1f}s",
+                metrics={"segments": len(converted),
+                         "longest_sec": round(longest, 3)},
+                ranges=converted,
+            ))
+        return findings

processor/app/processing/cleaning/collect.py

@@ -0,0 +1,647 @@
+"""证据采集 —— 从批次目录读出检查项需要的一切。
+
+检查项**不碰磁盘**（见 ``checks.CheckContext`` 的 IO 注入设计）。所有读取集中在
+这里，好处有两个：
+
+* 检查项本体是纯逻辑，测试喂假证据即可，不需要真 mp4 / parquet / cv2；
+* "读什么、怎么读"只有一处实现，不会出现两个检查项对同一列用不同口径。
+
+**本模块只读** —— 不写任何文件、不改任何数据。质检出结论，不出数据。
+"""
+
+from __future__ import annotations
+
+import glob
+import re
+from dataclasses import dataclass, field as dc_field
+from pathlib import Path
+from typing import Any, Iterable
+
+import numpy as np
+
+from app.processing.cleaning.checks import StreamEvidence
+from app.processing.cleaning.contract import (
+    pose_is_valid,
+    channels_for, normalize_device_modality,
+)
+
+# SLAM 列的命名：``observation.slam_*`` 是默认相机；双目/多把第二路存成
+# ``observation.<相机名>_slam_*``。这里按**相机**分组，每组里 trajectory 优先。
+#
+# 为什么不能写死两个列名：实测 Test94/episode_000003 **只有** gripper_2 前缀的
+# 两列，没有不带前缀的 —— 那种集有 SLAM 数据、却一个 SLAM 检查都不跑，且不报
+# 任何错。同一项目里不同集的列名不一致是常态（见 MODALITY_CHANNELS 的告诫）。
+#
+# 两个**不要**匹配进去的近亲：
+#   observation.slam_trajectory_ns            —— 时间戳伴生列，不是位姿
+#   processing.umi_slam_action.data_4.action  —— 处理缓存列，名字里恰好含 slam
+_SLAM_COLUMN_RE = re.compile(r"^observation\.(?:(.+)_)?slam_(trajectory|pose)$")
+
+# 列名 → 信道。值为**可能的列名**（含历史名）。同一信道的每个存在的列都会
+# 登记成一条流（左右两路力就是两条），流名取列名最后一段。
+#
+# ★ 这里**不能**用 `break` 只取第一个 —— 那样左右两路力只剩一路。
+#   要与别名列去重的话看 ``_COLUMN_ALIASES``，别在这里提前退出。
+#
+# slam 不在下表里 —— 它按相机分组解析，见 ``_slam_columns``。
+_COLUMN_CHANNELS: dict[str, tuple[str, ...]] = {
+    "slam": (
+        "observation.slam_trajectory",   # 高频样本缓冲（优先）
+        "observation.slam_pose",         # 低频快照（旧批才有）
+    ),
+    "gripper_state": ("observation.gripper_state",),
+    "force": (
+        "observation.gripper_left_force",
+        "observation.gripper_right_force",
+        "observation.gripper_force",
+    ),
+    "tactile": (
+        "observation.left_glove",
+        "observation.right_glove",
+        "observation.glove",
+    ),
+    "device_status": (
+        "status.left_glove",
+        "status.right_glove",
+        "status.glove",
+    ),
+    "depth": ("observation.images.depth",),
+    "action": ("action",),
+}
+
+# 别名列 → 协议列名。**同一份数据的第二套命名**，不新增信道，只是改名。
+#
+# 触觉数据有两套名字：
+#   采集协议写  observation.left_glove / right_glove
+#   导出时统一成 observation.tactile.left / right
+#   （见 lerobot_export._TACTILE_RENAME，hdf5_export / ai_annotation 读的是后者）
+#
+# 原始 session 目录里两套可能同时在（导出产物被合并回 canonical）；而**只跑过
+# 导出的树里只有后者**。此前只认协议名 —— 那种树上手套信道直接为空，所有手套
+# 检查静默跳过，不报任何错。
+_COLUMN_ALIASES: dict[str, str] = {
+    "observation.tactile.left": "observation.left_glove",
+    "observation.tactile.right": "observation.right_glove",
+}
+
+# 各信道的向量宽度 —— 用于把列值切成定长元组。
+#
+# ★ 不在表里的信道**不截断**（见 ``vector_series``）。默认截断到某个数字是
+#   危险的：触觉阵列是 16×16=256 维，此前因为这里没有 ``tactile`` 项而落到
+#   3 的兜底值，256 个感应点被静默截成 3 个 —— 检查项只看得到 1% 的阵列。
+#   换手套（或加新阵列通道）时同样会静默丢数据，所以默认必须是"不截断"。
+_CHANNEL_WIDTH: dict[str, int] = {
+    "gripper_state": 3,
+    "force": 3,
+    "action": 7,
+}
+
+
+def _apply_column_aliases(frame):
+    """把别名列归一成协议列名。
+
+    **只在协议名缺失时改** —— 两套都在时保留协议名：它们是同一份数据，
+    登记成两条流会让同一处缺陷被报两次，也让"左右手"的流名对不上。
+    （实测 S80C / D435 两套都在时逐元素完全相同。）
+    """
+    rename = {alias: canonical for alias, canonical in _COLUMN_ALIASES.items()
+              if alias in frame.columns and canonical not in frame.columns}
+    return frame.rename(columns=rename) if rename else frame
+
+_DEFAULT_FPS = 30.0
+_MAX_VIDEO_PROBES = 4
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """一个 episode 的全部证据 —— engine 交给检查项的那一份。"""
+
+    batch_dir: Path
+    streams: tuple[StreamEvidence, ...] = ()
+    channels: frozenset[str] = frozenset()
+    modalities: tuple[str, ...] = ()
+    fps: float = _DEFAULT_FPS
+    rows: int = 0
+    columns: tuple[str, ...] = ()
+    parquet: str = ""
+    notes: dict[str, Any] = dc_field(default_factory=dict)
+
+    @property
+    def duration_sec(self) -> float:
+        return (self.rows / self.fps) if self.fps else 0.0
+
+
+# ── 读文件 ────────────────────────────────────────────────────
+
+def _glob(pattern: str, root: Path) -> list[Path]:
+    return [Path(item) for item in sorted(glob.glob(str(root / pattern)))]
+
+
+def _file_holding(parquets: list[Path], episode_index: int) -> Path | None:
+    """哪个文件里装着这一集 —— 只读 ``episode_index`` 一列，不整份加载。
+
+    文件名对不上时的兜底（历史命名、手工搬过的目录）。返回 None 表示都没有。
+    """
+    import pyarrow.parquet as pq
+
+    for path in parquets:
+        try:
+            column = pq.ParquetFile(path).read(columns=["episode_index"])
+        except Exception:
+            continue
+        values = column.column("episode_index").to_pylist()
+        if episode_index in values:
+            return path
+    return None
+
+
+def resolve_episode_data(batch_dir: Path,
+                         episode_index: int | None = None) -> tuple[Path | None, bool]:
+    """定位这一集的数据文件。返回 ``(parquet, 还要不要按行过滤)``。
+
+    两种布局的粒度**不一样**，混了就会读出空帧：
+
+      canonical ``data/chunk-*/episode_NNNNNN.parquet`` —— 一集一文件。
+        选对**文件**即可，行全是这一集的。
+      导出产物 ``data/chunk-*/file-NNN.parquet`` —— 一文件多集，
+        必须再按 ``episode_index`` 列筛行。
+
+    ★ 这里曾经是「取 ``parquets[0]`` 再按列过滤」。canonical 布局下第 0 个文件
+      只装第 0 集，于是传任何**别的** ``episode_index`` 都筛出空帧 —— 不报错，
+      只是报告变成 ``empty_report``（``episode.status = ERROR``）。在"数据不对
+      就拦回人工审核"的链路里，表现是**除第 0 集外每一集都被卡住**。
+    """
+    root = Path(batch_dir)
+
+    canonical = _glob("data/chunk-*/episode_*.parquet", root)
+    if canonical:
+        if episode_index is None:
+            return canonical[0], False
+        # 文件名就是集号（LeRobot canonical 约定，注意编号可能有空洞）
+        wanted = f"episode_{int(episode_index):06d}.parquet"
+        for path in canonical:
+            if path.name == wanted:
+                return path, False
+        # 文件名对不上 —— 按列找，别静默返回空
+        return _file_holding(canonical, int(episode_index)), False
+
+    multi = _glob("data/chunk-*/*.parquet", root)
+    if not multi:
+        return None, False
+    if episode_index is None:
+        return multi[0], False
+    return _file_holding(multi, int(episode_index)), True
+
+
+def load_rows(parquet: Path, filter_episode_index: int | None = None):
+    """读 parquet；给了 ``filter_episode_index`` 就只取那一集的行。
+
+    只在**一文件多集**的布局下才该传它 —— canonical 的一集一文件布局下传了会
+    把这一集自己的行全筛掉。用 ``resolve_episode_data`` 拿到的第二个返回值决定。
+    """
+    import pyarrow.parquet as pq
+
+    frame = pq.ParquetFile(parquet).read().to_pandas()
+    if filter_episode_index is not None and "episode_index" in frame.columns:
+        frame = frame[frame["episode_index"].values == filter_episode_index]
+    return frame.reset_index(drop=True)
+
+
+# ── 列 → 序列 ─────────────────────────────────────────────────
+
+def slam_valid_counts(values) -> tuple[int, ...]:
+    """每帧的有效位姿样本数 —— 空帧即为 0。
+
+    slam_trajectory 是扁平的 ``[t,x,y,z,qx,qy,qz,qw]×N``。导出产物会把它补齐到
+    定长（补 NaN），所以"有效"= 非 NaN 的 8 元组个数。
+    """
+    counts: list[int] = []
+    for item in values:
+        if item is None:
+            counts.append(0)
+            continue
+        array = np.asarray(item, dtype=float).ravel()
+        valid = 0
+        for index in range(array.size // 8):
+            if np.isfinite(array[index * 8:index * 8 + 8]).all():
+                valid += 1
+        counts.append(valid)
+    return tuple(counts)
+
+
+def slam_poses(values, counts) -> tuple[tuple, ...]:
+    """逐帧取【第一个有效样本】的位姿（位置 + 四元数）。
+
+    ★ 刻意不重用 ``umi_slam_action.poses_from_trajectory`` 的插值重建 ——
+    那是生产口径（含时间基拟合与插值）。连续性检查要看的是**原始落盘数据**
+    有没有跳变；用插值后的平滑轨迹会掩盖真实跳变���
+    """
+    poses: list[tuple] = []
+    for item, count in zip(values, counts):
+        if not count:
+            poses.append(())
+            continue
+        array = np.asarray(item, dtype=float).ravel()
+        poses.append(tuple(float(v) for v in array[1:8]))
+    return tuple(poses)
+
+
+def _slam_columns(columns) -> list[str]:
+    """按**相机**挑出 SLAM 列，每个相机一个：trajectory 优先，回落到 pose。
+
+    相机名 = ``observation.`` 与 ``_slam_`` 之间那段，默认相机没有前缀：
+
+        observation.slam_trajectory           → 相机 ""
+        observation.gripper_2_slam_trajectory → 相机 "gripper_2"
+
+    每个相机只取一个 —— trajectory 是高频样本缓冲、pose 是低频快照，
+    两个都有时用前者（与旧行为一致，只是现在**每个相机各自**取一个，
+    而不是全局只取一个）。
+    """
+    by_camera: dict[str, dict[str, str]] = {}
+    for column in sorted(str(name) for name in columns):
+        match = _SLAM_COLUMN_RE.match(column)
+        if not match:
+            continue
+        camera, kind = match.group(1) or "", match.group(2)
+        by_camera.setdefault(camera, {})[kind] = column
+
+    picked: list[str] = []
+    for camera in sorted(by_camera):
+        kinds = by_camera[camera]
+        picked.append(kinds.get("trajectory") or kinds["pose"])
+    return picked
+
+
+def _column_series(values, channel: str, width: int | None = None) -> tuple:
+    """一列 → 序列。**字符串列原样保留，不试着数值化。**
+
+    ``vector_series`` 对字符串会走 ``np.asarray(..., dtype=float)`` 抛
+    ``ValueError``，被 ``except`` 吞掉后**每帧都变成空元组** —— 检查项拿到的是
+    "这一列没有数据"，看起来像"检查通过"。设备状态列（``status.left_glove``）
+    正是字符串，所以这里必须先分流。
+    """
+    if len(values) and isinstance(values.iloc[0], str):
+        return tuple("" if item is None else str(item) for item in values)
+    if width is None:
+        width = _CHANNEL_WIDTH.get(channel)
+    return vector_series(values.tolist(), width)
+
+
+def vector_series(values, width: int | None = None) -> tuple[tuple, ...]:
+    """把一列向量值转成元组序列；空/坏的写成空元组。
+
+    ``width=None``（默认）**不截断**。截断是静默的 —— 调用方只有显式声明了
+    正确宽度时才该发生（如 action 固定 7 维）；未知列宽一律保留整条，
+    免得"少了一半感应点"这种问题要等到训练效果不对才发现。
+    """
+    out: list[tuple] = []
+    for item in values:
+        if item is None:
+            out.append(())
+            continue
+        try:
+            array = np.asarray(item, dtype=float).ravel()
+            if width is not None:
+                array = array[:width]
+            out.append(tuple(float(v) for v in array))
+        except (TypeError, ValueError):
+            out.append(())
+    return tuple(out)
+
+
+def _video_files(video_dir: Path) -> list[Path]:
+    """列出视频目录下的 mp4（按名字排序，稳定可预期）。"""
+    root = Path(video_dir)
+    if not root.is_dir():
+        return []
+    return sorted(path for path in root.rglob("*.mp4") if path.is_file())
+
+
+def videos_for_episode(root: Path, episode_index: int | None) -> list[Path]:
+    """**这一集自己的**视频文件。取不到就返回空 —— 绝不猜。
+
+    ★ 不能"把 videos/ 下的 mp4 都拿来用"：v3.0 导出把 52 集的视频全放在
+    ``videos/chunk-000/<流名>/file-NNN.mp4`` 同一个目录里，随便取几个会拿
+    别的集的画面去比对这一集的数据行数，得出荒谬的丢帧结论（实测出现过
+    "视频 9164 帧 / 数据 819 行"）。
+
+    两种布局各有映射来源:
+      * canonical —— ``videos/<流名>/chunk-XXX/episode_XXXXXX.mp4``，
+        目录本身就对应这一集；有 ``project_dataset.episode_files`` 时用它。
+      * 导出产物 —— ``meta/episodes`` 里逐流记着 ``chunk_index``/``file_index``。
+    """
+    root = Path(root)
+    if episode_index is None:
+        # 一集一文件的布局：videos/ 下就是这一集的全部视频
+        return _video_files(root / "videos")
+
+    # canonical：走既有索引
+    try:
+        from app.project_dataset import episode_files
+        entry = episode_files(root, episode_index) or {}
+        found: list[Path] = []
+        for item in entry.get("videos") or []:
+            # episode_files 返回 (source_key, path) 的形式
+            path = item[1] if isinstance(item, (tuple, list)) and len(item) > 1 else item
+            candidate = Path(path)
+            if candidate.is_file():
+                found.append(candidate)
+        if found:
+            return found
+    except Exception:
+        pass
+
+    # 导出产物：查 meta/episodes 的逐流索引
+    return _videos_from_episode_meta(root, episode_index)
+
+
+def _videos_from_episode_meta(root: Path, episode_index: int) -> list[Path]:
+    """从 ``meta/episodes`` 的逐流 chunk/file index 拼出视频路径。"""
+    import pyarrow.parquet as pq
+
+    for path in sorted(glob.glob(str(root / "meta" / "episodes" / "**" / "*.parquet"),
+                                 recursive=True)):
+        try:
+            frame = pq.ParquetFile(path).read().to_pandas()
+        except Exception:
+            continue
+        if "episode_index" not in frame.columns:
+            continue
+        rows = frame[frame["episode_index"].values == episode_index]
+        if rows.empty:
+            continue
+
+        # 列名形如 videos/<流名>/chunk_index 与 videos/<流名>/file_index
+        columns = {str(name) for name in frame.columns}
+        streams = sorted({
+            name[len("videos/"):-len("/chunk_index")]
+            for name in columns
+            if name.startswith("videos/") and name.endswith("/chunk_index")
+        })
+        row = rows.iloc[0]
+        found: list[Path] = []
+        for stream in streams:
+            try:
+                chunk = int(row[f"videos/{stream}/chunk_index"])
+                file_index = int(row[f"videos/{stream}/file_index"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            candidate = (root / "videos" / f"chunk-{chunk:03d}" / stream
+                         / f"file-{file_index:03d}.mp4")
+            if candidate.is_file():
+                found.append(candidate)
+        if found:
+            return found
+    return []
+
+
+def _is_depth_key(name: str) -> bool:
+    """这个流名是不是纯深度流。
+
+    复用 ``lerobot_v21.is_depth_source`` —— 深度口径在这个仓库里有好几处实现
+    （``device_naming.is_depth_only_key`` 是同一套），但权威定义在那儿。
+    导入失败时回落到保守判断：名字含 depth 且不含 rgb/color。
+    """
+    try:
+        from app.lerobot_v21 import is_depth_source
+        return bool(is_depth_source(name))
+    except Exception:
+        low = str(name or "").lower()
+        return "depth" in low and not any(
+            token in low for token in ("rgb", "color", "video"))
+
+
+# ── 主入口 ────────────────────────────────────────────────────
+
+def gather_evidence(batch_dir: Path, *,
+                    episode_index: int | None = None,
+                    probe_video: bool = False,
+                    modality_hint: str | Iterable[str] | None = None) -> Evidence:
+    """读一个 episode 的全部证据。
+
+    ``probe_video=False``（默认）只读 parquet，毫秒级；视频检查要解码抽样，
+    一集几秒到几十秒，按需开。
+
+    ``modality_hint`` 用于告诉采集层"这台设备是什么"（来自工作流连线的设备
+    卡片）。**可以是多个** —— 一个质检节点上游同时连相机和夹爪时就有多个。
+    给不出时按数据特征推断；两个来源取并集，理由见 ``_detect_modalities``。
+
+    ★ ``batch_dir`` 必须是**单个 episode 的目录**，且 ``episode_index`` 必须
+      与它匹配。``localstore.get_episode()`` 返回的 ``path`` 是**项目目录**
+      （几十集共享），直接传进来会拿第 0 集的 parquet 去比全部集的视频
+      —— 实测过，会得出"视频 9164 帧 / 数据 819 行"。见 ``videos_for_episode``。
+    """
+    root = Path(batch_dir)
+    parquet, filter_rows = resolve_episode_data(root, episode_index)
+    if parquet is None:
+        return Evidence(batch_dir=root, notes={"reason": "no_parquet"})
+
+    # ★ 按行过滤只在"一文件多集"的布局下做。canonical 是一集一文件，文件已经
+    #   选对了，再按 episode_index 列筛会把这一集自己的行全筛空 —— 结果是不报
+    #   任何错的 empty_report。见 resolve_episode_data。
+    frame = load_rows(parquet, episode_index if filter_rows else None)
+    if frame.empty:
+        return Evidence(batch_dir=root, parquet=str(parquet.relative_to(root)),
+                        notes={"reason": "empty_episode"})
+
+    # 别名列先归一成协议名，再算 columns —— 必须在下面所有列名判断之前，
+    # 否则 observation.tactile.* 会被当成"这列不存在"
+    frame = _apply_column_aliases(frame)
+    columns = {str(name) for name in frame.columns}
+    fps = _detect_fps(root)
+    rows = len(frame)
+    streams: list[StreamEvidence] = []
+    channels: set[str] = {"time"}
+
+    def _relative(path: Path) -> str:
+        try:
+            return str(path.relative_to(root))
+        except ValueError:
+            return str(path)
+
+    # SLAM —— **每个相机一路**，各取 trajectory 优先（见 _slam_columns）。
+    # 这里曾经是 `break`：全局只登记一路，双目集第二路的 SLAM 从来没被采集过。
+    for column in _slam_columns(columns):
+        values = frame[column].tolist()
+        series: dict[str, Any] = {}
+        if column.endswith("trajectory"):
+            counts = slam_valid_counts(values)
+            series["valid_count"] = counts
+            series["pose"] = slam_poses(values, counts)
+            # 覆盖率必须走生产口径 —— "插值帧"的定义就是 poses_from_trajectory
+            # 里本地与相邻格子都够不到的那些，只读原始数据推不出来。
+            try:
+                from app.umi_slam_action import poses_from_trajectory
+                stamps = (frame["timestamp"].to_numpy(dtype=float)
+                          if "timestamp" in columns
+                          else np.arange(rows) / fps)
+                diag: dict[str, Any] = {}
+                poses_from_trajectory(values, stamps, rows, diagnostics=diag)
+                series["coverage"] = diag
+            except Exception as exc:
+                series["coverage_error"] = str(exc)[:200]
+        else:
+            poses = vector_series(values, 7)
+            series["valid_count"] = tuple(
+                1 if pose_is_valid(item) else 0 for item in poses)
+            series["pose"] = poses
+        # 流名取列名最后一段 —— 多相机时是 "gripper_2_slam_trajectory"，
+        # 单相机时是 "slam_trajectory"，两条流不会撞名。
+        streams.append(StreamEvidence(
+            key=column.rsplit(".", 1)[-1],
+            channel="slam", path=_relative(parquet),
+            columns=(column,), rows=rows, fps=fps, series=series,
+        ))
+        channels.add("slam")
+
+    # 其余标量/向量列
+    #
+    # ★ series 的键一律用【信道名】。检查项按信道取序列（``series["force"]``），
+    #   如果这里用列名（``series["gripper_left_force"]``），检查项就静默地取不到
+    #   数据、全部判通过 —— 而且不报任何错。左右两路力共用 ``force`` 键，
+    #   靠 stream.key 区分。
+    for channel, candidates in _COLUMN_CHANNELS.items():
+        if channel == "slam":
+            continue
+        for column in candidates:
+            if column not in columns:
+                continue
+            streams.append(StreamEvidence(
+                key=column.rsplit(".", 1)[-1], channel=channel,
+                path=_relative(parquet), columns=(column,), rows=rows, fps=fps,
+                # 走 _column_series：宽度取不到就**不截断**（兜底成某个数字会
+                # 静默丢数据），字符串列原样保留（数值化会变成全空元组）
+                series={channel: _column_series(frame[column], channel)},
+            ))
+            channels.add(channel)
+
+    # 视频 —— ★ 无论检不检查，都要登记成一条流。
+    #
+    # 只登记不检查时 ``video`` 是空 dict（视频检查项会自行跳过），但信道
+    # ``rgb`` 必须出现 —— 否则报告会写成"未采集 rgb"，而实际上视频就在那儿，
+    # 只是这一轮没去解码。那会让"训练用途"给出错误的结论。
+    video_root = root / "videos"
+    for path in videos_for_episode(root, episode_index)[:_MAX_VIDEO_PROBES]:
+        report: dict[str, Any] = {}
+        if probe_video:
+            try:
+                from app.video_quality import _check_stream
+                report = _check_stream(path, rows, fps)
+            except Exception as exc:
+                report = {"passed": False, "reason": "video_check_failed",
+                          "error": str(exc)[:200]}
+        # 流名 = 流名目录那一层（observation.images.xxx），**不是** chunk-XXX。
+        # 两种布局的层级顺序相反，所以不能写死取第几段：
+        #   canonical/v2.1  videos/<流名>/chunk-000/episode_000000.mp4
+        #   v3.0            videos/chunk-000/<流名>/file-000.mp4
+        # 取"路径里第一个不是 chunk-* 的目录段"，两边都成立。
+        # 写错的话所有视频流会同名（都叫 chunk-000），报告分不清哪路相机，
+        # 且下游按 stream 去重时会互相覆盖。
+        try:
+            relative = str(path.relative_to(root))
+            segments = path.relative_to(video_root).parts[:-1]   # 去掉文件名
+            key = next((seg for seg in segments
+                        if not seg.startswith("chunk-")), path.stem)
+        except ValueError:
+            relative, key = str(path), path.stem
+
+        # ★ 深度流不能算作 rgb 信道。之前一律按 rgb 登记，结果 D435 项目的
+        # 深度视频引出了"视频 9164 帧 / 数据 819 行"这种荒谬的丢帧结论 ——
+        # 那是拿深度流跟 rgb 数据行数比。判定复用 lerobot_v21 的既有口径，
+        # 不另起一套字符串匹配。
+        channel = "depth" if _is_depth_key(key) else "rgb"
+        streams.append(StreamEvidence(
+            key=key, channel=channel, path=relative,
+            rows=rows, fps=fps, video=report,
+        ))
+        channels.add(channel)
+
+    modalities = _detect_modalities(channels, modality_hint)
+    return Evidence(
+        batch_dir=root, streams=tuple(streams), channels=frozenset(channels),
+        modalities=modalities, fps=fps, rows=rows,
+        columns=tuple(sorted(columns)), parquet=_relative(parquet),
+    )
+
+
+def _detect_fps(root: Path) -> float:
+    """从 meta/info.json 取 fps；拿不到就用默认 30。"""
+    import json
+
+    for relative in ("meta/info.json", "info.json"):
+        candidate = root / relative
+        if not candidate.is_file():
+            continue
+        try:
+            data = json.loads(candidate.read_text(encoding="utf-8"))
+            value = float(data.get("fps") or 0)
+            if 0 < value < 1000:
+                return value
+        except Exception:
+            continue
+    return _DEFAULT_FPS
+
+
+def hint_values(hint: str | Iterable[str] | None) -> list[str]:
+    """把 hint 归一成字符串列表 —— 调用方有单数（旧调用）也有复数（工作流连线）。"""
+    if hint is None:
+        return []
+    if isinstance(hint, str):
+        return [hint] if hint.strip() else []
+    try:
+        return [str(item) for item in hint]
+    except TypeError:
+        return [str(hint)]
+
+
+def _infer_modalities(channels: set[str]) -> list[str]:
+    """只看数据特征能推断出什么。
+
+    ★ 永远给不出 ``stereo_rgb`` / ``stereo_rgbd_camera`` —— "立体"不是列名里
+      能看见的特征。这两个模态**只能**由工作流连线给出。所以它们是
+      ``_detect_modalities`` 取并集、而不是二选一的主要理由。
+    """
+    if "slam" in channels or "gripper_state" in channels:
+        return ["gripper_device"]
+    if "tactile" in channels:
+        return ["glove_sensor"]
+    if "depth" in channels:
+        return ["rgbd_camera"]
+    if "rgb" in channels:
+        return ["mono_rgb"]
+    return []
+
+
+def _detect_modalities(channels: set[str],
+                       hint: str | Iterable[str] | None) -> tuple[str, ...]:
+    """这台设备是什么 —— hint（工作流连线）与数据特征取**并集**。
+
+    两个来源各有各的盲区，缺一个都会让检查静默不跑：
+
+      只有 hint  → 按数据模态声明的检查项不跑（将来接 ``depth.*`` 时，
+                   D435 数据在但模态被写成 stereo_rgb 就查不到）
+      只有推断   → 工作流里那张卡片的 tab 键查不到，**用户在设置面板里配的
+                   阈值被静默忽略、一律走默认值**（推断不出 stereo_*）
+
+    并集对"配置查找"和"检查项筛除"都更宽 —— 而本项目反复踩的坑恰恰是
+    "检查项静默不跑"，所以宁可宽。
+
+    hint 在前：``engine.resolve_config`` 按这个顺序合并各设备卡片的配置，
+    "先出现的优先"，工作流连线的顺序才是用户预期的顺序。
+    """
+    from app.processing.cleaning.contract import DEVICE_MODALITIES
+
+    ordered: dict[str, None] = {}
+    for raw in hint_values(hint):
+        canonical = normalize_device_modality(raw)
+        if canonical in DEVICE_MODALITIES:
+            ordered.setdefault(canonical, None)
+    for modality in _infer_modalities(channels):
+        ordered.setdefault(modality, None)
+    return tuple(ordered)
+
+
+def channels_from_modalities(modalities) -> tuple[str, ...]:
+    """设备模态 → 该设备可能提供的信道（转调 contract，供 engine 用）。"""
+    return channels_for(modalities)

processor/app/processing/cleaning/contract.py

@@ -0,0 +1,274 @@
+"""清洗契约 —— 模态、信道、严重度的公共定义。
+
+这个文件把"平台里同一个东西有好几个名字"这件事收敛到一处:
+
+    device_naming.DEVICE_LABELS        mono_rgb / stereo_rgb / ...
+    workflow_dispatch.semantic_type    同上（同一套值，只是没人敢这么说）
+    api/projects._device_input_sources mono_camera / stereo_camera  ← 名字不一样
+    处理模块 slug                       mono_camera / stereo_camera
+
+**本模块不新建第 7 套枚举** —— DEVICE_MODALITIES 就是 device_naming 那 6 个值的
+权威声明，其余几套通过 ``normalize_device_modality()`` 单向映射进来。新增设备类型时
+只需改这一处，测试会锁住映射完整性。
+
+信道(channel) 是比设备模态更细的粒度: PDF 里"IMU 可选""SLAM 必须"这类判断
+是**信道级**的，硬塞进设备模态会毁掉它。所以设备模态 → 信道的推导放在这里。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field as dc_field
+from typing import Any, Iterable
+
+# ── 设备模态 ──────────────────────────────────────────────────
+# 与 app/device_naming.py:15 DEVICE_LABELS 的键**逐字一致**。
+# 改这里必须同步改那里，tests/test_cleaning_contract.py 会断言两边相等。
+DEVICE_MODALITIES: tuple[str, ...] = (
+    "mono_rgb",
+    "stereo_rgb",
+    "rgbd_camera",
+    "stereo_rgbd_camera",
+    "glove_sensor",
+    "gripper_device",
+)
+
+# 「摄像机类」模态 —— 判定 collection_type 时要用
+CAMERA_MODALITIES: frozenset[str] = frozenset({
+    "mono_rgb", "stereo_rgb", "rgbd_camera", "stereo_rgbd_camera",
+})
+
+# 会产出 RGB 视频的**全部**设备卡片 —— ``video.*`` 类检查适用于它们每一个。
+# 比 CAMERA_MODALITIES 多一个 gripper_device：UMI 夹爪自带鱼眼相机，
+# 视频检查对同样它成立。
+VIDEO_CAPABLE_MODALITIES: tuple[str, ...] = (
+    "mono_rgb", "stereo_rgb", "rgbd_camera", "stereo_rgbd_camera",
+    "gripper_device",
+)
+
+# ── 信道 ──────────────────────────────────────────────────────
+# 检查项按信道声明需求，而不是按设备模态 —— 这样一条"SLAM 连续性"检查
+# 既能被 UMI 夹爪触发，将来也能被别的带 SLAM 的设备复用。
+CHANNELS: tuple[str, ...] = (
+    "time",           # 时间戳 / 帧号
+    "rgb",            # RGB 视频
+    "depth",          # 深度
+    "slam",           # SLAM 位姿/轨迹
+    "gripper_state",  # 夹爪开合
+    "force",          # 力 / 触觉（夹爪力）
+    "tactile",        # 触觉阵列（手套）
+    "imu",            # 惯性单元
+    "keypoints",      # 手部关键点
+    "action",         # 动作（派生列）
+    # 设备的连接状态（``status.left_glove`` 这类**字符串**列）。
+    # 单独算一个信道而不是塞进 tactile 的 series：它是"设备这一帧在不在"，
+    # 与阵列读数正交 —— 手套掉线时阵列会静默保持最后一个值，看起来完全正常。
+    "device_status",
+)
+
+# 设备模态 → 该设备**可能**提供的信道。
+# 注意这是"可能"不是"必然" —— 实际有哪些信道由 collect.py 从真实列名推导，
+# 这里只用来回答"这个模态需不需要某类检查"。
+MODALITY_CHANNELS: dict[str, tuple[str, ...]] = {
+    "mono_rgb":           ("rgb", "time"),
+    "stereo_rgb":         ("rgb", "time"),
+    "rgbd_camera":        ("rgb", "depth", "time"),
+    "stereo_rgbd_camera": ("rgb", "depth", "time"),
+    "glove_sensor":       ("tactile", "device_status", "imu", "time"),
+    "gripper_device":     ("rgb", "slam", "gripper_state", "force", "action", "time"),
+}
+
+# 非设备来源的信道 —— 由处理节点产出，不属于任何输入设备
+DERIVED_CHANNELS: frozenset[str] = frozenset({"keypoints", "action"})
+
+
+def channels_for(modalities: Iterable[str]) -> tuple[str, ...]:
+    """一组设备模态覆盖的全部信道（去重、保序）。纯函数。"""
+    seen: dict[str, None] = {}
+    for modality in modalities:
+        for channel in MODALITY_CHANNELS.get(str(modality), ()):
+            seen.setdefault(channel, None)
+    return tuple(seen)
+
+
+def pose_is_valid(item) -> bool:
+    """位姿能不能用 —— 空元组和**全零占位**都不算。
+
+    ★ 全零占位长得像合法位姿：长度 7、能索引、能相减。但它的四元数模是 0，
+      任何涉及它的差分都会算出"瞬移"：
+
+          两个零四元数的点积 = 0 → acos(0) = π/2 → 夹角 180°
+
+      30fps 下就是 180°×30 = **94.25 rad/s** —— 一个物理上荒谬的角速度。
+      实测 Test94 的 ``observation.slam_pose`` 有 437/599 行是全零，SLAM 连续性
+      因此报出 465 处"跳变"（599 帧里几乎每一帧），把整集假判成 FAIL 并拦住批次。
+
+    判据只看四元数模：**位置可以合法地是 (0,0,0)**（原点就是合法位姿），
+    四元数模为 0 则一定不是合法朝向。
+
+    放在 contract 而不是 collect：检查项要用它，而 collect 依赖 checks
+    （检查项自动发现），collect ← checks 的导入会成环。
+    """
+    if not item or len(item) < 7:
+        return False
+    try:
+        return sum(float(value) ** 2 for value in item[3:7]) > 1e-12
+    except (TypeError, ValueError):
+        return False
+
+
+def normalize_device_modality(value: object) -> str | None:
+    """把别处的设备/输入类型名映射到 canonical 设备模态。
+
+    覆盖两套现存命名:
+      * ``stereo_camera`` / ``mono_camera``（api/projects、processing 模块 slug）
+      * ``fisheye_camera`` / ``rgb_camera``（历史工作流节点类型）
+    认不出来返回 ``None``（调用方应跳过该值，而不是终止）。
+    """
+    text = str(value or "").strip()
+    if not text:
+        return None
+    if text in DEVICE_MODALITIES:
+        return text
+    return _ALIASES.get(text)
+
+
+# 别名表 —— 只列真实存在于代码里的历史/并行命名。
+# 新增别名时同步加进 tests/test_cleaning_contract.py 的用例。
+_ALIASES: dict[str, str] = {
+    # api/projects._device_input_sources 与处理模块 slug 用的是 camera 后缀
+    "mono_camera": "mono_rgb",
+    "stereo_camera": "stereo_rgb",
+    "fisheye_camera": "mono_rgb",     # 历史节点，镜头类型对清洗不可见
+    "rgb_camera": "mono_rgb",         # 历史节点
+    "rgbd": "rgbd_camera",
+    "stereo_rgbd": "stereo_rgbd_camera",
+    # 中文/展示名兜底
+    "umi": "gripper_device",
+    "umi_gripper": "gripper_device",
+    "glove": "glove_sensor",
+}
+
+
+# ── 严重度 ────────────────────────────────────────────────────
+PASS = "pass"
+WARN = "warn"
+FAIL = "fail"
+PENDING = "pending_review"
+ERROR = "error"
+
+# 越靠前越严重 —— worst() 与排序都用它
+SEVERITY_ORDER: tuple[str, ...] = (ERROR, FAIL, PENDING, WARN, PASS)
+
+# 面向用户的展示文案（报告里的 ``status_label``）。界面是英文的，这里保持一致。
+SEVERITY_LABELS: dict[str, str] = {
+    PASS: "Pass",
+    WARN: "Warning",
+    FAIL: "Fail",
+    PENDING: "Pending review",
+    ERROR: "Error",
+}
+
+
+def worst(statuses: Iterable[str]) -> str:
+    """取一组状态里最严重的；空集合视为 PASS。纯函数。"""
+    rank = {status: index for index, status in enumerate(SEVERITY_ORDER)}
+    result = PASS
+    best = len(SEVERITY_ORDER)
+    for status in statuses:
+        index = rank.get(str(status), len(SEVERITY_ORDER))
+        if index < best:
+            best = index
+            result = str(status)
+    return result
+
+
+def is_blocking(status: str) -> bool:
+    """该状态是否应当拦截（退回人工审核）。"""
+    return str(status) in (FAIL, ERROR)
+
+
+# ── 结构 ──────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class Range:
+    """一段时间区间 —— PDF §5「第二层结果」。"""
+
+    start_sec: float
+    end_sec: float
+    code: str
+    severity: str
+    stream: str = ""
+    channel: str = ""
+    start_frame: int | None = None
+    end_frame: int | None = None
+    rule: str = ""
+    message: str = ""
+    evidence: dict[str, Any] = dc_field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "start_sec": round(float(self.start_sec), 3),
+            "end_sec": round(float(self.end_sec), 3),
+            "code": self.code,
+            "severity": self.severity,
+            "stream": self.stream,
+            "channel": self.channel,
+            "start_frame": self.start_frame,
+            "end_frame": self.end_frame,
+            "rule": self.rule,
+            "message": self.message,
+            "evidence": dict(self.evidence or {}),
+        }
+
+
+@dataclass(frozen=True)
+class StreamResult:
+    """一条数据流的检查结果 —— PDF §5「第一层结果」。"""
+
+    stream: str
+    modality: str = ""
+    label: str = ""
+    channels: tuple[str, ...] = ()
+    status: str = PASS
+    reasons: tuple[str, ...] = ()
+    metrics: dict[str, Any] = dc_field(default_factory=dict)
+    ranges: tuple[Range, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "stream": self.stream,
+            "modality": self.modality,
+            "label": self.label,
+            "channels": list(self.channels),
+            "status": self.status,
+            "reasons": list(self.reasons),
+            "metrics": dict(self.metrics or {}),
+            "ranges": [item.to_dict() for item in self.ranges],
+        }
+
+
+@dataclass(frozen=True)
+class Finding:
+    """一次检查产出的��论 —— 检查项 run() 的返回值单元。"""
+
+    rule: str
+    version: str
+    status: str
+    scope: str                        # stream | episode | cross_modal
+    stream: str = ""
+    message: str = ""
+    metrics: dict[str, Any] = dc_field(default_factory=dict)
+    ranges: tuple[Range, ...] = ()
+    elapsed_ms: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "rule": self.rule,
+            "version": self.version,
+            "status": self.status,
+            "scope": self.scope,
+            "stream": self.stream,
+            "message": self.message,
+            "metrics": dict(self.metrics or {}),
+            "ranges": [item.to_dict() for item in self.ranges],
+            "elapsed_ms": self.elapsed_ms,
+        }

processor/app/processing/cleaning/engine.py

@@ -0,0 +1,302 @@
+"""质检引擎 —— 把检查项串成一次运行，产出四层报告。
+
+流程::
+
+    collect.gather_evidence()      读批次目录 → Evidence
+            │
+            ▼
+    applicable_checks()            按实际信道/模态选检查项
+            │
+            ▼
+    逐项 run(ctx)                  产出 Finding
+            │
+            ▼
+    rollup 成 StreamResult        每条流一个结论
+            │
+            ▼
+    report.build_report()          四层结果
+
+**只出结论，不产出数据**：不写文件、不改 episode 状态、不做任何清理动作。
+报告由调用方决定怎么用（落盘 / 展示 / 过滤导出）。
+
+设计取舍
+--------
+* **检查项失败不拖垮整轮** —— 单项抛异常记成 ``ERROR`` 结论继续跑，
+  否则一个 bug 会让整集没有报告。
+* **不设 `on_failure`** —— 按用户要求简化：清洗只记录，不碰 episode 状态流转。
+  需要拦截时由调用方读报告的 ``passed`` / ``verdict`` 自行决定。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from pathlib import Path
+from typing import Any, Iterable
+
+from app.processing.cleaning import collect
+from app.processing.cleaning.checks import (
+    CheckContext, applicable_checks, all_checks,
+)
+from app.processing.cleaning.contract import (
+    ERROR, PASS, SEVERITY_LABELS, StreamResult, worst,
+)
+from app.processing.cleaning.report import build_report, empty_report
+
+
+def ruleset_revision() -> str:
+    """规则集指纹 —— 任何检查项的 slug/version 变了它就变。
+
+    用途：报告里带上这个值，规则更新后能识别出"这份报告是用旧规则跑的"。
+    与 ``workflow_dispatch.workflow_revision()`` 同款思路 —— 用内容哈希而不是
+    自增版本号，省掉版本分配和迁移。
+    """
+    parts = sorted(f"{check.slug}@{check.version}" for check in all_checks())
+    return hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()[:24]
+
+
+def resolve_config(evidence: collect.Evidence,
+                   config: dict | None) -> dict[str, dict]:
+    """把节点配置解析成 ``{检查项 slug: {"enabled": bool, "params": {...}}}``。
+
+    节点配置结构（见 data_quality 节点）::
+
+        {
+          "devices": {
+            "gripper_device": {
+              "checks": {
+                "umi.slam_continuity": {"enabled": true,
+                                        "params": {"max_linear_mps": 3.0}},
+                "video.freeze":       {"enabled": false}
+              }
+            }
+          }
+        }
+
+    本 episode 有多个设备卡片时，按 ``evidence.modalities`` 的顺序合并；
+    **先出现的优先**（后面的不覆盖前面已设的值）。实际采集里一个 episode
+    基本只对应一张卡片，多卡片是罕见情况，规则简单可预期即可。
+
+    没配到的检查项走默认：启用、用检查项自己声明的 ``default_params``。
+    """
+    resolved: dict[str, dict] = {}
+    devices = (config or {}).get("devices") or {}
+    for modality in evidence.modalities:
+        card = devices.get(str(modality)) or {}
+        for slug, item in (card.get("checks") or {}).items():
+            if slug in resolved:
+                continue                    # 先出现的优先
+            entry = item if isinstance(item, dict) else {}
+            resolved[slug] = {
+                "enabled": bool(entry.get("enabled", True)),
+                "params": dict(entry.get("params") or {}),
+            }
+    return resolved
+
+
+def _context_for(evidence: collect.Evidence, cfg: dict[str, dict]) -> CheckContext:
+    """按证据构造检查上下文。阈值按"当前检查项"逐个注入。"""
+    return CheckContext(
+        batch_dir=evidence.batch_dir,
+        channels=evidence.channels,
+        modalities=evidence.modalities,
+        data_rows=evidence.rows,
+        data_columns=evidence.columns,
+        duration_sec=evidence.duration_sec,
+        fps=evidence.fps,
+        streams=evidence.streams,
+    )
+
+
+def _stream_results(evidence: collect.Evidence,
+                    findings: Iterable) -> list[StreamResult]:
+    """把 findings 归拢成"每条流一个结论" —— 报告的第一层。"""
+    by_stream: dict[str, list] = {}
+    for item in findings:
+        by_stream.setdefault(item.stream or "", []).append(item)
+
+    results: list[StreamResult] = []
+    seen: set[str] = set()
+    for stream in evidence.streams:
+        items = by_stream.get(stream.key) or []
+        seen.add(stream.key)
+        status = worst(item.status for item in items) if items else PASS
+        results.append(StreamResult(
+            stream=stream.key,
+            modality=",".join(evidence.modalities),
+            label=stream.key,
+            channels=(stream.channel,) if stream.channel else (),
+            status=status,
+            reasons=tuple(item.rule for item in items if item.status != PASS),
+            metrics={k: v for item in items
+                     for k, v in (item.metrics or {}).items()
+                     if isinstance(v, (int, float, str, bool))},
+            ranges=tuple(r for item in items for r in (item.ranges or ())),
+        ))
+
+    # 没有对应证据流的 finding（如整集级结论）也要留在第一层里
+    for key, items in by_stream.items():
+        if key in seen:
+            continue
+        results.append(StreamResult(
+            stream=key or "episode",
+            status=worst(item.status for item in items),
+            reasons=tuple(item.rule for item in items if item.status != PASS),
+            ranges=tuple(r for item in items for r in (item.ranges or ())),
+        ))
+    return results
+
+
+def run_checks(batch_dir: Path, *,
+               episode_id: str = "",
+               episode_index: int | None = None,
+               project: str = "",
+               config: dict | None = None,
+               probe_video: bool = False,
+               modality_hint: str | Iterable[str] | None = None) -> dict:
+    """跑一个 episode 的全部适用检查，返回四层报告（纯 dict，不含副作用）。
+
+    ``modality_hint`` 是设备模态（可多个，来自工作流连线的设备卡片）。给了它，
+    ``resolve_config`` 才能查到用户在设置面板里按设备卡片配的阈值；给不出就
+    走数据推断（推断不出 ``stereo_*``，那些 tab 的配置会被静默忽略）。
+
+    ``episode_index`` 只在【一个文件装多集】的布局下需要（LeRobot v3.0 导出
+    产物就是这种）；canonical 布局一集一文件，留空即可。**传错会导致把整份
+    文件当成一集读**，所有指标因此失真 —— 而 ``localstore.get_episode()``
+    返回的 ``path`` 是**项目目录**（多集共享），所以工作流路径**必须**带上它。
+
+    ``probe_video=False``（默认）只读 parquet，毫秒级；视频检查要解码抽样，
+    每集约几秒到几十秒，按需开。
+    """
+    started = time.perf_counter()
+    evidence = collect.gather_evidence(
+        batch_dir, episode_index=episode_index,
+        probe_video=probe_video, modality_hint=modality_hint)
+
+    if not evidence.streams:
+        return empty_report(
+            episode_id=episode_id, project=project,
+            reason=str(evidence.notes.get("reason") or "no_data"))
+
+    resolved = resolve_config(evidence, config)
+    ctx = _context_for(evidence, resolved)
+
+    # ★ 配置是【黑名单】，**不是白名单** —— 不传 ``enabled``。
+    #
+    # ``applicable_checks`` 的 ``enabled`` 是白名单语义（``slug not in allow``
+    # 就跳过）。而前端设置面板只在用户**碰过**的检查项上写 entry（见
+    # DeviceQualityModal 的 setEntry，未触碰的项不落进 config），所以
+    # ``resolved`` 里通常只有一两条。把它当白名单 = 「用户在弹窗里改了一个
+    # 阈值 → 其余检查项全部静默停跑」：实测只配 umi.gripper_range 时，
+    # 9 项变 1 项，且不报任何错。
+    #
+    # 检查项没有"默认关闭"的概念（CleaningCheck 无 default_enabled），
+    # 适用即跑；配置唯一的语义就是**关掉某项**。
+    #
+    # （曾经写成 `{...enabled} or None`：那个 ``or None`` 只修了空集那半边
+    #   ——"空集=一个都不跑"——非空的白名单照样是错的。整条白名单都不该有。）
+    deny = {slug for slug, item in resolved.items() if not item["enabled"]} or None
+
+    checks = applicable_checks(
+        channels=evidence.channels,
+        modalities=evidence.modalities,
+        cross_modal_active=len(set(evidence.modalities)) >= 2
+                          or len({item.channel for item in evidence.streams}) >= 2,
+        disabled=deny,
+    )
+
+    findings: list = []
+    failed_checks: list[str] = []
+    for check in checks:
+        entry = resolved.get(check.slug) or {}
+        ctx.params = dict(entry.get("params") or {})
+        try:
+            findings.extend(check.run(ctx) or [])
+        except Exception as exc:
+            failed_checks.append(f"{check.slug}: {exc}")
+            findings.append(_error_finding(check, exc))
+
+    # 视频流登记了却没检查 —— 必须显式记一笔，但**不能混进 findings**。
+    #
+    # 视频检查项"适用"（rgb 信道存在）不等于"查过"：``probe_video=False`` 时
+    # 它们拿到的是空报告，内部直接 continue，一条结论都不产出。报告若就此收尾，
+    # 会得出 ``passed=True 全部通过`` —— 而实际上视频根本没看。
+    #
+    # ★ 但它不该混进 findings 的严重度排序：``PENDING`` 排在 ``WARN`` 之前，
+    #   一条"视频未检查"会把真实的力漂移警告盖掉（实测 52 集全被标成"待人工
+    #   确认"）。"覆盖度"和"数据有多坏"是两个维度 —— 分开报。
+    unchecked: list[dict] = []
+    if not probe_video:
+        rgb_streams = [item for item in evidence.streams if item.channel == "rgb"]
+        if rgb_streams:
+            unchecked.append({
+                "channel": "rgb",
+                "reason": "probe_video_disabled",
+                "message": f"{len(rgb_streams)} 路视频未检查（本轮只读了 parquet）",
+                "streams": [item.key for item in rgb_streams],
+            })
+
+    elapsed_ms = int((time.perf_counter() - started) * 1000)
+    report = build_report(
+        _stream_results(evidence, findings),
+        findings,
+        episode_id=episode_id,
+        project=project,
+        modalities=_modality_summary(evidence, [c.slug for c in checks]),
+        channels=evidence.channels,
+        ruleset_revision=ruleset_revision(),
+        template_source=modality_hint or "",
+        elapsed_ms=elapsed_ms,
+    )
+
+    report["unchecked"] = unchecked
+
+    if not checks:
+        # 一个检查项都没跑 —— 报告在说"没问题"，而实际是"没查"。
+        # 与 ``empty_report`` 同一条原则：没有结论不等于结论合格（fail closed）。
+        report["no_checks_ran"] = True
+
+    # ``episode`` 只反映【数据本身】的结论；``passed`` 额外要求没有未检查项。
+    #
+    # 分开的理由：前者是"数据有多坏"，后者是"我们看全了没有"。混在一起会让
+    # "视频没检查"盖过"力漂移"，也会让"数据确实没问题但没看全"看起来像数据坏了。
+    if unchecked or not checks:
+        report["passed"] = False
+
+    if failed_checks:
+        # 检查项本身出错不改判定 —— 但要让人看见，否则会误以为"这集没问题"
+        report["check_errors"] = failed_checks
+    return report
+
+
+def _modality_summary(evidence: collect.Evidence,
+                      checks_run: Iterable[str]) -> dict:
+    """PDF §1 的「数据清单」—— 这台设备是什么、有哪些信道、**实际跑了**哪些检查。
+
+    ``checks_run`` 必须是【真正执行了】的检查项（``applicable_checks`` 的结果），
+    不是配置里写的那份。两者可能差很远：设备卡片闸门会把不属于本设备的检查项
+    滤掉，而报告如果只报配置，就分不清"检查了没问题"和"压根没检查"。
+    """
+    return {
+        "device_cards": list(evidence.modalities),
+        "channels": sorted(evidence.channels),
+        "rows": evidence.rows,
+        "fps": evidence.fps,
+        "parquet": evidence.parquet,
+        "checks_run": sorted(checks_run),
+    }
+
+
+def _error_finding(check, exc: Exception):
+    """检查项抛异常时的占位结论。
+
+    用 ``ERROR``（处理失败）而不是 ``FAIL`` —— 这是"没检查成"，
+    不是"数据坏了"。混为一谈会让数据质量问题看起来比实际多。
+    """
+    from app.processing.cleaning.contract import Finding
+
+    return Finding(
+        rule=check.slug, version=check.version, status=ERROR,
+        scope="episode",
+        message=f"check failed to run: {type(exc).__name__}: {exc}",
+    )

processor/app/processing/cleaning/report.py

@@ -0,0 +1,250 @@
+"""清洗报告组装 —— PDF §5 的「四层结果」。
+
+    第一层 数据流     哪条流好、哪条流坏
+    第二层 时间区间   问题发生在哪几秒、哪些帧
+    第三层 episode    这一集整体什么结论
+    第四层 训练用途   能用于什么训练、不能用于什么
+
+全部是纯函数 —— 输入是检查项产出的 ``StreamResult`` / ``Finding``，
+输出是可 JSON 序列化的 dict。不碰磁盘、不碰 cv2，因此完全可单测。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Iterable
+
+from app.processing.cleaning.contract import (
+    Finding, Range, StreamResult,
+    PASS, WARN, FAIL, PENDING, ERROR,
+    SEVERITY_ORDER, SEVERITY_LABELS, worst, is_blocking,
+)
+
+SCHEMA_VERSION = 2
+
+# 「训练用途」判定表 —— 声明式，不是 if-else 堆出来的。
+# requires 里的信道必须全部具备，该用途才成立。
+# PDF §7 要求"说明 episode 适合纯视觉、触觉或联合训练"，这张表就是那个说明。
+TRAINING_USE_RULES: tuple[dict[str, Any], ...] = (
+    {"use": "pure_vision",           "label": "Pure vision",
+     "requires": ("rgb", "time")},
+    {"use": "vision_gripper_joint",  "label": "Vision + gripper",
+     "requires": ("rgb", "gripper_state", "time")},
+    {"use": "slam_trajectory",       "label": "SLAM trajectory",
+     "requires": ("slam", "time")},
+    {"use": "vision_tactile_joint",  "label": "Vision + tactile",
+     "requires": ("rgb", "tactile", "time")},
+    {"use": "bimanual_tactile",      "label": "Bimanual tactile",
+     "requires": ("tactile", "time")},
+)
+
+
+def _utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def build_timeline(streams: Iterable[StreamResult | dict]) -> list[dict]:
+    """把各条流里的区间拍平成一条时间轴，按时间排序去重。
+
+    详情页要一次拉完整条时间轴，而 streams 是嵌套的 —— 所以顶层冗余一份。
+    单一来源、单一方向（从 streams 派生），有测试保证一致。
+    """
+    items: list[dict] = []
+    for stream in streams:
+        if isinstance(stream, StreamResult):
+            for item in stream.ranges:
+                items.append(_range_row(item.to_dict(), stream.stream))
+        elif isinstance(stream, dict):
+            for item in stream.get("ranges") or []:
+                if isinstance(item, dict):
+                    items.append(_range_row(item, str(stream.get("stream") or "")))
+    items.sort(key=lambda row: (row["start_sec"], row["end_sec"], row["code"]))
+    deduped: list[dict] = []
+    for row in items:
+        if deduped and all(
+            row[key] == deduped[-1][key]
+            for key in ("start_sec", "end_sec", "code", "stream")
+        ):
+            continue
+        deduped.append(row)
+    return deduped
+
+
+def _range_row(item: dict, stream: str) -> dict:
+    return {
+        "stream": item.get("stream") or stream,
+        "channel": item.get("channel") or "",
+        "start_sec": float(item.get("start_sec") or 0.0),
+        "end_sec": float(item.get("end_sec") or 0.0),
+        "start_frame": item.get("start_frame"),
+        "end_frame": item.get("end_frame"),
+        "code": str(item.get("code") or ""),
+        "severity": str(item.get("severity") or WARN),
+        "rule": str(item.get("rule") or ""),
+        "message": str(item.get("message") or ""),
+    }
+
+
+def rollup_episode(streams: Iterable[StreamResult | dict],
+                   findings: Iterable[Finding | dict] = ()) -> dict:
+    """第三层：整集结论。纯函数。
+
+    取所有流 + 所有 finding 里最严重的那个状态。
+    """
+    statuses: list[str] = []
+    failed: list[str] = []
+    warned: list[str] = []
+    pending: list[str] = []
+
+    for stream in streams:
+        if isinstance(stream, StreamResult):
+            name, status = stream.stream, stream.status
+        else:
+            name, status = str(stream.get("stream") or ""), str(stream.get("status") or PASS)
+        statuses.append(status)
+        if is_blocking(status):
+            failed.append(name)
+        elif status == PENDING:
+            pending.append(name)
+        elif status == WARN:
+            warned.append(name)
+
+    for finding in findings:
+        status = finding.status if isinstance(finding, Finding) else str(finding.get("status") or PASS)
+        statuses.append(status)
+
+    overall = worst(statuses) if statuses else PASS
+    pieces: list[str] = []
+    if failed:
+        pieces.append(f"{len(failed)} stream(s) failed")
+    if warned:
+        pieces.append(f"{len(warned)} stream(s) with warnings")
+    if pending:
+        pieces.append(f"{len(pending)} stream(s) pending review")
+    return {
+        "status": overall,
+        "status_label": SEVERITY_LABELS.get(overall, overall),
+        "failed_streams": failed,
+        "warn_streams": warned,
+        "pending_streams": pending,
+        "summary": "; ".join(pieces) if pieces else "All checks passed",
+    }
+
+
+def rollup_training_use(channels: Iterable[str],
+                        episode_status: str = PASS) -> list[dict]:
+    """第四层：这个 episode 能用于哪些训练。纯函数。
+
+    信道不具备 → 该用途判 fail（"未采集"），这是**用途维度**的失败，
+    不代表数据本身坏 —— 所以 reason 写清楚是"未采集"而不是"质量差"。
+    """
+    have = {str(item) for item in channels}
+    rows: list[dict] = []
+    for rule in TRAINING_USE_RULES:
+        required = tuple(rule["requires"])
+        missing = [channel for channel in required if channel not in have]
+        if missing:
+            rows.append({
+                "use": rule["use"],
+                "label": rule["label"],
+                "status": FAIL,
+                "reason": f"not collected: {', '.join(missing)}",
+                "requires": list(required),
+                "missing": missing,
+            })
+        else:
+            rows.append({
+                "use": rule["use"],
+                "label": rule["label"],
+                "status": episode_status,
+                "reason": "" if episode_status == PASS else "data quality problem",
+                "requires": list(required),
+                "missing": [],
+            })
+    return rows
+
+
+def passed_for(status: str) -> bool:
+    """该状态是否算"通过"（只有 PASS 算通过，WARN 不算）。"""
+    return status == PASS
+
+
+def build_report(streams: Iterable[StreamResult],
+                 findings: Iterable[Finding] = (),
+                 *,
+                 episode_id: str = "",
+                 project: str = "",
+                 modalities: dict[str, Any] | None = None,
+                 channels: Iterable[str] = (),
+                 ruleset_revision: str = "",
+                 template_source: str = "",
+                 elapsed_ms: int = 0) -> dict:
+    """组装完整报告。纯函数 —— 唯一的副作用是 ``_utcnow()``。"""
+    stream_list = list(streams)
+    finding_list = list(findings)
+    episode = rollup_episode(stream_list, finding_list)
+    use_channels = {str(item) for item in channels}
+    for stream in stream_list:
+        use_channels.update(stream.channels)
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "episode_id": episode_id,
+        "project": project,
+        "computed_at": _utcnow(),
+        "elapsed_ms": int(elapsed_ms),
+        "ruleset_revision": ruleset_revision,
+        "template_source": template_source,
+
+        # 模态清单 —— PDF §1 的「数据清单」
+        "modalities": dict(modalities or {}),
+
+        # 判定总入口：只有 PASS 算通过
+        "passed": passed_for(episode["status"]),
+
+        # 四层结果
+        "streams": [
+            item.to_dict() if isinstance(item, StreamResult) else dict(item)
+            for item in stream_list
+        ],
+        "ranges": build_timeline(stream_list),
+        "episode": episode,
+        "training_use": rollup_training_use(use_channels, episode["status"]),
+
+        "findings": [
+            item.to_dict() if isinstance(item, Finding) else dict(item)
+            for item in finding_list
+        ],
+    }
+
+
+def empty_report(*, episode_id: str = "", project: str = "",
+                 reason: str = "no_data") -> dict:
+    """没有任何数据可检查时的占位报告。
+
+    ``passed`` 恒为 False —— 没有数据不等于数据合格（fail closed）。
+    """
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "episode_id": episode_id,
+        "project": project,
+        "computed_at": _utcnow(),
+        "elapsed_ms": 0,
+        "ruleset_revision": "",
+        "template_source": "",
+        "modalities": {},
+        "passed": False,
+        "streams": [],
+        "ranges": [],
+        "episode": {
+            "status": ERROR,
+            "status_label": SEVERITY_LABELS[ERROR],
+            "failed_streams": [],
+            "warn_streams": [],
+            "pending_streams": [],
+            "summary": reason,
+        },
+        "training_use": [],
+        "findings": [],
+        "reason": reason,
+    }

processor/app/processing/cleaning/store.py

@@ -0,0 +1,189 @@
+"""质检报告落盘 —— 写进 episode state 的 ``cleaning_report`` 字段。
+
+**报告与状态流转是同一次写入**：判 FAIL/ERROR 的批次会被拦回
+``to_review``（人工审核），并留下 ``cleaning_summary.blocking`` 这个粘性标记。
+
+只写报告、不碰状态的方案看着更"干净"，但挡住不坏数据 —— 自动批准散在
+``ai_annotation`` / ``video_quality`` 两处门禁里，它们各看各的报告，
+谁都不会读质检结论。判 FAIL 的集只要视频干净，照样被自动批准放行。
+
+另外**不动** ``deleted`` / ``rejected`` 这类状态：质检不能把用户删掉或否决过的
+批次复活。
+
+放在 ``state/episode_states/<episode_id>.json`` 而不是项目数据集里：
+后者是给 LeRobot 消费的干净树（``project_dataset`` 明确不建 ``processed/``、
+``meta/processing/``），而质检报告是 episode 级的可变状态 —— ``state/`` 正是
+它的既有归属，``ai_quality_report`` / ``video_quality_report`` 也都在这。
+
+读走 ``localstore.read_episode_state``（带内存缓存），写走
+``write_episode_state``（原子替换 + 同步更新缓存）—— 两条路径都自带锁，
+不要自己读写那个文件。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.processing.cleaning.contract import is_blocking
+
+# episode state 里放质检报告的字段名。
+REPORT_FIELD = "cleaning_report"
+# 只放摘要，完整报告另存 —— 报告里可能有几十条区间，全塞进 state 会让
+# 每次 ``read_episode_state`` 都要解析几百 KB。完整报告见 ``reports_dir()``。
+SUMMARY_FIELD = "cleaning_summary"
+
+# 完整报告单独存一个目录，避免污染 episode state
+_REPORTS_SUBDIR = "quality_reports"
+
+# 允许被质检拦回人工审核的状态。
+#
+# **不含 ``to_review``**（本来就在那儿，再写一次是空操作）、也不含 ``deleted``
+# 与 ``rejected`` —— 质检不能把用户删掉/否决过的批次复活。
+_BLOCKABLE_STATUSES = frozenset({
+    "processing", "completed", "reviewed", "approved", "failed",
+})
+
+
+def _reports_dir():
+    from app.localstore import STATE_ROOT
+    return STATE_ROOT / _REPORTS_SUBDIR
+
+
+def summary_of(report: dict) -> dict[str, Any]:
+    """从完整报告里抽一个轻量摘要 —— 列表页/徽标只读这个。
+
+    ``blocking`` 是**给自动批准路径看的**闸门（见 ``is_approval_blocked``），
+    不是展示字段：判 FAIL/ERROR 才为真，WARN 只是警告、不拦。
+    """
+    episode = report.get("episode") or {}
+    return {
+        "schema_version": report.get("schema_version"),
+        "passed": bool(report.get("passed")),
+        "blocking": is_blocking(str(episode.get("status") or "")),
+        "status": episode.get("status"),
+        "status_label": episode.get("status_label"),
+        "summary": episode.get("summary"),
+        "counts": {
+            "fail": len(episode.get("failed_streams") or []),
+            "warn": len(episode.get("warn_streams") or []),
+            "pending": len(episode.get("pending_streams") or []),
+        },
+        "ranges": len(report.get("ranges") or []),
+        "ruleset_revision": report.get("ruleset_revision"),
+        "computed_at": report.get("computed_at"),
+        "reason": report.get("reason"),
+    }
+
+
+def is_approval_blocked(state: dict) -> bool:
+    """该集的质检结论是否禁止**自动批准**。
+
+    自动批准（``to_review`` → ``reviewed``）散在好几处：AI 标注的质量门禁
+    （``ai_annotation._set_ai_quality_state``）、视频门禁
+    （``video_quality._apply_video_quality_result``）。它们只看**自己的**
+    报告，不看数据质检的结论 —— 于是质检判 FAIL、视频门禁判 PASS 时，坏数据
+    会被自动放行。
+
+    ★ 为什么不能只靠"把 status 推回 to_review"：
+      几条门禁是**并发**跑的（都在 run 完成回调里 create_task），写的先后没有
+      保证。若质检先把状态推回 to_review、视频门禁随后又置成 reviewed，
+      拦截就白做了。所以质检除了推状态，还留下这个**粘性标记**，让所有自动
+      批准路径都先看一眼。
+
+    标记不需要手工清除：下一次质检会整份覆盖 ``cleaning_summary``，
+    数据修好后 ``blocking`` 自然变回 False。
+    """
+    summary = (state or {}).get(SUMMARY_FIELD) or {}
+    return bool(summary.get("blocking"))
+
+
+def save_report(episode_id: str, report: dict) -> bool:
+    """把报告写进 episode state。返回是否写入成功。
+
+    **不改 ``status``** —— 只设 ``cleaning_report`` / ``cleaning_summary`` /
+    ``cleaning_at`` 三个字段。
+
+    episode 不存在时静默跳过（外键不存在就别凭空造一条 state）。
+    """
+    from app.localstore import mutate_episode_state, _write_json
+
+    key = str(episode_id)
+    if not key:
+        return False
+
+    # 完整报告先单独落盘 —— 它可能有几��条区间，塞进 episode state 会让每次
+    # read_episode_state 都要解析几百 KB。放在下面临界区**外面**：这是个大文件
+    # 写入（在 NAS 上可能是几十毫秒），不该占着状态锁。
+    try:
+        _write_json(_reports_dir() / f"{key}.json", report)
+    except Exception:
+        pass                                # 摘要照样进 state，完整报告失败不影响
+
+    summary = summary_of(report)
+
+    def _apply(state: dict) -> bool:
+        state[REPORT_FIELD] = report
+        state[SUMMARY_FIELD] = summary
+        state["cleaning_at"] = report.get("computed_at")
+
+        # 数据不对 → 拦回人工审核。与写报告**同一次锁内 RMW**：分成两次写的话
+        # 中间那个窗口里，另一条并发的门禁可能把状态改成 reviewed。
+        if summary.get("blocking"):
+            current = str(state.get("status") or "")
+            if current in _BLOCKABLE_STATUSES:
+                state["status"] = "to_review"
+                state["approved_at"] = None
+        return True
+
+    # 走锁内 RMW：跑完工作流后 video_quality 的门禁任务与本任务是并发写的，
+    # 手写 read→write 会让其中一方的字段被另一方的旧快照覆盖（详见
+    # localstore.mutate_episode_state 的注释）。episode 不存在时返回 None，
+    # 保持"不凭空造 state"的既有行为。
+    return bool(mutate_episode_state(key, _apply))
+
+
+def load_report(episode_id: str) -> dict | None:
+    """读完整报告（不存在返回 None）。"""
+    from app.localstore import _read_json
+
+    return _read_json(_reports_dir() / f"{episode_id}.json")
+
+
+def load_summary(episode_id: str) -> dict | None:
+    """读摘要（从 episode state 取，快）。"""
+    from app.localstore import read_episode_state
+
+    return (read_episode_state(str(episode_id)) or {}).get(SUMMARY_FIELD)
+
+
+def list_reports(limit: int = 0) -> list[dict]:
+    """列出全部摘要，按时间倒序 —— 给质量列表页用。
+
+    只扫 ``quality_reports/`` 目录，不 join ``scan_sessions()`` —— 后者在
+    SSHFS 上冷读极慢，而报告是自包含的（项目名就在里面）。
+    """
+    from app.localstore import _read_json
+
+    directory = _reports_dir()
+    if not directory.is_dir():
+        return []
+    items: list[dict] = []
+    for path in directory.glob("*.json"):
+        report = _read_json(path)
+        if not isinstance(report, dict):
+            continue
+        item = summary_of(report)
+        item["episode_id"] = report.get("episode_id") or path.stem
+        item["project"] = report.get("project")
+        items.append(item)
+    items.sort(key=lambda item: str(item.get("computed_at") or ""), reverse=True)
+    return items[:limit] if limit else items
+
+
+def forget_report(episode_id: str) -> None:
+    """删除报告（episode 被删除时调用）。"""
+    for path in (_reports_dir() / f"{episode_id}.json",):
+        try:
+            path.unlink(missing_ok=True)
+        except OSError:
+            pass

processor/app/processing/cleaning/trigger.py

@@ -0,0 +1,225 @@
+"""质检触发 —— 把纯引擎接到运行时（工作流跑完之后）。
+
+三层分工，别混：
+
+    engine.py    纯函数：读证据 → 跑检查 → 出报告。不写盘、不改状态。
+    store.py     落盘：写进 episode state 的 ``cleaning_report``，**不碰 status**。
+    trigger.py   本文件：从 run 快照里判断"该不该跑、按什么配置跑"，
+                 丢到线程池执行，再把报告交给 store。
+
+调用方是 ``api/worker.py`` 的 run 完成回调（与 ``video_quality`` 的门禁任务
+同一个挂载点）。
+
+★ 为什么这里要 `to_thread`
+-------------------------
+``engine.run_checks`` 是**同步**的，而且会读 parquet / 必要时解码视频。直接在
+协程里调用会把整个事件循环卡住几秒到几十秒（存储根在 NAS 上时更甚，见
+``routes/pages.py`` 里同样的告诫）。``asyncio.to_thread`` 把它挪到线程池。
+
+★ 与 video_quality 门禁的关系
+----------------------------
+两者挂在同一张 Data Quality 卡片上，**可能同时触发**（相机类工作流就是）：
+
+    video_quality_gate   → 通过→reviewed / 失败→to_review
+    cleaning（本模块）    → 判 FAIL/ERROR 才拦回 to_review；其余只记录
+
+三条路都写同一份 episode state，所以读改写都必须走
+``localstore.mutate_episode_state``（锁内 RMW），否则后写的一方会把另一方
+刚写的字段用旧快照冲掉 —— 尤其是 ``status``，被冲掉意味着失败批次看起来
+像已通过。
+
+**光推状态还不够**：几条门禁是并发跑的，谁先写没有保证。质检除了推状态，
+还在 ``cleaning_summary.blocking`` 上留一个粘性标记，让
+``ai_annotation`` / ``video_quality`` 的**自动批准**路径主动让路 ——
+否则质检刚推回 to_review，视频门禁随后又置成 reviewed。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from app.processing.cleaning import engine, store
+from app.processing.cleaning.contract import normalize_device_modality
+from app.workflow_types import canonical_node_type
+
+# 质检节点在工作流里的 slug。合并前的两个旧 slug（ai_quality_review /
+# data_cleaning）由 ``workflow_types.canonical_node_type`` 统一映射到这里。
+_QUALITY_NODE = "data_quality"
+
+
+def _nodes_by_id(graph: dict) -> dict[str, dict]:
+    nodes = (graph or {}).get("nodes") or []
+    return {str(node.get("id")): node for node in nodes if node.get("id") is not None}
+
+
+def _incoming_edges(graph: dict) -> dict[str, list[str]]:
+    """``{目标节点 id: [源节点 id, ...]}``。"""
+    incoming: dict[str, list[str]] = {}
+    for edge in (graph or {}).get("edges") or []:
+        source, target = edge.get("source"), edge.get("target")
+        if source is None or target is None:
+            continue
+        incoming.setdefault(str(target), []).append(str(source))
+    return incoming
+
+
+def _node_type(node: dict | None) -> str:
+    return canonical_node_type((node or {}).get("data", {}).get("nodeType"))
+
+
+def _upstream_device_cards(node_id: str, by_id: dict[str, dict],
+                           incoming: dict[str, list[str]]) -> tuple[str, ...]:
+    """从质检节点往回找，收集上游的**设备卡片**模态。
+
+    往回找而不是只看直接上游，是因为中间可能夹着处理节点
+    （相机 → RGB-D_3D_BareHand → 质检），直接上游是个处理节点、认不出模态。
+
+    设备卡片就是链路源头，遇到就不再往回走 —— 否则会顺着"卡片A → 卡片B"
+    这种不合法的连线继续爬到别处。
+    """
+    seen: set[str] = set()
+    queue = list(incoming.get(str(node_id), ()))
+    cards: list[str] = []
+    while queue:
+        current = queue.pop(0)
+        if current in seen:
+            continue
+        seen.add(current)
+        modality = normalize_device_modality(_node_type(by_id.get(current)))
+        if modality:
+            if modality not in cards:
+                cards.append(modality)
+            continue
+        queue.extend(incoming.get(current, ()))
+    return tuple(cards)
+
+
+def data_quality_target(graph: dict,
+                        node_configs: dict) -> tuple[dict, tuple[str, ...]] | None:
+    """找到**接在数据链路上**的 Data Quality 卡片。
+
+    返回 ``(卡片配置, 上游设备卡片模态)``；没有卡片、或卡片没接线 → ``None``
+    （画布上孤零零摆一张卡片只是配置，不该触发）。
+
+    ★ 判据是"**有入边**"，不是列举"哪些源节点算数"。
+      ``ai_annotation.video_quality_gate_config`` 用的是后者，它的白名单里
+      **没有 ``gripper_device``** —— 于是 UMI 夹爪工作流接上质检卡片后静默
+      地什么都不跑。这种白名单还会继续漏：每加一种设备就漏一次，而且漏了
+      不报错。质检节点的语义本来就与上游是哪类设备无关 —— 它检查的是
+      "这个批次目录里实际有什么数据"，跑哪些检查由引擎按真实信道决定。
+    """
+    by_id = _nodes_by_id(graph)
+    incoming = _incoming_edges(graph)
+
+    # 排序保证多张卡片时结果确定，不受画布 JSON 顺序影响
+    for node_id in sorted(by_id):
+        node = by_id[node_id]
+        if _node_type(node) != _QUALITY_NODE:
+            continue
+        if not incoming.get(node_id):
+            continue                        # 没接线 —— 只是块配置，不触发
+
+        data = node.get("data") or {}
+        config = dict(data.get("config") or {})
+        config.update((node_configs or {}).get(node.get("id")) or {})
+        return config, _upstream_device_cards(node_id, by_id, incoming)
+    return None
+
+
+async def run_cleaning_checks(episode_id: str, batch_dir: str | Path, *,
+                              config: dict | None = None,
+                              device_cards: tuple[str, ...] = (),
+                              episode_index: int | None = None,
+                              project: str = "",
+                              probe_video: bool = True) -> dict:
+    """跑一次质检并落盘，返回四层报告。
+
+    ``episode_index`` 必传 —— 工作流给的 ``batch_dir`` 是**项目目录**，多集
+    共享（见 ``collect.gather_evidence`` 的告诫）。漏传的后果不是报错，而是
+    拿第 0 集的数据去比全部集的视频，得出一堆假的丢帧结论。
+
+    ``probe_video=True`` 是刻意的：只读 parquet 时视频检查拿不到证据，
+    报告会被标 ``unchecked`` 并强制 ``passed=False`` —— 每一集都"未通过"的
+    门禁等于没有门禁。代价实测约 4.8s/集（单流 UMI，本机），跑在线程池里。
+    """
+    report = await asyncio.to_thread(
+        engine.run_checks,
+        Path(batch_dir),
+        episode_id=str(episode_id),
+        episode_index=episode_index,
+        project=str(project or ""),
+        config=config,
+        probe_video=probe_video,
+        modality_hint=device_cards or None,
+    )
+    await asyncio.to_thread(store.save_report, str(episode_id), report)
+    return report
+
+
+# 后台任务的强引用。
+#
+# ``asyncio.create_task`` 的返回值**必须有人持有**：只把它丢给事件循环的话，
+# 任务可能在执行到一半时被 GC 回收（asyncio 文档原文："Save a reference to
+# the result of this function, to avoid a task disappearing mid-execution"）。
+# 这里持有到它跑完为止。
+_BACKGROUND_TASKS: set[asyncio.Task] = set()
+
+
+def spawn_cleaning_for_run(run: dict, episode: dict) -> bool:
+    """worker 完成回调调用的**同步**入口。返回是否已调度。
+
+    先做图查找再建任务：卡片没接线时连任务都不建（同步、纯字典遍历，很快），
+    这样"没有质检节点"这条常见路径不会往事件循环里塞空任务。
+    """
+    if data_quality_target((run or {}).get("graph") or {},
+                           (run or {}).get("node_configs") or {}) is None:
+        return False
+    task = asyncio.create_task(trigger_cleaning_for_run(run, episode))
+    _BACKGROUND_TASKS.add(task)
+    task.add_done_callback(_BACKGROUND_TASKS.discard)
+    return True
+
+
+async def trigger_cleaning_for_run(run: dict, episode: dict) -> dict | None:
+    """跑一次质检的后台协程。卡片没接线时返回 None。
+
+    **永不抛异常**：这是后台任务，抛出去会变成 unhandled asyncio exception，
+    而调用方（worker 的完成响应）已经返回了，没人能处理。失败只记日志 ——
+    与 ``video_quality.run_video_quality_review`` 同样的取舍。
+    """
+    episode_id = str((run or {}).get("episode_id") or (episode or {}).get("id") or "")
+    batch_dir = (episode or {}).get("path")
+    if not episode_id or not batch_dir:
+        return None
+
+    try:
+        target = data_quality_target(
+            (run or {}).get("graph") or {},
+            (run or {}).get("node_configs") or {},
+        )
+        if target is None:
+            return None
+        config, device_cards = target
+
+        report = await run_cleaning_checks(
+            episode_id, batch_dir,
+            config=config, device_cards=device_cards,
+            # ``get_episode`` 的记录里 episode_index 可能是 0，不能用 or 兜底
+            episode_index=(episode.get("episode_index")
+                           if episode.get("episode_index") is not None else None),
+            project=str(episode.get("project") or ""),
+        )
+    except Exception as exc:                # noqa: BLE001 —— 后台任务不抛
+        print(f"[Quality] Data quality checks failed for {episode_id}: "
+              f"{type(exc).__name__}: {exc}")
+        return None
+
+    summary = store.summary_of(report)
+    verdict = str(summary.get("status"))
+    if summary.get("blocking"):
+        verdict += " -> blocked, back to manual review"
+    print(f"[Quality] {episode_id}: {verdict} "
+          f"({summary.get('ranges', 0)} ranges, "
+          f"{len(device_cards)} device card(s))")
+    return report

processor/app/processing/modules/ai_quality_review.py

@@ -1,36 +0,0 @@
-"""AI Quality Review — lightweight media and annotation quality gate.
-
-The actual check runs after the workflow result is persisted.  It checks video
-decode/frame continuity/black screens/freezes and, when connected after AI
-Annotation, annotation coverage too.  This node keeps the normal artifact
-contract so existing worker graphs remain compatible.  The service-level gate
-moves failed/incomplete batches to the existing Reviewing queue and only
-allows a passed result to become Approved.
-"""
-
-from app.processing import ProcessingModule, JobContext, ArtifactRef
-from app.processing.registry import register
-from app.processing.theme import REVIEW_COLOR
-
-
-@register
-class AIQualityReviewModule(ProcessingModule):
-    slug = "ai_quality_review"
-    version = "1.0"
-    category = "review"
-    label = "AI Quality Review"
-    icon = "ant-design:robot-outlined"
-    color = REVIEW_COLOR
-    inputs = ({"key": "data", "label": "Quality Review Target"},)
-    outputs = ({"key": "reviewed", "label": "Reviewed Data"},)
-    default_config = {"mode": "gate"}
-    execution_target = "server"
-    capabilities = ("quality_review",)
-
-    def run(self, ctx: JobContext) -> dict[str, ArtifactRef] | None:
-        # The workflow executor still receives the upstream artifact.  The
-        # episode-level gate is applied by the AI annotation service after its
-        # persisted ranges have been validated.
-        if not ctx.incoming:
-            ctx.skip("No upstream data — skipped")
-        return dict(ctx.incoming)

processor/app/processing/modules/data_quality.py

@@ -0,0 +1,126 @@
+"""Data Cleaning —— 数据清洗（质检）：一个节点统管确定性与 AI 两类检查。
+
+显示名是 Data Cleaning；slug 仍是 ``data_quality``（持久化契约，改它会让已保存
+工作流的 nodeType 对不上）。两者不一致是有意的 —— 见下方端口 key 的同类说明。
+
+本节点由两个旧节点合并而来，两者功能高度重叠：
+
+    ai_quality_review  视频检查(黑屏/冻结/丢帧/解码) + AI 标注覆盖率
+    data_cleaning      视频检查 + UMI/手套/EGO 检查（第 2 期接入）
+
+历史原因：视频检查最早"寄居"在 ``ai_quality_review`` 里，好让纯视频工作流
+也有质量门禁（见 ``ai_annotation.py`` 的 ``video_quality_review_node_config``
+docstring）。现在合并成一张卡片，语义与配置都归一处。
+
+**两个旧 slug 都作为别名保留**（``workflow_types.LEGACY_TO_CANONICAL``），
+已保存的工作流打开时自动迁移，连线不受影响 —— 端口的 key 刻意保持不变：
+
+    输入  data      所有旧连线都用它
+    输出  reviewed  旧连线用它接 lerobot_export
+
+检查分两层，与清洗方案 PDF §4 的两栏一一对应：
+
+    机器可直接判断（确定性、免费、可每集跑）
+      ├─ 视频：解码 / 黑屏 / 冻结 / 丢帧
+      ├─ UMI：帧对齐 / action / 夹爪量程 / SLAM 连续性
+      ├─ 手套：全零 / 死点 / 漂移 / 饱和
+      └─ EGO：曝光 / 关键点缺失 / 左右手
+
+    需联合判断或复核（有成本、可选）
+      └─ AI 标注覆盖率；将来的 VLM 语义复核
+
+检查项的算法实现与工作流适配器分开，与 ``app/processing/black_glove`` 同构：
+
+    app/processing/cleaning/                ← 契约 + 检查项 + 报告组装
+    app/processing/modules/data_quality.py  ← 本文件：artifact 契约 + 端口 + 配置
+
+新增检查项 = 在 ``app/processing/cleaning/checks/`` 下放一个 .py，本文件不用改。
+
+**只出结论，不产出数据** —— 原始数据一字不改，也不生成 clean_v1 之类的副本。
+区间信息完整保留在报告的 ``ranges`` 里，下游按 ``training_use`` 过滤即可。
+
+数据不对时**卡在人工审核**：判 FAIL/ERROR 的批次会被推回 ``to_review``
+（就是审核页的入口），并在 ``cleaning_summary.blocking`` 上留一个粘性标记，
+让 AI 标注 / 视频门禁的自动批准路径让路。WARN 只记录、不拦。
+"""
+
+from __future__ import annotations
+
+from app.processing import ProcessingModule, JobContext, ArtifactRef
+from app.processing.registry import register
+from app.processing.theme import REVIEW_COLOR
+
+
+@register
+class DataQualityModule(ProcessingModule):
+    slug = "data_quality"
+    version = "1.0"
+    category = "review"
+    label = "Data Cleaning"
+    # 必须取自 web/static/iconify-preload.js 的白名单 —— 图标是离线预载的,
+    # 不在表内的名字 iconify-icon 会去 api.iconify.design 拉,调色板一次渲染
+    # 全部节点,一个漏网图标就能让整块面板卡住。check-circle 表示"校验",
+    # 与同组 review 节点的 eye(human) 不冲突。
+    # 改图标后请跑 scripts/check_icon_preload.sh。
+    icon = "ant-design:check-circle-outlined"
+    color = REVIEW_COLOR
+
+    # 端口 key 是持久化契约 —— 取值必须与合并前的 ai_quality_review 逐字一致,
+    # 否则已保存工作流的连线会因 sourceHandle/targetHandle 对不上而失效。
+    # 详见 workflow_types.py 里前端对 ``out.key === inp.key`` 的校验。
+    inputs = ({"key": "data", "label": "Data"},)
+    outputs = ({"key": "reviewed", "label": "Reviewed Data"},)
+
+    # 配置结构（前端设置弹窗按设备卡片写入）::
+    #
+    #     {"devices": {
+    #        "gripper_device": {
+    #          "checks": {
+    #            "umi.slam_continuity": {"enabled": true,
+    #                                    "params": {"max_linear_mps": 3.0}},
+    #            "video.freeze":       {"enabled": false}
+    #          }}}}
+    #
+    # 引擎侧由 ``cleaning.engine.resolve_config()`` 解析。
+    default_config = {"devices": {}}
+
+    # ★ 刻意留空 —— 配置全部走专用弹窗（DeviceQualityModal），不走通用
+    #   config_schema 渲染。
+    #
+    #   通用那套是**平铺字段列表**，表达不了"按设备卡片分组 + 每项带阈值"的
+    #   嵌套结构；硬塞会变成一长串 enable_xxx 开关。曾短暂用过那套，结果是
+    #   三个阈值在节点里和检查项里各存一份（frame_tolerance 与
+    #   video.frame_drop.tolerance_ratio 同义），迟早不一致。
+    #
+    #   现在阈值只有一处定义：检查项的 ``default_params``；节点只存"覆盖值"。
+    config_schema = ()
+
+    # 真实检查在 run 完成回调里跑（那时才能读到合并后的 episode 数据），
+    # 与 human_review / 旧 ai_quality_review 的分工一致。
+    # 注：该字段当前无消费方，仅作语��标注（全仓 grep 只见 schema 与文档）。
+    execution_target = "server"
+    capabilities = ("data_quality", "quality_gate", "quality_review")
+
+    def run(self, ctx: JobContext) -> dict[str, ArtifactRef] | None:
+        """透传上游 artifact。上游没连 → skipped。
+
+        **真正的检查不在 ``run()`` 里跑** —— 在 worker 的 run 完成回调里
+        （``api/worker.py`` 调 ``cleaning.trigger.spawn_cleaning_for_run``）。
+
+        为什么不在 ``run()``：DAG 执行期 worker 是在 staging 目录里干活、
+        产物要等 ``_publish_episode_result`` 才合并回批次目录。在这一步读
+        批次目录，拿到的是**上一轮**的数据 —— 尤其 ``action`` 列，它由
+        ``umi_slam_action`` 派生产出，读早了会全是采集端的零占位。
+        完成回调时数据已经合并完毕，与 ``human_review`` / 旧
+        ``ai_quality_review`` 的分工一致。
+
+        检查所需的数据**不靠端口传** —— 完成回调手上就有
+        ``localstore.get_episode()`` 的记录（``path`` + ``episode_index``），
+        检查项直接读批次目录。
+
+        ★ 进来的是 ``episode_index`` 不是可选的：``path`` 是**项目目录**，
+          几十集共享，漏传会拿第 0 集的数据去比全部集的视频。
+        """
+        if not ctx.incoming:
+            ctx.skip("No upstream data — skipped")
+        return dict(ctx.incoming)

processor/app/project_dataset.py

@@ -102,6 +102,17 @@ def write_project_episode_index(project_root: Path,
     # The legacy flat JSONL index is intentionally not generated anymore.
     (project_root / "meta" / "episodes.jsonl").unlink(missing_ok=True)
 
+    # ★ 必须失效缓存 —— 本函数是**索引的唯一写入点**，而 project_episode_rows()
+    #   读的是带 60s TTL 的模块级缓存。不失效的话，同一次调用里"写完再读"会拿到
+    #   删除前的旧行。
+    #
+    #   实测后果（2026-09-11 引入缓存时漏掉这步，删除从此全坏）：
+    #     delete_project_episode: 读一次(预热缓存) → 删文件 → 写索引 → 校验
+    #     校验又调 project_episode_rows → 旧缓存 → 报 "missing data" → RuntimeError
+    #     →「清空回收站」500。盘上的索引其实是对的，纯粹是缓存没跟上。
+    #   （delete_episode 末尾也会 invalidate_session_cache()，但那要等异常之后。）
+    invalidate_project_cache(project_root)
+
 
 def is_project_dataset(root: Path) -> bool:
     root = Path(root)
@@ -1402,13 +1413,30 @@ def merge_normalized_episode(project_root: Path, episode_root: Path,
     }
 
 
+# 人工/脚本留下的备份与临时文件 —— 不是删除或合并操作产生的，不该算到校验头上。
+#
+# ★ 为什么必须放过它们：``delete_episode`` 在**删完文件之后**才跑本校验，校验失败就
+#   抛 RuntimeError → 500，而「清空回收站」是循环处理的，一个项目失败整轮中止。
+#   实测踩过：两个 D435 项目的 meta/ 里各有一个 ``info.json.bak-20260908-144550``
+#   （9-08 留下的），于是**每次清空都 500、什么都删不掉**，而前端没有错误分支，
+#   用户看到的是"点了没反应"。一个备份文件不该有这种杀伤力。
+_IGNORED_ENTRY_SUFFIXES = (".bak", ".orig", ".tmp", ".save", "~")
+
+
+def _is_ignorable_entry(name: str) -> bool:
+    """备份/临时文件，或隐藏文件 —— 校验一律不看。"""
+    if name.startswith("."):
+        return True
+    return name.endswith(_IGNORED_ENTRY_SUFFIXES) or ".bak-" in name
+
+
 def verify_project_dataset(project_root: Path) -> dict[str, Any]:
     root = Path(project_root)
     rows = project_episode_rows(root)
     errors: list[str] = []
     unexpected = sorted(
         path.name for path in root.iterdir()
-        if path.name not in _CANONICAL_ROOTS and not path.name.startswith(".")
+        if path.name not in _CANONICAL_ROOTS and not _is_ignorable_entry(path.name)
     ) if root.is_dir() else []
     errors.extend(f"unexpected project root entry: {name}" for name in unexpected)
     expected_meta = {"info.json", "stats.json", "tasks.json", "episodes"}
@@ -1416,7 +1444,7 @@ def verify_project_dataset(project_root: Path) -> dict[str, Any]:
     if meta_root.is_dir():
         unexpected_meta = sorted(
             path.name for path in meta_root.iterdir()
-            if path.name not in expected_meta and not path.name.startswith(".")
+            if path.name not in expected_meta and not _is_ignorable_entry(path.name)
         )
         errors.extend(f"unexpected meta entry: {name}" for name in unexpected_meta)
     for row in rows:
@@ -2074,11 +2102,25 @@ def append_project_episode(project_root: Path, episode_root: Path,
         existing = next((row for row in rows
                          if str(row.get("episode_id") or row.get("source_batch") or "") == str(episode_id)), None)
         if existing is None:
-            target_episode_index = max(
-                [_episode_index(row.get("episode_index")) for row in rows
-                 if _episode_index(row.get("episode_index")) is not None],
-                default=-1,
-            ) + 1
+            used = {_episode_index(row.get("episode_index")) for row in rows
+                    if _episode_index(row.get("episode_index")) is not None}
+            # ★ 优先沿用**名字里的编号**，让存储索引与公开 ID 一致。
+            #
+            #   此前一律 max(used)+1，于是"名字说 000005、索引是 3"这种对不上的
+            #   情况会出现 —— 实测 119 个带编号批次里 **21 个**中招。它的直接
+            #   危害在 _match_episode_row 的名字回退：按名字推出索引后会撞上
+            #   别的批次（模拟：删 ..._000002 时若它自己的行已缺失，会去删
+            #   index=2 那个批次的数据和视频）。
+            #
+            #   编号允许空洞（见本模块 delete_project_episode 的说明
+            #   "gaps are valid"），所以直接采用名字里的编号是安全的。
+            #   两种情况仍回落到 max+1：名字里没有编号；或该编号已被别的批次
+            #   占用（撞号）。
+            named = episode_index_from_name(episode_id)
+            if named is not None and named not in used:
+                target_episode_index = named
+            else:
+                target_episode_index = max(used, default=-1) + 1
             chunk_index = episode_chunk_for_index(target_episode_index)
         else:
             if not replace:
@@ -2104,6 +2146,17 @@ def append_project_episode(project_root: Path, episode_root: Path,
             if project_existed and backup_root.exists():
                 backup_root.rename(project_root)
             raise
+        # ★ 换入之后必须失效【project_root】的缓存，不能只靠
+        #   write_project_episode_index 里那次 —— 那次失效的是 **temp_root**
+        #   的 key，而内容是靠 rename 换过来的。
+        #
+        #   不失效的后果有两条：
+        #     (1) 紧跟的 verify_project_dataset(project_root) 读到的还是**追加前**
+        #         的旧行 —— 校验等于在验旧树，"通过"是空头支票（实测：连续三次
+        #         append 全部通过，而盘上索引早已是 [0,1,2,5,6,7]）；
+        #     (2) 缓存有 60 秒的盲目 TTL（TTL 内连指纹都不查），上传后前端
+        #         最长 60 秒看不到新批次。
+        invalidate_project_cache(project_root)
         result["verification"] = verify_project_dataset(project_root)
         result["backup"] = str(backup_root) if project_existed else None
         return result

processor/app/routes/export.py

@@ -38,6 +38,9 @@ router = APIRouter(prefix="/api/v1/export", tags=["export"])
 
 EXPORTS_DIR = STATE_ROOT / "exports"
 EXPORT_TASKS_DIR = STATE_ROOT / "export_tasks"
+# 可训练的数据集 —— 与 EXPORTS_DIR 分开:那边是按 run_id 命名的**处理产物**
+# (每条一集),这边是**能拿去训练的成品**,训练页只列这个目录。
+DATASETS_DIR = STATE_ROOT / "datasets"
 # 导出页/批量导出的构建目录与 zip 放本地盘:同一份视频数据不再在
 # NAS(SSHFS ~28MB/s)上读写三遍,只保留一次源文件读取。
 LOCAL_EXPORTS_DIR = settings.upload_staging_root / "exports"
@@ -484,6 +487,38 @@ async def batch_download_sessions(request: Request):
 
 # ── 导出任务(JSON,后台打包)─────────────────────────
 
+def _persist_trainable_dataset(export_root: Path, dataset_name: str) -> Path | None:
+    """把导出好的数据集落到 ``state/datasets/<名字>/``,让它能当训练输入。
+
+    原来是打包完直接 ``rmtree``(省本地空间)—— 结果导出的成果只剩一个 zip,
+    磁盘上什么都没有,训练页根本无从列起。
+
+    **交换式替换**,不是"先删旧的再搬新的":先把新数据集搬进 ``.staging``,
+    再把旧的挪到 ``.old``,然后 rename 上位,最后删 ``.old``。任何一步失败都不会
+    让目标位置处于"半个数据集"的状态 —— 直接 rmtree 再 move 的话,搬到一半
+    失败就两头落空。
+
+    返回落位后的路径;``export_root`` 里没有 ``meta/info.json``(不是数据集)时
+    返回 None,调用方照旧删掉临时目录。
+    """
+    if not (export_root / "meta" / "info.json").is_file():
+        return None
+
+    DATASETS_DIR.mkdir(parents=True, exist_ok=True)
+    target = DATASETS_DIR / dataset_name
+    staging = DATASETS_DIR / f".{dataset_name}.staging"
+    previous = DATASETS_DIR / f".{dataset_name}.old"
+
+    shutil.rmtree(staging, ignore_errors=True)
+    shutil.move(str(export_root), str(staging))
+    shutil.rmtree(previous, ignore_errors=True)
+    if target.exists():
+        target.rename(previous)
+    staging.rename(target)          # 同盘 rename,原子
+    shutil.rmtree(previous, ignore_errors=True)
+    return target
+
+
 def _load_task(job_id: str) -> dict | None:
     return _read_json(EXPORT_TASKS_DIR / f"{job_id}.json", None)
 
@@ -573,8 +608,9 @@ def _run_export_task(job_id: str, episode_ids: list[str], export_format: str,
         ]
         if blocked:
             raise RuntimeError("Some episodes are still in Reviewing")
-        # 构建与 zip 都在本地盘进行(NAS 只读一次源文件);zip 是最终
-        # 产物,构建目录打包完成后即删除以节省本地空间。
+        # 构建与 zip 都在本地盘进行(NAS 只读一次源文件)。产物两样都留:
+        # zip 供下载,数据集目录(LeRobot 分支)供训练页选用 —— 后者走
+        # _persist_trainable_dataset 落到 state/datasets/,不再是"打完包就删"。
         dest = LOCAL_EXPORTS_DIR / f"{job_id}.zip"
         dest.parent.mkdir(parents=True, exist_ok=True)
         export_root = LOCAL_EXPORTS_DIR / f"{dataset_name}-{job_id[:8]}"
@@ -591,12 +627,17 @@ def _run_export_task(job_id: str, episode_ids: list[str], export_format: str,
                                   progress_callback=_on_episode)
             _set_progress(0.75)
             _zip_directory(export_root, dest)
+            # 打包后**留下**数据集,不要删 —— 训练页的数据集列表就是从这里读的
+            # (state/datasets/)。只有它压根不是数据集时才清掉临时目录。
+            if _persist_trainable_dataset(export_root, dataset_name) is None:
+                shutil.rmtree(export_root, ignore_errors=True)
             _set_progress(0.95)
         else:
             _set_progress(0.2)
             _zip_episode_selection([str(e) for e in episode_ids], dest)
             _set_progress(0.95)
-        shutil.rmtree(export_root, ignore_errors=True)
+            # 非 LeRobot 分支产出的只是一个选集的 zip,没有数据集目录可留。
+            shutil.rmtree(export_root, ignore_errors=True)
         task = _load_task(job_id)
         if task:
             task["status"] = "completed"
@@ -788,7 +829,9 @@ _RE_TASKS: dict[str, dict] = {}
 _RE_TASKS_DIR = STATE_ROOT / "re_export_tasks"
 
 _PASSTHROUGH_TYPES = {
-    "annotation", "human_review", "ai_annotation", "ai_quality_review",
+    # data_quality 由 ai_quality_review + data_cleaning 合并而来；此处的 t 已过
+    # canonical_node_type()，旧 slug 不会出现。
+    "annotation", "human_review", "ai_annotation", "data_quality",
 }
 _CAMERA_TYPES = {"rgb_camera", "fisheye_camera", "rgbd_camera", "stereo_camera",
                  "stereo_rgbd_camera", "mono_camera"}

processor/app/routes/pages.py

@@ -21,10 +21,30 @@ _static_dir = STATIC_DIR
 
 # 静态资源缓存键的唯一来源:模板里写 ``?v={{ asset_version }}``。
 # 以前每个模板各写各的日期串,发版时靠人记得逐个改 —— 漏一个,那个页面
-# 就会继续发浏览器缓存里的旧脚本。现在只 bump app/version.py 一处。
-from app.version import __version__ as _asset_version
-
-templates.env.globals["asset_version"] = _asset_version
+# 就会继续发浏览器缓存里的旧脚本。
+#
+# ★ 取的是**前端号**(web/VERSION),不是后端号。改前端只 bump 那一个文件即可,
+#   提交信息里的「前端 X」就是它 —— 缓存键和版本记录是同一个数,不会对不上。
+#   (原来取后端号,于是每次改前端都要同时 bump 后端号和前端号两个地方。)
+from app.web_version import frontend_version as _frontend_version
+
+templates.env.globals["asset_version"] = _frontend_version()
+
+# 服务端取词 —— 模板里写 ``{{ t('nav_home') }}``。语言由 app/i18n.py 的
+# LanguageMiddleware 从 cookie 读进 ContextVar,这里是同一个上下文,读得到。
+# 这样首屏渲染出来的就是正确语言,不再"先英文后由 JS 纠正"(那会闪一下)。
+from app.i18n import get_current_lang as _get_lang
+from app.i18n import t as _t
+
+templates.env.globals["t"] = _t
+# 模板要写 <html lang="…">,所以语言码也放进全局。
+#
+# ★ 注册的是**函数**,模板里必须写成 ``{{ current_lang() }}`` 带括号。
+#   Jinja 的全局是"每次渲染取一次这个对象" —— 值是固定的,而语言是**每请求**
+#   才定的(存在 ContextVar 里),所以只能注册一个可调用的东西,渲染时调它。
+#   少写括号不会报错,只会把函数的 repr 渲染进 HTML:
+#       <html lang="&lt;function get_current_lang at 0x7f…&gt;">
+templates.env.globals["current_lang"] = _get_lang
 
 
 @router.get("/", response_class=HTMLResponse)
@@ -68,6 +88,16 @@ async def trash_page(request: Request):
     return templates.TemplateResponse("trash.html", {"request": request})
 
 
+@router.get("/train", response_class=HTMLResponse)
+async def train_page(request: Request):
+    """Model training — read-only view of checkpoints produced outside the platform.
+
+    Data comes from ``GET /api/v1/training/runs`` (see ``app/routes/training.py``).
+    Nothing on this page starts or stops training yet.
+    """
+    return templates.TemplateResponse("train.html", {"request": request})
+
+
 @router.get("/users", response_class=HTMLResponse)
 async def users_page(request: Request, _: dict = Depends(require_roles("admin"))):
     """Account management is visible only to administrators."""

processor/app/routes/training.py

@@ -0,0 +1,78 @@
+"""Training API —— 路由层,薄薄一层。
+
+业务逻辑在 ``app/training/`` 下(产物扫描 / GPU 读取 / 数据集发现),这里只负责
+把它们挂到 URL 上。**没有任何训练执行** —— 见那个包的 docstring。
+
+将来接执行时,新端点加在这里(创建 / 停止 / 日志),形状与现有的保持一致;
+真正的子进程管理写在 ``app/training/runner.py``。
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+
+from app.training import (
+    list_datasets, list_gpus, list_projects_progress, list_runs,
+)
+from app.training.runs import resolve_checkpoint_file
+
+router = APIRouter(prefix="/api/v1/training", tags=["training"])
+
+
+@router.get("/gpus")
+def gpus():
+    """本机 GPU(读 ``nvidia-smi``)。
+
+    **驱动不可用时靠 ``available: false`` 区分**,不要把它当成"利用率 0%" ——
+    详见 ``app/training/gpus.py``。
+    """
+    return list_gpus()
+
+
+@router.get("/datasets")
+def datasets():
+    """可训练的数据集 —— 审核页导出后落在 ``state/datasets/`` 的成品。
+
+    空列表是**正常**的(还没导出过),前端据此渲染引导而不是报错。
+    """
+    return list_datasets()
+
+
+@router.get("/runs")
+def runs():
+    """训练产物(checkpoints)。目录不存在时返回空列表,不是 404。"""
+    return list_runs()
+
+
+@router.get("/ready")
+def ready():
+    """各项目离「可以导出」还有多远 —— 训练页「到点提醒」用。
+
+    判据:**已通过集数达到项目设置的采集上限**(``params.target_episodes``)。
+    到点之后只**提醒**,不自动导出 —— 理由见 ``app/training/projects.py``。
+    """
+    return list_projects_progress()
+
+
+@router.get("/runs/{run_name}/checkpoints/{step}/files/{name:path}")
+def download_checkpoint_file(run_name: str, step: str, name: str):
+    """下载 checkpoint 里的单个文件。
+
+    ``{name:path}`` 而不是 ``{name}``:要下的文件在子目录里
+    (``pretrained_model/model.safetensors``),默认的路径参数不匹配斜杠。
+
+    **安全性由 ``resolve_checkpoint_file`` 保证** —— 它只在扫描出的真实文件清单里
+    按名精确匹配,不做路径拼接,所以构造不出清单外的路径(比如 ``../../etc/passwd``)。
+    详见那个函数的 docstring。
+
+    单个文件而不是打包 zip:一个 checkpoint 约 600MB,其中 ``training_state/``
+    (优化器状态,约 400MB)**只在续训时有用**,拿去推理/部署只需要
+    ``pretrained_model/``(约 200MB)。让用户按需下载,比强制他拉一个 600MB 的包好。
+    """
+    path = resolve_checkpoint_file(run_name, step, name)
+    if path is None or not path.is_file():
+        raise HTTPException(status_code=404, detail="No such checkpoint file")
+    # filename 只取最后一段 —— 让浏览器存成 model.safetensors 而不是把整条相对路径
+    # 当成文件名(带斜杠的文件名在多数系统上写不出来)。
+    return FileResponse(path, filename=path.name)