V0.4.0 · Windows / Python 3.12 / CPU · 本地单用户
把一批机器人演示数据，变成可检查、可追溯、可读取的训练样本。
| 流程总览：八节点链路与批次状态 | 数据质检：独立规则与逐条证据定位 |
|---|---|
 |
 |
| 格式转换：官方 LeRobot v3.0 写入 | 打包交付：独立解包与官方离线加载 |
 |
 |
全部界面截图已内嵌在本文后续章节，无需跳转；截图来自 2026-09-11 真实运行。
八节点链路对应具身数据交付的标准流程：上传／导入 → 数据清洗 → 数据筛选 → 数据标注 → 标注审核 → 数据质检 → 格式转换 → 打包交付。每个节点独立记录输入、处理、输出、版本与日志。导入后自动执行基础清洗；人工完成筛选与审核后，最终质检、官方 LeRobot v3.0 转换与 ZIP 独立验证连续执行。
不想安装？ 本 README 已包含全部界面截图与真实运行数据。另有一份独立的 静态展示页（
docs/index.html），需下载仓库后离线打开—— GitHub 不渲染仓库内的 HTML 文件，点开只会看到源码。
| 主张 | 证据 |
|---|---|
| 转换是对的 | 输出全量 116 帧与源 float32 映射一致，官方库离线抽查 6 个位置，DataLoader 批读取通过 |
| 交付包能读 | 在新目录独立解包，校验哈希、元数据、索引后官方离线加载通过；篡改 ZIP 在清单校验节点被拒 |
| 问题能定位 | 注入 NaN 定位到具体行；缺字段任务被隔离；缺视频任务单独记录，不中断其余任务 |
| 门禁是真的 | 候选集未确认时无法提交审核；最终质检未通过则不进入转换；产物哈希变化后旧包标为历史 |
| 运行可追溯 | 每次运行保存 request/state/events.jsonl 与逐节点日志，14 个节点全程 29.3 秒 |
| 范围可扩展且已验证 | 全量 demo_0–9（531 帧）跑通八节点闭环：输入质检 100/100、输出质检 110/110、官方离线加载 531 帧数值与 30 个采样位置比对一致、交付包 10 条独立验证通过 |
一次真实完整链路：14 个节点全部完成，源任务 0、2 → 输出 2 条／116 帧，端到端 29.26 秒。明细见 V0.4 验收。
- 只想看效果：作品展示页（静态，零安装，含全部界面截图与真实运行数据）
- 想跑起来：双击根目录
首次安装.cmd，装完双击桌面快捷方式 —— 见安装与启动 - 讲给面试官：演示路线
- 查实现：数据字典、V0.4 状态、导航验收
- 查操作：标准操作 SOP，HTML 手册 可离线打开
默认服务地址为 http://127.0.0.1:8501/，仅指向运行程序的本机。访问源码仓库不会自动启动工作台，GitHub Pages 也不提供该 Python 服务。本地验收与远程发布分别进行。
把仓库克隆或下载到本机，双击根目录的 首次安装.cmd。向导会自动完成：
- 检查并（必要时）安装 uv —— Python 环境管理器，不污染系统 Python
- 准备 Python 3.12（由 uv 托管）
- 安装主环境依赖（约 400 MB）
- 下载公开演示数据（约 46 MB）
- 在桌面创建「RoboData 工作台」快捷方式
完成后双击桌面快捷方式即可使用，浏览器自动打开。全程需要联网。
完整 HDF5 转换链路（格式转换节点）另需约 2.2 GB（含 CPU 版 PyTorch）。 向导会提示可选命令；不安装也不影响浏览、质检与标注功能。
需要 Python 3.12 和 uv。获取源码并解压到项目目录，或从实际可访问的仓库克隆源码；在包含 app.py 的目录执行 PowerShell 命令：
# 主环境
uv sync --frozen
# 体验 HDF5 批次全流程：预览和转换均需要独立环境
uv sync --project tools/conversion --frozen
uv run robodata fetch-hdf5
# 启动本地页面
.\启动工作台.cmdHDF5 样本约 46 MB；独立环境还需下载 CPU PyTorch 等依赖。首次安装完成后，日常双击 启动工作台.cmd 即可。已有服务正常运行时直接打开页面。
SO-100 浏览与故障演示另需执行 uv run robodata fetch-sample，下载默认子集（5 条 / 3,562 帧）约 53 MB；执行 获取全量数据.cmd 可补齐全量 50 条 / 32,068 帧（约 535 MB）。下载器固定版本与文件清单，支持复用、重试和完整性检查；代理只通过下载参数或当前进程变量配置。
| ① 上传／导入 | ② 数据清洗 |
|---|---|
 |
 |
