chore: checkpoint 第一版

openapi/openapi.yaml

@@ -1,8 +1,8 @@
 openapi: 3.1.0
 info:
   title: 数据采集终端—云端系统 API
-  version: 0.73.0
-  description: 工程框架、SaaS核心业务、设备v2能力协商与智能体启动状态查询、首次通话就绪与最低固件门禁、背景资料准备失败闭环、活动通话授权撤回安全停止、语音内容闭环、终端终稿补传、批量设备遥测、录音上传队列、隐私对账、固件、双轨录音、状态事件、具体资源分享、受控运营配置、Agent组合组件引用、质量证据门禁、运营自定义版本族投放、新通话运行时冻结与供应商启动传递、带并发版本校验的配置投放暂停恢复、带严重度和验收证据门禁的联调问题闭环、含阻断告警定位、当前主机健康及生产部署标记、实际应用环境、身份服务模式、异地备份、外部告警与模拟服务强制条件的发布候选技术验收快照、绑定候选版本与构建摘要并按业务时区生成的可审计试点日/周运行证据、可审计且不生成正式告警的接收器联通测试、外部依赖预检台账、证书到期清单，以及带价格版本冻结、供应商用量去重和硬额度控制的费用治理接口。
+  version: 0.77.0
+  description: 工程框架、SaaS核心业务、设备v2 RTC/VoiceChat兼容链路、设备v3火山硬件对话智能体控制面、每次会话人设与授权记忆冻结、SDK和音频能力门禁、动态配置生效证明、可靠设备事件和终稿补传、通话中受控记忆工具、首次通话就绪与最低固件门禁、背景资料准备失败闭环、活动通话授权撤回安全停止、语音内容闭环、批量设备遥测、录音上传队列、隐私对账、固件、双轨录音、状态事件、具体资源分享、受控运营配置、Agent组合组件引用、质量证据门禁、运营自定义版本族投放、新通话运行时冻结与供应商启动传递、带并发版本校验的配置投放暂停恢复、带严重度和验收证据门禁的联调问题闭环、含阻断告警定位、当前主机健康及生产部署标记、实际应用环境、身份服务模式、异地备份、外部告警与模拟服务强制条件的发布候选技术验收快照、绑定候选版本与构建摘要并按业务时区生成的可审计试点日/周运行证据、可审计且不生成正式告警的接收器联通测试、外部依赖预检台账、证书到期清单，以及带价格版本冻结、供应商用量去重和硬额度控制的费用治理接口。
 servers:
   - url: http://localhost:58080
     description: 本地开发
@@ -1474,6 +1474,163 @@ paths:
         '409':
           description: 绑定码无效、过期、撤销、用于其他目标，或设备已有有效绑定
           content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } }
