# Human Loop Core 与 Annotation QA 插件 ## 定位 平台通过两个编译期可信模块提供人工闭环能力: - `human-loop-core` 是系统插件,提供 HumanBatch、HumanItem、阶段 Attempt、追加事件、乐观锁和工作流挂起/恢复。 - `annotation-qa` 是组织级可选插件,提供切分标注、语义标注、人工质检、验收、供应商隔离、模板和 Viewer Adapter。 普通训练、自动驾驶、扫描等工作流在不包含人工节点时不会获得标注标签,也不会加载 Annotation QA 页面代码。 ## 为什么工作流保持 DAG 工作流画布禁止有向环并返回 `workflow_graph_cycle`。人工驳回不是重新执行已经完成的 DAG 节点,而是让一条 HumanItem 创建新的 StageAttempt 和 Revision: ```text split_annotation -> semantic_annotation -> quality_review ^ ^ | +------- reject target / rework --------+ DeliveryPackage -> acceptance HumanItem -> approved final export / rejected area ``` 驳回必须携带原因码、说明和目标阶段。默认最多返工 5 轮,超限进入 `escalated`,不会静默交付。 ## 数据处理粒度 - 数据集或 Run 形成 HumanBatch。 - 每个 Clip、Episode 或 Artifact 形成独立 HumanItem。 - 每个阶段进入 `ready` 时清空领取人;人工逐条领取、保存、提交和审核,阶段切换后重新进入待领取池。 - 已验收条目最多 32 条或等待 60 秒形成一个 ReleasePartition。 - ReleasePartition 通过带唯一键的 Outbox 创建 `human_release` 子 Run,从 Gate 下游继续执行。 `all_accepted` 兼容旧 Gate;新配置默认使用 `accepted_partition`,避免一个返工条目阻塞全部已通过数据。 ## 插件与深链 组织管理员在系统配置中启用 Annotation QA。服务端根据工作流节点派生以下 capability,客户端不能手工伪造: - `human_annotation` - `human_quality_review` - `human_acceptance` 项目卡片、编辑器和运行监控显示对应标签,分别进入: ```text /plugins/annotation-qa/workflows/:workflowId/annotate /plugins/annotation-qa/workflows/:workflowId/quality /plugins/annotation-qa/workflows/:workflowId/acceptance /plugins/annotation-qa/items/:itemId ``` ## API 核心接口: ```text GET /api/plugins GET /api/organizations/:id/plugins/:pluginId PUT /api/organizations/:id/plugins/:pluginId GET /api/human-batches GET /api/human-items GET /api/human-items?pool=available|mine|all GET /api/human-items/:id GET /api/human-items/:id/subject-content POST /api/human-items/:id/claim POST /api/human-items/:id/release POST /api/human-items/:id/submissions POST /api/human-items/:id/decisions GET /api/human-items/:id/events ``` Annotation QA 新接口位于 `/api/plugins/annotation-qa/*`。原 `/api/annotation-*` 在一个兼容周期内保留,并返回 `Deprecation`、`Sunset` 和 successor `Link` 响应头。 ## 历史数据与审计 插件首次启用时幂等迁移既有 AnnotationTask。HumanItem 保留 `legacyTaskId`,并继承 Revision、作者、工作组、供应商和当前状态;历史 `assignedUserId` 会转换为已领取状态,新任务不预分配。所有后续 created、claimed、released、submitted、approved、rejected、escalated 事件只追加不覆盖。 普通成员只能读取 `available` 和 `mine`;`all` 仅管理员可用。领取使用 `version` 乐观锁,竞争失败返回 `409 version_conflict`。领取者可在提交前释放,管理员可强制释放,不设置自动超时。 返工 Revision 的 `CountsAsOutput=false`,因此修改被打回数据不会重复计入正式产出。 ## Rerun 边界 Rerun 是可选 Viewer Adapter。`.rrd` Artifact 使用统一鉴权 Content 路由,前端先校验 `RRF2` 文件头;SDK 不可用或文件无效时回退到原始视频、文件信息和下载入口,标注与审核状态不受影响。