droboticflow/docs/delivery-classification-v4.zh-CN.md
2026-11-08 10:00:31 -08:00

11 KiB
Raw Permalink Blame History

最终分类总 JSON v4

本地实现对应 ADR-0005 的 2026-10-21 修订。历史 v1/v2/v3 和已交付文件保持原状。开关默认关闭;本文不授权启用工作流或发布。

DELIVERY_JSON_V4=true 要求 PART_INDEX_DELIVERY=true,与 DELIVERY_JSON_V3 互斥;源索引修订另需 SOURCE_INDEX_DELIVERY=true。新工作流须有内部 deliveryAudit JSON 输出,以及正常的 deliveryDirectory 输出。配套 Worker 负责固定审核追溯,大于 inline 限额的验收摘要走现有内部 artifact 存储,打包节点读取固定引用;必须先验证内部存储可用。旧 Worker/旧算子不能启用新协议。

客户格式保持 capture、partId、slices[].taskSplit、slices[].segments[] 和 discardedSlices。按马迪约定的采集目录/part 组织文件:每个 part 一个总分类 JSON;批次索引 delivery_index.json 和采集索引 annotation_manifest.json 只负责目录定位、文件校验及汇总,不额外携带审核流水。正式批次目录不可变。

  • sliceName 是已确认的基础分类名称;classification.dictionary 是可获得的字典快照。动作描述为空也保留这个分类,不代表无动作。
  • 字典快照固定 id/kind/version/code/name/tags。tags 是独立分类标签,与 category、别名和描述原义不混用。新选择由服务端从项目字典校验,客户不能伪造标签;历史缺失快照不按当前词条补填。
  • 每个动作显式导出有效 tags 和 tagSource。独立选择动作词条用该快照标签,来源为 action;没有独立选择则继承本切片冻结标签,来源为 slice,不伪造动作 dictionary。自由填写文字也沿用这个判定;有文字不代表选择了独立词条,没有文字不代表没有动作。独立词条缺 tags 时拒绝交付,不偷偷退回父标签。
  • 动作 contentKind 为 annotated(有描述)、invalid_marked(明确无效)、gap_placeholder(保留的留空区间)。descriptionStatus 描述文字覆盖情况,不能用于推断整个切片是否有动作。
  • isInvalid 与标签独立;无效动作可保留继承标签,但仍必须按无效判断排除有效动作处理。历史动作未覆盖的留空范围保留为继承父标签的 gap_placeholder,不能把该段视频漏掉。
  • discardedSlices[].classification.discardEvidence 保留业务舍弃原因、原因词条/版本/标签和补充说明。全舍弃 part 也输出总分类 JSON。审核退回原因不放在这里。
  • 舍弃原因有冻结字典时,旧兼容字段 reasonLabelId/reasonVersion/reasonName 从同一快照补齐,不导出空名称或版本 0;已有非空值若与快照冲突即拒绝交付。手填原因仍按原有规则保留,不猜造字典选择。
  • originalSource 冻结 BOS bucket、原采集 prefix、partPrefix、输入快照指纹和所选原始文件路径。来自任务创建时的输入引用,不查询当前目录猜原文件,不输出连接 ID、凭据或签名 URL。八类文件为左右视频、左右 PTS、IMU、相机标定、IMU 标定和采集 meta。sources、sourceMetadata.path 与标定路径统一相对原采集目录,pathBases 显式写为 original_capture;原 workspace 路径只留内部追溯。

内部 droboticflow.delivery.review-history/v2 JSON 按 capture/part/revision 关联,以 partSha256 固定原生主文件字节;包含最终验收、抽检、审核人/批注/轮次/确认项、已有正式退回基线、处理记录和阶段事件。该 artifact 留在内部 Run 存储,不进入最终交付列表、不可变客户批次或客户下载。分类选择的服务端快照另外保存在当前任务的恢复记录中,使字典改名、更新或停用后的撤销仍可恢复原版本,客户端不能伪造历史标签。旧记录没有的追溯不制造补写。追溯超出限制时拒绝交付,不静默截断。

最终分类取通过验收的固定物化修订;沿用既有“未抽中”验收策略的任务,内部保留明确豁免,不能伪造人工通过日期。返工正式修改分类后必须重新送检、验收;查看或处理意见本身不修改分类。相同名称而字典版本/标签不同的切片不能自动合并成一个分类。

时间按两级明确表达,全部区间采用左闭右开:

字段 坐标
taskSplit.startSecond/endSecond 原始 part 左相机视频秒数
segments[].startSecond/endSecond、clipStartMs/clipEndMs 本切片左相机内秒数/毫秒数
segments[].partStartSecond/partEndSecond 原始 part 左相机视频秒数
startTimestampUs/endTimestampUs 原始硬件时间戳,非墙钟时间、非从秒数估算

timeBases 描述以上坐标及帧区间基准。下游从原始左右 PTS 分别定位同一硬件时间窗,不能把左相机秒数直接当右相机秒数。原始输入快照指纹标识当时选择,不冒充每个 BOS 对象的版本号或内容 SHA;原始数据应保留,当前发布时仅以 HEAD 校验所引用文件存在,不证明同名文件从未被外部覆盖。