+  /api/v1/ops/firmware-signing-keys:
+    get:
+      operationId: listOpsFirmwareSigningKeys
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 维护端查询租户固件可信公钥台账, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareSigningKeyListResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+    post:
+      operationId: registerOpsFirmwareSigningKey
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RegisterFirmwareSigningKeyRequest' } } } }
+      responses:
+        '201': { description: 维护端已登记可信Ed25519公钥 }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-signing-keys/revoke:
+    post:
+      operationId: revokeOpsFirmwareSigningKey
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RevokeFirmwareSigningKeyRequest' } } } }
+      responses:
+        '200': { description: 固件签名公钥已吊销, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareSigningKeyResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-releases:
+    get:
+      operationId: listOpsFirmwareReleases
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters:
+        - $ref: '#/components/parameters/RequiredTenantSelectionHeader'
+        - { name: model, in: query, required: false, schema: { type: string, maxLength: 120 } }
+        - { name: status, in: query, required: false, schema: { type: string, enum: [UPLOADING, READY, PAUSED, RETIRED] } }
+      responses:
+        '200': { description: 查询租户内维护端和历史家庭端固件版本, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareReleaseListResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+    post:
+      operationId: prepareOpsFirmwareRelease
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PrepareOpsFirmwareReleaseRequest' } } } }
+      responses:
+        '201': { description: 创建租户级UPLOADING版本并返回15分钟私有上传地址, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareReleaseResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-releases/{id}/upload-session:
+    post:
+      operationId: renewOpsFirmwareUpload
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/ResourceID' }, { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 重新签发维护端私有上传地址, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareReleaseResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-releases/{id}/finalize:
+    post:
+      operationId: finalizeOpsFirmwareRelease
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/ResourceID' }, { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 大小、SHA-256和Ed25519签名通过后正式发布, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareReleaseResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-releases/{id}/pause:
+    post:
+      operationId: pauseOpsFirmwareRelease
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/ResourceID' }, { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 暂停版本、关联运行批次和未投递命令, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareReleaseResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-releases/{id}/resume:
+    post:
+      operationId: resumeOpsFirmwareRelease
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/ResourceID' }, { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 在签名公钥仍活动时恢复版本分发, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareReleaseResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-releases/{id}/retire:
+    post:
+      operationId: retireOpsFirmwareRelease
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/ResourceID' }, { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 退役固件版本并保留已验证制品和审计历史, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareReleaseResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-releases/{id}/download:
+    get:
+      operationId: downloadOpsFirmwareRelease
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/ResourceID' }, { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 返回短期私有下载地址、摘要和签名元数据, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareDownloadResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-rollouts:
+    get:
+      operationId: listOpsFirmwareRollouts
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 返回租户最近OTA升级批次和结果汇总, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareRolloutListResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+    post:
+      operationId: startOpsFirmwareRollout
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/StartFirmwareRolloutRequest' } } } }
+      responses:
+        '202': { description: 兼容设备按稳定哈希进入OTA升级批次并生成可靠命令, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareRolloutResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/ops/firmware-rollouts/{id}:
+    get:
+      operationId: getOpsFirmwareRollout
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/ResourceID' }, { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 返回批次及逐设备升级进度, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareRolloutResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '404': { $ref: '#/components/responses/NotFoundError' }
+  /api/v1/ops/firmware-rollouts/{id}/pause:
+    post:
+      operationId: pauseOpsFirmwareRollout
+      tags: [operations, firmware]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/ResourceID' }, { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 暂停OTA批次并取消未投递升级命令, content: { application/json: { schema: { $ref: '#/components/schemas/FirmwareRolloutResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
   /api/v1/ops/devices:
     get:
       operationId: listOpsDevices
@@ -1563,6 +1720,33 @@ paths:
         '403': { $ref: '#/components/responses/AccessDeniedError' }
         '404': { description: 设备不存在, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
         '409': { description: 设备已绑定、已隔离或已吊销, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+  /api/v1/ops/devices/{id}/activation-transitions:
+    parameters:
+      - { $ref: '#/components/parameters/ResourceID' }
+      - { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }
+    post:
+      operationId: transitionOpsDeviceActivation
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      description: 执行受控激活状态迁移。认领到BOUND、火山凭据下发到ACTIVE和删除到REVOKED由对应业务接口自动完成；本接口用于出厂放行、开始预配、标记丢失及恢复。
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeviceActivationTransitionRequest' } } } }
+      responses:
+        '200': { description: 激活状态已迁移, content: { application/json: { schema: { $ref: '#/components/schemas/OpsDeviceResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '404': { $ref: '#/components/responses/NotFoundError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+    get:
+      operationId: listOpsDeviceActivationTransitions
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      description: 按激活修订号倒序返回设备完整激活迁移审计，不包含任何平台或火山密钥。
+      responses:
+        '200': { description: 激活迁移历史, content: { application/json: { schema: { $ref: '#/components/schemas/DeviceActivationTransitionListResponse' } } } }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '404': { $ref: '#/components/responses/NotFoundError' }
   /api/v1/devices:
     get:
       operationId: listManagedDevices
@@ -2620,6 +2804,120 @@ paths:
         '503':
           description: 遥测服务暂时不可用
           content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } }
+  /device/v3/hardware-agent-credentials:provision:
+    post:
+      operationId: provisionHardwareAgentCredential
+      tags: [device, conversation]
+      description: 平台使用托管的Product Secret代设备完成火山动态注册，仅向已认证设备返回其一机一密Device Secret。响应禁止缓存，Product Secret永不下发设备。
+      security: [{ deviceSignature: [] }]
+      parameters:
+        - $ref: '#/components/parameters/DeviceIdHeader'
+        - $ref: '#/components/parameters/DeviceTimestampHeader'
+        - $ref: '#/components/parameters/DeviceNonceHeader'
+        - $ref: '#/components/parameters/DeviceContentDigestHeader'
+        - $ref: '#/components/parameters/DeviceSignatureHeader'
+        - $ref: '#/components/parameters/IdempotencyKeyHeader'
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/HardwareAgentCredentialProvisionRequest' } } } }
+      responses:
+        '200':
+          description: 已返回当前设备的一机一密；响应包含Cache-Control no-store
+          headers:
+            Cache-Control: { schema: { type: string, const: no-store } }
+          content: { application/json: { schema: { $ref: '#/components/schemas/HardwareAgentCredentialProvisionResponse' } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { description: 设备身份验证失败 }
+        '409': { description: 缺少硬件智能体绑定，或产品、Hardware ID与既有凭据冲突 }
+        '503': { description: 平台注册服务未配置或火山动态注册暂时失败 }
+  /device/v3/factory-reset:
+    post:
+      operationId: factoryResetDevice
+      tags: [device]
+      description: 设备在本机物理确认后请求恢复出厂。平台结束残留会话、解除用户绑定、将旧用户侧状态置为离线并推送device.binding.reset事件、暂停火山设备凭据、保留火山License、撤销旧绑定码并返回新的绑定码。平台设备身份和HMAC密钥保持不变。
+      security: [{ deviceSignature: [] }]
+      parameters:
+        - $ref: '#/components/parameters/DeviceIdHeader'
+        - $ref: '#/components/parameters/DeviceTimestampHeader'
+        - $ref: '#/components/parameters/DeviceNonceHeader'
+        - $ref: '#/components/parameters/DeviceContentDigestHeader'
+        - $ref: '#/components/parameters/DeviceSignatureHeader'
+        - $ref: '#/components/parameters/IdempotencyKeyHeader'
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeviceFactoryResetRequest' } } } }
+      responses:
+        '200':
+          description: 设备已恢复为CLAIMABLE并签发新绑定码
+          headers:
+            Cache-Control: { schema: { type: string, const: no-store } }
+            Idempotency-Replayed: { schema: { type: string, enum: ['true'] }, description: 仅在返回同一重置请求的原结果时出现。 }
+          content: { application/json: { schema: { $ref: '#/components/schemas/DeviceFactoryResetResponse' } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { description: 设备身份验证失败 }
+        '409': { description: 存在未上传聊天记录、正在进行固件升级、重置计数器过期、设备状态冲突或幂等键冲突 }
+        '503': { description: 恢复出厂暂时失败 }
+  /device/v3/agent-sessions:
+    post:
+      operationId: createHardwareAgentSession
+      tags: [device, conversation]
+      description: 设备在连接火山硬件对话智能体前调用。平台冻结本次授权、人设、近期摘要及长期记忆，并返回一次性会话参数；音频随后由设备直连供应商。
+      security: [{ deviceSignature: [] }]
+      parameters:
+        - $ref: '#/components/parameters/DeviceIdHeader'
+        - $ref: '#/components/parameters/DeviceTimestampHeader'
+        - $ref: '#/components/parameters/DeviceNonceHeader'
+        - $ref: '#/components/parameters/DeviceContentDigestHeader'
+        - $ref: '#/components/parameters/DeviceSignatureHeader'
+        - $ref: '#/components/parameters/IdempotencyKeyHeader'
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/HardwareAgentCreateRequest' } } } }
+      responses:
+        '201': { description: 硬件智能体会话配置已冻结, content: { application/json: { schema: { $ref: '#/components/schemas/HardwareAgentCreateResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { description: 设备身份验证失败 }
+        '403': { description: 缺少语音通话授权 }
+        '409': { description: 配置版本过期、设备已有活动通话或幂等冲突 }
+        '429': { description: 用量额度不足 }
+        '503': { description: 运行配置或服务暂时不可用 }
+  /device/v3/agent-sessions/{id}/events:
+    post:
+      operationId: submitHardwareAgentEvent
+      tags: [device, conversation]
+      description: 设备上报硬件智能体开始、存活、结束或失败事件；session_nonce仅保存在设备运行内存，用于阻止跨会话伪造。
+      security: [{ deviceSignature: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
+        - $ref: '#/components/parameters/DeviceIdHeader'
+        - $ref: '#/components/parameters/DeviceTimestampHeader'
+        - $ref: '#/components/parameters/DeviceNonceHeader'
+        - $ref: '#/components/parameters/DeviceContentDigestHeader'
+        - $ref: '#/components/parameters/DeviceSignatureHeader'
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/HardwareAgentEventRequest' } } } }
+      responses:
+        '200': { description: 事件已处理, content: { application/json: { schema: { $ref: '#/components/schemas/HardwareAgentEventResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { description: 设备身份或会话证明失败 }
+        '404': { description: 会话不存在 }
+        '409': { description: 事件重放内容或状态机冲突 }
+        '503': { description: 事件处理暂时不可用 }
+  /device/v3/agent-sessions/{id}/turns:batch:
+    post:
+      operationId: submitHardwareAgentConversationTurns
+      tags: [device, conversation]
+      description: 硬件智能体设备可靠补传最终话轮。与v2同构，按turn_key和sequence_no原子去重；增量字幕不得上传。
+      security: [{ deviceSignature: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
+        - $ref: '#/components/parameters/DeviceIdHeader'
+        - $ref: '#/components/parameters/DeviceTimestampHeader'
+        - $ref: '#/components/parameters/DeviceNonceHeader'
+        - $ref: '#/components/parameters/DeviceContentDigestHeader'
+        - $ref: '#/components/parameters/DeviceSignatureHeader'
+        - $ref: '#/components/parameters/IdempotencyKeyHeader'
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeviceTranscriptBatchRequest' } } } }
+      responses:
+        '200': { description: 最终话轮已合并, content: { application/json: { schema: { $ref: '#/components/schemas/DeviceTranscriptBatchResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { description: 设备身份验证失败 }
+        '403': { description: 当前设备或授权不允许写入 }
+        '404': { description: 会话不存在 }
+        '409': { description: 幂等键或话轮内容冲突 }
   /device/v2/conversations/{id}:
     get:
       operationId: getDeviceConversationState
@@ -4600,7 +4898,7 @@ components:
       required: [id, type, household_id, resource_type, resource_id, status, occurred_at]
       properties:
         id: { type: integer, format: int64 }
-        type: { type: string, enum: [device.presence.changed, conversation.started, conversation.completed, conversation.failed, story.created, story.revised, media.upload.completed, export.ready, privacy_request.updated, device.command.updated] }
+        type: { type: string, enum: [device.presence.changed, device.binding.reset, conversation.started, conversation.completed, conversation.failed, story.created, story.revised, media.upload.completed, export.ready, privacy_request.updated, device.command.updated] }
         household_id: { type: string, format: uuid }
         resource_type: { type: string }
         resource_id: { type: string, format: uuid }
@@ -4973,13 +5271,17 @@ components:
     OpsDevice:
       type: object
       additionalProperties: false
-      required: [id, tenant_id, model, status, credential_status, key_version, registered_at, updated_at, version]
+      required: [id, tenant_id, model, status, activation_state, activation_revision, activation_updated_at, credential_status, key_version, registered_at, updated_at, version, voice_runtime]
       properties:
         id: { type: string, format: uuid }
         tenant_id: { type: string, format: uuid }
         model: { type: string, minLength: 1, maxLength: 120 }
         hardware_revision: { type: string, maxLength: 80 }
         status: { type: string, enum: [registered, quarantined, revoked] }
+        activation_state: { $ref: '#/components/schemas/DeviceActivationState' }
+        activation_revision: { type: integer, format: int64, minimum: 1, description: 激活状态乐观并发版本。 }
+        activation_reason: { type: string, maxLength: 500 }
+        activation_updated_at: { type: string, format: date-time }
         minimum_security_version: { type: string, maxLength: 80 }
         minimum_firmware_version: { type: string, maxLength: 80 }
         household_id: { type: string, format: uuid }
@@ -4988,10 +5290,16 @@ components:
         subject_name: { type: string }
         credential_status: { type: string, enum: [active, revoked, missing] }
         key_version: { type: integer, format: int64, minimum: 0 }
+        firmware_version: { type: string, maxLength: 80, description: 设备最近一次上报的当前固件版本。 }
         last_reported_at: { type: string, format: date-time }
         registered_at: { type: string, format: date-time }
         updated_at: { type: string, format: date-time }
         version: { type: integer, format: int64, minimum: 1 }
+        voice_runtime: { type: string, enum: [legacy_voicechat, volc_hardware_agent] }
+        hardware_agent_bot_id: { type: string, maxLength: 200 }
+        hardware_agent_transport: { type: string, enum: [high_quality, low_load] }
+        hardware_agent_minimum_sdk_version: { type: string, maxLength: 80 }
+        hardware_agent_status: { type: string, enum: [ACTIVE, DISABLED, REVOKED] }
     OpsDeviceAssignmentOption:
       type: object
       additionalProperties: false
@@ -5012,6 +5320,8 @@ components:
         minimum_firmware_version: { type: string, maxLength: 80 }
         household_id: { type: string, format: uuid }
         subject_id: { type: string, format: uuid }
+        voice_runtime: { type: string, enum: [legacy_voicechat, volc_hardware_agent] }
+        activation_state: { type: string, enum: [FACTORY, CLAIMABLE, BOUND], description: 可选。未指定时，有归属为BOUND，无归属为CLAIMABLE；FACTORY仅允许未分配设备。 }
     UpdateOpsDeviceRequest:
       type: object
       additionalProperties: false
@@ -5024,6 +5334,43 @@ components:
         status: { type: string, enum: [registered, quarantined] }
         household_id: { type: string, format: uuid }
         subject_id: { type: string, format: uuid }
+        voice_runtime: { type: string, enum: [legacy_voicechat, volc_hardware_agent] }
+    DeviceActivationState:
+      type: string
+      enum: [FACTORY, CLAIMABLE, BOUND, PROVISIONING, ACTIVE, LOST, REVOKED]
+    DeviceActivationTransitionRequest:
+      type: object
+      additionalProperties: false
+      required: [target_state, reason, expected_revision]
+      properties:
+        target_state: { $ref: '#/components/schemas/DeviceActivationState' }
+        reason: { type: string, minLength: 1, maxLength: 500 }
+        expected_revision: { type: integer, format: int64, minimum: 1 }
+    DeviceActivationTransition:
+      type: object
+      additionalProperties: false
+      required: [id, to_state, reason, source, actor_type, activation_revision, created_at]
+      properties:
+        id: { type: string, format: uuid }
+        from_state: { $ref: '#/components/schemas/DeviceActivationState' }
+        to_state: { $ref: '#/components/schemas/DeviceActivationState' }
+        reason: { type: string }
+        source: { type: string }
+        actor_type: { type: string }
+        actor_public_id: { type: string, format: uuid }
+        request_id: { type: string }
+        activation_revision: { type: integer, format: int64, minimum: 1 }
+        created_at: { type: string, format: date-time }
+    DeviceActivationTransitionListResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data:
+          type: object
+          required: [items]
+          properties:
+            items: { type: array, items: { $ref: '#/components/schemas/DeviceActivationTransition' } }
     DeviceCredentialIssue:
       type: object
       additionalProperties: false
@@ -5379,12 +5726,29 @@ components:
         signing_key_id: { type: string, minLength: 1, maxLength: 120 }
         minimum_security_version: { type: string, maxLength: 80 }
         release_notes: { type: string, maxLength: 2000 }
+    PrepareOpsFirmwareReleaseRequest:
+      type: object
+      additionalProperties: false
+      required: [model, version, expected_size, expected_digest, signature, signing_key_id]
+      properties:
+        model: { type: string, minLength: 1, maxLength: 120 }
+        hardware_revision: { type: string, maxLength: 80 }
+        version: { type: string, minLength: 1, maxLength: 80 }
+        expected_size: { type: integer, format: int64, minimum: 1, maximum: 268435456 }
+        expected_digest: { type: string, pattern: '^[0-9a-f]{64}$' }
+        signature: { type: string, description: 对firmware-manifest-v1规范文本的Ed25519签名Base64 }
+        signing_key_id: { type: string, minLength: 1, maxLength: 120 }
+        minimum_security_version: { type: string, maxLength: 80 }
+        release_notes: { type: string, maxLength: 2000 }
+        release_channel: { type: string, enum: [STABLE, BETA, INTERNAL], default: STABLE }
+        mandatory: { type: boolean, default: false }
     FirmwareRelease:
       type: object
       additionalProperties: false
-      required: [id, model, version, expected_size, expected_digest, signature_algorithm, signature, signing_key_id, status, created_at, updated_at]
+      required: [id, model, version, expected_size, expected_digest, signature_algorithm, signature, signing_key_id, release_channel, mandatory, created_source, status, created_at, updated_at]
       properties:
         id: { type: string, format: uuid }
+        household_id: { type: string, format: uuid, description: 家庭端历史版本存在；维护端租户级版本为空。 }
         model: { type: string }
         hardware_revision: { type: string }
         version: { type: string }
@@ -5395,12 +5759,35 @@ components:
         signing_key_id: { type: string }
         minimum_security_version: { type: string }
         release_notes: { type: string }
+        release_channel: { type: string, enum: [STABLE, BETA, INTERNAL] }
+        mandatory: { type: boolean }
+        published_at: { type: string, format: date-time }
+        created_source: { type: string, enum: [CUSTOMER, OPS] }
         status: { type: string, enum: [UPLOADING, READY, PAUSED, RETIRED] }
         verified_at: { type: string, format: date-time }
         created_at: { type: string, format: date-time }
         updated_at: { type: string, format: date-time }
         upload_url: { type: string, format: uri, description: 仅创建响应返回的短期私有PUT地址 }
         upload_until: { type: string, format: date-time }
+    FirmwareDownload:
+      type: object
+      additionalProperties: false
+      required: [release_id, version, size, sha256, signature, signing_key_id, download_url, expires_at]
+      properties:
+        release_id: { type: string, format: uuid }
+        version: { type: string }
+        size: { type: integer, format: int64 }
+        sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
+        signature: { type: string }
+        signing_key_id: { type: string }
+        download_url: { type: string, format: uri }
+        expires_at: { type: string, format: date-time }
+    FirmwareDownloadResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/FirmwareDownload' }
     FirmwareReleaseImpact:
       type: object
       additionalProperties: false
@@ -5560,12 +5947,13 @@ components:
     ConversationSummary:
       type: object
       additionalProperties: false
-      required: [id, subject_id, device_id, status, engine_mode, retention_mode, audio_retention_enabled, created_at, updated_at]
+      required: [id, subject_id, device_id, status, runtime_type, engine_mode, retention_mode, audio_retention_enabled, created_at, updated_at]
       properties:
         id: { type: string, format: uuid }
         subject_id: { type: string, format: uuid }
         device_id: { type: string, format: uuid }
         status: { $ref: '#/components/schemas/ConversationStatus' }
+        runtime_type: { type: string, enum: [legacy_voicechat, volc_hardware_agent] }
         engine_mode: { type: string, enum: [s2s_pure, s2s_hybrid, cascade] }
         retention_mode: { type: string, enum: [none, transcript_only, transcript_and_audio] }
         audio_retention_enabled:
@@ -5611,6 +5999,18 @@ components:
         start_attempts: { type: integer, minimum: 0 }
         stop_attempts: { type: integer, minimum: 0 }
         last_checked_at: { type: string, format: date-time }
+    HardwareAgentTaskSummary:
+      type: object
+      additionalProperties: false
+      required: [provider, status, transport, last_event_sequence]
+      properties:
+        provider: { type: string, const: volcengine }
+        status: { type: string, enum: [READY, STARTING, ACTIVE, STOPPING, COMPLETED, FAILED, EXPIRED] }
+        transport: { type: string, enum: [high_quality, low_load] }
+        provider_started_at: { type: string, format: date-time }
+        provider_ended_at: { type: string, format: date-time }
+        last_event_at: { type: string, format: date-time }
+        last_event_sequence: { type: integer, format: int64, minimum: 0 }
     ConversationDetail:
       allOf:
         - $ref: '#/components/schemas/ConversationSummary'
@@ -5620,6 +6020,7 @@ components:
             household_id: { type: string, format: uuid }
             snapshots: { $ref: '#/components/schemas/ConversationSnapshotSummary' }
             rtc: { $ref: '#/components/schemas/RTCTaskSummary', description: 背景资料准备失败且未创建房间时省略。 }
+            hardware_agent: { $ref: '#/components/schemas/HardwareAgentTaskSummary', description: 火山硬件对话智能体运行时详情；传统RTC通话省略。 }
             history:
               type: array
               items: { $ref: '#/components/schemas/ConversationStateEntry' }
@@ -6051,6 +6452,149 @@ components:
         capabilities: { $ref: '#/components/schemas/DeviceCapabilities' }
         network: { $ref: '#/components/schemas/DeviceNetwork' }
         requested_goal: { type: string, const: open_conversation }
+    HardwareAgentCredentialProvisionRequest:
+      type: object
+      additionalProperties: false
+      required: [hardware_id]
+      properties:
+        hardware_id: { type: string, minLength: 1, maxLength: 200, pattern: '^[a-zA-Z0-9_\-.:@]+$' }
+    HardwareAgentProviderCredential:
+      type: object
+      required: [instance_id, product_key, device_name, hardware_id, device_secret, credential_ref, credential_version, credential_source, issued_at]
+      properties:
+        instance_id: { type: string, maxLength: 200 }
+        product_key: { type: string, maxLength: 200 }
+        device_name: { type: string, maxLength: 128 }
+        hardware_id: { type: string, maxLength: 200 }
+        device_secret: { type: string, writeOnly: true, description: 火山一机一密，仅在设备签名认证和no-store响应中返回；不得记录或上传。 }
+        credential_ref: { type: string, description: 非秘密的平台凭据引用。 }
+        credential_version: { type: integer, format: int64, minimum: 1 }
+        credential_source: { type: string, enum: [platform_dynamic_registration, platform_stored] }
+        issued_at: { type: string, format: date-time }
+    DeviceFactoryResetRequest:
+      type: object
+      additionalProperties: false
+      required: [reset_id, reset_counter, occurred_at, trigger, firmware_version, pending_turn_count]
+      properties:
+        reset_id: { type: string, format: uuid, description: 本次恢复出厂操作的唯一编号。 }
+        reset_counter: { type: integer, format: int64, minimum: 1, description: 设备安全存储中的单调递增重置计数器。 }
+        occurred_at: { type: string, format: date-time, description: 设备确认恢复出厂的UTC时间，不得晚于请求时间5分钟。 }
+        trigger: { type: string, enum: [physical_long_press, device_menu, service_tool] }
+        firmware_version: { type: string, minLength: 1, maxLength: 80 }
+        pending_turn_count: { type: integer, minimum: 0, description: 必须为0；设备应先补传最终聊天记录。 }
+        active_conversation_id: { type: string, format: uuid }
+    DeviceFactoryResetClaim:
+      type: object
+      additionalProperties: false
+      required: [code, issued_at, expires_at]
+      properties:
+        code: { type: string, minLength: 16, maxLength: 128, writeOnly: true }
+        issued_at: { type: string, format: date-time }
+        expires_at: { type: string, format: date-time }
+    DeviceFactoryResetResult:
+      type: object
+      additionalProperties: false
+      required: [reset_id, device_id, activation_state, reset_counter, binding_removed, provider_credential_status, license_action, ended_conversation_count, cancelled_command_count, config_revision, claim, local_actions, reset_at]
+      properties:
+        reset_id: { type: string, format: uuid }
+        device_id: { type: string, format: uuid }
+        activation_state: { type: string, const: CLAIMABLE }
+        reset_counter: { type: integer, format: int64, minimum: 1 }
+        binding_removed: { type: boolean }
+        previous_binding_id: { type: string, format: uuid }
+        provider_credential_status: { type: string, enum: [SUSPENDED, REVOKED, NOT_PROVISIONED] }
+        license_action: { type: string, const: RETAINED, description: 恢复出厂不释放火山License，避免同一硬件重新绑定时重复消耗额度。 }
+        ended_conversation_count: { type: integer, minimum: 0 }
+        cancelled_command_count: { type: integer, format: int64, minimum: 0 }
+        config_revision: { type: integer, format: int64, minimum: 1 }
+        claim: { $ref: '#/components/schemas/DeviceFactoryResetClaim' }
+        local_actions:
+          type: array
+          items: { type: string, enum: [clear_volc_credential, clear_user_context, clear_session_state, clear_network_credentials, reboot_to_claimable] }
+        reset_at: { type: string, format: date-time }
+    HardwareAgentCreateRequest:
+      type: object
+      additionalProperties: false
+      required: [device_time, capabilities, network, requested_goal, config_revision]
+      properties:
+        device_time: { type: string, format: date-time }
+        monotonic_ms: { type: integer, format: int64, minimum: 0 }
+        config_revision: { type: integer, format: int64, minimum: 1 }
+        capabilities:
+          type: object
+          additionalProperties: false
+          required: [hardware_agent, sdk_version, transports, input_audio_format, output_audio_format, server_event_callback, transcript_upload, dynamic_session_config, credential_rotation, near_pcm_recording, far_pcm_recording]
+          properties:
+            hardware_agent: { type: boolean, const: true }
+            sdk_version: { type: string, minLength: 1, maxLength: 80 }
+            transports: { type: array, minItems: 1, uniqueItems: true, items: { type: string, enum: [high_quality, low_load] } }
+            input_audio_format: { type: string, minLength: 1, maxLength: 80 }
+            output_audio_format: { type: string, minLength: 1, maxLength: 80 }
+            server_event_callback: { type: boolean }
+            transcript_upload: { type: boolean, const: true }
+            dynamic_session_config: { type: boolean, const: true }
+            credential_rotation: { type: boolean, const: true }
+            near_pcm_recording: { type: boolean }
+            far_pcm_recording: { type: boolean }
+        network: { $ref: '#/components/schemas/DeviceNetwork' }
+        requested_goal: { type: string, const: open_conversation }
+    HardwareAgentSession:
+      type: object
+      required: [conversation_id, status, runtime_type, runtime, session_config, privacy, session]
+      properties:
+        conversation_id: { type: string, format: uuid }
+        status: { type: string, const: SESSION_READY }
+        runtime_type: { type: string, const: volc_hardware_agent }
+        runtime:
+          type: object
+          required: [provider, bot_id, transport, provider_session_ref, session_nonce, config_digest, wait_for_session_update]
+          properties:
+            provider: { type: string, const: volcengine }
+            bot_id: { type: string }
+            transport: { type: string, enum: [high_quality, low_load] }
+            provider_session_ref: { type: string }
+            session_nonce: { type: string, description: 仅保存在设备运行内存，事件上报时原样回传。 }
+            config_digest: { type: string, pattern: '^[0-9a-f]{64}$' }
+            wait_for_session_update: { type: boolean }
+        session_config:
+          type: object
+          required: [dialog_id, authorized_context, prompt_bundle_version]
+          properties:
+            dialog_id: { type: string, format: uuid }
+            system_prompt: { type: string }
+            persona_tone: { type: string }
+            authorized_context: { type: string, maxLength: 1000 }
+            prompt_bundle_version: { type: string }
+            tool_url: { type: string, format: uri, description: 平台受控记忆工具地址；未启用时省略。 }
+            tool_scope_token: { type: string, description: 仅绑定本次通话和运行时会话引用的短期令牌；不得持久化。 }
+        privacy: { $ref: '#/components/schemas/ConversationPrivacy' }
+        session: { $ref: '#/components/schemas/ConversationSession' }
+    HardwareAgentEventRequest:
+      type: object
+      additionalProperties: false
+      required: [event_id, sequence_no, event_type, occurred_at, provider_session_ref, session_nonce]
+      properties:
+        event_id: { type: string, minLength: 1, maxLength: 255 }
+        sequence_no: { type: integer, format: int64, minimum: 1 }
+        event_type: { type: string, enum: [session_started, session_updated, session_ended, session_failed] }
+        occurred_at: { type: string, format: date-time }
+        provider_session_ref: { type: string }
+        session_nonce: { type: string }
+        provider_connection_ref: { type: string, maxLength: 200, description: 火山SDK实际返回的会话关联号；session_started时必填。 }
+        bot_id: { type: string, description: session_started时必填，必须匹配平台准备结果。 }
+        transport: { type: string, enum: [high_quality, low_load], description: session_started时必填。 }
+        config_digest: { type: string, pattern: '^[0-9a-f]{64}$', description: session_started时必填。 }
+        dynamic_config_applied: { type: boolean, description: session_started时必须为true，表示已收到session.updated。 }
+        error_code: { type: string, maxLength: 64 }
+    HardwareAgentEventResult:
+      type: object
+      required: [conversation_id, status, action, duplicate, accepted_at]
+      properties:
+        conversation_id: { type: string, format: uuid }
+        status: { $ref: '#/components/schemas/ConversationStatus' }
+        action: { type: string, enum: [continue, stop_session], description: 设备收到stop_session后必须立即断开火山会话，并补报session_ended或session_failed。 }
+        duplicate: { type: boolean }
+        accepted_at: { type: string, format: date-time }
     RTCGrant:
       type: object
       required: [app_id, room_id, user_id, agent_user_id, token, expires_at]
@@ -6849,6 +7393,30 @@ components:
       properties:
         request_id: { type: string }
         data: { $ref: '#/components/schemas/CreatedConversation' }
+    HardwareAgentCreateResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/HardwareAgentSession' }
+    HardwareAgentCredentialProvisionResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/HardwareAgentProviderCredential' }
+    DeviceFactoryResetResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/DeviceFactoryResetResult' }
+    HardwareAgentEventResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/HardwareAgentEventResult' }
     ActivateConversationResponse:
       type: object
       required: [request_id, data]