sync processor from GitLab 32d515b: glove display fixes, GPU acceleration, AI annotation propose-clip fix

.gitattributes

@@ -41,3 +41,6 @@ collector/**/*.jpg filter=lfs diff=lfs merge=lfs -text
 collector/**/*.png filter=lfs diff=lfs merge=lfs -text
 collector/**/*.bmp filter=lfs diff=lfs merge=lfs -text
 collector/**/*.task filter=lfs diff=lfs merge=lfs -text
+
+# processor 文档截图走 LFS(HF 拒绝非 LFS 二进制)
+processor/**/*.png filter=lfs diff=lfs merge=lfs -text

processor/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 更新日志
+
+## 1.7.0(2026-09-08)
+
+- 文档:中英文使用文档重构,补充各页面带标注截图与引导图
+- 部署:uvicorn + worker 开机自启(systemd),任务队列不再因 worker 未启动而积压
+- 其他:.gitignore 增加大目录防误传规则
+
+## 1.6.9(2026-09-07)
+
+- 深度预览预热扩展、导出链路优化(本地构建/指纹复用)、下载 gzip 修复

processor/README.md

@@ -1,13 +1,15 @@
-# Data Acquisition
+# processor
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-> Documentation: 2026-09-03  ·  Backend: `1.6.8`  ·  Web frontend: `1.5.6`
+> Documentation: 2026-09-02  ·  Backend: `1.6.8`  ·  Web frontend: `1.5.6`
 
-Data Acquisition is EgoData's service for data capture, processing, review, and export. It is
+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,
 an asynchronous Worker, Web review pages, and Workflow Studio.
 
+> Beginners: start with the [illustrated user guide](docs/en/README.md).
+
 ```text
 Capture upload → Project matching → Workflow processing → AI/Human review → LeRobot/HDF5 export
 ```