| 选择固定 HDF5 文件上传或本机路径、SO-100 目录，建立管理副本并核验来源。 | 自动基础检查，异常任务隔离；保留原始数值，导出无变更处理记录。 |
| ③ 数据筛选 | ④ 数据标注 |
|---|---|
 |
 |
| 任务级保留／隔离／排除，填写原因、确认候选集并导出筛选清单。 | 预览原始数据，填写任务、执行结果、标签与备注，保存或提交。 |
| ⑤ 标注审核 | ⑥ 数据质检 |
|---|---|
 |
|
| 独立查看提交结果，审核通过或退回；导出审核记录。 | 审核后重新检查数据与标注，独立规则、报告和运行证据；不通过会阻止转换。 |
| ⑦ 格式转换 | ⑧ 打包交付 |
|---|---|
|
|
| 官方写入 LeRobot v3.0，验证全量数值、官方加载与视频偏移，查看实际训练文件。 | 独立解包校验与官方加载通过后，下载当前有效 ZIP 及整包 SHA-256。 |
“流程总览”展示八节点状态和批次列表。原有技术页面继续保留：数据概览、任务浏览、质检报告、运行记录、公开样本转换。公开样本转换使用固定三条 HDF5；业务格式转换只使用当前审核候选集，两者路由独立。
基础清洗检查通过的任务建议保留，其余隔离，随后等待人工确认筛选。清洗采用检查与隔离，不自动删帧、插值或修复轨迹；清洗记录和筛选清单是数据引用，完整训练数据由格式转换节点生成。隔离、排除和审核退回均须原因。重新筛选使下游审核与产物失效，已有标注文本保留为草稿。保存使用修订号，旧页面不能覆盖新决定。
三种“失败”分别记录： 机器人执行失败属于人工任务标注；NaN、缺字段等属于数据质量问题；文件读取、编码或超时属于程序运行问题。记录完整的失败轨迹可以通过质检和审核，不以“机器人成功”作为数据合格的替代标准。
| 首页：入口说明与快速开始 | 运行记录：节点状态、耗时与证据定位 |
|---|---|
 |
 |
