9.7 KiB
最终分类总 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 启用决定
用户随后确认启用 v4,范围仅为切换后新启动的工作流;在途任务、它们后续的审核/打包子运行和已交付文件继续原协议。此决定替代上节“继续保持关闭”的准备范围,不代表生产开关已经启用。实际发布仍需完成镜像、兼容性和目标核对,并审查具体部署及工作流切换计划。
用户明确确认当前无 tags 的启用词条以词条名称作为第一个独立 tags 标签。该初始化是一次有界字典变更:保留词条 ID、名称、用途、category、aliases 和既有历史,递增版本并记录新修订;已有非空 tags 不覆盖。历史任务中的冻结快照不因此重写,亦不反查新词条替代历史分类。后续 tags 仍由管理员维护。
新工作流使用新的定义版本及固定打包镜像。旧定义不原地改参数或镜像;切换必须保留已启动采集的原工作流归属,并阻止新监听器重新接入这些目录。新 v4 接入还需完整的原始文件选择,包含采集 meta;旧协议保留原有接入要求。准备与验收步骤见 启用核对表。