@@ -16,7 +18,7 @@ Capture upload → Project matching → Workflow processing → AI/Human review
 
 - [System overview](#1-system-overview)
 - [Installation and startup](#7-installation-and-startup)
-- [Code layout and repository tree](#2-code-layout-and-repository-tree)
+- [Code layout](#2-code-layout)
 - [Project data structure](#3-project-data-structure)
 - [Video data specification](#4-video-data-specification)
 - [Workflow modules](#5-workflow-modules)
@@ -54,66 +56,30 @@ Web review pages
 LeRobot v2.1 / v3.0 or HDF5
 ```
 
-## 2. Code layout and repository tree
+The local `processor/` directory is the only source of frontend and backend code. The
+remote server provides data storage or SFTP access only; its deprecated frontend and backend
+code must not be used as the project source.
 
-<details>
-<summary>Click to expand: source tree and runtime directories</summary>
+## 2. Code layout
 
-The current maintained source tree is shown below. Runtime data, caches, virtual environments,
-local backups, test exports, and downloaded model weights are intentionally omitted.
+<details>
+<summary>Click to expand: code layout</summary>
 
 ```text
-Data Acquisition/
-├── app/
-│   ├── api/                          # Project, workflow, user, and Worker APIs
-│   ├── processing/
-│   │   ├── black_glove/              # Black-glove detection, tracking, and pose backend
-│   │   └── modules/                  # RGB, RGB-D, stereo, hand, glove, review, and export nodes
-│   ├── prompts/                      # AI annotation prompts and vocabularies
-│   ├── routes/                       # Page, session, video, annotation, and export routes
-│   ├── ai_annotation.py              # Local/API VLM annotation pipeline
-│   ├── browser_preview.py             # Browser preview metadata and media preparation
-│   ├── export_engine.py               # Export job orchestration
-│   ├── hdf5_export.py                 # HDF5 dataset writer
-│   ├── lerobot_export.py              # LeRobot v3.0 exporter and metadata writer
-│   ├── lerobot_v21.py                 # LeRobot v2.1 normalization support
-│   ├── project_dataset.py              # Canonical project and Episode operations
-│   ├── storage.py / remote_storage.py # Local and SFTP-backed storage
-│   ├── workflow_*.py                  # Workflow schema, binding, and dispatch
-│   ├── models.py / database.py         # Runtime state models and persistence
-│   └── main.py                         # FastAPI application entry point
-├── worker/
-│   ├── runner.py                      # Job claim, heartbeat, execution, and callback loop
-│   ├── client.py                      # Backend Worker API client
-│   └── README.md                      # Worker-specific notes
+processor/
+├── app/                    # FastAPI, storage, workflows, processing, and export logic
+├── worker/                 # Asynchronous processing Worker
+├── scripts/                # Deployment, startup, checks, and maintenance scripts
 ├── web/
-│   ├── templates/                     # Server-rendered application pages
-│   ├── static/
-│   │   ├── js/                        # Player, depth preview, overlays, review, and UI JS
-│   │   └── workflow-studio/            # Built Workflow Studio assets served by FastAPI
-│   └── workflow-studio/
-│       └── src/
-│           ├── api/                   # Frontend API clients
-│           ├── components/             # Canvas, nodes, palette, drawer, and settings UI
-│           ├── store/                  # Workflow and UI state stores
-│           └── App.tsx                 # Workflow Studio application root
-├── scripts/                           # Setup, startup, migration, and maintenance scripts
-│   ├── run_backend_linux.sh           # Linux FastAPI startup
-│   ├── run_worker_linux.sh            # Linux Worker startup
-│   ├── hot_reload_backend.py          # Development backend reload supervisor
-│   ├── hot_reload_worker.py           # Development Worker reload supervisor
-│   ├── migrate_*.py / repack_*.py      # Dataset migration and repair tools
-│   └── systemd/                       # Linux service templates
-├── tests/
-│   └── test_depth_codec.py             # 12-bit depth codec tests
-├── requirements*.txt                  # Python dependency manifests
-├── deploy.py                          # Cross-platform deployment entry point
-├── deploy.sh / deploy.bat             # Linux and Windows deployment entry points
-├── Dockerfile / .dockerignore         # Container build files
-├── .env.example                       # Safe configuration template
-├── .gitignore                         # Runtime data, secrets, models, and cache exclusions
-├── README.md                          # English documentation
-└── README.zh-CN.md                    # Chinese documentation
+│   ├── templates/          # Web page templates
+│   ├── static/             # CSS, JavaScript, and frontend build artifacts
+│   └── workflow-studio/    # React + Vite workflow editor source
+├── tests/                  # Automated tests
+├── requirements*.txt       # Python dependency manifests
+├── deploy.py               # Cross-platform deployment entry point
+├── deploy.sh               # Linux deployment entry point
+├── deploy.bat              # Windows deployment entry point
+└── .env.example            # Configuration template
 ```
 
 Runtime data is stored under `STORAGE_DIR` by default:
@@ -122,9 +88,7 @@ Runtime data is stored under `STORAGE_DIR` by default:
 data/
 ├── sessions/               # Project datasets
 ├── state/                  # System state, queues, run records, and export jobs
-├── logs/                   # Runtime and archive-sync logs
-├── .meta-history/          # Metadata migration rollback snapshots
-└── tmp/                    # Upload, AI, and Worker temporary files
+└── tmp/                    # Upload and Worker temporary files
 ```
 
 Runtime data, model weights, archives, credentials, and virtual environments must not be
@@ -132,7 +96,6 @@ committed to Git. Dependency manifests such as `requirements*.txt` and `package.
 kept in the repository.
 
 </details>
-
 ## 3. Project data structure
 
 <details>
@@ -211,7 +174,7 @@ RGB and is never duplicated alongside the RGB stream.
 New metric-depth videos use:
 
 ```text
-HEVC (H.265) in MP4
+HEVC (H.265) in MP4 / hvc1 / gray12le / qp=6 / range=full
 ```
 
 The depth video stores 12-bit logarithmic depth codes, not pseudo-color images:
@@ -224,11 +187,6 @@ The corresponding feature in `meta/info.json` is marked with `video.is_depth_map
 depth encoding parameters. Readers dequantize the codes back to millimeters. The original depth
 video is preserved during processing and export.
 
-Depth is never exported as a JET/RGB pseudo-color video. Exported depth remains a single-channel
-`gray12le` video containing the original 12-bit logarithmic codes. The frontend must use the
-`codes_to_heatmap_bgr()` rule for decoded depth codes; it must not quantize decoded codes a second
-time as if they were millimeter values.
-
 ### Frontend depth preview
 
 Pseudo-color depth is used only for browser preview and is never written back to the dataset:
@@ -388,17 +346,6 @@ RGB video in the browser; a second skeleton video is not saved. System-level run
 under `data/state/runs/`, and temporary export products under `data/state/exports/`; neither is
 part of the project dataset directory.
 
-Glove tactile data is kept as fixed-size numeric arrays in the Parquet data, for example
-`observation.tactile.left` and `observation.tactile.right` with shape `[256]`. The current
-LeRobot training export does not generate or retain tactile MP4 files. Tactile visualization is a
-frontend preview concern; it is not required as a video feature by the LeRobot export.
-
-The export module supports LeRobot v2.1 and v3.0. A v3.0 export is directly readable by the
-current official LeRobot reader. A v2.1 export follows the official v2.1 layout and must be
-converted with the official `convert_dataset_v21_to_v30` tool before using a v3.0 reader.
-Batch export creates one dataset directory per selected Episode or project selection; each output
-contains only the canonical `data/`, `meta/`, and `videos/` directories.
-
 The upload archive lifecycle is: receive → extract → normalize → write to project → validate →
 update status. Temporary upload files and extraction directories are cleaned only after extraction,
 atomic commit, and validation all succeed. On failure, staging content is retained for retry and
@@ -411,7 +358,7 @@ diagnosis.
 ### Linux
 
 ```bash
-cd "Data Acquisition"
+cd "processor"
 cp .env.example .env
 # Edit .env and set API_KEY, WORKER_API_KEY, JWT_SECRET, and storage settings.
 chmod +x deploy.sh
@@ -432,14 +379,14 @@ model, and endpoint in the `AI Annotation` settings in Workflow Studio.
 ### Windows
 
 ```bat
-cd /d "Data Acquisition"
+cd /d "processor"
 copy .env.example .env && deploy.bat
 ```
 
 ### Start the backend manually
 
 ```bash
-cd "Data Acquisition"
+cd "processor"
 source .venv-linux/bin/activate
 export PYTHONPATH="$PWD"
 ./scripts/run_backend_linux.sh
@@ -454,7 +401,7 @@ uvicorn app.main:app --host 0.0.0.0 --port 8000
 ### Start the Worker
 
 ```bash
-cd "Data Acquisition"
+cd "processor"
 export EGODATA_SERVER_URL=http://127.0.0.1:8000
 export EGODATA_WORKER_API_KEY='same Worker API key as the server'
 ./scripts/run_worker_linux.sh
@@ -466,7 +413,7 @@ independent and must not be copied between operating systems.
 ### Workflow Studio
 
 ```bash
-cd "Data Acquisition/web/workflow-studio"
+cd "processor/web/workflow-studio"
 npm ci
 npm run dev
 ```
@@ -484,7 +431,7 @@ The build output is written to `web/static/workflow-studio/` and served by FastA
 <details>
 <summary>Click to expand: environment variables and security configuration</summary>
 
-Configuration is stored in `Data Acquisition/.env` or environment variables and must not be
+Configuration is stored in `processor/.env` or environment variables and must not be
 committed:
 
 | Setting | Purpose |
@@ -505,22 +452,6 @@ credentials in logs, workflow JSON, frontend code, or documentation.
 
 </details>
 
-### GitHub publication checklist
-
-Before publishing this directory:
-
-```bash
-git status --short --ignored
-git check-ignore -v .env data .backups .venv-linux models
-git ls-files | rg -i '(^|/)(\.env|.*secret.*|.*token.*|.*credential.*|.*password.*|.*\.pem|.*\.key)$'
-```
-
-The repository excludes runtime datasets, temporary files, local state, backups, virtual
-environments, archives, and secrets through `.gitignore`. Keep `.env` local and commit only
-`.env.example`. Do not use `git add -f` for `data/`, `.backups/`, model weights, or generated
-exports. If a real credential was ever placed in a tracked file, rotate it before publishing;
-removing it from the working tree alone does not remove it from Git history.
-
 ## 9. API
 
 <details>
@@ -559,7 +490,7 @@ The running FastAPI OpenAPI document is the authoritative API contract.
 Backend and Worker checks:
 
 ```bash
-cd "Data Acquisition"
+cd "processor"
 python -m compileall app worker
 python deploy.py --check-only
 PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q tests/test_depth_codec.py
@@ -568,7 +499,7 @@ PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q tests/test_depth_codec.py
 Frontend check:
 
 ```bash
-cd "Data Acquisition/web/workflow-studio"
+cd "processor/web/workflow-studio"
 npm run build
 ```
 

processor/README.zh-CN.md

@@ -1,12 +1,14 @@
-# Data Acquisition
+# processor
 
 [中文](README.zh-CN.md) | [English](README.md)
 
 > 文档版本：2026-09-02  ·  后端版本：`1.6.8`  ·  WEB 前端版本：`1.5.6`
 
-Data Acquisition 是 EgoData 的数据采集、处理、审核和导出服务，面向具身智能与机器人
+processor 是 EgoData 的数据采集、处理、审核和导出服务，面向具身智能与机器人
 操作数据。系统由 FastAPI 后端、异步 Worker、Web 审核页面和 Workflow Studio 组成。
 
+> 项目文档：[项目文档介绍](docs/README.md)。
+
 ```text
 采集端上传 → 项目匹配 → 工作流处理 → AI/人工审核 → LeRobot/HDF5 导出
 ```
@@ -53,13 +55,16 @@ Web 审核页面
 LeRobot v2.1 / v3.0 或 HDF5
 ```
 
+本机 `processor/` 目录是前端和后端代码的唯一来源。远端服务器只提供数据目录
+或 SFTP 存储，不作为本项目的前端、后端代码来源；服务器中的旧代码已废弃。
+
 ## 2. 代码目录
 
 <details>
 <summary>点击展开：代码目录</summary>
 
 ```text
-Data Acquisition/
+processor/
 ├── app/                    # FastAPI、存储、工作流、处理和导出逻辑
 ├── worker/                 # 异步处理 Worker
 ├── scripts/                # 部署、启动、检查和数据维护脚本
@@ -88,7 +93,6 @@ data/
 `package.json` 等依赖清单应保留在仓库中。
 
 </details>
-
 ## 3. 项目数据结构
 
 <details>
@@ -165,7 +169,7 @@ RGB 和 Depth 始终作为独立数据流保存。纯 Depth 流不会被当作 R
 新的真实深度视频统一使用：
 
 ```text
-HEVC (H.265) in MP4
+HEVC (H.265) in MP4 / hvc1 / gray12le / qp=6 / range=full
 ```
 
 深度视频保存的是 12-bit 对数深度码，不是伪彩色图像：
@@ -342,7 +346,7 @@ meta/episodes/chunk-000/episode_000000.parquet
 ### Linux
 
 ```bash
-cd "Data Acquisition"
+cd "processor"
 cp .env.example .env
 # 编辑 .env，设置 API_KEY、WORKER_API_KEY、JWT_SECRET 和存储配置。
 chmod +x deploy.sh
@@ -363,14 +367,14 @@ python deploy.py --no-services      # 前台运行，不安装自启动服务。
 ### Windows
 
 ```bat
-cd /d "Data Acquisition"
+cd /d "processor"
 copy .env.example .env && deploy.bat
 ```
 
 ### 手动启动后端
 
 ```bash
-cd "Data Acquisition"
+cd "processor"
 source .venv-linux/bin/activate
 export PYTHONPATH="$PWD"
 ./scripts/run_backend_linux.sh
@@ -385,7 +389,7 @@ uvicorn app.main:app --host 0.0.0.0 --port 8000
 ### 启动 Worker
 
 ```bash
-cd "Data Acquisition"
+cd "processor"
 export EGODATA_SERVER_URL=http://127.0.0.1:8000
 export EGODATA_WORKER_API_KEY='与服务端一致的 Worker API Key'
 ./scripts/run_worker_linux.sh
@@ -397,7 +401,7 @@ Windows 使用 `scripts/run_worker_windows.ps1`。Linux 和 Windows 的虚拟环
 ### Workflow Studio
 
 ```bash
-cd "Data Acquisition/web/workflow-studio"
+cd "processor/web/workflow-studio"
 npm ci
 npm run dev
 ```
@@ -415,7 +419,7 @@ npm run build
 <details>
 <summary>点击展开：环境变量和安全配置</summary>
 
-配置写入 `Data Acquisition/.env` 或环境变量，不提交到仓库：
+配置写入 `processor/.env` 或环境变量，不提交到仓库：
 
 | 配置 | 作用 |
 | --- | --- |
@@ -472,7 +476,7 @@ GET /openapi.json
 后端和 Worker 基础检查：
 
 ```bash
-cd "Data Acquisition"
+cd "processor"
 python -m compileall app worker
 python deploy.py --check-only
 PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q tests/test_depth_codec.py
@@ -481,7 +485,7 @@ PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q tests/test_depth_codec.py
 前端检查：
 
 ```bash
-cd "Data Acquisition/web/workflow-studio"
+cd "processor/web/workflow-studio"
 npm run build
 ```
 

processor/app/ai_annotation.py

@@ -2265,6 +2265,33 @@ async def _upload_video_file(client: httpx.AsyncClient, upload_base: str,
     return None
 
 
+def _slice_propose_clip(video_path: Path, out_dir: Path) -> Path | None:
+    """整片规划专用切片:降采样到 ≤640px / 5fps 低码率。
+
+    长批次(如 305s)原分辨率整片 base64 内联会打出 50MiB+ 的 JSON,
+    租用网关直接把连接掐断(ReadError)。规划阶段只需要看清动作边界,
+    5fps/640px 足够;时长不变,start_s/end_s 仍映射源视频时间。
+    """
+    import subprocess
+
+    out = out_dir / "propose_clip.mp4"
+    cmd = ["ffmpeg", "-y", "-loglevel", "error",
+           "-i", str(video_path),
+           "-vf", "scale='min(640,iw)':-2,fps=5",
+           "-c:v", "libx264", "-crf", "30", "-preset", "veryfast",
+           "-pix_fmt", "yuv420p",
+           "-movflags", "+faststart", "-an", str(out)]
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        print(f"[ai_annotation] propose clip error: {exc}")
+        return None
+    if r.returncode != 0 or not out.is_file() or out.stat().st_size < 1024:
+        print(f"[ai_annotation] propose clip failed: {r.stderr[:300]}")
+        return None
+    return out
+
+
 def _inline_video_data_url(clip: Path, *,
                            max_bytes: int = API_INLINE_VIDEO_MAX_BYTES,
                            label: str = "API VLM") -> str:
@@ -2414,7 +2441,7 @@ async def _vlm_propose_api(video_path: Path, fps: float, total_frames: int,
         raise VLMAnnotationError("configuration_error", err)
     whole = {"start_frame_index": 0,
              "end_frame_index": max(0, total_frames - 1)}
-    clip = _slice_segment_clip(video_path, fps, whole, None, None, tmp_dir)
+    clip = _slice_propose_clip(video_path, tmp_dir)
     if clip is None:
         raise VLMAnnotationError("video_slice_failed", "API VLM 输入视频切片失败")
     try:
@@ -2425,6 +2452,8 @@ async def _vlm_propose_api(video_path: Path, fps: float, total_frames: int,
     except ValueError as exc:
         raise VLMAnnotationError(
             "api_video_too_large", str(exc)) from exc
+    # propose 剪辑统一 5fps,fps 提示与剪辑实际一致(时长不变,时间轴对齐)
+    propose_fps = 5.0
     prompts = _prompts()
     template = prompts.get("plan_prompt_zh" if lang == "zh" else "plan_prompt_en")
     vocab = prompts.get("vocab_zh" if lang == "zh" else "vocab_en", "")
@@ -2437,7 +2466,7 @@ async def _vlm_propose_api(video_path: Path, fps: float, total_frames: int,
         "\n\n输出要求：最终答案必须放在 assistant 的 content 字段中，"
         "只输出完整 JSON，不要把答案只放在 reasoning 或思考内容中。")
     content = [
-        _api_video_content(vlm_cfg, video_ref, fps),
+        _api_video_content(vlm_cfg, video_ref, propose_fps),
         {"type": "text", "text": prompt},
     ]
     try:

processor/app/api/projects.py

@@ -576,6 +576,15 @@ def get_hierarchy(
                 if s in n["project"]["name"].lower()
                 or any(s in e["name"].lower() or s in e["id"].lower() for e in n["episodes"])]
 
+    # 预热深度预览:列表可见批次在用户点开前后台生成(尽力而为)
+    try:
+        from app.routes.ingestion import _trigger_depth_prewarm
+
+        _trigger_depth_prewarm(
+            [e["id"] for node in tree for e in node.get("episodes", [])])
+    except Exception:
+        pass
+
     return {"projects": tree, "total": sum(len(n["episodes"]) for n in tree)}
 
 

processor/app/browser_preview.py

@@ -13,10 +13,12 @@ the configured storage directory.
 from __future__ import annotations
 
 import hashlib
+import json
 import os
 import shutil
 import subprocess
 import threading
+import time
 from pathlib import Path
 
 from app.config import settings
@@ -25,6 +27,9 @@ from app.config import settings
 _LOCKS: dict[str, threading.Lock] = {}
 _LOCKS_GUARD = threading.Lock()
 
+_FASTSTART_CACHE: dict[str, bool] = {}
+_FASTSTART_CACHE_LOCK = threading.Lock()
+
 
 def _cache_root() -> Path:
     root = settings.upload_staging_root / "browser-preview"
@@ -43,6 +48,296 @@ def _lock_for(key: str) -> threading.Lock:
         return _LOCKS.setdefault(key, threading.Lock())
 
 
+# ── Local source mirror (depth streams) ──────────────────────────────
+# Depth videos live on the SSHFS mount, where random reads for seek/decode
+# cost seconds.  A bit-identical local copy turns every later decode into a
+# local-disk read.  This is a disposable transport cache of the SOURCE file
+# (never a derived/colorized asset); the authoritative stream stays in the
+# configured storage directory.
+
+_MIRROR_MAX_BYTES = 8 * 1024 ** 3
+_MIRROR_INFLIGHT: set[str] = set()
+_MIRROR_INFLIGHT_GUARD = threading.Lock()
+
+
+def _mirror_root() -> Path:
+    root = settings.upload_staging_root / "depth-mirror"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def _prune_mirror(keep: Path) -> None:
+    """Remove oldest mirror files beyond the byte budget (LRU by mtime)."""
+    try:
+        files = [p for p in _mirror_root().iterdir()
+                 if p.is_file() and p.suffix == ".mp4"]
+    except OSError:
+        return
+    total = sum(p.stat().st_size for p in files if p != keep) + (
+        keep.stat().st_size if keep.is_file() else 0)
+    if total <= _MIRROR_MAX_BYTES:
+        return
+    for path in sorted(files, key=lambda p: p.stat().st_mtime_ns):
+        if path == keep or total <= _MIRROR_MAX_BYTES:
+            continue
+        try:
+            total -= path.stat().st_size
+            path.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def _copy_mirror(source: Path, destination: Path, key: str) -> None:
+    """Background copy to a temp file, then atomic rename."""
+    temporary = destination.with_suffix(".part")
+    temporary.unlink(missing_ok=True)
+    try:
+        shutil.copy2(source, temporary)
+        if not temporary.is_file() or temporary.stat().st_size <= 0:
+            raise RuntimeError("mirror copy produced an empty file")
+        os.replace(temporary, destination)
+        _prune_mirror(destination)
+    except (OSError, RuntimeError):
+        temporary.unlink(missing_ok=True)
+    finally:
+        with _MIRROR_INFLIGHT_GUARD:
+            _MIRROR_INFLIGHT.discard(key)
+
+
+def _write_turbo_cube(path: Path) -> None:
+    """Write the static 4096-entry 1D Turbo cube used by the transcode.
+
+    4096 entries keep the range mapping at 12-bit precision: a 256-entry LUT
+    evaluated after an 8-bit intermediate caused visible banding (only ~58
+    distinct color levels survived the chain instead of ~173).
+    """
+    if path.is_file():
+        return
+    from app.lerobot_v21 import turbo_lut
+
+    lut = turbo_lut(4096)
+    lines = ["TITLE Turbo", "LUT_1D_SIZE 4096", "",
+             "DOMAIN_MIN 0 0 0", "DOMAIN_MAX 1 1 1", ""]
+    for r, g, b in lut:
+        lines.append(f"{r / 255.0:.6f} {g / 255.0:.6f} {b / 255.0:.6f}")
+    path.write_text("\n".join(lines) + "\n", encoding="ascii")
+
+
+def _depth_stats_path(source: Path) -> Path:
+    key = _cache_key(source)
+    return _cache_root() / f"depth-{key}.stats.json"
+
+
+def read_depth_stats(source: Path) -> dict | None:
+    """Disk-persisted q01/q99 bounds for ``source`` (same fingerprint key).
+
+    Written once by :func:`_ensure_depth_stats` during preview generation;
+    survives restarts so neither the stats endpoint nor a re-transcode ever
+    pays a second full-stream decode for the same source file.
+    """
+    try:
+        path = _depth_stats_path(source)
+        if not path.is_file():
+            return None
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if (isinstance(data, dict)
+                and isinstance(data.get("q01"), (int, float))
+                and isinstance(data.get("q99"), (int, float))
+                and float(data["q99"]) > float(data["q01"])):
+            return data
+    except (OSError, ValueError):
+        pass
+    return None
+
+
+def _histogram_depth_stats(source: Path) -> dict | None:
+    """Single-decode q01/q99 code bounds via a streaming 4096-bin histogram.
+
+    The stream is read as raw gray12le codes and histogrammed in O(1)
+    memory; percentiles are exact over every decoded pixel.  The previous
+    ``select=`` sampling pass decoded the whole stream anyway while keeping
+    only a fraction of the frames, so nothing is lost.
+    """
+    import numpy as np
+
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        return None
+    hist = np.zeros(4096, dtype=np.int64)
+    proc = subprocess.Popen(
+        [ffmpeg, "-v", "error", "-i", str(source), "-map", "0:v:0",
+         "-f", "rawvideo", "-pix_fmt", "gray12le", "-"],
+        stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+    try:
+        while True:
+            chunk = proc.stdout.read(8 * 1024 * 1024)
+            if not chunk:
+                break
+            values = np.frombuffer(chunk, dtype="<u2")
+            hist += np.bincount(values.astype(np.int64), minlength=4096)[:4096]
+    finally:
+        try:
+            proc.stdout.close()
+        except OSError:
+            pass
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+    total = int(hist.sum())
+    if total < 2:
+        return None
+    cumulative = np.cumsum(hist)
+    q01 = float(np.searchsorted(cumulative, total * 0.01, side="right"))
+    q99 = float(np.searchsorted(cumulative, total * 0.99, side="right"))
+    return {"q01": q01, "q99": q99, "total_pixels": total}
+
+
+def _ensure_depth_stats(source: Path, local: Path | None = None) -> dict | None:
+    """Return q01/q99 for ``source``, computed once and persisted to disk.
+
+    ``source`` is the authoritative path used for the cache fingerprint;
+    ``local`` (the transport mirror) is decoded when it is ready so the pass
+    never competes with an SSHFS random read.
+    """
+    cached = read_depth_stats(source)
+    if cached is not None:
+        return cached
+    with _lock_for(f"stats:{_cache_key(source)}"):
+        cached = read_depth_stats(source)
+        if cached is not None:
+            return cached
+        stats = _histogram_depth_stats(local or source)
+        if stats is None:
+            return None
+        try:
+            _depth_stats_path(source).write_text(
+                json.dumps(stats), encoding="utf-8")
+        except OSError:
+            pass
+        return stats
+
+
+def depth_preview_exists(source: Path) -> bool:
+    """Cheap cache-hit check for prewarm scheduling (no transcode)."""
+    try:
+        destination = _cache_root() / f"depth-{_cache_key(Path(source))}.mp4"
+        return destination.is_file() and destination.stat().st_size > 0
+    except OSError:
+        return False
+
+
+def ensure_depth_h264_preview(source: Path, q01: float = 0.0,
+                              q99: float = 4095.0) -> Path:
+    """Generate (once) an 8-bit Turbo-colored H.264 preview of a depth stream.
+
+    The browser display pipeline already quantizes codes into an 8-bit Turbo
+    ramp; this bakes the identical mapping (same clamp/scale math, same
+    colormap) into a disposable local MP4 so the review page plays it through
+    a native ``<video>`` element — instant open, native seek, no per-open
+    12-bit decode or 229MB raw-code transfer.  The preview never enters the
+    dataset; the canonical gray12le stream stays authoritative.
+    """
+    source = Path(source)
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        raise RuntimeError("ffmpeg is required to build depth previews")
+    key = _cache_key(source)
+    destination = _cache_root() / f"depth-{key}.mp4"
+    if destination.is_file() and destination.stat().st_size > 0:
+        return destination
+    with _lock_for(key):
+        if destination.is_file() and destination.stat().st_size > 0:
+            return destination
+        q01 = float(q01 if q01 is not None else 0.0)
+        q99 = float(q99 if q99 is not None else 4095.0)
+        span = max(q99 - q01, 1.0)
+        # Decode from the local mirror when it is ready; SSHFS random reads
+        # during the stats/transcode passes otherwise dominate generation.
+        # Wait briefly for the background copy — a ~6s copy is cheaper than
+        # decoding the whole stream over the mount.
+        original = source
+        try:
+            source = ensure_local_mirror(source, wait_seconds=45)
+        except Exception:
+            pass
+        if q01 <= 0 and q99 >= 4095:
+            # No cached adaptive bounds: compute them once from a single
+            # decode (persisted next to the preview, keyed on the
+            # authoritative source path) so the ramp matches the former
+            # q01/q99 colorization and never re-decodes for the same file.
+            stats = _ensure_depth_stats(original, source)
+            if stats and float(stats.get("q99") or 0) > float(stats.get("q01") or 0):
+                q01 = float(stats["q01"])
+                q99 = float(stats["q99"])
+            span = max(q99 - q01, 1.0)
+        # Map the range in the native 12-bit domain (the lut filter evaluates
+        # ``val`` at the input depth), then apply a 4096-entry Turbo cube:
+        # quantizing through an 8-bit intermediate produced visible banding.
+        cube = _cache_root() / "turbo.cube"
+        _write_turbo_cube(cube)
+        temporary = destination.with_name(
+            f".{destination.stem}.{os.getpid()}.part.mp4")
+        temporary.unlink(missing_ok=True)
+        try:
+            subprocess.run(
+                [ffmpeg, "-y", "-loglevel", "error", "-i", str(source),
+                 "-vf", (f"lut=y='clip((val-{q01:.2f})*4095/{span:.2f},0,4095)',"
+                         f"lut1d=file={cube},format=yuv420p"),
+                 "-an", "-c:v", "libx264", "-preset", "veryfast",
+                 "-crf", "18", "-g", "25", "-keyint_min", "25",
+                 "-sc_threshold", "0", "-movflags", "+faststart",
+                 str(temporary)],
+                check=True, capture_output=True, timeout=3600,
+            )
+            if not temporary.is_file() or temporary.stat().st_size == 0:
+                raise RuntimeError("ffmpeg produced an empty depth preview")
+            os.replace(temporary, destination)
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError("depth preview transcode timed out") from exc
+        except subprocess.CalledProcessError as exc:
+            detail = (exc.stderr or b"").decode("utf-8", errors="replace")[-500:]
+            raise RuntimeError(f"depth preview transcode failed: {detail}") from exc
+        finally:
+            temporary.unlink(missing_ok=True)
+    return destination
+
+
+def ensure_local_mirror(source: Path, wait_seconds: float = 0.0) -> Path:
+    """Return a local copy of ``source`` when ready, else ``source``.
+
+    The first request for a video schedules an asynchronous copy and keeps
+    serving from the original path; once the mirror lands (atomic rename),
+    every later call — including the next frame of the same request stream —
+    returns the local path.  The key includes size+mtime, so a reprocessed
+    MP4 silently invalidates the old mirror.
+
+    ``wait_seconds > 0`` polls for the copy to land before falling back to
+    the remote path (used by preview generation, whose decode pass is much
+    faster from local disk than over SSHFS).
+    """
+    source = Path(source)
+    key = _cache_key(source)
+    destination = _mirror_root() / f"{key}.mp4"
+    if destination.is_file() and destination.stat().st_size > 0:
+        return destination
+    with _MIRROR_INFLIGHT_GUARD:
+        if key not in _MIRROR_INFLIGHT:
+            _MIRROR_INFLIGHT.add(key)
+            threading.Thread(
+                target=_copy_mirror, args=(source, destination, key),
+                daemon=True,
+            ).start()
+    if wait_seconds > 0:
+        deadline = time.monotonic() + wait_seconds
+        while time.monotonic() < deadline:
+            if destination.is_file() and destination.stat().st_size > 0:
+                return destination
+            time.sleep(0.25)
+        return destination if destination.is_file() else source
+    return source
+
+
 def _is_h264_yuv420(source: Path) -> bool:
     """Avoid re-encoding an already browser-compatible source."""
     ffprobe = shutil.which("ffprobe")
@@ -61,17 +356,98 @@ def _is_h264_yuv420(source: Path) -> bool:
         return False
 
 
+def _probe_faststart(source: Path) -> bool:
+    """moov 在 mdat 之前 = faststart(浏览器可流式播放,否则播放会早停)。
+
+    只读前几个顶层 box 的头部,moov/mdat 先后顺序即可判定;探测失败
+    保守返回 True(透传原文件,维持旧行为)。结果按源文件指纹记忆。
+    """
+    key = _cache_key(source)
+    with _FASTSTART_CACHE_LOCK:
+        cached = _FASTSTART_CACHE.get(key)
+        if cached is not None:
+            return cached
+    result = True
+    try:
+        with open(source, "rb") as handle:
+            handle.seek(0, os.SEEK_END)
+            size = handle.tell()
+            handle.seek(0)
+            for _ in range(8):
+                if handle.tell() > size - 8:
+                    break
+                pos = handle.tell()
+                header = handle.read(8)
+                if len(header) < 8:
+                    break
+                length = int.from_bytes(header[:4], "big")
+                box_type = header[4:8]
+                if length == 1:
+                    ext = handle.read(8)
+                    length = int.from_bytes(ext, "big") if len(ext) == 8 else 0
+                if length == 0:
+                    length = size - pos
+                if length < 8:
+                    break
+                if box_type == b"moov":
+                    result = True
+                    break
+                if box_type == b"mdat":
+                    result = False
+                    break
+                handle.seek(pos + length)
+    except OSError:
+        result = True
+    with _FASTSTART_CACHE_LOCK:
+        _FASTSTART_CACHE[key] = result
+    return result
+
+
+def _remux_faststart(source: Path, destination: Path) -> None:
+    """``-c copy -movflags +faststart`` 容器重排(不重编码,字节级无损)。
+
+    moov 索引移到文件头,浏览器无需跳到文件尾即可开始流式播放。
+    """
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        raise RuntimeError("ffmpeg is required for faststart remux")
+    temporary = destination.with_name(
+        f".{destination.stem}.{os.getpid()}.part.mp4")
+    temporary.unlink(missing_ok=True)
+    try:
+        subprocess.run(
+            [ffmpeg, "-y", "-loglevel", "error", "-i", str(source),
+             "-map", "0:v:0", "-an", "-c:v", "copy",
+             "-movflags", "+faststart", str(temporary)],
+            check=True, capture_output=True, timeout=600,
+        )
+        if not temporary.is_file() or temporary.stat().st_size == 0:
+            raise RuntimeError("faststart remux produced an empty file")
+        os.replace(temporary, destination)
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError("faststart remux timed out") from exc
+    except subprocess.CalledProcessError as exc:
+        detail = (exc.stderr or b"").decode("utf-8", errors="replace")[-300:]
+        raise RuntimeError(f"faststart remux failed: {detail}") from exc
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
 def ensure_h264_preview(source: Path) -> Path:
     """Return an H.264/yuv420p MP4 suitable for HTML5 playback.
 
+    Browser-decodable sources are passed through directly when their moov
+    index sits at the front (faststart); non-faststart files are remuxed
+    once into the local cache (``-c copy``, byte-lossless, only the
+    container box order changes) so HTML5 streaming does not stall a few
+    seconds into playback.  Remux failure falls back to the original file.
+
     Callers should run this function via ``asyncio.to_thread`` so a cold
     transcode never blocks FastAPI's event loop.
     """
     source = Path(source)
     if not source.is_file():
         raise FileNotFoundError(f"Video source not found: {source}")
-    if _is_h264_yuv420(source):
-        return source
 
     ffmpeg = shutil.which("ffmpeg")
     if not ffmpeg:
@@ -81,10 +457,22 @@ def ensure_h264_preview(source: Path) -> Path:
     destination = _cache_root() / f"{key}.mp4"
     if destination.is_file() and destination.stat().st_size > 0:
         return destination
+    if _is_h264_yuv420(source) and _probe_faststart(source):
+        return source
 
     with _lock_for(key):
         if destination.is_file() and destination.stat().st_size > 0:
             return destination
+        if _is_h264_yuv420(source):
+            # 非 faststart 的 h264:一次性无损重排 moov 到文件头。
+            # remux 失败回退原文件,绝不阻断播放。
+            try:
+                _remux_faststart(source, destination)
+                if destination.is_file() and destination.stat().st_size > 0:
+                    return destination
+            except Exception:
+                pass
+            return source
 
         # Keep the final .mp4 suffix so ffmpeg can infer the output muxer.
         temporary = destination.with_name(

processor/app/config.py

@@ -7,7 +7,7 @@ from pydantic_settings import BaseSettings
 class Settings(BaseSettings):
     # Database. In local mode this normally points to the server through an
     # SSH tunnel (for example 127.0.0.1:15432).
-    DATABASE_URL: str = "postgresql+asyncpg://user:password@localhost:5432/data_acq"
+    DATABASE_URL: str = "postgresql+asyncpg://odoo:myodoo@172.19.0.2:5432/data_acq"
     DB_CONNECT_TIMEOUT: float = 5.0
     DB_COMMAND_TIMEOUT: float = 10.0
     DB_POOL_TIMEOUT: float = 5.0
@@ -16,12 +16,12 @@ class Settings(BaseSettings):
     # SFTP_ROOT on the storage server.
     STORAGE_DIR: str = "data"
     STORAGE_BACKEND: str = "local"  # local | sftp
-    SFTP_HOST: str = "localhost"
+    SFTP_HOST: str = "192.168.110.41"
     SFTP_PORT: int = 22
-    SFTP_USERNAME: str = ""
+    SFTP_USERNAME: str = "Stouch"
     SFTP_PASSWORD: str = ""
     SFTP_KEY_FILE: str = ""
-    SFTP_ROOT: str = ""
+    SFTP_ROOT: str = "/vol1/docker/odoo-dev/Data Acquisition/data"
     SFTP_KNOWN_HOSTS: str = ""
     SFTP_STRICT_HOST_KEY: bool = False
     SFTP_CONNECT_TIMEOUT: int = 15
@@ -46,7 +46,7 @@ class Settings(BaseSettings):
     # Local server
     HOST: str = "0.0.0.0"
     PORT: int = 8000
-    PUBLIC_BASE_URL: str = "http://127.0.0.1:8000"
+    PUBLIC_BASE_URL: str = "http://192.168.110.41:2586"
     LOG_LEVEL: str = "info"
 
     # Cleaning

processor/app/database.py

@@ -178,7 +178,7 @@ async def get_session() -> AsyncSession:
 async def _seed_default_users():
     """Insert the configurable bootstrap administrator if the table is empty.
 
-    The public template uses a configurable demo account for a first local demo only. Existing
+    The public template uses Root/Root for a first local demo only. Existing
     databases are never modified because seeding stops when any user exists.
     Production deployments should set both bootstrap environment variables to
     private values before the first startup.
@@ -193,9 +193,9 @@ async def _seed_default_users():
         if cnt > 0:
             return  # Already seeded
 
-        username = (os.environ.get("EGODATA_BOOTSTRAP_USERNAME", "demo-admin").strip()
-                    or "demo-admin")
-        password = os.environ.get("EGODATA_BOOTSTRAP_PASSWORD", "change-me")
+        username = (os.environ.get("EGODATA_BOOTSTRAP_USERNAME", "Root").strip()
+                    or "Root")
+        password = os.environ.get("EGODATA_BOOTSTRAP_PASSWORD", "Root")
         email = (os.environ.get("EGODATA_BOOTSTRAP_EMAIL", "").strip()
                  or f"{username.lower()}@egodata.local")
         defaults = [User(

processor/app/lerobot_export.py

@@ -492,6 +492,65 @@ def _probe_video(path: Path) -> tuple[int, float, int, int]:
         return 0, 0.0, 0, 0
 
 
+def _probe_depth_video(path: Path) -> dict:
+    """Probe a depth stream with ffprobe first, OpenCV as fallback.
+
+    OpenCV builds without 12-bit HEVC support silently report zeros for
+    gray12le streams.  ffprobe returns the true pixel format and dimensions;
+    the container duration estimates the frame count when ``nb_frames`` is
+    absent from the stream entry (common for HEVC).
+    """
+    import json
+    import subprocess
+
+    result = {"frames": 0, "fps": 0.0, "width": 0, "height": 0, "pix_fmt": ""}
+    try:
+        completed = subprocess.run(
+            ["ffprobe", "-v", "error", "-select_streams", "v:0",
+             "-show_entries",
+             "stream=codec_name,pix_fmt,width,height,r_frame_rate,nb_frames:"
+             "format=duration",
+             "-of", "json", str(path)],
+            capture_output=True, text=True, timeout=15, check=False,
+        )
+        payload = json.loads(completed.stdout or "{}")
+        streams = payload.get("streams") or []
+        if streams:
+            stream = streams[0]
+            result["pix_fmt"] = str(stream.get("pix_fmt") or "")
+            for name in ("width", "height"):
+                try:
+                    result[name] = int(stream.get(name) or 0)
+                except (TypeError, ValueError):
+                    pass
+            try:
+                result["frames"] = int(stream.get("nb_frames") or 0)
+            except (TypeError, ValueError):
+                pass
+            rate = str(stream.get("r_frame_rate") or "").split("/")
+            try:
+                if len(rate) == 2 and float(rate[1]) > 0:
+                    result["fps"] = float(rate[0]) / float(rate[1])
+            except (TypeError, ValueError, ZeroDivisionError):
+                pass
+        if not result["frames"] and result["fps"] > 0:
+            try:
+                duration = float((payload.get("format") or {}).get("duration") or 0)
+            except (TypeError, ValueError):
+                duration = 0.0
+            if duration > 0:
+                result["frames"] = int(round(duration * result["fps"]))
+    except (OSError, subprocess.SubprocessError, ValueError, TypeError,
+            json.JSONDecodeError):
+        pass
+    count, fps, width, height = _probe_video(path)  # OpenCV fallback
+    result["frames"] = result["frames"] or count
+    result["fps"] = result["fps"] or float(fps or 0.0)
+    result["width"] = result["width"] or int(width or 0)
+    result["height"] = result["height"] or int(height or 0)
+    return result
+
+
 def _copy_depth_video_canonical(source: Path, destination: Path) -> None:
     """Copy a depth stream and normalize HEVC's MP4 sample entry.
 
@@ -1602,7 +1661,8 @@ def build_lerobot_dataset(dataset_name: str, episode_ids: list[str], output_dir:
                           hand_3d_paths: list[str] | None = None,
                           hand_3d_right_paths: list[str] | None = None,
                           version: str = "v3.0",
-                          hand_3d_unit: str | None = None) -> Path:
+                          hand_3d_unit: str | None = None,
+                          progress_callback=None) -> Path:
     """Build a LeRobot dataset (``version`` = "v2.1" | "v3.0").
 
     Depth sources are exported as their preview video (``is_depth_map``)
@@ -1837,19 +1897,31 @@ def build_lerobot_dataset(dataset_name: str, episode_ids: list[str], output_dir:
             destination.mkdir(parents=True, exist_ok=True)
             _copy_depth_video_canonical(depth_path, output_video)
             total_videos += 1
-            _depth_count, depth_fps, depth_width, depth_height = _probe_video(depth_path)
+            depth_probe = _probe_depth_video(depth_path)
+            _depth_count = int(depth_probe.get("frames") or 0)
+            depth_fps = float(depth_probe.get("fps") or fps)
+            depth_width = int(depth_probe.get("width") or 0)
+            depth_height = int(depth_probe.get("height") or 0)
+            # The canonical stream is a single-plane gray12le.  Declare the
+            # channels from the actual pixel format instead of the RGB-loop
+            # default of 3 so the intermediate feature is truthful before
+            # _canonicalize_video_features runs downstream.
+            depth_channels = (
+                1 if depth_probe.get("pix_fmt") in {"gray12le", "gray16le", "gray10le"}
+                else 3
+            )
             episode_video_meta[f"observation.images.{depth_source}"] = (
                 _depth_count, depth_fps or fps)
             has_metric = depth_source in generated_depth
             video_features[f"observation.images.{depth_source}"] = {
                 "dtype": "video",
-                "shape": [depth_height or 0, depth_width or 0, 3],
+                "shape": [depth_height or 0, depth_width or 0, depth_channels],
                 "names": ["height", "width", "channel"],
                 "video_info": {
                     "video.fps": depth_fps or fps,
                     "video.height": depth_height or 0,
                     "video.width": depth_width or 0,
-                    "video.channels": 1,
+                    "video.channels": depth_channels,
                     # 有 metric 流时主键是纯可视化;无 metric(老批次/
                     # 编码失败)才把主键当深度流兜底
                     "video.is_depth_map": not has_metric,
@@ -1946,6 +2018,12 @@ def build_lerobot_dataset(dataset_name: str, episode_ids: list[str], output_dir:
         episode_row_ranges.append((out_episode_index, task_id, frame_count,
                                    len(rows) - frame_count, len(rows)))
         episode_video_meta_records.append(episode_video_meta)
+        if progress_callback is not None:
+            try:
+                progress_callback(done=out_episode_index + 1,
+                                  total_episodes=len(episodes))
+            except Exception:
+                pass  # 进度回调失败不影响导出本身
 
     # 变长异步传感器列固定长度化:官方加载器不支持变长列(实测
     # list<int64> 对声明 int64[1] 直接 cast 失败)。取全数据集最大

processor/app/lerobot_v21.py

@@ -113,6 +113,48 @@ def depth_to_heatmap_bgr(depth_mm):
     return codes_to_heatmap_bgr(quantize_depth(depth_mm))
 
 
+# Turbo colormap (Google) polynomial coefficients — matches Rerun's default
+# depth visualization (blue → cyan → green → yellow → red continuous ramp).
+_TURBO_POLY = {
+    "r": [0.13572138, 4.61539260, -42.66032258, 132.13108234,
+          -152.94239396, 59.28637943],
+    "g": [0.09140261, 2.19418839, 4.84296658, -14.18503333,
+          4.27729857, 2.82956604],
+    "b": [0.10667330, 12.64194608, -60.58204836, 110.36276771,
+          -89.90310912, 27.34824973],
+}
+_TURBO_LUT: list[list[int]] | None = None
+
+
+def turbo_lut(size: int = 256) -> list[list[int]]:
+    """N-entry Google Turbo colormap (RGB), generated once per process.
+
+    The frontend uses 256 entries; the preview transcode uses a 4096-entry
+    cube so the range mapping keeps 12-bit precision (a 256-entry LUT in the
+    8-bit domain caused visible banding on smooth depth gradients).
+    """
+    global _TURBO_LUT
+    if size == 256 and _TURBO_LUT is not None:
+        return _TURBO_LUT
+    lut = []
+    for i in range(size):
+        x = i / max(1, size - 1)
+        rgb = []
+        for channel in ("r", "g", "b"):
+            c = _TURBO_POLY[channel]
+            v = c[0] + x * (c[1] + x * (c[2] + x * (c[3] + x * (c[4] + x * c[5]))))
+            rgb.append(int(max(0, min(255, round(v * 255)))))
+        lut.append(rgb)
+    if size == 256:
+        _TURBO_LUT = lut
+    return lut
+
+
+def turbo_lut_256() -> list[list[int]]:
+    """256-entry Google Turbo colormap (RGB), generated once per process."""
+    return turbo_lut(256)
+
+
 def _depth_video_info_from_path(path: Path) -> dict[str, Any]:
     """Read depth metadata beside a canonical video when available."""
     path = Path(path)
@@ -677,6 +719,7 @@ class DepthVideoReader:
             raise RuntimeError(f"Metric depth video has invalid dimensions: {self.path}")
         self.frame_count = int(probe.get("frames") or 0)
         self.fps = float(probe.get("fps") or 30.0)
+        self.pix_fmt = pix_fmt
         self.video_info = _depth_video_info_from_path(self.path)
         self.mode = _depth_video_mode(self.video_info)
         self._frame_bytes = self.width * self.height * 2
@@ -755,12 +798,19 @@ class DepthVideoReader:
     def close(self) -> None:
         process = self._process
         if process.poll() is None:
+            # The decoder usually sits blocked on a full stdout pipe once the
+            # caller stops reading.  SIGTERM makes FFmpeg try a graceful
+            # flush that never completes in that state (measured 5s timeouts
+            # per close), so give it a very short grace window and then kill.
             process.terminate()
-        try:
-            process.wait(timeout=5)
-        except subprocess.TimeoutExpired:
-            process.kill()
-            process.wait(timeout=5)
+            try:
+                process.wait(timeout=0.3)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                try:
+                    process.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    pass
         if process.stdout:
             process.stdout.close()
         if process.stderr:
@@ -773,6 +823,91 @@ class DepthVideoReader:
         self.close()
 
 
+class DepthCodeSeekReader:
+    """Sequential code reader positioned at an exact frame via FFmpeg seek.
+
+    The canonical depth contract encodes keyint=2 (an IDR every two frames),
+    so input seeking lands one frame before the target at most.  FFmpeg's
+    accurate seek drops the lead-in frames itself (verified: ``-ss`` at an
+    exact frame timestamp yields that frame as the first output), which turns
+    a scrub jump from an O(N) sequential decode into a constant-time seek.
+
+    The pooled window path replaces its sequential reader with one of these
+    after a jump, so forward playback continues from the new position without
+    re-seeking per window.
+    """
+
+    def __init__(self, path: Path, start_frame: int, fps: float = 30.0,
+                 pix_fmt: str = "gray12le"):
+        import numpy as np
+
+        self.path = Path(path)
+        ffmpeg = shutil.which("ffmpeg")
+        if not ffmpeg:
+            raise RuntimeError("ffmpeg is required to seek depth video")
+        probe = _probe_video(self.path)
+        self.width = int(probe.get("width") or 0)
+        self.height = int(probe.get("height") or 0)
+        if self.width <= 0 or self.height <= 0:
+            raise RuntimeError(f"Depth video has invalid dimensions: {self.path}")
+        self._frame_bytes = self.width * self.height * 2
+        # Keep the stream identity so a later scrub jump on the same pool
+        # entry re-derives the seek timestamp from the real fps/pix_fmt
+        # instead of falling back to defaults (wrong seek → frame desync).
+        self.fps = float(fps or 30.0)
+        self.pix_fmt = pix_fmt
+        seek_time = max(0, int(start_frame)) / self.fps
+        # Truncate to milliseconds (never round up): ffmpeg's accurate seek
+        # returns the first frame with ts >= seek_time, so a rounded-up value
+        # such as 36.6667 lands one frame PAST the target (36.66667 -> frame
+        # 1101 instead of 1100).  A 1ms truncation is always below the
+        # target frame ts and at least ~32ms above the previous frame's.
+        seek_time = math.floor(seek_time * 1000) / 1000
+        self._process = subprocess.Popen(
+            [ffmpeg, "-v", "error",
+             "-ss", f"{seek_time:.3f}", "-i", str(self.path),
+             "-f", "rawvideo", "-pix_fmt", pix_fmt, "pipe:1"],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        )
+
+    def read_codes(self):
+        """Read one stored little-endian uint16 frame without colorization."""
+        import numpy as np
+
+        if self._process.stdout is None:
+            return None
+        chunks: list[bytes] = []
+        remaining = self._frame_bytes
+        while remaining:
+            data = self._process.stdout.read(remaining)
+            if not data:
+                return None
+            chunks.append(data)
+            remaining -= len(data)
+        return np.frombuffer(b"".join(chunks), dtype="<u2").reshape(
+            self.height, self.width,
+        ).copy()
+
+    def close(self) -> None:
+        process = self._process
+        if process.poll() is None:
+            # Same blocked-pipe situation as DepthVideoReader.close(); a
+            # graceful SIGTERM flush hangs for seconds on a full stdout pipe.
+            process.terminate()
+            try:
+                process.wait(timeout=0.3)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                try:
+                    process.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    pass
+        if process.stdout:
+            process.stdout.close()
+        if process.stderr:
+            process.stderr.close()
+
+
 def _to_mp4(source: Path, destination: Path) -> Path:
     """Put a video in the v2.1 MP4 path, preserving codec when possible."""
     destination.parent.mkdir(parents=True, exist_ok=True)

processor/app/localstore.py

@@ -306,6 +306,9 @@ def _scan_project_dir(project_dir: Path, project: str) -> list[dict]:
             "episode_index": episode_index,
             "project": project_name,
             "status": state.get("status", "completed"),
+            # AI 标注运行中(running)时前端禁止查看批次;passed/failed
+            # 或未配置 AI 节点(null)均正常放行。
+            "ai_quality_status": state.get("ai_quality_status"),
             "fps": state_fps or declared_fps,
             "frame_count": frame_count,
             "camera_names": sorted(cameras),

processor/app/main.py

@@ -53,7 +53,7 @@ async def lifespan(app: FastAPI):
     ).start()
     from app import upload_queue
     upload_queue.start()
-    print(f"[Startup] Data Acquisition Service on port {settings.PORT}")
+    print(f"[Startup] processor Service on port {settings.PORT}")
     print(f"[Startup] Storage: {settings.STORAGE_DIR} ({settings.STORAGE_BACKEND})")
     try:
         yield
@@ -63,7 +63,7 @@ async def lifespan(app: FastAPI):
 
 
 app = FastAPI(
-    title="Data Acquisition Service",
+    title="processor Service",
     version="0.1.0",
     lifespan=lifespan,
 )
@@ -74,6 +74,24 @@ app.add_middleware(GZipMiddleware, minimum_size=500)
 # Auth middleware — protect routes (after gzip, before everything else)
 app.add_middleware(AuthMiddleware)
 
+# 媒体/压缩文件下载不走 gzip:zip/mp4/parquet/hdf5 本身已是压缩格式,
+# 再压一遍只是烧 CPU(zlib level 9 压缩 180MB ≈ 10s),而且流式压缩会
+# 删掉 Content-Length —— 浏览器下载进度显示"未知大小",大文件看起来
+# 像卡死。这些路径直接透传原始字节(去掉 accept-encoding 头即可)。
+_NO_COMPRESS_PATH_HINTS = (
+    "download", "stream", "depth-codes", "depth-preview", "skeleton", "hdf5",
+)
+
+
+@app.middleware("http")
+async def no_compress_media(request, call_next):
+    if any(hint in request.url.path for hint in _NO_COMPRESS_PATH_HINTS):
+        request.scope["headers"] = [
+            (key, value) for key, value in request.scope["headers"]
+            if key.lower() != b"accept-encoding"
+        ]
+    return await call_next(request)
+
 # Static JS/CSS is versioned (workflow assets use content hashes; the legacy
 # page scripts use a ``?v=...`` query).  Tell the browser to retain these
 # resources across full page navigation instead of revalidating every common

processor/app/media_cache.py

@@ -21,7 +21,7 @@ import time
 _lock = threading.Lock()
 _MEDIA_GROUPS: dict[str, tuple[float, dict]] = {}
 _HAND3D_META: dict[str, tuple[float, dict]] = {}
-_TTL = 600.0  # 兜底自愈;正常路径由 invalidate_episode 显式失效
+_TTL = 3600.0  # 兜底自愈;正常路径由 invalidate_episode 显式失效(hand-3d meta 冷计算 ~20s,10min 太短)
 
 
 def _fresh(entry: tuple[float, dict] | None, now: float) -> bool:

processor/app/paths.py

@@ -13,3 +13,4 @@ WEB_ROOT = PROJECT_ROOT / "web"
 TEMPLATES_DIR = WEB_ROOT / "templates"
 STATIC_DIR = WEB_ROOT / "static"
 WORKFLOW_STUDIO_DIR = WEB_ROOT / "workflow-studio"
+

processor/app/processing/__init__.py

@@ -1,201 +1,201 @@
-"""Processing Module Framework — pluggable pipeline nodes.
-
-每个功能(相机输入、骨骼识别、手套、标注、审核、导出)是一个独立模块:
-一个文件 = 一个模块(元数据 + run()),放在 app/processing/modules/ 下,
-自动发现注册。前端画布与 worker 执行都从注册表取模块定义。
-
-新增自定义模块三步:
-1. 复制 modules/example 模板为 app/processing/modules/<slug>.py
-2. 填写 slug/label/category/inputs/outputs/config_schema 等元数据,实现 run(ctx)
-3. 重启后端与 worker —— 前端面板自动出现可拖拽卡片,worker 自动执行
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field as dc_field
-from pathlib import Path
-from typing import Any, Callable
-
-
-def field(name: str, kind: str, label: str, default=None, **extra) -> dict:
-    """config_schema 单字段定义: {"name","type","label","default",**extra}。"""
-    value = {"name": name, "type": kind, "label": label, "default": default}
-    value.update(extra)
-    return value
-
-
-@dataclass
-class ModuleResult:
-    """Returned by a ProcessingModule after execution (legacy, kept for compat)."""
-    success: bool
-    data: dict[str, Any] = dc_field(default_factory=dict)
-    outputs: dict[str, "ArtifactRef"] = dc_field(default_factory=dict)
-    metrics: dict[str, Any] = dc_field(default_factory=dict)
-    error: str | None = None
-
-
-@dataclass
-class ArtifactRef:
-    """Portable reference to a workflow input/output artifact."""
-
-    kind: str
-    path: str | None = None
-    source_key: str | None = None
-    schema_version: str = "1.0"
-    metadata: dict[str, Any] = dc_field(default_factory=dict)
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "kind": self.kind,
-            "path": self.path,
-            "source_key": self.source_key,
-            "schema_version": self.schema_version,
-            "metadata": self.metadata,
-        }
-
-    @classmethod
-    def from_dict(cls, value: dict[str, Any]) -> "ArtifactRef":
-        return cls(
-            kind=str(value.get("kind", "unknown")),
-            path=value.get("path"),
-            source_key=value.get("source_key"),
-            schema_version=str(value.get("schema_version", "1.0")),
-            metadata=dict(value.get("metadata") or {}),
-        )
-
-
-@dataclass(frozen=True)
-class ModuleDescriptor:
-    """Metadata shared by the backend module registry and card palette."""
-
-    slug: str
-    version: str
-    category: str
-    label: str
-    icon: str
-    color: str
-    inputs: tuple[dict[str, str], ...] = ()
-    outputs: tuple[dict[str, str], ...] = ()
-    default_config: dict[str, Any] = dc_field(default_factory=dict)
-    config_schema: tuple[dict[str, Any], ...] = ()
-    execution_target: str = "worker"
-    capabilities: tuple[str, ...] = ()
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "type": self.slug,
-            "slug": self.slug,
-            "version": self.version,
-            "category": self.category,
-            "label": self.label,
-            "icon": self.icon,
-            "color": self.color,
-            "inputs": list(self.inputs),
-            "outputs": list(self.outputs),
-            "defaultConfig": self.default_config,
-            "default_config": self.default_config,
-            "configSchema": list(self.config_schema),
-            "config_schema": list(self.config_schema),
-            "executionTarget": self.execution_target,
-            "execution_target": self.execution_target,
-            "capabilities": list(self.capabilities),
-        }
-
-
-class ModuleSkip(Exception):
-    """模块主动跳过(无有效输入等)—— 节点标记 skipped,不视为失败。"""
-
-    def __init__(self, reason: str):
-        self.reason = reason
-        super().__init__(reason)
-
-
-@dataclass
-class JobContext:
-    """Worker 与模块之间的统一执行上下文。"""
-
-    node_id: str
-    node_type: str
-    config: dict[str, Any]
-    job: dict[str, Any]
-    input_root: Path                       # 批次解压目录(源文件扫描)
-    output_root: Path                      # 输出根(outputs/)
-    incoming: dict[str, ArtifactRef]       # targetHandle → 上游 ArtifactRef(源节点为空 dict)
-    progress: Callable[[float], None]      # 本节点进度 0..1
-    node_states: dict                      # 节点状态累加器
-
-    @property
-    def output_dir(self) -> Path:
-        d = self.output_root / self.node_id
-        d.mkdir(parents=True, exist_ok=True)
-        return d
-
-    def ref(self, kind: str, path: Path, source_key: str | None = None,
-            metadata: dict | None = None) -> ArtifactRef:
-        """构造 ArtifactRef,路径自动相对化:input_root 下 → 相对 input_root,否则相对 output_root。"""
-        try:
-            rel = path.resolve().relative_to(self.input_root.resolve())
-        except ValueError:
-            rel = path.resolve().relative_to(self.output_root.resolve())
-        return ArtifactRef(kind=kind, path=str(rel).replace("\\", "/"),
-                           source_key=source_key, metadata=metadata or {})
-
-    def resolve(self, ref: ArtifactRef) -> Path | None:
-        """按 input_root/output_root 依次解析 ArtifactRef 路径。"""
-        if not ref or not ref.path:
-            return None
-        p = self.input_root / ref.path
-        if p.exists():
-            return p
-        p = self.output_root / ref.path
-        return p if p.exists() else None
-
-    def find_videos(self) -> list[Path]:
-        """按 config 的 source_keys/source_key/position 匹配批次内视频(见 batch.py)。"""
-        from app.processing.batch import find_videos
-        return find_videos(self.input_root, self.config)
-
-    def find_parquet(self) -> list[Path]:
-        """批次内全部 parquet(排除 auto_labels/hand_kpts 等合并产物)。"""
-        from app.processing.batch import find_parquet
-        return find_parquet(self.input_root)
-
-    def skip(self, reason: str):
-        raise ModuleSkip(reason)
-
-
-class ProcessingModule:
-    """Base class for a pipeline processing node.
-
-    Subclass, fill in the metadata class attributes, implement ``run()``,
-    and decorate with ``@register`` from app.processing.registry — the
-    module appears in the Workflow Studio palette and runs in the worker
-    automatically.
-    """
-
-    slug: str = ""
-    version: str = "1.0"
-    category: str = "process"          # input | process | review | export
-    label: str = ""
-    icon: str = "ant-design:appstore-outlined"
-    color: str = "#64748b"
-    inputs: tuple[dict[str, str], ...] = ()
-    outputs: tuple[dict[str, str], ...] = ()
-    default_config: dict[str, Any] = dc_field(default_factory=dict)
-    config_schema: tuple[dict[str, Any], ...] = ()
-    execution_target: str = "worker"
-    capabilities: tuple[str, ...] = ()
-
-    @classmethod
-    def descriptor(cls) -> ModuleDescriptor:
-        return ModuleDescriptor(
-            slug=cls.slug, version=cls.version, category=cls.category, label=cls.label,
-            icon=cls.icon, color=cls.color, inputs=tuple(cls.inputs),
-            outputs=tuple(cls.outputs), default_config=dict(cls.default_config),
-            config_schema=tuple(cls.config_schema), execution_target=cls.execution_target,
-            capabilities=tuple(cls.capabilities),
-        )
-
-    def run(self, ctx: JobContext) -> dict[str, ArtifactRef] | None:
-        """执行入口。返回输出 handle → ArtifactRef;None 或 raise ModuleSkip → 节点 skipped。"""
-        raise NotImplementedError
+"""Processing Module Framework — pluggable pipeline nodes.
+
+每个功能(相机输入、骨骼识别、手套、标注、审核、导出)是一个独立模块:
+一个文件 = 一个模块(元数据 + run()),放在 app/processing/modules/ 下,
+自动发现注册。前端画布与 worker 执行都从注册表取模块定义。
+
+新增自定义模块三步:
+1. 复制 modules/example 模板为 app/processing/modules/<slug>.py
+2. 填写 slug/label/category/inputs/outputs/config_schema 等元数据,实现 run(ctx)
+3. 重启后端与 worker —— 前端面板自动出现可拖拽卡片,worker 自动执行
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field as dc_field
+from pathlib import Path
+from typing import Any, Callable
+
+
+def field(name: str, kind: str, label: str, default=None, **extra) -> dict:
+    """config_schema 单字段定义: {"name","type","label","default",**extra}。"""
+    value = {"name": name, "type": kind, "label": label, "default": default}
+    value.update(extra)
+    return value
+
+
+@dataclass
+class ModuleResult:
+    """Returned by a ProcessingModule after execution (legacy, kept for compat)."""
+    success: bool
+    data: dict[str, Any] = dc_field(default_factory=dict)
+    outputs: dict[str, "ArtifactRef"] = dc_field(default_factory=dict)
+    metrics: dict[str, Any] = dc_field(default_factory=dict)
+    error: str | None = None
+
+
+@dataclass
+class ArtifactRef:
+    """Portable reference to a workflow input/output artifact."""
+
+    kind: str
+    path: str | None = None
+    source_key: str | None = None
+    schema_version: str = "1.0"
+    metadata: dict[str, Any] = dc_field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "path": self.path,
+            "source_key": self.source_key,
+            "schema_version": self.schema_version,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "ArtifactRef":
+        return cls(
+            kind=str(value.get("kind", "unknown")),
+            path=value.get("path"),
+            source_key=value.get("source_key"),
+            schema_version=str(value.get("schema_version", "1.0")),
+            metadata=dict(value.get("metadata") or {}),
+        )
+
+
+@dataclass(frozen=True)
+class ModuleDescriptor:
+    """Metadata shared by the backend module registry and card palette."""
+
+    slug: str
+    version: str
+    category: str
+    label: str
+    icon: str
+    color: str
+    inputs: tuple[dict[str, str], ...] = ()
+    outputs: tuple[dict[str, str], ...] = ()
+    default_config: dict[str, Any] = dc_field(default_factory=dict)
+    config_schema: tuple[dict[str, Any], ...] = ()
+    execution_target: str = "worker"
+    capabilities: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.slug,
+            "slug": self.slug,
+            "version": self.version,
+            "category": self.category,
+            "label": self.label,
+            "icon": self.icon,
+            "color": self.color,
+            "inputs": list(self.inputs),
+            "outputs": list(self.outputs),
+            "defaultConfig": self.default_config,
+            "default_config": self.default_config,
+            "configSchema": list(self.config_schema),
+            "config_schema": list(self.config_schema),
+            "executionTarget": self.execution_target,
+            "execution_target": self.execution_target,
+            "capabilities": list(self.capabilities),
+        }
+
+
+class ModuleSkip(Exception):
+    """模块主动跳过(无有效输入等)—— 节点标记 skipped,不视为失败。"""
+
+    def __init__(self, reason: str):
+        self.reason = reason
+        super().__init__(reason)
+
+
+@dataclass
+class JobContext:
+    """Worker 与模块之间的统一执行上下文。"""
+
+    node_id: str
+    node_type: str
+    config: dict[str, Any]
+    job: dict[str, Any]
+    input_root: Path                       # 批次解压目录(源文件扫描)
+    output_root: Path                      # 输出根(outputs/)
+    incoming: dict[str, ArtifactRef]       # targetHandle → 上游 ArtifactRef(源节点为空 dict)
+    progress: Callable[[float], None]      # 本节点进度 0..1
+    node_states: dict                      # 节点状态累加器
+
+    @property
+    def output_dir(self) -> Path:
+        d = self.output_root / self.node_id
+        d.mkdir(parents=True, exist_ok=True)
+        return d
+
+    def ref(self, kind: str, path: Path, source_key: str | None = None,
+            metadata: dict | None = None) -> ArtifactRef:
+        """构造 ArtifactRef,路径自动相对化:input_root 下 → 相对 input_root,否则相对 output_root。"""
+        try:
+            rel = path.resolve().relative_to(self.input_root.resolve())
+        except ValueError:
+            rel = path.resolve().relative_to(self.output_root.resolve())
+        return ArtifactRef(kind=kind, path=str(rel).replace("\\", "/"),
+                           source_key=source_key, metadata=metadata or {})
+
+    def resolve(self, ref: ArtifactRef) -> Path | None:
+        """按 input_root/output_root 依次解析 ArtifactRef 路径。"""
+        if not ref or not ref.path:
+            return None
+        p = self.input_root / ref.path
+        if p.exists():
+            return p
+        p = self.output_root / ref.path
+        return p if p.exists() else None
+
+    def find_videos(self) -> list[Path]:
+        """按 config 的 source_keys/source_key/position 匹配批次内视频(见 batch.py)。"""
+        from app.processing.batch import find_videos
+        return find_videos(self.input_root, self.config)
+
+    def find_parquet(self) -> list[Path]:
+        """批次内全部 parquet(排除 auto_labels/hand_kpts 等合并产物)。"""
+        from app.processing.batch import find_parquet
+        return find_parquet(self.input_root)
+
+    def skip(self, reason: str):
+        raise ModuleSkip(reason)
+
+
+class ProcessingModule:
+    """Base class for a pipeline processing node.
+
+    Subclass, fill in the metadata class attributes, implement ``run()``,
+    and decorate with ``@register`` from app.processing.registry — the
+    module appears in the Workflow Studio palette and runs in the worker
+    automatically.
+    """
+
+    slug: str = ""
+    version: str = "1.0"
+    category: str = "process"          # input | process | review | export
+    label: str = ""
+    icon: str = "ant-design:appstore-outlined"
+    color: str = "#64748b"
+    inputs: tuple[dict[str, str], ...] = ()
+    outputs: tuple[dict[str, str], ...] = ()
+    default_config: dict[str, Any] = dc_field(default_factory=dict)
+    config_schema: tuple[dict[str, Any], ...] = ()
+    execution_target: str = "worker"
+    capabilities: tuple[str, ...] = ()
+
+    @classmethod
+    def descriptor(cls) -> ModuleDescriptor:
+        return ModuleDescriptor(
+            slug=cls.slug, version=cls.version, category=cls.category, label=cls.label,
+            icon=cls.icon, color=cls.color, inputs=tuple(cls.inputs),
+            outputs=tuple(cls.outputs), default_config=dict(cls.default_config),
+            config_schema=tuple(cls.config_schema), execution_target=cls.execution_target,
+            capabilities=tuple(cls.capabilities),
+        )
+
+    def run(self, ctx: JobContext) -> dict[str, ArtifactRef] | None:
+        """执行入口。返回输出 handle → ArtifactRef;None 或 raise ModuleSkip → 节点 skipped。"""
+        raise NotImplementedError

processor/app/processing/black_glove/README.md

@@ -24,7 +24,7 @@ Before publishing a public repository, verify the redistribution terms for the
 bundled model files. If the model terms do not allow redistribution, keep the
 code layout and replace the files with a documented download step.
 
-The Python dependencies are declared in the parent `Data Acquisition`
+The Python dependencies are declared in the parent `processor`
 `requirements.txt`. RTMPose model assets may be downloaded by `rtmlib` on
 first use and cached by the Python environment; this is a package/runtime
 dependency, not a dependency on another repository directory.

processor/app/processing/black_glove/__init__.py

@@ -1,4 +1,4 @@
-"""Self-contained black-glove detection support for the Data Acquisition worker.
+"""Self-contained black-glove detection support for the processor worker.
 
 The workflow adapter imports this package directly.  It intentionally does not
 depend on the legacy repository-level demo directories.

processor/app/processing/black_glove/d435_hands_demo.py

@@ -92,11 +92,11 @@ BAND_HALF_M = 0.12          # 手深带半宽（米）
 BAND_MIN_VALID = 4
 GATE_M = 0.15               # 时序一致性门（米/帧）
 
-# 内嵌出厂标定（示例回退值；生产环境应使用录制会话中的标定文件）
+# 内嵌出厂标定（开发机 D435，serial 213622075531，设备提取 + 录制期
 # head_stereo.json 交叉核对零警告）。仅供无 --calib、无脚本旁 JSON 时
 # 回退；深度内参权威来源是录制会话的 head_stereo.json。
 _EMBEDDED_CALIB = {
-    "serial": "sample-d435",
+    "serial": "213622075531",
     "color_intrinsics": {
         "width": 1280, "height": 720,
         "fx": 912.2550048828125, "fy": 910.3241577148438,
@@ -356,18 +356,36 @@ class MediaPipeHandPipeline:
         self._pixel_filters: Dict[Tuple[int, int], OneEuroFilter2D] = {}
         self._world_filters: Dict[Tuple[int, int], OneEuroFilter3D] = {}
 
-        # 构建 landmarker
-        options = vision.HandLandmarkerOptions(
-            base_options=mp_python.BaseOptions(model_asset_path=model_path),
-            running_mode=vision.RunningMode.VIDEO,
-            num_hands=num_hands,
-            min_hand_detection_confidence=det_conf,
-            min_hand_presence_confidence=0.5,
-            min_tracking_confidence=track_conf,
-        )
-        self._landmarker = vision.HandLandmarker.create_from_options(options)
+        # 构建 landmarker:优先 GPU delegate,初始化/首帧冒烟失败回退 CPU
+        # (与 rgb_hand_3d 模块同一策略;Blackwell 等新卡不支持时自动回退)。
+        def make(delegate):
+            return vision.HandLandmarker.create_from_options(
+                vision.HandLandmarkerOptions(
+                    base_options=mp_python.BaseOptions(
+                        model_asset_path=model_path, delegate=delegate),
+                    running_mode=vision.RunningMode.VIDEO,
+                    num_hands=num_hands,
+                    min_hand_detection_confidence=det_conf,
+                    min_hand_presence_confidence=0.5,
+                    min_tracking_confidence=track_conf,
+                ))
+
+        self._landmarker = make(mp_python.BaseOptions.Delegate.CPU)
+        try:
+            candidate = make(mp_python.BaseOptions.Delegate.GPU)
+            # 冒烟:VIDEO 模式要求时间戳单调递增,逐帧新建 Image 喂 3 帧
+            for i in range(3):
+                probe = mp.Image(image_format=mp.ImageFormat.SRGB,
+                                 data=np.zeros((64, 64, 3), np.uint8))
+                candidate.detect_for_video(probe, i)
+            self._landmarker.close()
+            self._landmarker = candidate
+            print("[d435_hands_demo] HandLandmarker GPU delegate active")
+        except Exception as exc:
+            print(f"[d435_hands_demo] HandLandmarker GPU 初始化失败（{exc}），回退 CPU")
         self._preprocessor = _Preprocessor()
-        self._t0 = time.perf_counter()
+        # _t0 预借 50ms:GPU 冒烟已用掉时间戳 0/1/2,首帧 ts 必须大于 2
+        self._t0 = time.perf_counter() - 0.05
 
     def process(self, frame: np.ndarray) -> FrameResult:
         """处理一帧 BGR 图像，返回 FrameResult（.hands: [HandResult, ...]）。"""

processor/app/processing/black_glove/d435_tracking.py

@@ -116,3 +116,4 @@ class AlphaBetaHandSlots:
 
     def close(self) -> None:
         self.slots = [self._new_slot(), self._new_slot()]
+

processor/app/processing/black_glove/pose_backends.py

@@ -29,6 +29,14 @@ class RtmposePoseBackend:
     name = "rtmpose"
 
     def __init__(self, device: str = "cpu"):
+        if device == "auto":
+            # auto = 有 CUDA provider 用 cuda,否则 cpu(rtmlib 不识别 auto)
+            try:
+                import onnxruntime as ort
+                device = ("cuda" if "CUDAExecutionProvider"
+                          in ort.get_available_providers() else "cpu")
+            except Exception:
+                device = "cpu"
         try:
             from rtmlib import RTMPose
             self._pose = RTMPose(_RTMPOSE_URL, model_input_size=(256, 256),
@@ -78,12 +86,13 @@ class MediaPipePoseBackend:
             return vision.HandLandmarker.create_from_options(options)
 
         self._lm = make(mp_python.BaseOptions.Delegate.CPU)
-        if device == "cuda":
+        if device in ("auto", "cuda"):
             try:
                 candidate = make(mp_python.BaseOptions.Delegate.GPU)
                 _smoke(candidate, mp)
                 self._lm.close()
                 self._lm = candidate
+                device = "cuda"
             except Exception as exc:
                 print(f"HandLandmarker GPU 初始化失败（{exc}），回退 CPU")
                 device = "cpu"

processor/app/processing/modules/depth_hand_3d.py

@@ -960,7 +960,7 @@ def _run_rgb_estimated_pair(pair: dict, video_path: Path, config: dict,
     import pandas as pd
 
     # Imported lazily to keep the depth helper independent during normal
-    # module discovery.  Both modules are inside Data Acquisition; this is
+    # module discovery.  Both modules are inside processor; this is
     # not a dependency on the legacy Python project.
     from app.processing.modules.stereo_triangulate import (
         _detect_hands, _rgb_frame_rows,

processor/app/processing/modules/rgb_world_tracking.py

@@ -1,7 +1,7 @@
 """RGB-only hand-to-camera tracking used by the Hand Skeleton module.
 
 This module is deliberately self-contained.  It does not import the legacy
-``Python`` project or any code outside ``Data Acquisition``.
+``Python`` project or any code outside ``processor``.
 
 MediaPipe gives us two useful pieces of information from an RGB frame:
 

processor/app/routes/auth.py

@@ -18,9 +18,9 @@ router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
 USERS_FILE = STATE_ROOT / "users.json"
 
 # Bootstrap account for a new legacy file store. Existing users.json is kept.
-_BOOTSTRAP_USERNAME = (os.environ.get("EGODATA_BOOTSTRAP_USERNAME", "demo-admin").strip()
-                       or "demo-admin")
-_BOOTSTRAP_PASSWORD = os.environ.get("EGODATA_BOOTSTRAP_PASSWORD", "change-me")
+_BOOTSTRAP_USERNAME = (os.environ.get("EGODATA_BOOTSTRAP_USERNAME", "Root").strip()
+                       or "Root")
+_BOOTSTRAP_PASSWORD = os.environ.get("EGODATA_BOOTSTRAP_PASSWORD", "Root")
 _BOOTSTRAP_EMAIL = (os.environ.get("EGODATA_BOOTSTRAP_EMAIL", "").strip()
                     or f"{_BOOTSTRAP_USERNAME.lower()}@egodata.local")
 

processor/app/routes/export.py

@@ -5,6 +5,8 @@
 
 from __future__ import annotations
 
+import hashlib
+import shutil
 import tempfile
 import zipfile
 import re
@@ -17,6 +19,7 @@ from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query
 from fastapi.responses import FileResponse
 from starlette.background import BackgroundTask
 
+from app.config import settings
 from app.localstore import (
     STATE_ROOT, scan_sessions, get_episode, list_deleted_episodes, list_runs,
     get_workflow, list_projects, _read_json, _write_json, _remove_json,
@@ -34,6 +37,9 @@ router = APIRouter(prefix="/api/v1/export", tags=["export"])
 
 EXPORTS_DIR = STATE_ROOT / "exports"
 EXPORT_TASKS_DIR = STATE_ROOT / "export_tasks"
+# 导出页/批量导出的构建目录与 zip 放本地盘:同一份视频数据不再在
+# NAS(SSHFS ~28MB/s)上读写三遍,只保留一次源文件读取。
+LOCAL_EXPORTS_DIR = settings.upload_staging_root / "exports"
 
 
 def _utcnow() -> str:
@@ -83,6 +89,12 @@ def _zip_directory(root: Path, dest: Path) -> None:
                               compress_type=zipfile.ZIP_STORED if path.suffix.lower() in {".mp4", ".parquet"} else zipfile.ZIP_DEFLATED)
 
 
+# 旧版本导出代码遗留的非标准边车文件:标注已在 parquet 列里
+# (annotation/annotation_index/annotation_scope),设备信息在 info.json
+# (robot_type)。打包时剥离,不随 zip 分发。
+_SIDECAR_EXCLUDE = {"meta/annotations.jsonl", "meta/devices.json"}
+
+
 def _zip_lerobot(root: Path, dest: Path) -> None:
     """打包 LeRobot 标准结构(data/ + meta/ + videos/),不携带处理副产品
     (hand_3d/skeleton/calibration 等)。连接驱动导出带视频 feature 的
@@ -94,9 +106,12 @@ def _zip_lerobot(root: Path, dest: Path) -> None:
             if not sub_dir.is_dir():
                 continue
             for path in sub_dir.rglob("*"):
-                if path.is_file():
-                    archive.write(path, str(path.relative_to(root)),
-                                  compress_type=zipfile.ZIP_STORED if path.suffix.lower() in {".mp4", ".parquet"} else zipfile.ZIP_DEFLATED)
+                if not path.is_file():
+                    continue
+                if str(path.relative_to(root)) in _SIDECAR_EXCLUDE:
+                    continue
+                archive.write(path, str(path.relative_to(root)),
+                              compress_type=zipfile.ZIP_STORED if path.suffix.lower() in {".mp4", ".parquet"} else zipfile.ZIP_DEFLATED)
 
 
 def _cleanup_later(path: str) -> None:
@@ -272,8 +287,25 @@ def _episode_export_target(episode_id: str) -> dict | None:
                             return {"kind": "hdf5", "version": None,
                                     "product": candidate, "root": candidate.parent}
                     elif (candidate / "meta" / "info.json").is_file():
+                        # 版本以产物自身的 codebase_version 为准(实际
+                        # 构建版本),不能信任工作流配置 —— 旧产物可能是
+                        # v2.1 代码按配置 v3.0 构建前的遗留,文件名/徽标
+                        # 会与实际布局不符。
+                        product_version = str(cfg.get("version") or "v3.0")
+                        try:
+                            import json as _json
+                            info = _json.loads(
+                                (candidate / "meta" / "info.json")
+                                .read_text(encoding="utf-8"))
+                            built = str(info.get("codebase_version") or "")
+                            if built.lower().startswith("v2"):
+                                product_version = "v2.1"
+                            elif built.lower().startswith("v3"):
+                                product_version = "v3.0"
+                        except (OSError, ValueError):
+                            pass
                         return {"kind": "lerobot",
-                                "version": str(cfg.get("version") or "v3.0"),
+                                "version": product_version,
                                 "product": candidate, "root": candidate}
 
     return None
@@ -364,9 +396,11 @@ async def download_single_episode(episode_id: str):
                                           delete=False)
         tmp.close()
         _zip_lerobot(target["root"], Path(tmp.name))
-        return FileResponse(tmp.name, media_type="application/zip",
-                            filename=f"{project_name}.zip",
-                            background=BackgroundTask(_cleanup_later, tmp.name))
+        version = target["version"] or "v3.0"
+        return FileResponse(
+            tmp.name, media_type="application/zip",
+            filename=f"{project_name}-{version}.zip",
+            background=BackgroundTask(_cleanup_later, tmp.name))
     return _build_episode_zip([episode_id], f"egodata-{episode_id}-", f"{project_name}.zip")
 
 
@@ -415,8 +449,73 @@ def _list_tasks() -> list[dict]:
     return [t for t in (_read_json(f, {}) for f in sorted(EXPORT_TASKS_DIR.glob("*.json"))) if t]
 
 
+# running 任���超过该时长仍未结束 → 线程大概率已异常死亡,标记 failed
+# (正常 3 批次导出实测 ~3 分钟;30 分钟是宽裕兜底)
+_EXPORT_RUNNING_TIMEOUT_SECONDS = 30 * 60
+
+
+def _mark_stale_running_failed(task: dict) -> bool:
+    """把卡死在 running 的超时任务标记为 failed(返回是否发生了修改)。"""
+    if task.get("status") != "running":
+        return False
+    try:
+        created = datetime.fromisoformat(
+            str(task.get("created_at") or "").replace("Z", "+00:00"))
+        elapsed = (datetime.now(timezone.utc) - created).total_seconds()
+        if elapsed > _EXPORT_RUNNING_TIMEOUT_SECONDS:
+            task["status"] = "failed"
+            task["error"] = ("Export timed out (running for over "
+                             "30 minutes without finishing)")
+            task["finished_at"] = _utcnow()
+            _save_task(task)
+            return True
+    except (ValueError, TypeError):
+        pass
+    return False
+
+
+def _episode_set_fingerprint(episode_ids: list[str]) -> str:
+    """所选批次源文件的指纹(size+mtime):数据变过才需要重新构建。"""
+    digest = hashlib.sha256()
+    for episode_id in episode_ids:
+        ep = get_episode(str(episode_id))
+        if ep is None:
+            continue
+        root = Path(ep["path"])
+        if not is_project_dataset(root):
+            continue
+        try:
+            row = episode_row(root, str(episode_id))
+        except Exception:
+            continue
+        if row is None:
+            continue
+        index = int(row.get("episode_index"))
+        files = episode_files(root, index)
+        candidates = [*files.get("data", []),
+                      *(path for _, path in files.get("videos", []))]
+        for path in candidates:
+            try:
+                st = Path(path).stat()
+                digest.update(
+                    f"{Path(path).name}|{st.st_size}|{st.st_mtime_ns}"
+                    .encode("utf-8"))
+            except OSError:
+                continue
+    return digest.hexdigest()
+
+
 def _run_export_task(job_id: str, episode_ids: list[str], export_format: str,
                      dataset_name: str, split_ratio: float) -> None:
+    def _set_progress(progress: float, **extra) -> None:
+        """后台任务阶段进度(前端按钮实时显示,不再静默等待)。"""
+        task = _load_task(job_id)
+        if not task:
+            return
+        task["progress"] = max(0.0, min(1.0, float(progress)))
+        task.update(extra)
+        _save_task(task)
+
     try:
         blocked = [
             str(episode_id) for episode_id in episode_ids
@@ -425,20 +524,34 @@ def _run_export_task(job_id: str, episode_ids: list[str], export_format: str,
         ]
         if blocked:
             raise RuntimeError("Some episodes are still in Reviewing")
-        dest = EXPORTS_DIR / f"{job_id}.zip"
+        # 构建与 zip 都在本地盘进行(NAS 只读一次源文件);zip 是最终
+        # 产物,构建目录打包完成后即删除以节省本地空间。
+        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]}"
         if export_format in {"lerobot_v2", "lerobot_v3"}:
             from app.lerobot_export import build_lerobot_dataset
-            export_root = EXPORTS_DIR / f"{dataset_name}-{job_id[:8]}"
             version = "v2.1" if export_format == "lerobot_v2" else "v3.0"
+
+            def _on_episode(done: int, total_episodes: int) -> None:
+                _set_progress(0.05 + 0.65 * (done / max(1, total_episodes)))
+
+            _set_progress(0.05)
             build_lerobot_dataset(dataset_name, episode_ids, export_root,
-                                  split_ratio, version=version)
+                                  split_ratio, version=version,
+                                  progress_callback=_on_episode)
+            _set_progress(0.75)
             _zip_directory(export_root, dest)
+            _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)
         task = _load_task(job_id)
         if task:
             task["status"] = "completed"
+            task["progress"] = 1.0
             task["output_dir"] = str(dest)
             task["finished_at"] = _utcnow()
             _save_task(task)
@@ -510,6 +623,32 @@ async def export_start(body: dict, background_tasks: BackgroundTasks,
     if export_format not in {"lerobot_v2", "lerobot_v3"}:
         raise HTTPException(status_code=400,
                             detail="Unsupported export format")
+    # 防重复提交:同一批次集合已有 running 任务时直接拒绝,避免并行
+    # 任务互相抢 NAS 带宽(此前实测两次点击各跑一遍,时间翻倍)。
+    requested = set(episode_ids)
+    for existing in _list_tasks():
+        if existing.get("status") != "running":
+            continue
+        if set(existing.get("episode_ids") or []) == requested:
+            raise HTTPException(
+                status_code=409,
+                detail="An export for the same episodes is already running",
+            )
+    # 复用已完成结果:同批次(顺序一致)+ 同格式 + 源文件未变 → 直接
+    # 返回既有任务,前端轮询立即 completed 并触发下载(秒级)。
+    fingerprint = _episode_set_fingerprint(episode_ids)
+    for existing in _list_tasks():
+        if existing.get("status") != "completed":
+            continue
+        if (existing.get("episode_ids") or []) != episode_ids:
+            continue
+        if existing.get("export_format") != export_format:
+            continue
+        if existing.get("source_fingerprint") != fingerprint:
+            continue
+        output = Path(str(existing.get("output_dir") or ""))
+        if output.is_file():
+            return existing
     job = {
         "id": str(uuid4()),
         "dataset_name": dataset_name,
@@ -520,6 +659,7 @@ async def export_start(body: dict, background_tasks: BackgroundTasks,
         "export_format": export_format,
         "error": None,
         "output_dir": None,
+        "source_fingerprint": fingerprint,
         "created_at": _utcnow(),
         "finished_at": None,
     }
@@ -538,6 +678,8 @@ async def export_start(body: dict, background_tasks: BackgroundTasks,
 @router.get("/list")
 async def export_list(limit: int = Query(20, ge=1, le=100), offset: int = 0):
     tasks = sorted(_list_tasks(), key=lambda t: t.get("created_at") or "", reverse=True)
+    for task in tasks:
+        _mark_stale_running_failed(task)
     return tasks[offset:offset + limit]
 
 
@@ -546,6 +688,7 @@ async def export_status(job_id: str):
     task = _load_task(job_id)
     if task is None:
         raise HTTPException(status_code=404, detail="Export job not found")
+    _mark_stale_running_failed(task)
     return task
 
 
@@ -554,20 +697,31 @@ async def download_export_job(job_id: str):
     task = _load_task(job_id)
     if task is None:
         raise HTTPException(status_code=404, detail="Export job not found")
-    dest = EXPORTS_DIR / f"{job_id}.zip"
-    if not dest.exists():
+    # 新任务 zip 在本地盘(output_dir);历史任务回退 NAS 路径。
+    dest = Path(str(task.get("output_dir") or ""))
+    if not dest.is_file():
+        dest = EXPORTS_DIR / f"{job_id}.zip"
+    if not dest.is_file():
         raise HTTPException(status_code=404, detail="Export output not ready")
-    return FileResponse(dest, media_type="application/zip",
-                        filename=f"{task.get('dataset_name', 'dataset')}.zip")
+    # 文件名带格式版本后缀,下载后一眼可辨 v2.1 / v3.0
+    export_format = str(task.get("export_format") or "")
+    suffix = ("-v2.1" if export_format == "lerobot_v2"
+              else "-v3.0" if export_format == "lerobot_v3" else "")
+    return FileResponse(
+        dest, media_type="application/zip",
+        filename=f"{task.get('dataset_name', 'dataset')}{suffix}.zip")
 
 
 @router.delete("/{job_id}")
 async def delete_export_job(job_id: str, _: str = Depends(verify_api_key)):
+    task = _load_task(job_id)
     _remove_json(EXPORT_TASKS_DIR / f"{job_id}.json")
-    try:
-        (EXPORTS_DIR / f"{job_id}.zip").unlink(missing_ok=True)
-    except Exception:
-        pass
+    for path in (Path(str((task or {}).get("output_dir") or "")),
+                 EXPORTS_DIR / f"{job_id}.zip"):
+        try:
+            path.unlink(missing_ok=True)
+        except Exception:
+            pass
     return {"message": "Export job deleted"}
 
 

processor/app/routes/ingestion.py

@@ -6,6 +6,8 @@ data/sessions/<项目>/<批次名>/ + data/state/(审核状态、标注)。
 
 from __future__ import annotations
 
+import threading
+from collections import deque
 from pathlib import Path
 from uuid import UUID
 
@@ -80,6 +82,123 @@ def _ep_to_out_brief(ep: dict) -> dict:
 
 # ── 列表 / 详情 ───────────────────────────────────────
 
+# ── 深度预览预热(列表加载后后台生成,点击批次时已就绪) ──────────────
+# /episodes 每 15s 被前端轮询一次;把列表前 N 个有深度视频的批次排入
+# 单线程队列,后台先镜像后转码。全部尽力而为:失败静默,点击路径照常
+# 兜底生成。
+
+_PREWARM_QUEUE: deque[str] = deque()
+_PREWARM_QUEUED: set[str] = set()
+_PREWARM_LOCK = threading.Lock()
+_PREWARM_RUNNING = False
+_PREWARM_MAX_PER_PASS = 8
+_PREWARM_MAX_QUEUE = 24
+
+
+def _episode_depth_video_paths(ep: dict) -> list[Path]:
+    """该批次所有深度视频文件的权威路径(预热用,宽松按名称识别)。"""
+    batch = Path(ep.get("path") or "")
+    videos = batch / "videos"
+    if not videos.is_dir():
+        return []
+    from app.lerobot_v21 import is_depth_source
+
+    paths: list[Path] = []
+    try:
+        for feat in videos.iterdir():
+            if not feat.is_dir() or not is_depth_source(feat.name):
+                continue
+            for chunk in feat.glob("chunk-*/episode_*.mp4"):
+                if chunk.is_file():
+                    paths.append(chunk)
+    except OSError:
+        pass
+    return paths
+
+
+def _prewarm_worker() -> None:
+    """单线程消费预热队列;无任务即退出,由下次触发重启。
+
+    每个可见批次依次预热:素材清单(media-groups)→ 手部 3D 元数据 →
+    帧数据(frames-data)→ 深度预览转码。前三项填充服务端内存缓存,
+    让"点击批次"的首开在后端重启后也保持 ~1-2s(否则冷开要再付
+    media-groups ~7.7s + hand-3d 元数据 ~10.8s 的 NAS 读取)。
+    """
+    global _PREWARM_RUNNING
+    try:
+        while True:
+            with _PREWARM_LOCK:
+                if not _PREWARM_QUEUE:
+                    return
+                episode_id = _PREWARM_QUEUE.popleft()
+            try:
+                ep = get_episode(episode_id)
+                if ep is None:
+                    continue
+                # 1) 素材清单(点击门控的第一个 await)
+                try:
+                    episode_media_groups(episode_id)
+                except Exception:
+                    pass
+                # 2) 手部 3D 元数据(meta-only 路径,填充 hand3d meta 缓存)
+                try:
+                    from app.routes.video import get_hand_3d
+
+                    get_hand_3d(episode_id, None, None, None, None)
+                except Exception:
+                    pass
+                # 3) 帧数据(手套/传感器载荷,填 _frames_data_cache)
+                try:
+                    episode_frames_data(episode_id)
+                except Exception:
+                    pass
+                # 4) 深度预览转码(已有)
+                for video_path in _episode_depth_video_paths(ep):
+                    try:
+                        from app.browser_preview import (
+                            depth_preview_exists,
+                            ensure_depth_h264_preview,
+                            ensure_local_mirror,
+                        )
+
+                        if depth_preview_exists(video_path):
+                            continue
+                        ensure_local_mirror(video_path, wait_seconds=120)
+                        ensure_depth_h264_preview(video_path)
+                    except Exception:
+                        continue
+                print(f"[Prewarm] warmed {episode_id}")
+            except Exception:
+                continue
+    finally:
+        with _PREWARM_LOCK:
+            _PREWARM_RUNNING = False
+
+
+def _trigger_depth_prewarm(episode_ids: list[str]) -> None:
+    """把前 N 个未预热的批次排入队列并启动后台 worker(去重、有界)。"""
+    global _PREWARM_RUNNING
+    with _PREWARM_LOCK:
+        queued = 0
+        for episode_id in episode_ids:
+            if episode_id in _PREWARM_QUEUED:
+                continue
+            if queued >= _PREWARM_MAX_PER_PASS:
+                break
+            if len(_PREWARM_QUEUE) >= _PREWARM_MAX_QUEUE:
+                break
+            _PREWARM_QUEUED.add(episode_id)
+            _PREWARM_QUEUE.append(episode_id)
+            queued += 1
+        if not queued or _PREWARM_RUNNING:
+            return
+        _PREWARM_RUNNING = True
+        threading.Thread(
+            target=_prewarm_worker, name="depth-preview-prewarm",
+            daemon=True,
+        ).start()
+
+
 @router.get("/episodes")
 def episode_list(status: str | None = None, limit: int = 50, offset: int = 0,
                        brief: bool = False):
@@ -98,6 +217,11 @@ def episode_list(status: str | None = None, limit: int = 50, offset: int = 0,
                 episodes = [e for e in episodes if e.get("status") == status]
     total = len(episodes)
     episodes = episodes[offset:offset + limit]
+    # 预热深度预览:用户从列表点开前,后台先把预览生成好(尽力而为)
+    try:
+        _trigger_depth_prewarm([e["id"] for e in episodes])
+    except Exception:
+        pass
     serialize = _ep_to_out_brief if brief else _ep_to_out
     return {"episodes": [serialize(e) for e in episodes], "total": total,
             "limit": limit, "offset": offset}
@@ -254,6 +378,9 @@ def episode_frames_data(episode_id: str):
                         # 列(hand_pose 等)不含这些关键字,天然排除
                         if not ("sensor" in lower or "glove" in lower or "tactile" in lower):
                             continue
+                        # IMU/valid 列是遥测而非触觉压力阵列,不参与热力图
+                        if "imu" in lower or lower.endswith("_valid"):
+                            continue
                         if sname in available_sensors:
                             continue
                         # 真实压力数据(全文件均匀采样)才驱动热力图
@@ -357,45 +484,6 @@ def _member_label(camera: str, role: str) -> str:
     return label_map.get(role, camera)
 
 
-def _detect_glove_sources(batch_dir, ep_id_str: str, project_name: str = "") -> list[dict]:
-    """Detect real glove/tactile columns in the canonical episode parquet."""
-    if batch_dir is None:
-        return []
-    from app.localstore import episode_has_glove_sensor
-    episode = get_episode(ep_id_str)
-    if episode is None:
-        episode = {"id": ep_id_str, "project": project_name or ""}
-    if not episode_has_glove_sensor(episode):
-        return []
-    try:
-        import pyarrow.parquet as pq
-    except ImportError:
-        return []
-    sources: list[dict] = []
-    for parq_file in _canonical_data_files(Path(batch_dir), ep_id_str):
-        try:
-            names = pq.ParquetFile(parq_file).schema_arrow.names
-        except Exception:
-            continue
-        for col in names:
-            if not col.startswith("observation."):
-                continue
-            source_key = col.split(".", 1)[1]
-            lower = source_key.lower()
-            if not any(token in lower for token in ("glove", "sensor", "tactile")):
-                continue
-            if not _col_has_pressure(parq_file, col):
-                continue
-            sources.append({
-                "id": f"glove:{source_key}",
-                "kind": "glove",
-                "source_key": source_key,
-                "label": source_key,
-                "heatmap_url": f"/api/v1/video/{ep_id_str}/heatmap/{{frame}}?sensor={source_key}",
-            })
-    return sources
-
-
 def _detect_depth_sources(batch_dir, ep_id_str: str, master_frame_count: int = 0,
                           master_fps: float = 0) -> list[dict]:
     """Detect canonical metric-depth video streams for the review page.
@@ -441,6 +529,15 @@ def _detect_depth_sources(batch_dir, ep_id_str: str, master_frame_count: int = 0
             # filename alone must not turn a colour video into 3D input.
             if not metric_depth:
                 continue
+            # Warm the local transport mirror in the background while the
+            # review page is still mounting; the first full-stream decode
+            # then reads from local disk instead of the SSHFS mount.
+            try:
+                from app.browser_preview import ensure_local_mirror
+
+                ensure_local_mirror(video_path)
+            except Exception:
+                pass
             frames = 0
             fps = float(master_fps or info.get("fps") or 0)
             try:
@@ -478,9 +575,11 @@ def _detect_depth_sources(batch_dir, ep_id_str: str, master_frame_count: int = 0
                     f"/api/v1/video/{ep_id_str}/depth-codes/{source_name}/{{frame}}"),
                 "depth_codes_window_url": (
                     f"/api/v1/video/{ep_id_str}/depth-codes-window/"
-                    f"{source_name}?start_frame={{start}}&end_frame={{end}}"),
+                    f"{source_name}?start_frame={{start}}&end_frame={{end}}"
+                    f"&scale=2"),
                 "depth_codes_full_url": (
-                    f"/api/v1/video/{ep_id_str}/depth-codes-full/{source_name}"),
+                    f"/api/v1/video/{ep_id_str}/depth-codes-full/{source_name}"
+                    f"?scale=2"),
                 # Deprecated alias retained for clients that used the old
                 # frame URL; it now returns raw uint16 codes, never JET.
                 "depth_preview_url": (
@@ -599,7 +698,6 @@ def episode_media_groups(episode_id: str):
         result["singles"].append(entry)
         result["sources"].append(_as_source(entry, None))
 
-    result["sources"].extend(_detect_glove_sources(batch_dir, episode_id, ep.get("project") or ""))
     result["sources"].extend(_detect_depth_sources(
         batch_dir,
         episode_id,

processor/app/routes/video.py

@@ -3,6 +3,7 @@
 import os
 import re
 import asyncio
+import shutil
 import threading
 from pathlib import Path
 from uuid import UUID, uuid4
@@ -32,6 +33,9 @@ _DEPTH_READER_POOL_LOCK = threading.Lock()
 _DEPTH_READER_POOL_MAX = 8
 _DEPTH_FRAME_CACHE: dict[tuple[str, int], object] = {}
 _DEPTH_FRAME_CACHE_MAX = 48
+# Sequential decode is cheap, but decoding through more than this many
+# frames to reach a scrub target is not; jump via a seek reader instead.
+_DEPTH_WINDOW_SEEK_GAP = 6
 
 
 def _read_canonical_depth_codes(path: Path, frame_index: int):
@@ -89,6 +93,39 @@ def _read_canonical_depth_codes(path: Path, frame_index: int):
         return result
 
 
+def _depth_local_source(depth_video: Path) -> Path:
+    """Decode from a local mirror of the NAS depth file when one is ready.
+
+    The mirror is a bit-identical disposable cache (see
+    ``browser_preview.ensure_local_mirror``); a missing/cold mirror falls
+    back to the authoritative path for this request.
+    """
+    try:
+        from app.browser_preview import ensure_local_mirror
+
+        return ensure_local_mirror(depth_video)
+    except Exception:
+        return depth_video
+
+
+def _downscale_depth_codes(codes, scale: int):
+    """Optionally area-downsample raw depth codes for display transport.
+
+    The browser canvas usually renders the depth tile far below the native
+    resolution, so a 2x/4x downsample cuts the payload by 4x/16x without
+    visible loss.  Codes stay in the canonical uint16 domain so the
+    frontend colormap/range pipeline is untouched.
+    """
+    if not scale or int(scale) <= 1:
+        return codes
+    import cv2
+
+    s = int(scale)
+    h, w = codes.shape
+    return cv2.resize(codes, (max(1, w // s), max(1, h // s)),
+                      interpolation=cv2.INTER_AREA)
+
+
 def _read_canonical_depth_code_window(path: Path, start_frame: int,
                                       end_frame: int):
     """Read a contiguous raw-code window from one sequential decoder.
@@ -122,10 +159,20 @@ def _read_canonical_depth_code_window(path: Path, start_frame: int,
                     pass
 
     with state["lock"]:
-        if start_frame < state["next_frame"]:
+        gap = start_frame - state["next_frame"]
+        if gap < 0 or gap > _DEPTH_WINDOW_SEEK_GAP:
+            # Backward or far-forward jump: position a seek reader at the
+            # exact target frame instead of decoding from frame 0 (or from a
+            # stale pool position).  The keyint=2 depth contract keeps the
+            # seek cost constant regardless of the jump distance.
+            from app.lerobot_v21 import DepthCodeSeekReader
+
+            fps = float(getattr(state["reader"], "fps", 0) or 30.0)
+            pix_fmt = str(getattr(state["reader"], "pix_fmt", "") or "gray12le")
             state["reader"].close()
-            state["reader"] = DepthVideoReader(path)
-            state["next_frame"] = 0
+            state["reader"] = DepthCodeSeekReader(
+                path, start_frame, fps, pix_fmt)
+            state["next_frame"] = start_frame
         frames = []
         while state["next_frame"] <= end_frame:
             codes = state["reader"].read_codes()
@@ -1152,6 +1199,7 @@ def _hand3d_meta(path: Path, source_key: str | None = None) -> dict:
     metric_3d_available = True
     valid_hand_frames = 0
     valid_landmark_points = 0
+    counted = False  # 计数是否真实执行过(前端据此区分"全空"与"统计失败")
     try:
         columns = set(_pd.read_parquet(path, engine="pyarrow").columns)
         field_map = _hand3d_column_map(columns, source_key)
@@ -1181,14 +1229,16 @@ def _hand3d_meta(path: Path, source_key: str | None = None) -> dict:
 
         # Count real finite landmarks for source selection.  This is only
         # metadata for the review UI; it never changes the stored data.
+        # 采样统计:均匀散布读 1/3 的 row group(NAS 上全量读这些列
+        # 实测 ~20s),计数按采样率放大保持量级;采样失败回退全量读。
         count_raw = [field_map.get(name) for name in (
             "hand_0_present", "hand_1_present",
             "hand_0_landmarks_3d", "hand_1_landmarks_3d",
         ) if field_map.get(name)]
-        if count_raw:
-            count_df = _pd.read_parquet(path, columns=list(dict.fromkeys(count_raw)),
-                                        engine="pyarrow")
-            for _, count_row in count_df.iterrows():
+
+        def _count_rows(rows_iter) -> None:
+            nonlocal valid_hand_frames, valid_landmark_points
+            for _, count_row in rows_iter:
                 row_has_hand = False
                 for hk in ("hand_0", "hand_1"):
                     present_name = field_map.get(f"{hk}_present")
@@ -1209,6 +1259,35 @@ def _hand3d_meta(path: Path, source_key: str | None = None) -> dict:
                     row_has_hand = row_has_hand or bool(finite.any())
                 if row_has_hand:
                     valid_hand_frames += 1
+
+        if count_raw:
+            count_columns = list(dict.fromkeys(count_raw))
+            counted = False
+            try:
+                import pyarrow.parquet as _pq
+
+                parquet = _pq.ParquetFile(path)
+                total_rows = int(parquet.metadata.num_rows)
+                groups = list(range(0, parquet.num_row_groups, 3)) or [0]
+                sampled_rows = sum(
+                    int(parquet.metadata.row_group(i).num_rows) for i in groups)
+                sample_factor = (total_rows / max(1, sampled_rows))
+                before_frames = valid_hand_frames
+                before_points = valid_landmark_points
+                for group_index in groups:
+                    count_df = parquet.read_row_group(
+                        group_index, columns=count_columns).to_pandas()
+                    _count_rows(count_df.iterrows())
+                valid_hand_frames = before_frames + int(
+                    (valid_hand_frames - before_frames) * sample_factor)
+                valid_landmark_points = before_points + int(
+                    (valid_landmark_points - before_points) * sample_factor)
+                counted = True
+            except Exception:
+                count_df = _pd.read_parquet(path, columns=count_columns,
+                                            engine="pyarrow")
+                _count_rows(count_df.iterrows())
+                counted = True
     except Exception:
         # Metadata failure must not prevent the frame endpoint from working.
         pass
@@ -1231,6 +1310,7 @@ def _hand3d_meta(path: Path, source_key: str | None = None) -> dict:
         "render_video": "",
         "valid_hand_frames": int(valid_hand_frames),
         "valid_landmark_points": int(valid_landmark_points),
+        "counted": bool(counted),
         "meta_schema_version": 2,
     }
 def _parse_range(range_header: str, file_size: int) -> tuple[int, int]:
@@ -1281,7 +1361,8 @@ async def get_depth_codes(
         raise HTTPException(status_code=404, detail=f"Depth source not found: {name}")
     try:
         codes = await asyncio.to_thread(
-            _read_canonical_depth_codes, depth_video, frame_index)
+            _read_canonical_depth_codes, _depth_local_source(depth_video),
+            frame_index)
     except IndexError:
         raise HTTPException(
             status_code=404,
@@ -1325,6 +1406,124 @@ async def get_depth_jet_lut():
                          "values": lut.tolist()})
 
 
+@router.get("/depth-color-lut")
+async def get_depth_color_lut():
+    """Return the 256-entry Google Turbo LUT (bgr order, Rerun-style depth
+    colormap) for frontend-only depth colorization."""
+    from app.lerobot_v21 import turbo_lut_256
+
+    values = [[b, g, r] for (r, g, b) in turbo_lut_256()]
+    return JSONResponse({"name": "google_turbo", "order": "bgr",
+                         "values": values})
+
+
+_DEPTH_STATS_CACHE: dict[str, dict] = {}
+_DEPTH_STATS_CACHE_LOCK = threading.Lock()
+
+
+def _depth_stats_for(source: Path) -> dict | None:
+    """q01/q99 bounds for a depth source: memory cache → disk persistence.
+
+    The disk copy is written once by preview generation (fingerprint-keyed)
+    and survives restarts, so the stats endpoint and the preview stream can
+    answer instantly without a second full-stream decode.
+    """
+    try:
+        stats_key = f"{source.resolve()}@{source.stat().st_mtime_ns}"
+    except OSError:
+        return None
+    with _DEPTH_STATS_CACHE_LOCK:
+        cached = _DEPTH_STATS_CACHE.get(stats_key)
+    if cached is not None:
+        return cached
+    try:
+        from app.browser_preview import read_depth_stats
+
+        disk = read_depth_stats(source)
+        if disk is not None:
+            with _DEPTH_STATS_CACHE_LOCK:
+                _DEPTH_STATS_CACHE[stats_key] = disk
+            return disk
+    except Exception:
+        pass
+    return None
+
+
+def _compute_depth_stats(source: Path) -> dict | None:
+    """Sample-decode the stored depth video and return q01/q99 code bounds.
+
+    One ffmpeg pass keeps ~32 spread frames; the sampled domain is the
+    canonical uint16 gray12le codes, so the percentiles map directly onto the
+    frontend color range (Rerun-style adaptive depth scaling).
+    """
+    import subprocess
+
+    import numpy as np
+    from app.lerobot_v21 import DEPTH_QMAX
+
+    ffprobe = shutil.which("ffprobe")
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffprobe or not ffmpeg:
+        return None
+    probe = subprocess.run(
+        [ffprobe, "-v", "error", "-select_streams", "v:0",
+         "-count_packets", "-show_entries", "stream=nb_read_packets",
+         "-of", "csv=p=0", str(source)],
+        check=False, capture_output=True, text=True, timeout=30)
+    total = 0
+    try:
+        total = int(float(str(probe.stdout).strip().split(",")[0]))
+    except (ValueError, IndexError):
+        total = 0
+    step = max(1, (total or 900) // 32)
+    proc = subprocess.run(
+        [ffmpeg, "-v", "error", "-i", str(source), "-map", "0:v:0",
+         "-vf", f"select=not(mod(n\\,{step}))",
+         "-f", "rawvideo", "-pix_fmt", "gray12le", "-"],
+        check=False, capture_output=True, timeout=600)
+    data = np.frombuffer(proc.stdout, dtype="<u2")
+    if data.size < 2:
+        return None
+    # Keep the same 12-bit code domain as the raw frames served to the
+    # browser.  Sampling with gray16le made ffmpeg bit-shift every value
+    # (~x16) to fill the wider format, so q01/q99 came out ~16x too large
+    # and the frontend Turbo ramp collapsed into its darkest segment.
+    data = np.clip(data, 0, DEPTH_QMAX)
+    return {
+        "q01": float(np.percentile(data, 1)),
+        "q99": float(np.percentile(data, 99)),
+        "total_frames": total,
+    }
+
+
+@router.get("/depth-stats/{episode_id}/{name}")
+async def get_depth_stats(episode_id: str, name: str):
+    """q01/q99 depth-code bounds for adaptive frontend colorization."""
+    ep = get_episode(episode_id)
+    if ep is None:
+        raise HTTPException(status_code=404, detail="Episode not found")
+    session_dir = Path(ep["path"])
+    safe_name = str(name).replace("/", "_").replace("\\", "_").replace("..", "_")
+    source = find_depth_video(session_dir, safe_name, str(ep.get("id") or ""))
+    if source is None:
+        raise HTTPException(status_code=404, detail=f"Depth source not found: {name}")
+    cached = _depth_stats_for(source)
+    if cached is not None:
+        return JSONResponse(
+            cached,
+            headers={"Cache-Control": "public, max-age=3600"})
+    # No whole-video decode on a cache miss: preview generation computes and
+    # persists these bounds during its own decode, so the frontend receives
+    # the neutral full-range fallback now and re-fetches after the load.
+    from app.lerobot_v21 import DEPTH_QMAX
+
+    return JSONResponse(
+        {"q01": 0.0, "q99": float(DEPTH_QMAX), "total_frames": 0,
+         "pending": True},
+        headers={"Cache-Control": "no-store"},
+    )
+
+
 @router.get("/{episode_id}/depth-preview/{name}/{frame_index}")
 async def get_depth_preview(
     episode_id: str,
@@ -1341,12 +1540,15 @@ async def get_depth_codes_window(
     name: str,
     start_frame: int = Query(0, ge=0),
     end_frame: int | None = Query(None, ge=0),
+    scale: int = Query(1, ge=1, le=8),
 ):
     """Return a short contiguous window of canonical uint16 depth codes.
 
-    This is a transport optimization for the browser-only JET renderer. The
-    response is still the exact stored code domain (little-endian uint16),
-    never a heatmap or a persisted colorized frame.
+    This is a transport optimization for the browser-only colorized renderer.
+    The response is still the exact stored code domain (little-endian
+    uint16), never a heatmap or a persisted colorized frame.  ``scale``
+    downsamples each frame by an integer factor (INTER_AREA) to cut the
+    payload; the frontend colormap pipeline is unaffected.
     """
     ep = get_episode(episode_id)
     if ep is None:
@@ -1367,7 +1569,7 @@ async def get_depth_codes_window(
     try:
         frames = await asyncio.to_thread(
             _read_canonical_depth_code_window,
-            depth_video, start_frame, requested_end,
+            _depth_local_source(depth_video), start_frame, requested_end,
         )
     except IndexError:
         raise HTTPException(
@@ -1380,6 +1582,9 @@ async def get_depth_codes_window(
             detail=f"Unable to decode depth codes: {exc}",
         ) from exc
     first = frames[0]
+    if int(scale) > 1:
+        frames = [_downscale_depth_codes(frame, scale) for frame in frames]
+        first = frames[0]
     payload = b"".join(frame.tobytes(order="C") for frame in frames)
     actual_end = start_frame + len(frames) - 1
     return Response(
@@ -1395,6 +1600,7 @@ async def get_depth_codes_window(
             "X-Depth-End": str(actual_end),
             "X-Depth-Frames": str(len(frames)),
             "X-Depth-Frame-Bytes": str(first.nbytes),
+            "X-Depth-Scale": str(scale),
             "X-Depth-Qmax": "4095",
         },
     )
@@ -1420,12 +1626,14 @@ def _open_depth_code_stream(path: Path):
 
 
 @router.get("/{episode_id}/depth-codes-full/{name}")
-async def get_depth_codes_full(episode_id: str, name: str):
+async def get_depth_codes_full(episode_id: str, name: str,
+                               scale: int = Query(1, ge=1, le=8)):
     """Stream the complete stored depth-code sequence in frame order.
 
     This is a transport-only optimization for the frontend renderer.  The
     payload is raw little-endian uint16 gray12le code data; it is never JET,
-    RGB, millimetres, or a persisted preview image.
+    RGB, millimetres, or a persisted preview image.  ``scale`` downsamples
+    each frame by an integer factor (INTER_AREA) before streaming.
     """
     ep = get_episode(episode_id)
     if ep is None:
@@ -1439,7 +1647,7 @@ async def get_depth_codes_full(episode_id: str, name: str):
     try:
         import numpy as np
         reader, first = await asyncio.to_thread(
-            _open_depth_code_stream, depth_video)
+            _open_depth_code_stream, _depth_local_source(depth_video))
     except IndexError:
         raise HTTPException(status_code=404, detail=f"Empty depth source: {name}")
     except (OSError, RuntimeError, ValueError) as exc:
@@ -1448,6 +1656,8 @@ async def get_depth_codes_full(episode_id: str, name: str):
             detail=f"Unable to decode depth codes: {exc}",
         ) from exc
 
+    if int(scale) > 1:
+        first = _downscale_depth_codes(first, scale)
     width, height = int(first.shape[1]), int(first.shape[0])
     frame_bytes = int(first.nbytes)
     expected_frames = int(reader.frame_count or 0)
@@ -1471,6 +1681,7 @@ async def get_depth_codes_full(episode_id: str, name: str):
         "X-Depth-Frame-Bytes": str(frame_bytes),
         "X-Depth-Start": "0",
         "X-Depth-End": str(max(0, expected_frames - 1)),
+        "X-Depth-Scale": str(scale),
         "X-Depth-Qmax": "4095",
         "X-Depth-Transport": "full-sequential-raw-codes",
     }
@@ -1482,16 +1693,45 @@ async def get_depth_codes_full(episode_id: str, name: str):
     def iterator():
         count = 0
         current = first
+        histogram = np.zeros(4096, dtype=np.int64)
+        stats_cache_key = None
         try:
             while current is not None:
+                histogram += np.bincount(
+                    current.reshape(-1).astype(np.int64),
+                    minlength=4096)[:4096]
                 yield current.tobytes(order="C")
                 count += 1
                 current = reader.read_codes()
                 if current is not None:
                     current = np.ascontiguousarray(
                         current, dtype="<u2")
+                    if int(scale) > 1:
+                        current = _downscale_depth_codes(current, scale)
         finally:
             reader.close()
+            # Piggyback the q01/q99 display stats on the full-stream pass:
+            # the depth-stats endpoint then needs no second whole-video
+            # decode (which competed with this one and doubled open time).
+            try:
+                stats_cache_key = (
+                    f"{depth_video.resolve()}"
+                    f"@{depth_video.stat().st_mtime_ns}")
+                cumulative = np.cumsum(histogram)
+                total_pixels = int(cumulative[-1])
+                if total_pixels > 0:
+                    q01 = float(np.searchsorted(
+                        cumulative, total_pixels * 0.01, side="right"))
+                    q99 = float(np.searchsorted(
+                        cumulative, total_pixels * 0.99, side="right"))
+                    with _DEPTH_STATS_CACHE_LOCK:
+                        _DEPTH_STATS_CACHE[stats_cache_key] = {
+                            "q01": q01,
+                            "q99": q99,
+                            "total_frames": int(reader.frame_count or count),
+                        }
+            except Exception:
+                pass
 
     return StreamingResponse(
         iterator(),
@@ -1705,9 +1945,37 @@ async def _h264_preview_path(source: Path) -> Path:
         raise HTTPException(status_code=503, detail=str(exc)) from exc
 
 
+def _depth_h264_preview_path(source: Path, q01: float, q99: float) -> Path:
+    from app.browser_preview import ensure_depth_h264_preview
+
+    try:
+        return ensure_depth_h264_preview(source, q01=q01, q99=q99)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+
 def _video_response(file_path: Path, range_header: str | None):
-    """Serve an MP4 with byte ranges required by HTML5/Plyr."""
+    """Serve an MP4 with byte ranges required by HTML5/Plyr.
+
+    Cacheable by the browser (ETag = size+mtime): repeat opens of RGB and
+    depth preview streams are served from the browser cache, so the video
+    element paints its first frame without waiting on a re-download.
+    """
+    file_path = Path(file_path)
     file_size = file_path.stat().st_size
+    try:
+        stat = file_path.stat()
+        etag = f'W/"{stat.st_size:x}-{stat.st_mtime_ns:x}"'
+    except OSError:
+        etag = None
+    common_headers = {
+        "Accept-Ranges": "bytes",
+        "Cache-Control": "public, max-age=3600",
+    }
+    if etag:
+        common_headers["ETag"] = etag
 
     def _stream_full():
         with open(file_path, "rb") as f:
@@ -1717,7 +1985,7 @@ def _video_response(file_path: Path, range_header: str | None):
     if not range_header:
         return StreamingResponse(
             _stream_full(), media_type="video/mp4",
-            headers={"Content-Length": str(file_size), "Accept-Ranges": "bytes"},
+            headers={**common_headers, "Content-Length": str(file_size)},
         )
 
     start, end = _parse_range(range_header, file_size)
@@ -1736,9 +2004,9 @@ def _video_response(file_path: Path, range_header: str | None):
 
     return StreamingResponse(
         _stream_range(), status_code=206, media_type="video/mp4",
-        headers={"Content-Range": f"bytes {start}-{end}/{file_size}",
-                 "Content-Length": str(content_length),
-                 "Accept-Ranges": "bytes"},
+        headers={**common_headers,
+                 "Content-Range": f"bytes {start}-{end}/{file_size}",
+                 "Content-Length": str(content_length)},
     )
 
 
@@ -1894,14 +2162,27 @@ async def stream_browser_depth_preview(
     camera: str,
     range_header: str | None = Header(None, alias="Range"),
 ):
-    """Serve a browser-compatible depth stream; colorization stays in Canvas."""
+    """Serve an 8-bit Turbo H.264 preview of the depth stream.
+
+    Generated once per source into the local disposable preview cache
+    (identical clamp/scale/colormap math as the browser renderer used to
+    apply), so the review page plays it through a native <video> element.
+    The canonical 12-bit stream remains the authoritative dataset asset.
+    """
     ep = get_episode(episode_id)
     if ep is None:
         raise HTTPException(status_code=404, detail="Episode not found")
     source = find_depth_video(Path(ep["path"]), camera, str(ep.get("id") or ""))
     if source is None:
         raise HTTPException(status_code=404, detail="Depth video not found")
-    preview = await _h264_preview_path(source)
+    # Prefer the q01/q99 bounds from the in-memory cache or the disk copy
+    # persisted by preview generation; a neutral full-range mapping is used
+    # when the stats have not been computed yet.
+    stats = _depth_stats_for(source) or {}
+    preview = await asyncio.to_thread(
+        _depth_h264_preview_path, source,
+        float(stats.get("q01") or 0.0), float(stats.get("q99") or 4095.0),
+    )
     return _video_response(preview, range_header)
 
 

processor/app/version.py

@@ -8,5 +8,5 @@
 
 前端版本独立管理, 见 web/workflow-studio/package.json 的 version 字段.
 """
-# 1.6.8 初始管理员改为可配置,公开模板使用占位演示凭据
-__version__ = "1.6.8"
+# 1.7.0 中英文文档重构(带截图引导图)+ 服务开机自启 + 任务队列修复
+__version__ = "1.7.0"

processor/deploy.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""EgoData Data Acquisition 一键部署脚本.
+"""EgoData processor 一键部署脚本.
 
 跨平台 (Linux / Windows)，纯标准库实现：
 
@@ -558,7 +558,7 @@ def phase_env(ip: str) -> dict:
             replace_if=("", "change-me-worker-key"))
     # 缺失或等于示例默认值(过期的 IP/端口)时, 补为当前局域网地址
     fix("PUBLIC_BASE_URL", f"http://{ip}:{DEFAULT_BACKEND_PORT}",
-        replace_if=("", "http://127.0.0.1:8000"))
+        replace_if=("", "http://192.168.110.41:2586"))
     if values.get("STORAGE_BACKEND") == "sftp":
         warn(".env 使用 STORAGE_BACKEND=sftp, 本脚本不配置 SSH 隧道/SFTP, 请自行确保可用")
 
@@ -1173,7 +1173,7 @@ def phase_report(rep: dict, ports: dict, vllm_enabled: bool, args) -> None:
 
 def parse_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(
-        description="EgoData Data Acquisition 一键部署 (跨平台)")
+        description="EgoData processor 一键部署 (跨平台)")
     p.add_argument("--check-only", action="store_true",
                    help="只做硬件能力体检, 零副作用")
     p.add_argument("--download-model", action="store_true",
@@ -1200,7 +1200,7 @@ def main() -> None:
         except (OSError, ValueError):
             pass
     say("═" * 62)
-    say(f"  EgoData Data Acquisition 一键部署")
+    say(f"  EgoData processor 一键部署")
     say(f"  项目目录: {PROJECT_ROOT}")
     say(f"  系统: {platform.system()} {platform.release()}  "
         f"Python: {sys.version.split()[0]}")

processor/docs/README.md

@@ -0,0 +1,896 @@
+# processor 项目文档介绍
+
+processor 是数据接收、处理、审核和导出系统。
+
+本文档把项目的功能、页面、图片和操作方法整理在一起。阅读时按照页面顺序向下查看，不需要在多个文档之间来回跳转。
+
+## 目录
+
+1. [项目整体流程](#1-项目整体流程)
+2. [安装和启动](#2-安装和启动)
+3. [首页](#3-首页)
+4. [项目和接收数据](#4-项目和接收数据)
+5. [工作流](#5-工作流)
+6. [标注数据](#6-标注数据)
+7. [视频查看和审核](#7-视频查看和审核)
+8. [已通过和导出](#8-已通过和导出)
+9. [失败处理](#9-失败处理)
+10. [垃圾桶](#10-垃圾桶)
+11. [常见问题](#11-常见问题)
+12. [数据和程序说明](#12-数据和程序说明)
+13. [代码结构与功能说明](#13-代码结构与功能说明)
+
+## 1. 项目整体流程
+
+系统的完整流程是：
+
+```text
+安装启动
+  ↓
+打开首页
+  ↓
+创建或选择项目
+  ↓
+接收数据
+  ↓
+选择并运行工作流
+  ↓
+查看视频和处理结果
+  ↓
+标注、检查和审核
+  ↓
+导出数据
+```
+
+系统当前的主要页面：
+
+- Home：查看整体数据状态；
+- Projects：查看项目和 Episode；
+- Workflow：配置和运行工作流；
+- Annotation：处理标注；
+- Video Review：查看视频和审核数据；
+- Trash：查看已删除的数据。
+
+Users 用户系统目前仍在开发中，暂不纳入当前操作流程。
+
+## 2. 安装和启动
+
+### 2.1 下载并打开项目
+
+下载项目后，打开：
+
+```text
+processor/
+```
+
+### 2.2 启动程序
+
+Linux：
+
+```bash
+cd processor
+python deploy.py
+```
+
+只检查电脑环境，不启动服务：
+
+```bash
+python deploy.py --check-only
+```
+
+使用外部 AI API 时：
+
+```bash
+python deploy.py --skip-vllm
+```
+
+Windows 用户可以运行项目中的 Windows 部署脚本。
+
+### 2.3 打开网页
+
+等待服务启动后，在浏览器打开管理员提供的地址。
+
+看到登录页面，说明网页已经启动。打开：
+
+```text
+/health
+```
+
+可以检查服务是否正常。
+
+> 图片位置：待补充“启动成功和登录页面”截图。
+
+### 2.4 出现问题
+
+- 页面打不开：检查后端是否启动；
+- 数据不处理：检查 Worker 是否启动；
+- 工作流搭建好后，上传对应的数据会自动跑工作流，如果没有自动处理检查一下工作流，或者手动出现跑一下
+
+## 3. 首页
+
+### 3.1 首页有什么作用？
+
+首页用来查看所有数据的总体状态。
+
+### 3.2 首页真实页面
+
+![首页功能图](images/02-home-annotated.png)
+
+图中主要区域：
+
+1. 左侧页面菜单；
+2. 顶部数据统计；
+3. 项目列表；
+4. 最近的数据；
+5. 刷新按钮。
+
+### 3.3 数据状态
+
+| 状态      | 说明             |
+| --------- | ---------------- |
+| Reviewing | 正在检查         |
+| Approved  | 已经通过         |
+| Failed    | 处理失败         |
+| Trash     | 已删除，可以恢复 |
+
+### 3.4 怎么操作？
+
+1. 登录后进入首页；
+2. 查看顶部数据统计；
+3. 点击项目名称查看项目；
+4. 数据没有更新时，点击右上角 Refresh。
+
+### 3.5 看到什么算正常？
+
+数据从 Reviewing 变成 Approved，表示数据检查完成并通过。
+
+如果一直显示 Processing，等待后刷新页面；仍然不变时检查 Worker。
+
+## 4. 项目和接收数据
+
+### 4.1 项目是什么？
+
+项目用于保存一组相关的数据。一个项目下面可以有多个 Episode。
+
+processor 负责接收采集端发送的数据，并把数据放入对应项目中。采集设备本身不在 processor 中完成采集。
+
+### 4.2 查看已有项目
+
+打开左侧 `Projects`，可以查看已有项目和接收到的数据。
+
+[![项目列表功能](images/projects-list-annotated.png)](images/projects-list-annotated.png)
+
+图中功能：
+
+1. `搜索项目`：输入项目名称，快速找到项目；
+2. `新建项目`：建立一个新的数据接收项目；
+3. `项目信息`：查看项目名称、状态、工作流、实际输入、Episode 数量和接收统计；
+4. `Edit Project`：修改项目名称、工作流和项目状态；
+5. `Delete`：删除当前项目，删除后可在垃圾桶中查看；
+6. `展开接收批次`：点击项目行或右侧箭头，查看已接收的批次和 Episode。
+
+`active` 表示项目正在使用，可以继续接收数据；`paused` 表示项目暂停使用。
+
+### 4.3 新建项目
+
+点击右上角 `New Project`，填写项目基本信息。
+
+[![新建项目功能](images/project-new-annotated.png)](images/project-new-annotated.png)
+
+各项内容：
+
+- `Project Name`：项目名称；
+- `Workflow`：给项目绑定一个当前工作流，可以新建工作流，新建的工作流初始为空，也可以选择已有的工作流；
+- `Status`：`active` 表示启用，`paused` 表示暂停；
+- `Target Episodes`：计划接收的数据数量，`0` 表示不限制；
+- `Description`：项目说明，可以不填写；
+- `Save`：保存项目。
+
+项目名称不能为空。保存新项目后，系统会询问是否进入工作流页面继续设置。
+
+### 4.4 选择工作流
+
+在新建项目页面的 `Workflow` 中选择对应工作流。
+
+[![选择项目工作流](images/project-workflow-select-annotated.png)](images/project-workflow-select-annotated.png)
+
+工作流列表功能：
+
+1. 点击 `Workflow` 输入框打开工作流列表；
+2. 点击 `+ New Workflow` 新建空白工作流；
+3. 带 `Template` 标记的是模板工作流；
+4. 点击已有工作流名称，将它绑定到当前项目；
+5. 点击右侧按钮，进入工作流页面编辑该工作流。
+
+一个项目使用一个当前工作流。重新选择其他工作流时会另存为新的绑定当前的工作流。
+
+选择原则：
+
+- RGB 数据选择 RGB 相关工作流；
+- RGB 加 Depth 选择 RGB-D 相关工作流；
+- 有手套传感器时选择包含 Glove Sensor 的工作流；
+- 不确定时不要随便选择，先确认项目输入数据类型。
+
+### 4.5 接收数据流程
+
+```text
+采集端生成数据
+  ↓
+采集端发送数据
+  ↓
+processor 接收数据
+  ↓
+解压和检查
+  ↓
+匹配项目和工作流
+  ↓
+项目中出现新的 Episode
+```
+
+### 4.6 接收数据时怎么操作？
+
+1. 新建项目并选择正确的工作流；
+2. 保持项目状态为 `active`；
+3. 由采集端向 processor 发送数据；
+4. 等待 processor 接收、解压和检查；
+5. 展开项目，确认新的批次和 Episode 已经出现。
+
+项目已经绑定工作流时，系统会处理新接收的数据。没有绑定工作流时，数据只会被接收和保存，不会执行后处理；之后绑定工作流并保存，系统会补充处理已有批次。
+
+### 4.7 重要提醒
+
+- 接收过程中不要关闭采集端的发送程序；
+- 解压和检查完成前不要重复发送同一个数据；
+- 每个 Episode 应该有对应的视频或传感器数据；
+- 接收失败时先查看失败提示，再重新发送或重新处理；
+- 项目和工作流不匹配时，不要强行运行。
+
+## 5. 工作流
+
+### 5.1 工作流是什么？
+
+工作流决定系统如何处理接收到的数据。
+
+```text
+输入数据 → 处理数据 → 检查结果 → 导出数据
+```
+
+### 5.2 工作流页面
+
+点击左侧 `Workflow` 进入工作流页面。
+
+[![工作流页面](images/workflow-empty-annotated.png)](images/workflow-empty-annotated.png)
+
+图中功能：
+
+1. `工作流选择`：切换已有工作流或新建工作流；
+2. `工作流名称`：查看或修改当前工作流名称；
+3. `编辑画布`：放置节点并用连接线组成处理流程；
+4. `节点列表`：提供输入、处理、审核和导出节点；
+5. `Template`：从模板开始建立工作流；
+6. `Save`：保存当前工作流。
+
+### 5.3 从模板开始
+
+点击右上角 `Template`，选择和接收数据匹配的模板。
+
+[![选择工作流模板](images/workflow-template-annotated.png)](images/workflow-template-annotated.png)
+
+1. `RGB-D_Workflow`：使用 RGB 和深度数据的处理链；
+2. `Stereo-RGB_Workflow`：使用左、右两路 RGB 数据的处理链；
+3. `Cancel`：不使用模板，关闭选择窗口。
+
+新建或已有工作流都可以套用模板。选择模板会替换当前画布中的处理链，但不会改变当前工作流的名称。
+
+模板只提供处理步骤。输入设备节点会根据项目实际接收的数据生成。画布中已经有未保存修改时，先保存再更换模板。
+
+### 5.4 检查完整流程
+
+下面是已经连接好的工作流示例。
+
+[![完整工作流](images/workflow-editor-annotated.png)](images/workflow-editor-annotated.png)
+
+1. `Stereo RGB Camera`：项目接收到的左、右 RGB 视频；
+2. `Glove Sensor`：项目接收到的手套传感器数据；
+3. `AI Annotation`：根据 RGB 视频生成任务文字和标注片段；
+4. `Human Review`：把视频、传感器和标注结果交给人工审核；
+5. `LeRobot Export`：按工作流设置准备导出数据；
+6. `Save`：确认连接正确后保存工作流。
+
+图中的视频、手套数据和 AI 标注会一起进入人工审核：
+
+```text
+Stereo RGB Camera ─┬→ AI Annotation ─┐
+                   └─────────────┤
+Glove Sensor ───────────────────┤
+                                    ↓
+                             Human Review
+                                    ↓
+                             LeRobot Export
+```
+
+### 5.5 AI 标注设置
+
+打开 `AI Annotation` 节点的设置窗口，选择标注语言和 API。
+
+[![AI 标注设置](images/workflow-ai-settings-annotated.png)](images/workflow-ai-settings-annotated.png)
+
+1. `Label Language`：选择中文或英文标注；
+2. `Saved API Profile`：选择已经保存的 API 方案；
+3. `API Provider`：选择 API 厂商；
+4. `API Model`：填写或选择使用的模型；
+5. `API Key`：���写 API 密钥；
+6. `API Base URL`：填写 API 地址，使用官方默认地址时可以留空；
+7. `Test Connection`：保存前测试 API 是否可用；
+8. `Save`：保存 AI 标注设置。
+
+> API 密钥应显示为隐藏状态。不要分享显示完整密钥的截图。
+
+### 5.6 工作流模块说明
+
+右侧模块分为 `INPUT`、`PROCESS`、`REVIEW` 和 `EXPORT` 四组。把模块拖到画布中，再按照输入和输出连接。
+
+#### INPUT：输入数据
+
+| 模块                | 接收的数据             | 提供的数据                             | 什么时候使用                                      |
+| ------------------- | ---------------------- | -------------------------------------- | ------------------------------------------------- |
+| Glove Sensor        | 手套压力和关节数据     | Glove Sensor Data                      | 项目中有手套传感器时使用                          |
+| RGB Camera          | 单路彩色视频           | RGB Video                              | 单目普通相机、单目鱼眼相机或 RGB-D 相机的彩色画面 |
+| RGB-D Camera        | 彩色视频和真实深度流   | RGB Video、Depth                       | 单个 RGB-D 相机，有深度数据                       |
+| Stereo RGB Camera   | 左、右两路彩色视频     | Left RGB Video、Right RGB Video        | 只有双目 RGB 视频时使用，不会直接提供真实深度     |
+| Stereo RGB-D Camera | 左、右彩色视频和深度流 | Left RGB Video、Right RGB Video、Depth | 双目视频同时带有真实深度时使用                    |
+
+#### PROCESS：处理数据
+
+| 模块                 | 需要什么          | 产生什么   | 作用                                       |
+| -------------------- | ----------------- | ---------- | ------------------------------------------ |
+| Human Annotation     | RGB Video         | Annotation | 由人工建立和修改任务片段                   |
+| AI Annotation        | RGB Video         | Annotation | 使用本地模型或 API 自动生成中文、英文标注  |
+| RGB_TO_2D_BareHand   | RGB Video         | Hand 2D    | 识别裸手的视频中二维关键点                 |
+| RGB_TO_2D_BlackGlove | RGB Video         | Hand 2D    | 识别黑手套的视频中二维关键点               |
+| RGB-D_3D_BareHand    | RGB Video + Depth | Hand 3D    | 使用匹配的深度数据计算裸手真实三维关键点   |
+| RGB-D_3D_BlackGlove  | RGB Video + Depth | Hand 3D    | 使用匹配的深度数据计算黑手套真实三维关键点 |
+
+`RGB_TO_2D` 模块产生的是二维关键点。页面中的空间预览只是帮助查看，不作为真实米制 3D 数据导出。
+
+#### REVIEW：检查数据
+
+| 模块              | 作用                                                              | 结果                                               |
+| ----------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
+| Human Review      | 由用户播放视频，检查关键点、深度、传感器和标注                    | 审核通过后输出 Reviewed Data                       |
+| AI Quality Review | 自动检查视频能否解码、帧是否连续、是否黑屏或卡帧、AI 标注是否完整 | 检查通过后输出 Reviewed Data，异常数据进入人工处理 |
+
+#### EXPORT：导出数据
+
+| 模块           | 作用                   | 主要设置                                           |
+| -------------- | ---------------------- | -------------------------------------------------- |
+| LeRobot Export | 导出 LeRobot 数据集    | 选择 v2.1 或 v3.0；包含对应的 meta、data 和 videos |
+| HDF5 Export    | 导出一个 HDF5 数据文件 | 使用 gzip 压缩保存                                 |
+
+导出模块应连接在审核模块之后。这样只有检查通过的数据才会进入导出流程。
+
+### 5.7 常见处理方式
+
+普通 RGB：
+
+```text
+RGB → Hand 2D → Human Review → Export
+```
+
+RGB 和深度：
+
+```text
+RGB + Depth → Hand 3D → Human Review → Export
+```
+
+RGB 和手套传感器：
+
+```text
+RGB + Glove Sensor → Human Review → Export
+```
+
+### 5.8 重要规则
+
+- 有 RGB 和 Depth，才能计算真实 3D；
+- 只有 RGB 时，可以得到 2D 关键点；
+- 只有 RGB 时显示的空间效果不等于真实 metric 3D；
+- 输入不匹配时，对应步骤会被跳过。
+
+看到 Input mismatch，说明工作流需要的数据和当前项目数据不匹配，需要换用正确的工作流。
+
+## 6. 标注数据
+
+### 6.1 选择需要标注的数据
+
+点击左侧 `Annotation`。先在右侧展开项目，再选择一个 Episode。
+
+[![标注数据列表](images/annotation-list-annotated.png)](images/annotation-list-annotated.png)
+
+1. `Annotation`：进入标注页面；
+2. 点击项目名称展开项目；
+3. 点击 Episode 编号，加载视频和已有标注。
+
+中间显示 `Select an episode to review` 时，表示还没���选择 Episode，不是系统故障。
+
+### 6.2 查看和编辑标注
+
+[![标注编辑页面](images/annotation-editor-annotated.png)](images/annotation-editor-annotated.png)
+
+1. `Preview Options`：控制关键点、轨迹、深度和 3D 预览；
+2. `RGB 和 2D 关键点`：查看原始画面和图片上的手部关键点；
+3. `3D 手部空间`：查看空间中的手部关键点；
+4. `深度伪彩色预览`：查看深度数据的网页显示效果；
+5. `AI Annotate`：按工作流设置运行 AI 标注；
+6. `标注片段`：点击右侧某个片段，查看或修改它；
+7. `Set Start / Set End`：用当前帧设置片段的开始帧和结束帧；
+8. `Save Changes`：保存片段名称和帧范围的修改。
+
+### 6.3 人工修改标注
+
+1. 在右侧点击需要修改的标注片段；
+2. 检查开始帧、结束帧和任务名称；
+3. 修改后点击 `Save Changes`；
+4. 检查下方时间条中的标注块。
+
+### 6.4 AI 标注
+
+1. 确认工作流中已经设置 `AI Annotation`；
+2. 按工作流设置选择中文或英文；
+3. 点击 `AI Annotate`；
+4. 等待标注片段生成；
+5. 人工检查并修改不正确的内容。
+6. 工作流中有这个功能会自动进行标注
+7. 可能会因为网络波动导致一个小片段，没有对应的标注信息
+
+## 7. 视频查看和审核
+
+### 7.1 选择待审核数据
+
+点击 `Video Review` 下的 `Reviewing`，在右侧选择一个待审核 Episode。
+
+[![待审核数据列表](images/reviewing-list-annotated.png)](images/reviewing-list-annotated.png)
+
+1. `Reviewing`：查看等待人工审核的数据；
+2. `展开项目`：查看项目下的 Episode；
+3. `选择 Episode`：打开数据，并查看帧率、帧数、相机和处理状态；
+4. `Approve`：检查正确后，通过当前 Episode；
+5. `Reprocess`：处理结果不正确时，重新运行项目绑定的工作流。
+
+### 7.2 检查视频和处理结果
+
+[![视频审核页面](images/reviewing-player-annotated.png)](images/reviewing-player-annotated.png)
+
+1. `Preview Options`：显示或隐藏不同的预览内容；
+2. `RGB 原图`：查看彩色视频；打开关键点显示后会叠加 2D 手部关键点；
+3. `3D 手部空间`：检查空间中的手部关键点；
+4. `深度伪彩色预览`：检查深度数据是否正常；
+5. `只读标注片段`：检查任务名称和帧范围；
+6. `播放和逐帧控制`：播放视频，或使用上一帧、下一帧检查细节；
+7. `Approve`：确认当前 Episode 审核通过。
+
+审核时先等待关联数据加载完成，再点击播放。RGB、2D、3D、深度和传感器画面应使用相同帧号显示。
+
+### 7.3 深度画面说明
+
+深度画面中的蓝色、绿色、黄色等颜色只是网页中的预览效果。
+
+深度视频保存的是原始 12-bit 深度码，也不会把伪彩色图片写回原始数据。
+
+### 7.4 常见显示问题
+
+- 黑屏：等待当前 Episode 加载完成，再刷新页面；
+- 没有 3D 手部：检查工作流是否包含 3D 处理，以及 Episode 是否有 Depth；
+- 关键点不动：重新处理对应 Episode；
+- 播放卡顿：等待关联数据完成缓存后再播放。
+
+## 8. 已通过和导出
+
+### 8.1 已通过数据
+
+点击 `Video Review` 下的 `Approved`，可以查看已经通过审核的数据。
+
+[![已通过和导出](images/approved-list-annotated.png)](images/approved-list-annotated.png)
+
+1. `Approved`：进入已通过列表；
+2. `多选模式`：点击页面顶部 `Select` 进入；进入后按钮变为 `Cancel`；
+3. `Select All`：选择当前列表中的全部 Episode；
+4. `Episode 复选框`：可以单选一条，也可以同时选择多条；
+5. `Export`：导出这一条 Episode；
+6. `Unreview`：取消审核通过状态，让数据回到待审核列表。
+
+### 8.2 导出流程
+
+导出一条 Episode：
+
+1. 在该 Episode 的项目卡片中点击 `Export`；
+2. 等待导出完成并下载压缩包。
+
+批量导出：
+
+1. 点击页面顶部 `Select`；
+2. 勾选一条或多条 Episode，也可以点击 `Select All`；
+3. 选择后页面会显示 `Batch Download` 操作条；
+4. 点击 `Batch Download`，等待导出完成。
+
+导出格式使用当前工作流导出节点中的设置，例如 LeRobot 2.1、LeRobot 3.0 或 HDF5，不需要进入独立导出页面。
+
+### 8.3 导出内容
+
+```text
+项目名称/
+├── meta/       # 说明和统计信息
+├── data/       # 每帧数据、关键点和传感器数据
+└── videos/     # 视频
+```
+
+后处理后的关键点、标注和手套传感器数据，会和对应的数据一起导出。
+
+## 9. 失败处理
+
+### 9.1 处理流程
+
+```text
+看到 Failed
+  ↓
+打开失败数据
+  ↓
+查看错误提示
+  ↓
+点击 Retry 或 Reprocess
+  ↓
+等待重新处理
+```
+
+> 图片位置：待补充“Failed 失败页面”截图。
+
+### 9.2 常见错误
+
+| 错误          | 处理方法                     |
+| ------------- | ---------------------------- |
+| 没有 RGB      | 检查是否��传了彩色视频       |
+| 没有 Depth    | 不能计算真实 3D              |
+| 工作流不匹配  | 选择正确的工作流             |
+| AI 标注失败   | 检查 API 设置后重试          |
+| 视频打不开    | 由采集端重新发送或联系管理员 |
+| Worker 未运行 | 联系管理员重启服务           |
+
+重试两次仍然失败时，请发送数据名称、错误截图、失败时间和操作步骤。
+
+## 10. 垃圾桶
+
+### 10.1 垃圾桶有什么作用？
+
+删除的数据会先进入垃圾桶。
+
+### 10.2 怎么操作？
+
+[![垃圾桶页面](images/trash-annotated.png)](images/trash-annotated.png)
+
+1. 点击左侧 `Trash` 进入垃圾桶；
+2. 查看数据的剩余保留时间；
+3. 需要保留时点击 `Restore` 恢复；
+4. 确定不再需要时点击 `Delete` 永久删除；
+5. `Purge All` 会永久删除垃圾桶中的全部数据。
+
+### 10.3 重要提醒
+
+- 垃圾桶中的数据可以恢复；
+- 永久删除后通常不能恢复；
+- 清空垃圾桶前要再次确认；
+- 找不到数据时，先检查项目名称和删除时间。
+
+## 11. 常见问题
+
+### 页面打不开
+
+检查服务是否启动。
+
+### 数据一直处理中
+
+刷新页面。如果长时间不变，可能是 Worker 没有运行。
+
+### 深度画面是黑色
+
+等待加载完成后刷新，并检查当前 Episode 是否真的有深度视频。
+
+### 只有 2D，没有 3D
+
+真实 3D 需要 RGB 和 Depth 两种输入。只有 RGB 时不能计算真实空间位置。
+
+### 播放卡顿
+
+等待数据加载完成后再播放。检查细节时可以使用上一帧和下一帧。
+
+### AI 标注没有结果
+
+检查 API 设置、模型、网络和语言设置，然后重新运行 AI 标注。
+
+### 导出失败
+
+确认数据已经审核完成，再重新导出。
+
+## 12. 数据和程序说明
+
+### 12.1 项目目录
+
+```text
+processor/
+├── app/        # 后端、工作流、视频和导出
+├── worker/     # 后台处理任务
+├── web/        # 页面和前端代码
+├── scripts/    # 启动、检查和维护脚本
+├── tests/      # 自动测试
+├── deploy.py   # 一键部署入口
+└── .env        # 本机配置，不要提交到 Git
+```
+
+### 12.2 项目数据目录
+
+```text
+data/sessions/<project>/
+├── data/
+├── meta/
+└── videos/
+```
+
+原始深度视频保存为深度码。浏览器显示的伪彩色不会写回原始数据。
+
+### 12.3 启动检查
+
+```bash
+python deploy.py --check-only
+python -m compileall app worker
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q
+```
+
+不要把 .env、API Key、Token、真实数据和服务器凭据提交到 Git。
+
+## 13. 代码结构与功能说明
+
+本章用于说明页面背后的前端、后端、Worker 和数据处理代码。普通操作不需要修改这些文件；需要维护功能时，可以根据本章快速找到对应位置。
+
+### 13.1 系统代码链路
+
+    浏览器页面
+        ↓
+    HTML 模板和 JavaScript
+        ↓
+    FastAPI 后端接口
+        ↓
+    项目、Episode、标注和工作流
+        ↓
+    Worker 领取处理任务
+        ↓
+    工作流模块执行后处理
+        ↓
+    保存关键点、3D、传感器和标注结果
+        ↓
+    视频审核和数据导出
+
+业务数据主要保存在项目文件中。用户账号可以使用数据库；数据库暂时不可用时，程序保留兼容回退能力。
+
+### 13.2 代码目录树
+
+    processor/
+    ├── app/                         # Python 后端
+    │   ├── main.py                  # FastAPI 启动入口
+    │   ├── config.py                # 环境变量和系统配置
+    │   ├── paths.py                 # 统一目录路径
+    │   ├── localstore.py            # 项目、工作流和 Episode 文件状态
+    │   ├── database.py              # 用户账号数据库连接
+    │   ├── models.py                # 数据库模型
+    │   ├── workflow_dispatch.py     # 工作流匹配、自动派发和历史回填
+    │   ├── workflow_bindings.py     # 工作流与实际设备输入绑定
+    │   ├── ai_annotation.py         # AI 标注服务
+    │   ├── export_engine.py         # 导出任务公共逻辑
+    │   ├── lerobot_export.py        # LeRobot 3.0 数据生成
+    │   ├── lerobot_v21.py           # LeRobot 2.1 兼容处理
+    │   ├── hdf5_export.py           # HDF5 数据生成
+    │   ├── routes/                  # 页面和业务接口
+    │   ├── api/                     # 项目、工作流和 Worker 接口
+    │   └── processing/              # 工作流后处理框架
+    │       ├── registry.py           # 自动注册处理模块
+    │       ├── catalog.py            # 向工作流页面提供模块清单
+    │       ├── batch.py              # 查找批次中的视频和 Parquet
+    │       └── modules/              # 每个工作流节点的执行代码
+    ├── worker/                      # 后台处理程序
+    │   ├── __main__.py              # Worker 启动入口
+    │   ├── runner.py                # 领取和执行工作流任务
+    │   └── client.py                # 与后端 Worker API 通信
+    ├── web/                         # 前端页面
+    │   ├── templates/               # HTML 页面模板
+    │   ├── static/js/               # 页面交互、播放和渲染
+    │   └── workflow-studio/         # React 工作流编辑器源码
+    ├── scripts/                     # 部署、迁移和维护脚本
+    ├── tests/                       # 自动测试
+    ├── models/                      # 本地模型文件
+    ├── docs/                        # 中文和英文项目文档
+    ├── deploy.py                    # 一键部署入口
+    └── requirements*.txt            # Python 依赖
+
+<code>.venv*</code>、<code>.pytest_cache</code> 和 <code>.backups</code> 是本机环境、测试缓存或备份，不属于主要业务代码。
+
+### 13.3 前端代码
+
+前端由两部分组成：
+
+1. 普通页面使用 HTML 模板和原生 JavaScript；
+2. 工作流编辑器使用 React 和 TypeScript。
+
+#### 页面模板
+
+| 文件 | 作用 |
+| --- | --- |
+| <code>web/templates/base.html</code> | 公共页面框架、左侧菜单和通用资源 |
+| <code>web/templates/overview.html</code> | 首页 |
+| <code>web/templates/tasks.html</code> | 项目管理页面 |
+| <code>web/templates/index.html</code> | 标注和视频审核页面 |
+| <code>web/templates/trash.html</code> | 垃圾桶页面 |
+| <code>web/templates/login.html</code> | 登录页面 |
+| <code>web/templates/users.html</code> | 用户管理页面，目前仍在开发 |
+| <code>web/templates/workflow_studio.html</code> | 工作流编辑器入口 |
+
+#### 页面 JavaScript
+
+| 文件 | 作用 |
+| --- | --- |
+| <code>web/static/js/dashboard.js</code> | 首页统计、最近数据和刷新 |
+| <code>web/static/js/tasks.js</code> | 项目创建、编辑、删除和批次展开 |
+| <code>web/static/js/app.js</code> | Episode 列表、审核、删除和导出操作 |
+| <code>web/static/js/player.js</code> | 视频加载、统一播放时钟和帧同步 |
+| <code>web/static/js/annotations.js</code> | 标注片段、时间条和逐帧标注 |
+| <code>web/static/js/slice-preview.js</code> | 右上角标注片段预览 |
+| <code>web/static/js/hand-overlay.js</code> | 在 RGB 原图上绘制 2D 手部关键点 |
+| <code>web/static/js/depth-renderer.js</code> | 将原始 12-bit 深度码渲染为网页伪彩色 |
+| <code>web/static/js/heatmap.js</code> | 手套传感器数据同步显示 |
+| <code>web/static/js/media-cache.js</code> | 使用 IndexedDB 缓存关键点和传感器数据 |
+| <code>web/static/js/i18n.js</code> | 中英文界面文字 |
+| <code>web/static/js/login.js</code> | 登录表单 |
+| <code>web/static/js/users.js</code> | 用户管理交互，目前仍在开发 |
+
+工作流编辑器源码位于 <code>web/workflow-studio/src/</code>。编译后的文件位于 <code>web/static/workflow-studio/</code>，修改工作流页面时应修改源码并重新构建，不要直接修改编译结果。
+
+### 13.4 后端入口和页面接口
+
+<code>app/main.py</code> 是后端入口，主要负责：
+
+- 启动 FastAPI；
+- 初始化文件目录和用户数据库；
+- 预热项目与 Episode 元数据缓存；
+- 启动上传处理队列；
+- 注册页面、项目、视频、标注、工作流和导出接口；
+- 提供静态文件缓存和大媒体文件传输规则。
+
+| 文件 | 作用 |
+| --- | --- |
+| <code>app/routes/pages.py</code> | 返回首页、项目、审核、工作流和垃圾桶页面 |
+| <code>app/routes/dashboard.py</code> | 首页统计、最近 Episode 和趋势 |
+| <code>app/routes/session.py</code> | 接收压缩包、解压、整理目录和导入元数据 |
+| <code>app/routes/ingestion.py</code> | Episode 列表、详情、审核、重跑、删除和恢复 |
+| <code>app/routes/video.py</code> | RGB 视频、深度码、深度预览、2D、3D 和传感器接口 |
+| <code>app/routes/annotations.py</code> | 创建、修改、删除和逐帧读取标注 |
+| <code>app/routes/export.py</code> | 单个导出、批量导出、任务状态和下载 |
+| <code>app/routes/auth.py</code> | 登录、退出和当前用户 |
+| <code>app/routes/devices.py</code> | 采集设备心跳和输入能力 |
+
+### 13.5 项目、工作流和 Worker API
+
+| 文件 | 作用 |
+| --- | --- |
+| <code>app/api/projects.py</code> | 项目创建、编辑、删除、输入源和工作流绑定 |
+| <code>app/api/workflows.py</code> | 工作流创建、保存、运行、使用情况和重试 |
+| <code>app/api/worker.py</code> | Worker 领取任务、下载输入、心跳、完成和失败上报 |
+| <code>app/api/exceptions.py</code> | 汇总和清理处理异常 |
+| <code>app/api/users.py</code> | 用户创建、��色、状态和删除，目前仍在开发 |
+
+后端与 Worker 的任务过程：
+
+    后端创建运行记录
+        ↓
+    Worker 领取任务
+        ↓
+    Worker 下载 Episode 输入
+        ↓
+    执行工作流节点
+        ↓
+    Worker 上传结果并报告完成
+        ↓
+    Episode 进入审核或通过状态
+
+Worker 会定期发送心跳。如果 Worker 中断，任务不会立刻丢失，后端可以在超时后重新安排。
+
+### 13.6 工作流后处理模块
+
+<code>app/processing/modules/</code> 中一个 Python 文件通常对应一个工作流节点。模块通过注册表自动出现在工作流编辑器中，并由 Worker 执行。
+
+| 模块文件 | 作用 |
+| --- | --- |
+| <code>mono_camera.py</code> | 单路 RGB 输入 |
+| <code>rgbd_camera.py</code> | RGB 和深度输入 |
+| <code>stereo_camera.py</code> | 左、右双目 RGB 输入 |
+| <code>stereo_rgbd_camera.py</code> | 左、右 RGB 和深度输入 |
+| <code>glove_sensor.py</code> | 手套传感器输入 |
+| <code>mediapipe_hand.py</code> | MediaPipe 手部关键点和手势识别 |
+| <code>rgb_hand_3d.py</code> | 裸手 RGB 二维关键点和预览空间效果 |
+| <code>black_hand_rgb_3d.py</code> | 黑手套 RGB 二维关键点和预览空间效果 |
+| <code>depth_hand_3d.py</code> | RGB-D 手部模块使用的真实 3D 计算辅助代码，不是独立节点 |
+| <code>black_glove_hand.py</code> | 黑手套关键点处理 |
+| <code>ai_annotation.py</code> | 声明并触发 AI 自动标注 |
+| <code>annotation.py</code> | 人工标注工作流节点 |
+| <code>human_review.py</code> | 人工审核门 |
+| <code>ai_quality_review.py</code> | 视频和标注自动质量检查 |
+| <code>lerobot_export.py</code> | LeRobot 导出节点 |
+| <code>hdf5_export.py</code> | HDF5 导出节点 |
+
+增加工作流模块时，应同时检查：
+
+1. 模块输入和输出类型；
+2. Worker 是否能够执行；
+3. 工作流编辑器是否正确显示；
+4. 处理结果是否能在审核页面读取；
+5. 导出模块是否包含新增结果。
+
+### 13.7 数据、缓存和导出
+
+| 文件 | 作用 |
+| --- | --- |
+| <code>app/localstore.py</code> | 扫描和缓存项目、Episode、工作流及运行状态 |
+| <code>app/storage.py</code> | 文件上传、校验、保存和远程同步 |
+| <code>app/remote_storage.py</code> | 远程存储访问 |
+| <code>app/media_groups.py</code> | 组织 RGB、深度和传感器媒体组 |
+| <code>app/media_cache.py</code> | 服务端媒体缓存 |
+| <code>app/browser_preview.py</code> | 生成浏览器兼容的视频预览 |
+| <code>app/artifact_resolver.py</code> | 查找工作流处理结果 |
+| <code>app/export_engine.py</code> | 统一导出流程 |
+| <code>app/lerobot_export.py</code> | 生成 LeRobot 3.0 数据集 |
+| <code>app/lerobot_v21.py</code> | 生成和兼容 LeRobot 2.1 数据 |
+| <code>app/hdf5_export.py</code> | 生成 HDF5 数据集 |
+
+源数据、后处理结果和导出副本需要分清：
+
+    data/sessions/    # 项目源数据和合并后的后处理字段
+    data/tmp/         # 临时处理文件
+    浏览器 IndexedDB # 前端预览缓存，可以重新生成
+    导出压缩包        # 根据工作流设置生成的交付文件
+
+不要把浏览器伪彩色深度图当作源数据保存。源深度仍然是原始深度码。
+
+### 13.8 修改功能时去哪里
+
+| 需要修改的功能 | 前端位置 | 后端或处理位置 |
+| --- | --- | --- |
+| 首页统计 | <code>dashboard.js</code> | <code>routes/dashboard.py</code> |
+| 项目页面 | <code>tasks.js</code> | <code>api/projects.py</code> |
+| 上传和解压 | 项目页面 | <code>routes/session.py</code> |
+| 工作流编辑器 | <code>workflow-studio/src/</code> | <code>api/workflows.py</code> |
+| 工作流自动运行 | 项目状态显示 | <code>workflow_dispatch.py</code> |
+| RGB 视频播放 | <code>player.js</code> | <code>routes/video.py</code> |
+| 播放帧同步 | <code>player.js</code> | <code>routes/video.py</code> |
+| 2D 手部关键点 | <code>hand-overlay.js</code> | 手部处理模块 |
+| 3D 手部空间 | <code>player.js</code> | <code>processing/modules/*3d*.py</code> |
+| 深度伪彩色 | <code>depth-renderer.js</code> | <code>routes/video.py</code> |
+| 手套传感器 | <code>heatmap.js</code> | <code>glove_sensor.py</code> |
+| 标注时间条 | <code>annotations.js</code> | <code>routes/annotations.py</code> |
+| AI 标注 | <code>annotations.js</code> | <code>ai_annotation.py</code> |
+| 视频审核 | <code>app.js</code> | <code>routes/ingestion.py</code> |
+| 单个和批量导出 | <code>app.js</code> | <code>routes/export.py</code> |
+| LeRobot 格式 | 导出按钮 | <code>lerobot_export.py</code>、<code>lerobot_v21.py</code> |
+| HDF5 格式 | 导出按钮 | <code>hdf5_export.py</code> |
+| 垃圾桶 | <code>trash.html</code> | <code>routes/ingestion.py</code> |
+| 用户管理 | <code>users.js</code> | <code>api/users.py</code> |
+
+### 13.9 排查问题的顺序
+
+遇到问题时，建议按照下面顺序检查：
+
+1. 先确认问题出现在哪个页面；
+2. 找到该页面对应的 JavaScript；
+3. 在浏览器开发者工具中检查接口是否失败；
+4. 根据接口地址找到对应的 Python 路由；
+5. 如果是工作流任务，再检查 Worker 和处理模块；
+6. 如果是显示不同步，再检查当前 Episode 的帧数、帧率和缓存；
+7. 修改后运行测试，再打开真实数据验证。
+
+## 结尾
+
+先上传，再处理；处理完成后检查；检查正确后再导出。

processor/docs/en/README.md

@@ -0,0 +1,862 @@
+# processor Project Guide
+
+processor is a system for receiving, processing, reviewing, and exporting data.
+
+This guide keeps the project features, pages, screenshots, and operating instructions in one document. Read it from top to bottom without switching between multiple files.
+
+## Contents
+
+1. [Overall process](#1-overall-process)
+2. [Installation and startup](#2-installation-and-startup)
+3. [Home](#3-home)
+4. [Projects and received data](#4-projects-and-received-data)
+5. [Workflow](#5-workflow)
+6. [Data annotation](#6-data-annotation)
+7. [Video viewing and review](#7-video-viewing-and-review)
+8. [Approved data and export](#8-approved-data-and-export)
+9. [Failed data](#9-failed-data)
+10. [Trash](#10-trash)
+11. [Frequently asked questions](#11-frequently-asked-questions)
+12. [Data and program information](#12-data-and-program-information)
+13. [Code structure and responsibilities](#13-code-structure-and-responsibilities)
+
+## 1. Overall process
+
+The complete process is:
+
+    Install and start
+      ↓
+    Open Home
+      ↓
+    Create or select a project
+      ↓
+    Receive data
+      ↓
+    Select and run a workflow
+      ↓
+    View videos and processing results
+      ↓
+    Annotate, inspect, and review
+      ↓
+    Export data
+
+The main pages currently available in the system are:
+
+- Home: view the overall data status;
+- Projects: view projects and Episodes;
+- Workflow: configure and run workflows;
+- Annotation: manage annotations;
+- Video Review: view videos and review data;
+- Trash: view deleted data.
+
+The Users feature is still under development and is not included in the current operating process.
+
+## 2. Installation and startup
+
+### 2.1 Download and open the project
+
+After downloading the project, open:
+
+    processor/
+
+### 2.2 Start the program
+
+Linux:
+
+    cd processor
+    python deploy.py
+
+To check the computer environment without starting the services:
+
+    python deploy.py --check-only
+
+When using an external AI API:
+
+    python deploy.py --skip-vllm
+
+Windows users can run the Windows deployment script included in the project.
+
+### 2.3 Open the web page
+
+Wait for the services to start, then open the address provided by the administrator in a browser.
+
+When the sign-in page appears, the web application has started. Open:
+
+    /health
+
+to check whether the service is healthy.
+
+> Screenshot to be added: successful startup and sign-in page.
+
+### 2.4 If something goes wrong
+
+- If the page does not open, check whether the backend is running.
+- If data is not processed, check whether the Worker is running.
+- After a workflow is configured, matching uploaded data should run through it automatically. If processing does not start, check the workflow or run it manually.
+
+## 3. Home
+
+### 3.1 What is Home for?
+
+Home shows the overall status of all data.
+
+### 3.2 Home page
+
+![Home page](../images/02-home-annotated.png)
+
+The numbered areas are:
+
+1. Left navigation menu;
+2. Summary statistics;
+3. Project list;
+4. Recent data;
+5. Refresh button.
+
+### 3.3 Data statuses
+
+| Status | Meaning |
+| --- | --- |
+| Reviewing | Waiting for or undergoing inspection |
+| Approved | Review passed |
+| Failed | Processing failed |
+| Trash | Deleted and recoverable |
+
+### 3.4 How to use it
+
+1. Sign in and open Home.
+2. Check the summary statistics at the top.
+3. Click a project name to view the project.
+4. If the data is not current, click Refresh in the upper-right corner.
+
+### 3.5 What indicates normal operation?
+
+When data changes from Reviewing to Approved, its inspection is complete and it has passed review.
+
+If Processing remains visible, wait and refresh the page. If it still does not change, check the Worker.
+
+## 4. Projects and received data
+
+### 4.1 What is a project?
+
+A project stores a related group of data. One project can contain multiple Episodes.
+
+processor receives data sent by the collector and stores it in the corresponding project. Data acquisition itself does not take place inside processor.
+
+### 4.2 View existing projects
+
+Open <code>Projects</code> in the left navigation to view existing projects and received data.
+
+[![Project list](../images/projects-list-annotated.png)](../images/projects-list-annotated.png)
+
+The numbered controls are:
+
+1. <code>Search projects</code>: enter a project name to find it quickly;
+2. <code>New Project</code>: create a new project that will receive data;
+3. <code>Project information</code>: view the project name, status, workflow, observed inputs, Episode count, and receiving statistics;
+4. <code>Edit Project</code>: change the project name, workflow, or status;
+5. <code>Delete</code>: delete the current project. Deleted data can be viewed in Trash;
+6. <code>Expand received batches</code>: click the project row or the arrow on the right to view received batches and Episodes.
+
+<code>active</code> means the project is in use and can continue receiving data. <code>paused</code> means the project is paused.
+
+### 4.3 Create a project
+
+Click <code>New Project</code> in the upper-right corner and enter the project information.
+
+[![Create a project](../images/project-new-annotated.png)](../images/project-new-annotated.png)
+
+The fields are:
+
+- <code>Project Name</code>: the project name;
+- <code>Workflow</code>: bind one current workflow to the project. You may create a new empty workflow or select an existing workflow;
+- <code>Status</code>: <code>active</code> enables the project and <code>paused</code> pauses it;
+- <code>Target Episodes</code>: planned number of Episodes. <code>0</code> means no limit;
+- <code>Description</code>: optional project description;
+- <code>Save</code>: save the project.
+
+The project name cannot be empty. After a new project is saved, the system asks whether you want to open the Workflow page and continue configuration.
+
+### 4.4 Select a workflow
+
+Select the required workflow from the <code>Workflow</code> field on the project form.
+
+[![Select a project workflow](../images/project-workflow-select-annotated.png)](../images/project-workflow-select-annotated.png)
+
+The workflow list provides:
+
+1. Click the <code>Workflow</code> field to open the workflow list;
+2. Click <code>+ New Workflow</code> to create an empty workflow;
+3. A workflow with the <code>Template</code> tag is a template workflow;
+4. Click an existing workflow name to bind it to the current project;
+5. Click the button on the right to open and edit that workflow.
+
+One project uses one current workflow. Selecting another workflow saves it as the project's new current workflow binding.
+
+Choose according to the input data:
+
+- Choose an RGB workflow for RGB data.
+- Choose an RGB-D workflow for RGB plus Depth data.
+- Choose a workflow containing Glove Sensor when glove sensor data is present.
+- If you are unsure, confirm the project's input types before making a selection.
+
+### 4.5 Data receiving process
+
+    Collector generates data
+      ↓
+    Collector sends data
+      ↓
+    processor receives data
+      ↓
+    Extract and inspect
+      ↓
+    Match the project and workflow
+      ↓
+    New Episodes appear in the project
+
+### 4.6 How to receive data
+
+1. Create a project and select the correct workflow.
+2. Keep the project status set to <code>active</code>.
+3. Send data from the collector to processor.
+4. Wait for processor to receive, extract, and inspect the data.
+5. Expand the project and confirm that the new batch and Episodes appear.
+
+When a project already has a workflow, the system processes newly received data. Without a bound workflow, data is only received and stored. If a workflow is bound and saved later, the system processes the existing batches.
+
+### 4.7 Important notes
+
+- Do not close the collector's sending program while data is being transferred.
+- Do not send the same data again before extraction and inspection finish.
+- Each Episode should contain its corresponding video or sensor data.
+- If receiving fails, read the failure message before sending or processing the data again.
+- Do not force a workflow to run when the project inputs do not match it.
+
+## 5. Workflow
+
+### 5.1 What is a workflow?
+
+A workflow determines how received data is processed.
+
+    Input data → Process data → Inspect results → Export data
+
+### 5.2 Workflow page
+
+Click <code>Workflow</code> in the left navigation.
+
+[![Workflow page](../images/workflow-empty-annotated.png)](../images/workflow-empty-annotated.png)
+
+The numbered controls are:
+
+1. <code>Workflow selector</code>: switch between existing workflows or create a new workflow;
+2. <code>Workflow name</code>: view or change the current workflow name;
+3. <code>Canvas</code>: place nodes and connect them into a processing flow;
+4. <code>Node list</code>: input, processing, review, and export nodes;
+5. <code>Template</code>: start from a workflow template;
+6. <code>Save</code>: save the current workflow.
+
+### 5.3 Start from a template
+
+Click <code>Template</code> in the upper-right corner and select a template that matches the received data.
+
+[![Select a workflow template](../images/workflow-template-annotated.png)](../images/workflow-template-annotated.png)
+
+1. <code>RGB-D_Workflow</code>: a processing chain for RGB and depth data;
+2. <code>Stereo-RGB_Workflow</code>: a processing chain for left and right RGB data;
+3. <code>Cancel</code>: close the dialog without applying a template.
+
+A template can be applied to a new or existing workflow. Applying it replaces the processing chain on the current canvas but does not change the current workflow name.
+
+A template contains processing steps only. Input device nodes are generated from the data actually received by the project. If the canvas contains unsaved changes, save them before applying another template.
+
+### 5.4 Check a complete workflow
+
+The following image shows a connected workflow.
+
+[![Complete workflow](../images/workflow-editor-annotated.png)](../images/workflow-editor-annotated.png)
+
+1. <code>Stereo RGB Camera</code>: left and right RGB videos received by the project;
+2. <code>Glove Sensor</code>: glove sensor data received by the project;
+3. <code>AI Annotation</code>: generate task text and annotation segments from RGB video;
+4. <code>Human Review</code>: send video, sensor data, and annotations for manual review;
+5. <code>LeRobot Export</code>: prepare the data for export using the workflow settings;
+6. <code>Save</code>: save the workflow after checking its connections.
+
+In this example, the video, glove data, and AI annotations all enter manual review:
+
+    Stereo RGB Camera ─┬→ AI Annotation ─┐
+                       └─────────────────┤
+    Glove Sensor ────────────────────────┤
+                                        ↓
+                                 Human Review
+                                        ↓
+                                 LeRobot Export
+
+### 5.5 AI annotation settings
+
+Open the settings dialog of the <code>AI Annotation</code> node to select the annotation language and API.
+
+[![AI annotation settings](../images/workflow-ai-settings-annotated.png)](../images/workflow-ai-settings-annotated.png)
+
+1. <code>Label Language</code>: choose Chinese or English annotations;
+2. <code>Saved API Profile</code>: select a saved API profile;
+3. <code>API Provider</code>: select the API provider;
+4. <code>API Model</code>: enter or select the model;
+5. <code>API Key</code>: enter the API key;
+6. <code>API Base URL</code>: enter the API address. Leave it empty to use the provider's official default;
+7. <code>Test Connection</code>: test whether the API is available before saving;
+8. <code>Save</code>: save the AI annotation settings.
+
+> API keys should appear masked. Do not share screenshots that reveal a complete API key.
+
+### 5.6 Workflow module reference
+
+The node list on the right is divided into <code>INPUT</code>, <code>PROCESS</code>, <code>REVIEW</code>, and <code>EXPORT</code>. Drag a node onto the canvas and connect its inputs and outputs.
+
+#### INPUT: source data
+
+| Module | Receives | Provides | When to use it |
+| --- | --- | --- | --- |
+| Glove Sensor | Glove pressure and joint data | Glove Sensor Data | When the project contains glove sensor data |
+| RGB Camera | One color video | RGB Video | A monocular standard camera, monocular fisheye camera, or the color stream of an RGB-D camera |
+| RGB-D Camera | Color video and a real depth stream | RGB Video, Depth | One RGB-D camera with depth data |
+| Stereo RGB Camera | Left and right color videos | Left RGB Video, Right RGB Video | Stereo RGB video without a direct real-depth output |
+| Stereo RGB-D Camera | Left and right color videos plus depth | Left RGB Video, Right RGB Video, Depth | Stereo video that also contains real depth |
+
+#### PROCESS: processed data
+
+| Module | Requires | Produces | Purpose |
+| --- | --- | --- | --- |
+| Human Annotation | RGB Video | Annotation | Manually create and edit task segments |
+| AI Annotation | RGB Video | Annotation | Automatically generate Chinese or English annotations using a local model or API |
+| RGB_TO_2D_BareHand | RGB Video | Hand 2D | Detect 2D keypoints in bare-hand video |
+| RGB_TO_2D_BlackGlove | RGB Video | Hand 2D | Detect 2D keypoints in black-glove video |
+| RGB-D_3D_BareHand | RGB Video + Depth | Hand 3D | Calculate real 3D bare-hand keypoints using matched depth data |
+| RGB-D_3D_BlackGlove | RGB Video + Depth | Hand 3D | Calculate real 3D black-glove keypoints using matched depth data |
+
+The <code>RGB_TO_2D</code> modules produce two-dimensional keypoints. Their spatial preview is for viewing only and is not exported as real metric 3D data.
+
+#### REVIEW: inspect data
+
+| Module | Purpose | Result |
+| --- | --- | --- |
+| Human Review | Let a user play the video and inspect keypoints, depth, sensor data, and annotations | Output Reviewed Data after approval |
+| AI Quality Review | Automatically check decoding, frame continuity, black or frozen frames, and AI annotation coverage | Output Reviewed Data after passing; send abnormal data for manual handling |
+
+#### EXPORT: export data
+
+| Module | Purpose | Main settings |
+| --- | --- | --- |
+| LeRobot Export | Export a LeRobot dataset | Select v2.1 or v3.0; includes the corresponding meta, data, and videos |
+| HDF5 Export | Export one HDF5 data file | Save with gzip compression |
+
+Connect an export module after a review module so that only inspected and approved data enters the export flow.
+
+### 5.7 Common workflow examples
+
+Standard RGB:
+
+    RGB → Hand 2D → Human Review → Export
+
+RGB and depth:
+
+    RGB + Depth → Hand 3D → Human Review → Export
+
+RGB and glove sensor:
+
+    RGB + Glove Sensor → Human Review → Export
+
+### 5.8 Important rules
+
+- Both RGB and Depth are required to calculate real 3D.
+- RGB alone can produce 2D keypoints.
+- A spatial preview produced from RGB alone is not real metric 3D.
+- A step is skipped when its required input does not match the Episode.
+
+<code>Input mismatch</code> means the workflow requires different data from the current project. Select a matching workflow.
+
+## 6. Data annotation
+
+### 6.1 Select data to annotate
+
+Click <code>Annotation</code> in the left navigation. Expand a project on the right, then select an Episode.
+
+[![Annotation data list](../images/annotation-list-annotated.png)](../images/annotation-list-annotated.png)
+
+1. <code>Annotation</code>: open the Annotation page;
+2. Click a project name to expand it;
+3. Click an Episode number to load its video and existing annotations.
+
+If the center shows <code>Select an episode to review</code>, no Episode has been selected. This is not a system failure.
+
+### 6.2 View and edit annotations
+
+[![Annotation editor](../images/annotation-editor-annotated.png)](../images/annotation-editor-annotated.png)
+
+1. <code>Preview Options</code>: show or hide keypoints, trails, depth, and 3D previews;
+2. <code>RGB and 2D keypoints</code>: view the original image and 2D hand keypoints;
+3. <code>3D hand space</code>: view hand keypoints in space;
+4. <code>Depth pseudo-color preview</code>: view depth data in the browser;
+5. <code>AI Annotate</code>: run AI annotation using the workflow settings;
+6. <code>Annotation segment</code>: click a segment on the right to view or edit it;
+7. <code>Set Start / Set End</code>: use the current frame as the segment's start or end frame;
+8. <code>Save Changes</code>: save changes to the segment name and frame range.
+
+### 6.3 Manually edit an annotation
+
+1. Click the annotation segment that needs editing.
+2. Check its start frame, end frame, and task name.
+3. Make the changes and click <code>Save Changes</code>.
+4. Check the annotation block on the timeline at the bottom.
+
+### 6.4 AI annotation
+
+1. Confirm that <code>AI Annotation</code> is configured in the workflow.
+2. Select Chinese or English in the workflow settings.
+3. Click <code>AI Annotate</code>.
+4. Wait for the annotation segments to be generated.
+5. Manually inspect the result and correct any errors.
+6. If the workflow contains this feature, AI annotation runs automatically during workflow processing.
+7. Network fluctuations may occasionally leave a short segment without annotation information.
+
+## 7. Video viewing and review
+
+### 7.1 Select data awaiting review
+
+Click <code>Reviewing</code> under <code>Video Review</code>, then select an Episode from the right panel.
+
+[![Reviewing list](../images/reviewing-list-annotated.png)](../images/reviewing-list-annotated.png)
+
+1. <code>Reviewing</code>: view data waiting for manual review;
+2. <code>Expand project</code>: view the Episodes in a project;
+3. <code>Select Episode</code>: open the data and view its FPS, frame count, cameras, and processing status;
+4. <code>Approve</code>: approve the current Episode after checking it;
+5. <code>Reprocess</code>: run the workflow bound to the project again when the result is incorrect.
+
+### 7.2 Inspect video and processing results
+
+[![Video review](../images/reviewing-player-annotated.png)](../images/reviewing-player-annotated.png)
+
+1. <code>Preview Options</code>: show or hide different preview layers;
+2. <code>RGB image</code>: view the color video. When keypoint display is enabled, 2D hand keypoints are overlaid;
+3. <code>3D hand space</code>: inspect hand keypoints in space;
+4. <code>Depth pseudo-color preview</code>: check whether the depth data looks normal;
+5. <code>Read-only annotation segments</code>: inspect task names and frame ranges;
+6. <code>Playback and frame controls</code>: play the video or inspect details with the previous-frame and next-frame buttons;
+7. <code>Approve</code>: approve the current Episode.
+
+Wait for the related data to finish loading before playback. RGB, 2D, 3D, depth, and sensor views should display the same frame number.
+
+### 7.3 About the depth view
+
+Blue, green, yellow, and other colors in the depth view are only a browser preview.
+
+The depth video stores raw 12-bit depth codes. The pseudo-color image is not written back to the original data.
+
+### 7.4 Common display problems
+
+- Black screen: wait for the current Episode to load, then refresh the page.
+- No 3D hand: check whether the workflow includes 3D processing and whether the Episode contains Depth.
+- Keypoints do not move: reprocess that Episode.
+- Playback stutters: wait until the related data has been cached before playing.
+
+## 8. Approved data and export
+
+### 8.1 Approved data
+
+Click <code>Approved</code> under <code>Video Review</code> to view data that has passed review.
+
+[![Approved data and export](../images/approved-list-annotated.png)](../images/approved-list-annotated.png)
+
+1. <code>Approved</code>: open the Approved list;
+2. <code>Multi-select mode</code>: click <code>Select</code> at the top of the page. The button changes to <code>Cancel</code> while this mode is active;
+3. <code>Select All</code>: select every Episode in the current list;
+4. <code>Episode checkbox</code>: select one Episode or multiple Episodes;
+5. <code>Export</code>: export this single Episode;
+6. <code>Unreview</code>: remove approval and return the Episode to the Reviewing list.
+
+### 8.2 Export process
+
+Export one Episode:
+
+1. Click <code>Export</code> on that Episode's card.
+2. Wait for the export to finish and download the archive.
+
+Batch export:
+
+1. Click <code>Select</code> at the top of the page.
+2. Select one or more Episodes, or click <code>Select All</code>.
+3. A <code>Batch Download</code> action bar appears after Episodes are selected.
+4. Click <code>Batch Download</code> and wait for the export to finish.
+
+The export format comes from the current workflow's export node, such as LeRobot 2.1, LeRobot 3.0, or HDF5. No separate export page is required.
+
+### 8.3 Exported content
+
+    Project name/
+    ├── meta/       # Descriptions and statistics
+    ├── data/       # Per-frame data, keypoints, and sensor data
+    └── videos/     # Videos
+
+Processed keypoints, annotations, and glove sensor data are exported together with the corresponding source data.
+
+## 9. Failed data
+
+### 9.1 Handling process
+
+    See Failed
+      ↓
+    Open the failed data
+      ↓
+    Read the error message
+      ↓
+    Click Retry or Reprocess
+      ↓
+    Wait for processing
+
+> Screenshot to be added: Failed page.
+
+### 9.2 Common errors
+
+| Error | What to do |
+| --- | --- |
+| No RGB | Check whether a color video was uploaded |
+| No Depth | Real 3D cannot be calculated |
+| Workflow mismatch | Select a matching workflow |
+| AI annotation failed | Check the API settings and retry |
+| Video cannot be opened | Send it again from the collector or contact the administrator |
+| Worker is not running | Ask the administrator to restart the service |
+
+If processing still fails after two retries, provide the data name, an error screenshot, the time of failure, and the steps that caused it.
+
+## 10. Trash
+
+### 10.1 What is Trash for?
+
+Deleted data first enters Trash.
+
+### 10.2 How to use it
+
+[![Trash](../images/trash-annotated.png)](../images/trash-annotated.png)
+
+1. Click <code>Trash</code> in the left navigation;
+2. Check the remaining retention time;
+3. Click <code>Restore</code> if the data should be kept;
+4. Click <code>Delete</code> only when the data can be permanently removed;
+5. <code>Purge All</code> permanently deletes everything in Trash.
+
+### 10.3 Important notes
+
+- Data in Trash can be restored.
+- Permanently deleted data usually cannot be recovered.
+- Confirm again before emptying Trash.
+- If data cannot be found, first check its project name and deletion time.
+
+## 11. Frequently asked questions
+
+### The page does not open
+
+Check whether the service is running.
+
+### Data remains in Processing
+
+Refresh the page. If the status does not change for a long time, the Worker may not be running.
+
+### The depth view is black
+
+Wait for loading to finish, refresh the page, and confirm that the current Episode really contains a depth video.
+
+### There is 2D but no 3D
+
+Real 3D requires both RGB and Depth. RGB alone cannot calculate real spatial positions.
+
+### Playback stutters
+
+Wait for loading to finish before playing. Use the previous-frame and next-frame buttons when checking details.
+
+### AI annotation has no result
+
+Check the API settings, model, network, and language, then run AI annotation again.
+
+### Export fails
+
+Confirm that the data has passed review, then export it again.
+
+## 12. Data and program information
+
+### 12.1 Project directory
+
+    processor/
+    ├── app/        # Backend, workflow, video, and export
+    ├── worker/     # Background processing tasks
+    ├── web/        # Pages and frontend code
+    ├── scripts/    # Startup, inspection, and maintenance scripts
+    ├── tests/      # Automated tests
+    ├── deploy.py   # One-command deployment entry point
+    └── .env        # Local configuration; do not commit to Git
+
+### 12.2 Project data directory
+
+    data/sessions/<project>/
+    ├── data/
+    ├── meta/
+    └── videos/
+
+Raw depth videos store depth codes. The browser's pseudo-color preview is not written back to the original data.
+
+### 12.3 Startup checks
+
+    python deploy.py --check-only
+    python -m compileall app worker
+    PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q
+
+Do not commit <code>.env</code>, API keys, tokens, real data, or server credentials to Git.
+
+## 13. Code structure and responsibilities
+
+This chapter explains the frontend, backend, Worker, and data-processing code behind the pages. Normal operation does not require changing these files. When maintaining a feature, use this chapter to find the corresponding code quickly.
+
+### 13.1 System code flow
+
+    Browser page
+        ↓
+    HTML templates and JavaScript
+        ↓
+    FastAPI backend APIs
+        ↓
+    Projects, Episodes, annotations, and workflows
+        ↓
+    Worker claims a processing job
+        ↓
+    Workflow modules run post-processing
+        ↓
+    Save keypoints, 3D, sensor, and annotation results
+        ↓
+    Video review and data export
+
+Business data is primarily stored in project files. User accounts can use a database. The application retains a compatibility fallback when the database is temporarily unavailable.
+
+### 13.2 Code directory tree
+
+    processor/
+    ├── app/                         # Python backend
+    │   ├── main.py                  # FastAPI application entry point
+    │   ├── config.py                # Environment variables and system settings
+    │   ├── paths.py                 # Shared directory paths
+    │   ├── localstore.py            # Project, workflow, and Episode file state
+    │   ├── database.py              # User account database connection
+    │   ├── models.py                # Database models
+    │   ├── workflow_dispatch.py     # Workflow matching, dispatch, and backfill
+    │   ├── workflow_bindings.py     # Bind workflows to actual device inputs
+    │   ├── ai_annotation.py         # AI annotation service
+    │   ├── export_engine.py         # Shared export-job logic
+    │   ├── lerobot_export.py        # LeRobot 3.0 dataset generation
+    │   ├── lerobot_v21.py           # LeRobot 2.1 compatibility
+    │   ├── hdf5_export.py           # HDF5 dataset generation
+    │   ├── routes/                  # Page and business APIs
+    │   ├── api/                     # Project, workflow, and Worker APIs
+    │   └── processing/              # Workflow processing framework
+    │       ├── registry.py           # Automatic module registration
+    │       ├── catalog.py            # Module catalog for the workflow page
+    │       ├── batch.py              # Find videos and Parquet files in a batch
+    │       └── modules/              # Execution code for workflow nodes
+    ├── worker/                      # Background processing program
+    │   ├── __main__.py              # Worker entry point
+    │   ├── runner.py                # Claim and execute workflow jobs
+    │   └── client.py                # Communicate with the backend Worker API
+    ├── web/                         # Frontend pages
+    │   ├── templates/               # HTML page templates
+    │   ├── static/js/               # Page interaction, playback, and rendering
+    │   └── workflow-studio/         # React workflow editor source
+    ├── scripts/                     # Deployment, migration, and maintenance
+    ├── tests/                       # Automated tests
+    ├── models/                      # Local model files
+    ├── docs/                        # Chinese and English documentation
+    ├── deploy.py                    # One-command deployment entry point
+    └── requirements*.txt            # Python dependencies
+
+<code>.venv*</code>, <code>.pytest_cache</code>, and <code>.backups</code> are local environments, test caches, or backups. They are not part of the main business code.
+
+### 13.3 Frontend code
+
+The frontend has two parts:
+
+1. Standard pages use HTML templates and plain JavaScript.
+2. The workflow editor uses React and TypeScript.
+
+#### Page templates
+
+| File | Responsibility |
+| --- | --- |
+| <code>web/templates/base.html</code> | Common page frame, left navigation, and shared resources |
+| <code>web/templates/overview.html</code> | Home page |
+| <code>web/templates/tasks.html</code> | Project management page |
+| <code>web/templates/index.html</code> | Annotation and video-review pages |
+| <code>web/templates/trash.html</code> | Trash page |
+| <code>web/templates/login.html</code> | Login page |
+| <code>web/templates/users.html</code> | User management page, still under development |
+| <code>web/templates/workflow_studio.html</code> | Workflow editor entry page |
+
+#### Page JavaScript
+
+| File | Responsibility |
+| --- | --- |
+| <code>web/static/js/dashboard.js</code> | Home statistics, recent data, and refresh |
+| <code>web/static/js/tasks.js</code> | Create, edit, delete, and expand projects and batches |
+| <code>web/static/js/app.js</code> | Episode list, review, deletion, and export actions |
+| <code>web/static/js/player.js</code> | Video loading, central playback clock, and frame synchronization |
+| <code>web/static/js/annotations.js</code> | Annotation segments, timeline, and frame-level annotation |
+| <code>web/static/js/slice-preview.js</code> | Annotation segment preview in the upper-right corner |
+| <code>web/static/js/hand-overlay.js</code> | Draw 2D hand keypoints over the RGB video |
+| <code>web/static/js/depth-renderer.js</code> | Render raw 12-bit depth codes as browser pseudo-color |
+| <code>web/static/js/heatmap.js</code> | Display glove sensor data in sync with video |
+| <code>web/static/js/media-cache.js</code> | Cache keypoints and sensor data in IndexedDB |
+| <code>web/static/js/i18n.js</code> | Chinese and English interface text |
+| <code>web/static/js/login.js</code> | Login form |
+| <code>web/static/js/users.js</code> | User management interactions, still under development |
+
+The workflow editor source is in <code>web/workflow-studio/src/</code>. Its compiled files are in <code>web/static/workflow-studio/</code>. Change the source and rebuild the editor; do not edit the compiled output directly.
+
+### 13.4 Backend entry point and page APIs
+
+<code>app/main.py</code> is the backend entry point. It is responsible for:
+
+- Starting FastAPI;
+- Initializing file directories and the user database;
+- Warming project and Episode metadata caches;
+- Starting the upload processing queue;
+- Registering page, project, video, annotation, workflow, and export APIs;
+- Configuring static-file caching and large-media transfer behavior.
+
+| File | Responsibility |
+| --- | --- |
+| <code>app/routes/pages.py</code> | Return the Home, Projects, Review, Workflow, and Trash pages |
+| <code>app/routes/dashboard.py</code> | Home statistics, recent Episodes, and trends |
+| <code>app/routes/session.py</code> | Receive archives, extract files, normalize directories, and import metadata |
+| <code>app/routes/ingestion.py</code> | Episode list, details, approval, reprocessing, deletion, and restoration |
+| <code>app/routes/video.py</code> | RGB video, depth code, depth preview, 2D, 3D, and sensor APIs |
+| <code>app/routes/annotations.py</code> | Create, edit, delete, and read per-frame annotations |
+| <code>app/routes/export.py</code> | Single export, batch export, export status, and downloads |
+| <code>app/routes/auth.py</code> | Login, logout, and current-user APIs |
+| <code>app/routes/devices.py</code> | Collector heartbeat and input capabilities |
+
+### 13.5 Project, workflow, and Worker APIs
+
+| File | Responsibility |
+| --- | --- |
+| <code>app/api/projects.py</code> | Create, edit, and delete projects; manage inputs and workflow bindings |
+| <code>app/api/workflows.py</code> | Create, save, run, inspect usage, and retry workflows |
+| <code>app/api/worker.py</code> | Claim jobs, download inputs, send heartbeats, and report completion or failure |
+| <code>app/api/exceptions.py</code> | Aggregate and clear processing exceptions |
+| <code>app/api/users.py</code> | Create users and manage roles, statuses, and deletion; still under development |
+
+The backend and Worker job flow is:
+
+    Backend creates a workflow run
+        ↓
+    Worker claims the job
+        ↓
+    Worker downloads the Episode input
+        ↓
+    Workflow nodes execute
+        ↓
+    Worker uploads the result and reports completion
+        ↓
+    Episode enters Reviewing or Approved
+
+The Worker sends regular heartbeats. If it stops, the job is not immediately lost; the backend can schedule it again after the lease expires.
+
+### 13.6 Workflow processing modules
+
+In <code>app/processing/modules/</code>, one Python file usually represents one workflow node. Modules are registered automatically, displayed in the workflow editor, and executed by the Worker.
+
+| Module file | Responsibility |
+| --- | --- |
+| <code>mono_camera.py</code> | Single RGB input |
+| <code>rgbd_camera.py</code> | RGB and depth input |
+| <code>stereo_camera.py</code> | Left and right stereo RGB input |
+| <code>stereo_rgbd_camera.py</code> | Left and right RGB plus depth input |
+| <code>glove_sensor.py</code> | Glove sensor input |
+| <code>mediapipe_hand.py</code> | MediaPipe hand keypoint and gesture recognition |
+| <code>rgb_hand_3d.py</code> | Bare-hand RGB 2D keypoints and spatial preview |
+| <code>black_hand_rgb_3d.py</code> | Black-glove RGB 2D keypoints and spatial preview |
+| <code>depth_hand_3d.py</code> | Real 3D calculation helper used by RGB-D hand modules; not a standalone node |
+| <code>black_glove_hand.py</code> | Black-glove keypoint processing |
+| <code>ai_annotation.py</code> | Declare and trigger automatic AI annotation |
+| <code>annotation.py</code> | Human annotation workflow node |
+| <code>human_review.py</code> | Human-review gate |
+| <code>ai_quality_review.py</code> | Automatic video and annotation quality checks |
+| <code>lerobot_export.py</code> | LeRobot export node |
+| <code>hdf5_export.py</code> | HDF5 export node |
+
+When adding a workflow module, check:
+
+1. The module input and output types;
+2. Whether the Worker can execute it;
+3. Whether the workflow editor displays it correctly;
+4. Whether the Review page can read its output;
+5. Whether export modules include the new output.
+
+### 13.7 Data, cache, and export code
+
+| File | Responsibility |
+| --- | --- |
+| <code>app/localstore.py</code> | Scan and cache projects, Episodes, workflows, and run states |
+| <code>app/storage.py</code> | Upload, validate, save, and remotely synchronize files |
+| <code>app/remote_storage.py</code> | Remote storage access |
+| <code>app/media_groups.py</code> | Organize RGB, depth, and sensor media groups |
+| <code>app/media_cache.py</code> | Server-side media cache |
+| <code>app/browser_preview.py</code> | Generate browser-compatible video previews |
+| <code>app/artifact_resolver.py</code> | Locate workflow processing results |
+| <code>app/export_engine.py</code> | Shared export flow |
+| <code>app/lerobot_export.py</code> | Generate LeRobot 3.0 datasets |
+| <code>app/lerobot_v21.py</code> | Generate and support LeRobot 2.1 data |
+| <code>app/hdf5_export.py</code> | Generate HDF5 datasets |
+
+Keep source data, processing results, and export copies distinct:
+
+    data/sessions/     # Project source data and merged processing fields
+    data/tmp/          # Temporary processing files
+    Browser IndexedDB # Frontend preview cache; can be regenerated
+    Export archives   # Delivery files generated from workflow settings
+
+Do not store the browser's pseudo-color depth images as source data. The source depth remains raw depth codes.
+
+### 13.8 Where to change a feature
+
+| Feature | Frontend | Backend or processing |
+| --- | --- | --- |
+| Home statistics | <code>dashboard.js</code> | <code>routes/dashboard.py</code> |
+| Projects page | <code>tasks.js</code> | <code>api/projects.py</code> |
+| Upload and extraction | Projects page | <code>routes/session.py</code> |
+| Workflow editor | <code>workflow-studio/src/</code> | <code>api/workflows.py</code> |
+| Automatic workflow run | Project status display | <code>workflow_dispatch.py</code> |
+| RGB video playback | <code>player.js</code> | <code>routes/video.py</code> |
+| Playback frame synchronization | <code>player.js</code> | <code>routes/video.py</code> |
+| 2D hand keypoints | <code>hand-overlay.js</code> | Hand-processing modules |
+| 3D hand space | <code>player.js</code> | <code>processing/modules/*3d*.py</code> |
+| Depth pseudo-color | <code>depth-renderer.js</code> | <code>routes/video.py</code> |
+| Glove sensor | <code>heatmap.js</code> | <code>glove_sensor.py</code> |
+| Annotation timeline | <code>annotations.js</code> | <code>routes/annotations.py</code> |
+| AI annotation | <code>annotations.js</code> | <code>ai_annotation.py</code> |
+| Video review | <code>app.js</code> | <code>routes/ingestion.py</code> |
+| Single and batch export | <code>app.js</code> | <code>routes/export.py</code> |
+| LeRobot format | Export button | <code>lerobot_export.py</code>, <code>lerobot_v21.py</code> |
+| HDF5 format | Export button | <code>hdf5_export.py</code> |
+| Trash | <code>trash.html</code> | <code>routes/ingestion.py</code> |
+| User management | <code>users.js</code> | <code>api/users.py</code> |
+
+### 13.9 Troubleshooting order
+
+When a problem occurs, check it in this order:
+
+1. Confirm which page shows the problem.
+2. Find the JavaScript file used by that page.
+3. Check the browser developer tools for failed API requests.
+4. Use the API address to find the corresponding Python route.
+5. If it is a workflow job, inspect the Worker and processing module.
+6. If displays are out of sync, inspect the current Episode's frame count, FPS, and cache.
+7. Run the tests after making changes, then validate with real data.
+
+## Closing note
+
+Receive the data first, process it next, inspect it after processing, and export it only after it passes review.

processor/docs/images/README.md

@@ -0,0 +1,26 @@
+# 教程截图
+
+请把脱敏后的页面截图放在这里，并使用以下文件名：
+
+```text
+01-start-success.png
+02-home.png
+03-upload.png
+04-workflow.png
+05-video-review.png
+06-review.png
+07-export.png
+08-failed.png
+09-trash.png
+```
+
+截图规则：
+
+- 红色箭头：要点击的位置；
+- 黄色框：需要注意的位置；
+- 蓝色编号：操作顺序；
+- 绿色框：成功状态；
+- 不要保留密码、Token、API Key、服务器地址或真实隐私信息。
+
+如果暂时没有截图，教程中的“截图位置”文字可以保留，后续替换图片即可。
+