侧栏为 八个业务节点＋批次总览＋运行记录。八个节点对应具身数据交付的标准流程：上传／导入 → 数据清洗 → 数据筛选 → 数据标注 → 标注审核 → 数据质检 → 格式转换 → 打包交付。顶部八节点进度条可直接跳转，URL 携带 page 与 batch_id，可分享和复现到具体节点页面。
批次总览包含“数据概览、任务浏览、来源与字段”；数据质检包含“当前质检、报告与历史”，可按原运行时间查看并下载本批次历史报告。节点、日志和问题定位继续保留。
独立样本浏览、故障演示及公开样本转换收纳在折叠的 高级工具。
| 来源 | 固定范围 | 字段与处理范围 |
|---|---|---|
| jmrog/so100_sweet_pick | revision 54141acb0bd6bcb868e34b4eb328f26481d333b2；硬盘已备 Episode 0–49（32,068 帧），默认启用 Episode 0–4（3,562 帧）。 |
LeRobot v2.0 真机数据，状态／动作各 6 维，laptop 单相机 640×480、30 Hz、AV1 编码；支持导入、预览、质检、标注、转换与交付。 |
| robomimic/robomimic_datasets | revision 74fa018461f479cd9fd15b924a16103012096203；test/test.hdf5 共 demo_0–9（531 帧），默认启用 demo_0–2（174 帧）。 |
Panda / Lift 仿真测试片段，状态 9 维、动作 7 维、agentview 84×84 RGB；业务候选子集可转换和打包。 |
HDF5 本地上传仍受固定配置约束，不是通用 HDF5 导入器。测试副本必须显式标记；标记不会让结构或质量检查自动通过。
两种来源都能跑完整条链路（导入 → 质检 → 筛选 → 标注 → 最终质检 → 转换 → 交付 → 独立验证），转换链路上各有各的适配器：
- HDF5 → v3.0：由
tools/conversion/worker.py直接读取 HDF5 的 demo 结构，映射字段后用官方LeRobotDataset.create()写入。 - SO-100 v2.0 → v3.0：源是 LeRobot v2.0，缺 v2.1 要求的
meta/episodes_stats.jsonl，因此先补齐 per-episode 统计（数值读 parquet，视频抽帧后走官方sample_images），再逐阶段调用官方转换函数。官方convert_dataset()末尾会rmtree并原地替换源数据集，平台只调用其阶段函数，源数据始终只读。
状态与动作保留来源语义，不补充未经核对的单位或控制含义。HDF5 时间由 frame_index/20 派生；H.264 视频有损。SO-100 视频为 AV1 有损，v2.1→v3.0 是 remux 不重编码，因此不对逐像素恒等作断言，而是核对帧数与解码样本哈希。来源全局统计 9,666 与文件实际 531 帧不一致，作为警告保留，输出按候选任务重新计数。详见 数据字典 和 来源与许可。
固定样本 test.hdf5 实际包含 10 条 demo（demo_0–9，合计 531 帧），默认只启用
demo_0–2（174 帧，与 V0.4 验收一致）。通过 ROBODATA_HDF5_EPISODES 可调整范围，
无需修改代码：
$env:ROBODATA_HDF5_EPISODES = "0-9" # 全量 10 条 / 531 帧
$env:ROBODATA_HDF5_EPISODES = "0-2,5,7-9" # 混合区间与单点
.\启动工作台.cmd也可直接双击 启动工作台全量数据.cmd。范围变化会改变输入指纹，已有批次需要
重新导入，这是预期行为。越界或非法范围直接失败，不静默降级；校验使用冻结的帧数
清单（tools/conversion/worker.py 的 _ALL_DEMO_LENGTHS），不从被检文件自证。
启动入口命名约束： 桌面启动器会枚举项目根目录的
*.cmd并执行其中第一个， 因此启动工作台.cmd必须保持排序最前。新增启动入口时，文件名不要以排在.（U+002E）之前的字符开头（如-、!、#），否则会抢占默认启动， 现象是桌面快捷方式"打不开"或启动异常。另外，根目录的.cmd应保持纯 ASCII 内容：cmd.exe按当前代码页解码批处理文件，UTF-8 中文在默认 GBK 代码页下会乱码。
全量范围已通过端到端验收（2026-09-12，证据见 work/full-range-acceptance.json，
由 scripts/verify_full_range.py 生成）：在 ROBODATA_HDF5_EPISODES=0-9 下，
10 条 / 531 帧走完导入 → 质检 → 筛选确认 → 标注审核 → 格式转换 → 打包交付 → 独立验证，
输入质检 100/100 项、输出质检 110/110 项、0 数据问题，官方库离线加载并对 531 帧
数值与 30 个采样位置像素比对一致，交付包 531 帧 / 10 条整包路径可移植、独立加载通过。
SO-100 全量 50 条 / 32,068 帧（约 535 MB） 已在本地备齐（可执行 获取全量数据.cmd
或 uv run robodata fetch-sample --full），默认只启用 Episode 0–4（3,562 帧，约 53 MB），
保证日常演示秒开。通过 ROBODATA_SO100_EPISODES 可调整：
$env:ROBODATA_SO100_EPISODES = "0-49" # 全量 50 条 / 32,068 帧
$env:ROBODATA_SO100_EPISODES = "0-9" # 前 10 条
.\启动工作台.cmdSO-100 已通过端到端验收（2026-09-13，证据见 work/so100-acceptance.json，
由 scripts/verify_so100.py 生成）：默认 5 条 / 3,562 帧走完导入 → 质检 → 筛选确认
→ 标注审核 → 最终质检 → 格式转换 → 打包交付 → 独立验证，输入质检 55/55 项、
输出质检 55/55 项、0 数据问题，官方库离线加载并对 3,562 帧数值与 15 个采样位置
像素比对一致，交付包 53 MB 路径可移植、解包后独立加载通过。
转换链路额外验证两点：v2.0 → v2.1 阶段为 5 条任务补齐了 per-episode 统计； 源目录在转换前后 SHA-256 不变（平台不原地替换）。
若运行环境的临时文件批量清理被安全策略拦截（表现为转换节点报"工作进程意外退出，
退出码 1"，日志出现 SAFE_DELETE_BULK_CONFIRM_REQUIRED），追加设置
ROBODATA_STREAMING_ENCODING=1：LeRobot 改用流式编码直接把帧写入视频，
不再落临时图片目录，因此不产生批量删除。默认关闭以保持既有编码路径。
当前范围不包括通用 MCAP 接入、逐帧轨迹修复、多相机硬件同步、模型训练和多人权限系统。基础规则与官方加载通过，不代表训练效果、物理安全或任务成功率。
排查路径：批次／运行编号 → 失败节点 → 中文原因和文件证据 → 任务、字段、行位置或堆栈 → 处理后启动新运行。
“运行记录”保存节点状态、耗时和程序日志；“业务审计历史”保存筛选、标注与审核决定。即使最终报告没有生成，已写入的运行日志仍可查看。每次显式执行创建新运行；刷新读取同一记录。
work/runs/<run_id>/ 保存 request.json、state.json、events.jsonl、节点标准输出／错误日志和阶段证据。批次快照、管理副本位于 work/business/。候选内容变化、验证未完成或文件指纹不匹配时，不作为当前有效交付提供下载。
原有故障演示可展开侧栏“高级工具”，在样本页面使用“异常演示副本”“视频缺失演示副本”和“运行超时演示”。具体注入位置及结果含义见 SOP。
主环境负责页面、轻量读取、质检、后台协调及业务状态；tools/conversion/ 使用独立 Python 进程完成 HDF5 解析、官方写入与离线加载。两个环境分别锁定依赖。转换组合与维护说明见 独立环境文档。
uv run robodata batches
uv run robodata runs
uv run robodata show-run <run_id> --events
uv run robodata show-flow <batch_id>
# 审核完成后的最终检查；通过后自动完成转换和交付
uv run robodata final-check-batch <batch_id> --revision <revision>
# 对下载 ZIP 在新目录独立校验并官方离线读取
uv run robodata verify-delivery --archive <zip_path>
uv run pytest -q命令中的 <run_id>、<batch_id>、<revision>、<zip_path> 需替换为实际编号、修订或路径。更多导入、批次检查和交付验证命令见 SOP。
CI 在 windows-latest 上执行同一组测试（.github/workflows/tests.yml）；需要独立转换环境与固定样本的用例在缺失时自动跳过，其余用例不依赖下载数据。
V0.1、故障样本验证、V0.2、V0.3 保留各阶段的实测范围与结果。V0.3 的 91 项测试和固定三条转换结果属于历史基线。V0.4 真实自动链保留源任务 0、2，输出 2 条／116 帧；全量 float32 数值比对、6 个图像位置与官方读取一致、22/22 项输出质检及交付包独立加载通过。异常副本另验证任务隔离、剩余 57 帧转换和篡改 ZIP 拒绝。最终测试与实际浏览器操作按 V0.4 验收 的范围阅读，不以界面测试代替真实数据验证。
原始数据、管理副本、运行日志、报告和交付 ZIP 默认保存在被 Git 忽略的 data/、work/、reports/。历史证据中引用的本地产物需自行复现，不随源码自动下载。
当前界面截图在 docs/assets/v04/（2026-09-11 实测）；仓库另附脱敏后的 公开证据摘要，可直接用于作品展示页。
关键决策都放弃了什么，写在这里而不是藏起来。
| 决策 | 选择 | 放弃的 |
|---|---|---|
| 数据列式存储 | Parquet | 放弃 MCAP 的流式写入与 ROS 生态直连；换取与 LeRobot 官方格式一致和 Pandas 生态 |
| 运行环境 | 主环境与 tools/conversion/ 双环境隔离 |
放弃单环境部署的便利；换取 torch / h5py 重依赖不污染页面环境 |
| 视频编码 | H.264 | 放弃无损；换取体积与官方加载器兼容性，因此文档明确标注图片为有损 |
| 时间派生 | HDF5 按 frame_index / 20 |
源数据无时间戳字段，放弃精确同步；换取可复现的确定性派生 |
| 清洗策略 | 任务级隔离，不自动删帧、插值或修轨迹 | 放弃自动修复；换取原始数据不被静默改动，每条隔离必须填原因 |
| 失败建模 | 任务失败 / 数据异常 / 程序失败 三类分开 | 放弃单一成功失败判断；换取完整失败轨迹仍可作为有效数据保留 |
| 产物失效 | 内容版本或哈希变化即标记历史 | 放弃"永远可下载"的便利；换取不会误把过期产物当当前有效交付 |
MIT。数据来自公开数据集，来源与许可见 DATA_NOTICE.md。