📐 Plan part-level slicing index to replace physical slice cutting

This commit is contained in:
d-robotics 2026-10-08 23:44:20 -07:00
parent ee82e73aee
commit dfe61d99bb

View File

@ -0,0 +1,80 @@
# 交付切分索引方案:part 级 JSON 替代物理切分
对应需求(马迪 2026-10-08):数据不需要真的切分,一个 part 一个总 JSON 记录切分信息,含任务级(切片)与动作级(动作区间)切分信息。
## 现状(已核实)
- 物化(送检时触发):`internal/api/human_slice_materialization.go` 把源视频逐片重编码切分(`writeFrameAccurateSlices`,h264-ultrafast-crf23),每片写 `left.mp4/right.mp4/left_pts.csv/right_pts.csv/imu.csv/annotation.json/synchronized-slice.json/headpose.json/handpose.json`,产出 `acceptedSliceDirectory` 目录 artifact。
- 打包:`operator-repos/builtin/package/src/operator.py` `_run_accepted_slice_directory` 校验每片帧数=PTS 行数、SHA-256,复制到交付根 `clips/slice-xxxxxx/`,姿态按片裁剪,写 part 级 6 个 JSON + `calibration/`。
- 发布:`internal/worker/capture_delivery.go` 条件创建 + `manifest.json` 最后写入。
- 审核与验收的播放走源视频 + 边界网格(`annotation_operations.go` 的 `fullLeftVideos`/`newAnnotationBoundaryGrid`),**不读切片文件**;验收"文件清单/文件齐全"检查(`src/lib/acceptance-workspace.js` `acceptanceChecks`)从物化成员推导,随物化产物形态自适应。
- 舍弃切片目前**物理排除**在 clips/ 之外(coverage `selected_accepted_intervals`)。
## 方案:两步走
### 第一步(加法,不改现有交付内容):交付根新增 `slicing-index.json`
打包算子把 revision-manifest 各片信息 + 每片动作区间聚合成一个 part 级 JSON:
```json
{
"schemaVersion": "droboticflow.slicing-index/v1",
"collectionId": "…", "revision": 12, "taskId": "…", "runId": "…",
"commonRange": {"startTimestampUs": …, "endTimestampUs": …, "semantics": "half-open"},
"boundaryContract": "hardware-frame-v1",
"slices": [
{
"sliceId": "slice-000001", "sliceName": "…",
"deliveryDisposition": "keep | discard",
"discardReason": "…(仅 discard)",
"startTimestampUs": …, "endTimestampUs": …,
"startSecond": …, "endSecond": …,
"actions": [
{"id": "…", "status": "…", "isInvalid": false, "description": "…",
"startTimestampUs": …, "endTimestampUs": …,
"startSecond": …, "endSecond": …}
]
}
]
}
```
- `*TimestampUs` 为采集硬件时钟绝对时间(跨片对齐用它);`*Second` 相对本 part 交付整段视频起点。
- 改动仅 `operator.py`:聚合已加载数据,写文件,登记进 `packages-manifest.json`(schemaVersion 升 v7,新增 `slicingIndex` 引用);`capture_delivery.go` 无改动(照单发布)。
- 客户立刻拿到两级切分索引,clips/ 照旧。不破坏任何现有契约,不需要业务决策。
- 验证:operator 单测(`tests/backend/test_fanyu_annotation_operators.py`)+ 本地副本栈打包一轮,比对索引与各片 annotation.json 一致。
### 第二步(契约变更,需业务拍板后实施):停止物理切分,交付整段
part 根直接放:`left.mp4`、`right.mp4`、`left_pts.csv`、`right_pts.csv`、`imu.csv`、`headpose.json`、`handpose.json`、`slicing-index.json`(同上,成为切分的权威记录);`calibration/` 与其余 part 级 JSON 不变;`clips/` 目录取消。
改动点:
| 文件 | 改法 |
| --- | --- |
| `internal/api/human_slice_materialization.go` | 删除逐片切分循环与 `mediaKey` 缓存;整段视频按字节复制进 accepted 目录;PTS/IMU 按 common range 整段裁剪一次;姿态整段裁剪一次;生成 `slicing-index.json`;保留整段视频帧数=PTS 行数校验(已有)与覆盖区间算术校验;revision-manifest 升 v4 |
| `operator-repos/builtin/package/src/operator.py` | 双格式兼容:按 slicing-index/manifest schemaVersion 识别新旧物化产物;新格式复制整段文件+校验和,packages-manifest v7 描述整段文件;姿态裁剪一次 |
| `src/lib/acceptance-workspace.js`、`FinalAcceptanceWorkspace.tsx` | 文件清单与 filesReady 检查按整段文件集合推导 |
| `internal/api/run_artifact_members.go` | 成员枚举适配新布局 |
| 文档 | `CONTEXT.md` 增加"交付切分索引"术语;`docs/capture-delivery-directory.md`、`docs/manuals/delivery-tree-reference.zh-CN.md` 更新 |
附带收益:物化不再重编码(省 CPU 与时间,重跑 1830 条那类场景明显加速);交付视频与 normalize 产物字节一致、无二次编码损耗。
## 必须先决策的冲突:舍弃片段语义
CONTEXT.md 定义"舍弃切片=明确选择不交付",当前靠物理排除实现。停止物理切分后,**整段视频会包含被舍弃的区间**(索引标记 discard,客户自行过滤)。若舍弃原因涉及敏感内容,等于把"不交付"的数据交出去了。选项:
1. **接受**:整段照发,索引标记为不交付区间——实现最简单,需客户书面确认业务上可接受;
2. **混合**:含舍弃片段的 part 仍走物理切分(老格式),无舍弃的走整段——语义严格但两格式长期共存;
3. 维持现状,只做第一步。
## 兼容与发布边界
- 第一步只需发 package operator 镜像(API 不动)。
- 第二步 API 与 operator 镜像必须同批发布(`docs/capture-delivery-directory.md` 的既有边界),走 `scripts/release.py`。
- 在途任务:物化产物带 schemaVersion,算子双格式识别;已物化老格式任务照旧打包,回滚=回退镜像,不动存量数据。
- 老交付目录不受影响(`.delivery-owner.json` 快照与条件创建语义不变)。
## 建议
先做第一步(本周可发,客户立即受益),第二步等舍弃语义决策(吴龙涛/马迪确认选项 1/2/3)后排期。