新 v4 要求完整的冻结分类、非空标签、原始来源和可靠时间边界;任一缺失或动作重叠、时间戳不连续即停止交付。批次发布再核对原始 bucket/part 归属、文件存在性和消费契约,不能只凭主文件的 SHA 放行。元数据修订复用原始引用,不追随后来改变的采集记录。未发布的旧本地 v4 样例须重新生成;正式 v1/v2/v3 及其恢复路径保持兼容。历史缺证据应先核实补齐,已交付文件不覆盖,修正交付另建不可变批次。

平台只输出分类索引,不按标签执行 BOS 数据切割、搬运或集中打包。内部审核文件不在客户目录内,也不从主 JSON 引用。

2026-10-22 时间与来源门禁补充

新 v4 不再接受缺少秒数↔PTS 映射、仅靠动作首尾连续的旧证据;必须与固定同步窗口一致,不能从帧率或时长猜补。保留原映射与秒数,缺证据的历史结果需另行核对后生成新修订,不能自动迁移。

原始来源检查补充核对 Run 接入时保存的选择指纹:对完全相同的对象键 HEAD 后,按既有 key|ETag|size 算法比较,包含当时选择的可选音频。打包前、Worker 发布前和批次预览/发布均校验;不再仅证明对象存在。该指纹不是逐文件 SHA256 或不可变对象版本保证,也不按当前目录重新生成期望指纹。历史 v1–v3 和已交付字节不变,详见 标注时间完整性。

本地可用 python -m tests.backend.export_delivery_v4_fixture <全新输出目录> 生成明确标记的合成样例。目录中 partNNNN/part.json 是客户主文件;internal/partNNNN/review-history.json 是分离的内部示例,不属于客户包。不要把整个验证输出目录直接交付给客户。

独立消费验证:设置 FANYU_DELIVERY_CONSUMER_FIXTURE_DIR 为全新绝对目录,先运行 Go TestDeliveryV4ConsumerReplicaFixture,再以同一环境变量运行 tests/backend/test_delivery_v4_consumer.py。合成真实双目视频分别经过物理切片、源索引和元数据复用;独立进程仅读取导出 JSON 与原始文件,核对每帧覆盖、非零 part 起点、标签继承、无效与舍弃。独立读取器 tests/backend/consume_delivery_v4.py 只生成处理计划,不执行切割或写源数据。

2026-10-22 组合候选与默认关闭阶段

用户确认先与前端分层版本合并验证,DELIVERY_JSON_V4 继续保持关闭,启用另行制定计划。新代码的标签编辑、字典快照保存和内部物化元数据并非全部受该打包参数控制;关闭参数只保证不主动选择 v4 交付路径,不代表 API 行为与旧版本逐字节一致。

整采集的多 part 输入可能无法证明单 part 的原始来源。普通物理切片、源索引及元数据复用会省略不可靠的新增 originalSource 并保留诊断,不因这项可选证据阻塞旧任务;跨 Run/组织错误与存储失败仍拒绝,已有冻结来源不追随新目录。真正生成或发布 v4 时,缺原始来源、标签或时间证据仍被打包/批次门禁拒绝,不能据此输出不完整 JSON。

回退旧 API 不是无损写入保证:新版本保存分类后,旧版本重建草稿数组可能丢弃字典快照。回退前应暂停相关写操作或准备能保留新字段的兼容回退版本;只保留恢复历史不等于能自动恢复所有后续修改。已交付不可变文件不因此原地迁移或覆盖。

2026-10-22 启用决定(在途任务范围已由 2026-11-08 修订替代)

用户随后确认启用 v4,范围仅为切换后新启动的工作流;在途任务、它们后续的审核/打包子运行和已交付文件继续原协议。此决定替代上节“继续保持关闭”的准备范围,不代表生产开关已经启用。实际发布仍需完成镜像、兼容性和目标核对,并审查具体部署及工作流切换计划。

用户明确确认当前无 tags 的启用词条以词条名称作为第一个独立 tags 标签。该初始化是一次有界字典变更:保留词条 ID、名称、用途、category、aliases 和既有历史,递增版本并记录新修订;已有非空 tags 不覆盖。历史任务中的冻结快照不因此重写,亦不反查新词条替代历史分类。后续 tags 仍由管理员维护。

新工作流使用新的定义版本及固定打包镜像。旧定义不原地改参数或镜像;切换必须保留已启动采集的原工作流归属,并阻止新监听器重新接入这些目录。新 v4 接入还需完整的原始文件选择,包含采集 meta;旧协议保留原有接入要求。准备与验收步骤见 启用核对表。

2026-11-08 旧任务交付修订

用户进一步要求不再新生成旧格式交付包。同一组织、项目和版本家族已启用 V4 时,旧任务后续放行也冻结兼容的 V4 打包配置;原工作流、人工任务归属和已验收内容不变。执行、重试与重启沿用冻结镜像及参数。无法证明原始来源、冻结字典、标签和时间证据时停在明确失败状态,先恢复证据,不回退旧格式。

已完整发布的旧文件仅允许校验完成清单、成员哈希和归属后只读恢复状态;缺失或冲突的旧上传不得继续补发。转换生成独立候选或新交付批次,不覆盖旧完成清单。线上替换、历史证据恢复和新批次正式发布需要分别验证;本地转换通过不代表全部历史包可正式交付。