droboticflow/docs/annotation-slice-discard.md

48 lines
7.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 舍弃片段:保留审核证据、不标注、不交付
## 行为
- 切片独立使用 `deliveryDisposition: keep | discard`,缺省为 keep。`isInvalid`、空动作确认和删除切片保持原有含义。
- 标注员在切片或逐片标注阶段明确确认舍弃,填写 1–1000 字原因。操作保存当前切片划分和状态,不改变领取人,不删除原视频,不移动相邻边界。
- 舍弃段不需要动作描述。已确认的描述保存为审核证据,恢复时回填,并重新核对、提交审核。
- 已舍弃区间不能被直接移动、删除、拆分或合并;先恢复,再调整边界。旧客户端不能通过漏传字段静默恢复舍弃状态。
- 质检和验收均保留全部切片、视频、PTS/IMU和舍弃原因;按原流程打回和重新审核。不改变抽检比例或既有角色权限。最终验收继续保持匿名,操作人身份保存在内部审计记录中。
- “处理覆盖”包含保留和舍弃区间,仍必须完整、无重叠地覆盖统一帧范围。“交付范围”仅包含保留区间,不把正常舍弃造成的交付间隔误报成漏标。
- 当前描述型工作台(模板 v6 起)允许保留切片部分或全部语义留空。提交任务即确认空白,不要求逐片标记无效;没有描述的保留切片以 `empty_confirmed` 保存(仅表示确认没有语义描述),不改变交付用途。已有描述仍须有文本、位于所属切片、无重叠且对齐统一帧边界;未保存的编辑仍须保存或取消。旧版任务标签流程的完成规则不变。
- 留空仍经过原有质检、验收,保留全部视频及同步文件;`annotation.json` 只记录实际填写的描述,全片留空时 `actions` / `descriptions` 为 `[]`。不会自动补无效片段,不会把未标注区间从交付视频中裁掉。总 JSON 交付形态不发布视频,“不裁掉”体现为未交付区间的证据仍留在已验收的物化版本里。
- 新增描述从当前播放头开始,不自动回填前面的空白。已有动作描述(包括最后一条)可删除并保留空白,不移动相邻描述;这与“删除切片并合并范围”是两种不同操作。只有真正首尾相接的动作才显示共用分界拖动手柄。
- 全部舍弃仍需完成原有审核。完成后状态为“无可交付片段”,不创建客户交付目录或空包,交付包记录没有可导出文件;父/子 Run 正常结束。
- 有舍弃/恢复历史的任务保留此前内部审核版本和生成证据,增加相应存储占用;不新增历史版本选择器,不改变项目删除权限或既有项目删除范围。
## 保存与审核
`POST /api/plugins/annotation-qa/tasks/{taskId}/slice-dispositions` 接收当前 HumanItem 版本、切片 ID、用途、原因及当前工作区。必须是当前领取的标注员,且处于标注阶段、没有正在执行的切片/提交流程。
服务端校验区间和版本,写入真实操作者、时间、被移出的描述及操作历史,再更新 HumanItem。提交后不能直接修改;旧版本请求被拒绝。其他保存接口只接受已保存的用途,不能伪造或遗漏舍弃决定。
## 打包与兼容
- 含舍弃的内部清单使用 `droboticflow.slice-materialization/v3`,仍包含所有审核切片;逐片目录交付使用 `droboticflow.delivery.manifest/v6`,只列保留项;总 JSON 交付使用 `droboticflow.delivery.part-index/v1`,保留与舍弃区间分别落在 `slices[]` 与 `discardedSlices[]`。
- Worker 将已审核的物化版本和清单 SHA-256传给打包算子。打包必须匹配该版本,不接受更改后的清单或未知用途。两种交付形态都校验逐片 `deliveryDisposition` 与 `synchronized-slice.json` 一致,不一致即 fail-closed。
- 逐片目录形态:每次新契约打包在独立临时目录构建,仅复制保留切片的白名单文件;左右视频、PTS、IMU、描述和姿态文件一致过滤。舍弃原因和历史描述不进入对外交付文件。
- 总 JSON 形态(`PART_INDEX_DELIVERY=true`):交付物只有一份 `part.json`,媒体不随交付发布。舍弃区间作为一等分类随索引交付,**携带 `discardEvidence`(原因、原因字典名、备注、操作人、时间)**;舍弃前的历史描述仍留在平台内部审核记录,不进入索引。
- 发布仍使用原有指定交付根目录和项目/采集目录结构;已有交付目标冲突不会自动覆盖或删除历史文件。两种形态共用同一份 `.delivery-owner.json` 归属标记,因此同一 part 不会被两次不同交付写入。
- 总 JSON 形态拒绝接管「有文件但没有归属标记」的目标目录:向已有历史目录追加索引前,该目录必须已带归属标记,否则拒绝发布而不是静默认领。
- 全保留的旧清单继续走原有 v1/v2兼容逻辑。原始人工和带前置处理工作流都保留原能力。
- Fanyu Worker 的部署配置 `FANYU_SLICE_DISCARD_PACKAGE_IMAGE` 指定兼容新旧契约的 digest-pinned 打包镜像,仅覆盖 builtin package 节点;实际镜像摘要写入执行快照,不改历史 Run 或其他前置算子镜像。总 JSON 形态还要求 Worker 识别 `part.json` 的路由块:旧 Worker 会把它当作普通运行 artifact 上传,而不写入冻结交付目标。
## 验证
- API测试:原因必填、身份/领取/阶段/版本限制、舍弃和恢复、旧描述保留、禁止隐式丢弃状态、完整处理覆盖。
- 前端测试:舍弃免标注但不计为已标注,灰色状态和原因可见,验收仍保留全部切片。
- 真实媒体测试:60秒、双目4fps、逐帧PTS和双类型IMU,分三段。全保留交付60秒;中间舍弃交付40秒;全舍弃不生成交付目录。逐项检查帧数、文件清单和SHA-256。
- `TestSeedSliceDiscardFanyu` 是显式开启的部署验收夹具,只创建带独立验证前缀的项目、供应商、测试账号、合成输入和人工节点起点。后续通过真实公开API走标注/质检/验收,由真实Worker执行打包,不用于声称验证了前置算法质量。
测试开关默认关闭,凭据仅从临时环境变量读取,不写入代码或验收产物。线上夹具没有持续接入监听,不会批量启动已有采集目录。
### 恢复后再编辑与用途继承(2026-10-16)
已恢复的子切片可以继续切分动作、填写描述、再次舍弃,也可以在原地切分面板继续拆片。用途基线始终优先使用同 ID 的当前服务端切片;只有新切出的子片没有同 ID 记录时,才按 `sourceIds` 中最近父片在前的顺序读取已保存父片。更老的舍弃祖先不能覆盖当前普通子片的用途。前端显式用途命令与服务端基线采用相同优先级;不按工作区数组的排列顺序选择祖先。
用途仍须通过明确的舍弃/恢复操作保存;普通快照不能改用途,身份、版本、覆盖与原因字典校验不变。恢复后新写的动作在再次舍弃时归档,邻片判断及原有审计证据保留。不改写已有任务或历史,沿用既有数据结构,无迁移;回退旧代码会重新暴露该父子切片组合的操作限制。