story/docs/火山硬件对话智能体迁移设计.md

火山硬件对话智能体迁移设计

状态：方案评审稿
适用基线：v0.70.0-rc.1
编制日期：2026-08-31

1. 结论

本次迁移建议采用“保留业务控制面，替换会话执行面”的方式，不对现有平台做推倒重建。

• 保留：设备身份与绑定、家庭和长者档案、授权、通话主记录、配置灰度、字幕存储、摘要/故事/事实候选、人工确认记忆、隐私导出删除、录音管理、费用额度、告警、诊断、固件和审计。
• 替换：设备领取 RTC Token、设备加入平台分配的 RTC 房间、平台 Worker 调用 StartVoiceChat/StopVoiceChat、Agent RTC 用户和 RTC Task 对账。
• 新增：火山产品/设备/Bot/License 映射、硬件智能体设备凭证生命周期、硬件会话适配器、动态会话配置、MCP/Function Calling 工具网关、硬件会话事件和用量归集。
• 兼容：旧 RTC VoiceChat 链路和新硬件智能体链路至少并行一个灰度周期，按设备能力位和灰度配置选择，不按固件版本猜测。

推荐终端优先采用火山硬件智能体“高质量方案”（UDP/RTC）。现有终端本身已有 RTC、弱网恢复和网络切换验收基础，和该方案的目标更一致。火山官方同时提供低负载 WebSocket 方案；只有在量产板的 RAM、CPU、功耗或网络实测不满足高质量 SDK 时，才切换到低负载方案。官方对比说明高质量方案弱网和实时互动更好，低负载方案资源消耗更低。火山官方 SDK 集成指引

2. 当前链路与目标链路

2.1 当前链路

设备 -> 平台创建通话 -> 平台签发 RTC Token -> 设备加入 RTC 房间
    -> 设备确认入房 -> Worker 调用 StartVoiceChat -> 豆包 Agent 入房
    -> 火山/设备回传字幕和状态 -> 平台存储与内容处理
    -> 设备或平台发起停止 -> Worker 调用 StopVoiceChat -> 通话终态

当前关键实现：

• /device/v2/conversations 创建通话并返回 RTC Grant；
• /activate 在设备入房后可靠投递 conversation.agent_start_requested；
• voiceprovider.VolcengineClient 把平台稳定任务契约映射为 StartVoiceChat/StopVoiceChat；
• RTC 房间、设备 RTC 用户、Agent RTC 用户和供应商 Task 是诊断主关联键；
• 最终字幕进入 conversation_turn，继续触发摘要、故事、事实和记忆流水线。

2.2 目标链路

设备 -> 平台准备硬件会话并冻结授权/配置/背景
    -> 设备使用火山硬件智能体 SDK 直连 Bot
    -> SDK 收发音频并提供字幕、状态、Function Calling 事件
    -> 设备把最终字幕和状态回传平台
    -> Bot 通过 MCP/Function Calling 访问平台受控记忆/业务工具
    -> 用户、平台或授权撤回触发停止 -> 设备关闭 SDK 会话 -> 平台收敛终态

火山硬件智能体的标准协议使用 product_key + device_name + device_secret 建立设备身份，连接时指定与产品关联的 bot。设备首次可通过 DynamicRegister 获取设备独享密钥；WebSocket 标准协议支持字幕事件、端侧 Function Calling、主动播报和文本提问。火山标准协议文档

3. 架构原则

3.1 平台数据库仍是业务事实唯一主库

火山侧负责实时对话执行，不成为家庭、长者、授权、记忆和费用策略的主数据源。平台必须保存每次会话实际使用的：

• 产品、设备、Bot 和 License 的脱敏引用；
• 平台路由版本、角色版本、声音版本、模型版本和提示词版本；
• 发送给火山的会话配置摘要及 SHA-256；
• 授权和背景资料冻结快照；
• 火山会话 ID、传输方案、状态时间线、字幕来源和用量来源。

3.2 设备必须先通过平台业务门禁，再连接智能体

设备拥有火山凭证不等于拥有业务授权。每次对话前仍必须先调用平台准备接口，由平台检查：

• 设备已登记、未隔离、未吊销并已绑定长者；
• 固件和硬件智能体 SDK 版本满足最低要求；
• voice_chat 授权有效；
• 客户组织、设备并发、时长和费用额度未超限；
• 角色、模型、音色和 Bot 路由已发布；
• 背景资料和记忆快照生成成功或按既定规则无记忆降级。

平台拒绝准备时，设备不得调用火山 SDK 建立对话。

3.3 不把长期记忆主库直接迁到火山

现有记忆包含人工确认、授权撤回、版本、来源、租户/长者隔离和隐私删除证明。迁移后继续使用平台 pgvector 和记忆工具：

• 会话启动时，把已授权的短背景摘要作为动态会话参数注入；
• 通话中通过平台 MCP/Function Calling 工具查询记忆；
• 工具令牌绑定 conversation_id + provider_session_id + device_id + subject_id，短期有效；
• 模型只能提交查询内容，不能自行指定租户或长者；
• 火山原生长期记忆只可作为可删除、可对账的派生缓存，不能成为主库。

火山硬件智能体产品能力包含 MCP、联网问答、长期记忆和设备管理，但这不改变本项目的业务数据权威边界。火山硬件智能体产品页

4. 功能迁移矩阵

现有功能	迁移方式	新责任边界	结论
设备 HMAC 身份、绑定、家庭归属	原样保留；新增火山设备映射	平台仍负责业务身份，火山凭证只负责智能体建连	保留并扩展
/bootstrap、配置、命令、遥测	原样保留，增加硬件智能体能力位和 SDK 信息	平台	保留
RTC 房间分配与 Token	新运行时不再使用	火山硬件 SDK 自行建连	新链路废弃
StartVoiceChat/StopVoiceChat	新运行时不再调用；旧链路继续兼容	设备 SDK / 火山硬件智能体	新链路废弃
s2s_pure/s2s_hybrid/cascade	不再作为设备会话模式；改为平台内部服务档位或 Bot/模型配置	平台路由 + 火山 Bot	重定义
角色、提示词、模型、音色灰度	平台继续版本化；基础配置同步 Bot，会话差异通过动态参数注入	平台为权威，火山为执行副本	保留并改造
欢迎语、主动播报	使用 Bot/会话配置；本地系统提示可用 input_tts	火山 SDK + 设备应用	迁移
背景资料冻结	准备会话时生成；等待 session.updated 后才开放麦克风	平台生成，设备注入	保留并改造
实时打断、VAD、ASR、TTS	使用火山硬件智能体原生能力	火山	下沉
最终字幕	设备监听最终事件，写入本地加密队列，批量调用现有 turns:batch	设备可靠上传，平台去重存储	保留并改造
字幕服务端回调	若火山提供则作为第二来源，按供应商事件 ID 去重	火山回调 + 平台	待商务/技术确认
摘要、开放话题、故事、事实候选	输入仍为平台最终话轮	平台 Worker	原样保留
人工确认记忆、向量检索	继续使用现有数据库和流程	平台	原样保留
通话中记忆工具	从 VoiceChat 模板 URL 改为 MCP/Function Calling 工具网关	平台工具网关	改造
设备音量、诊断等指令	云端命令链保留；安全的本地动作可同时暴露为端侧 FC	平台命令 + 设备白名单执行器	扩展
授权撤回停止	心跳返回 stop，设备关闭 SDK；必须补充服务端强制终止或凭证吊销	平台发令，火山/设备执行	关键改造
双轨录音	需验证 SDK 是否提供近端采集和远端解码 PCM 回调	设备录制 + 对象存储	有条件迁移
用量与费用	增加 License、AI 对话时长和模型用量来源；区分估算与账单	平台费用域	改造
诊断工作台	房间/Task 改为产品、设备、Bot、License、会话、传输和事件	平台	改造
配置灰度与回滚	增加 hardware_agent 运行时；按设备稳定分桶	平台	扩展
固件发布	SDK、License 兼容、产品信息和安全存储纳入固件门禁	平台 + 设备	扩展
隐私导出/删除	平台数据链路保留；新增火山会话历史/设备数据删除与凭证吊销对账	平台主导	扩展
发布候选验收	替换 RTC 三模式矩阵，新增硬件 SDK 真机矩阵	平台验收工具	改造

5. 终端改造

5.1 新增硬件智能体运行时模块

建议固件同时保留两个实现：

VoiceRuntime
├── LegacyRTCRuntime          现有 RTC + 平台 StartVoiceChat
└── VolcHardwareAgentRuntime  新硬件智能体 SDK

平台配置返回显式 voice_runtime：

{
  "voice_runtime": "volc_hardware_agent",
  "runtime_revision": 12,
  "transport": "high_quality",
  "minimum_sdk_version": "<现场冻结版本>"
}

设备只在完整校验配置后切换运行时；切换失败回退上一有效配置。不要根据 engine_mode 或固件版本自动推断。

5.2 凭证与激活

设备侧需要保存：

• 火山 instance_id、product_key、device_name；
• 动态注册换取的设备独享 device_secret；
• 当前凭证版本、注册时间和最后成功鉴权时间。

安全要求：

• product_secret只允许保存在平台KMS或Secret挂载中，不能进入设备固件、应用、安装包或设备日志；
• 设备使用平台设备身份调用/device/v3/hardware-agent-credentials:provision，由平台完成DynamicRegister并下发本设备的device_secret；
• device_secret 使用安全芯片、TEE 或设备密钥封装后持久化；
• 日志、遥测和崩溃转储不得输出任何 Secret 或完整签名；
• 必须验证设备 Secret 的轮换、吊销和售后换板流程。

5.3 会话状态机

建议复用现有通话状态：

PREPARING -> SESSION_READY -> STARTING_AGENT -> ACTIVE
          -> FAILED
ACTIVE -> STOPPING -> COMPLETED
                   -> FAILED

数据库可继续把 SESSION_READY 对外兼容映射为 ROOM_ISSUED，但新 /device/v3 契约应使用真实语义，不再暴露不存在的 RTC Room。

终端事件映射：

火山/SDK 事件	平台动作
SDK 初始化成功	更新遥测，不代表会话成功
session.created	保存火山会话标识，等待会话配置
session.updated	调用平台 activate，允许采集和播放
用户最终 ASR	写入本地可靠字幕队列
Agent 最终字幕	写入本地可靠字幕队列
Function Call	白名单校验后端侧执行，或转发平台工具网关
Agent 错误/断开	上报稳定错误码，按策略恢复或停止
正常关闭	调用平台 stop 并冲刷字幕、用量和录音队列

6. 平台接口设计

现有 /device/v2 的创建响应把 rtc 定义为必填对象。为了不破坏量产固件，建议新增 /device/v3/agent-sessions，不要修改 v2 字段语义。

6.1 准备会话

POST /device/v3/agent-sessions

请求沿用设备 HMAC 和幂等键，声明：

• capabilities.hardware_agent=true；
• SDK 版本、传输方案、音频格式；
• 是否支持字幕可靠队列、动态会话配置、凭证轮换、近/远端 PCM 录制；
• 网络和设备时间。

响应建议：

{
  "conversation_id": "...",
  "status": "SESSION_READY",
  "runtime": {
    "provider": "volc_hardware_agent",
    "bot_id": "<已关联 Bot>",
    "transport": "high_quality",
    "session_nonce": "<短期、单次>",
    "config_digest": "sha256:...",
    "wait_for_session_update": true
  },
  "session_config": {
    "dialog_id": "<平台生成的非个人标识>",
    "system_context": "<已授权且脱敏的本次背景>",
    "tool_scope_token": "<短期令牌>"
  },
  "privacy": {},
  "heartbeat_interval_sec": 10,
  "expires_at": "..."
}

响应不得返回 product_secret 或 device_secret。

6.2 激活会话

POST /device/v3/agent-sessions/{conversation_id}/activate

请求包含 provider_session_id、connected_at、transport、bot_id、config_digest 和设备侧关联号。平台核对准备记录和配置摘要后进入 ACTIVE。

6.3 心跳

继续使用严格递增序号，但把 rtc 改为：

{
  "agent_link": {
    "connected": true,
    "input_active": true,
    "output_active": true,
    "provider_session_id": "...",
    "reconnect_count": 0
  }
}

平台继续返回 continue、stop、stop_after_turn；新增 rotate_provider_credential 和 refresh_session_config 前，必须有显式设备能力位。

6.4 字幕

复用 /device/v2/conversations/{id}/turns:batch 或在 v3 提供同构接口。只上传最终字幕，不把增量字幕写入长期存储。保持 turn_key + sequence_no 去重和冲突检测。

6.5 停止

设备先请求 SDK 停止并停止采集，再调用平台 stop。平台在以下任一条件满足后收敛 COMPLETED：

• 收到可信服务端结束事件；
• 设备报告关闭成功且心跳租约结束；
• 强制终止接口确认成功。

如果只能依赖设备报告，授权撤回和设备失控时无法做到服务端 fail-close，不能直接通过生产隐私门禁。

7. 后端模块与数据模型

7.1 运行时抽象

现有 voiceprovider.Client 的 Start/Query/Stop 契约只适合 RTC VoiceChat。建议新增：

type ConversationRuntime interface {
    Prepare(context.Context, PrepareRequest) (PrepareResult, error)
    Terminate(context.Context, TerminateRequest) error
    Reconcile(context.Context, SessionRef) (RuntimeState, error)
}

• LegacyVoiceChatRuntime 封装现有 voiceprovider.Client；
• VolcHardwareAgentRuntime 不负责创建音频会话，只负责设备/Bot 配置同步、服务端终止、事件对账和用量拉取；
• 通话状态机、幂等、Outbox、审计和租约留在 orchestration。

7.2 新表建议

hardware_agent_device_binding

• device_id、provider、instance_ref、product_ref；
• provider_device_name、hardware_id_digest；
• bot_ref、license_ref、credential_version；
• status、registered_at、revoked_at、last_verified_at。

conversation_runtime_session

• conversation_id、runtime_type、transport；
• provider_session_ref、provider_device_ref、bot_ref；
• session_nonce_digest、config_digest；
• status、connected_at、last_event_at、ended_at；
• 唯一约束：一个通话最多一个活动运行时会话；同一供应商会话只能映射一个通话。

hardware_agent_config_sync

• 平台版本 ID、Bot/产品引用、期望摘要、实际摘要；
• 同步状态、供应商请求引用、最后错误码和验证时间；
• 用于发现火山控制台手工修改造成的配置漂移。

7.3 事件归一化

扩展现有 provider_event，归一化为：

• hardware_agent.session.started；
• hardware_agent.session.updated；
• hardware_agent.transcript.final；
• hardware_agent.function_call；
• hardware_agent.usage.final；
• hardware_agent.session.stopped；
• hardware_agent.session.failed。

设备上传事件和服务端回调必须使用不同 source_type，最终以 provider_event_key 和话轮键双层去重。

8. 工具、记忆和业务动作

8.1 工具分类

类型	示例	执行位置	控制要求
设备本地无副作用	查询电量、读取音量	设备	白名单、参数校验
设备本地可逆动作	调整音量、切换灯效	设备	范围限制、结果回传
平台只读工具	检索已确认记忆、读取已授权日程	平台工具网关	会话短令牌、租户/长者反查
平台有副作用工具	创建提醒、联系家人、修改资料	平台业务 API	用户确认、幂等键、权限和审计
高风险动作	删除数据、转账、医疗决策	不直接开放给模型	使用既有人工流程

8.2 工具网关安全

• 工具调用必须映射到活动通话，不能只信任模型传来的 subject_id；
• 参数使用固定 JSON Schema，拒绝未知字段；
• 每个调用有稳定 call_id，平台按 conversation_id + call_id 幂等；
• 返回内容限制长度并做提示词注入隔离；
• 工具超时返回结构化降级结果，不中断音频主链；
• 全量记录工具名、结果状态、耗时和资源版本，不记录不必要的敏感正文。

9. 隐私、录音和删除

9.1 授权撤回

当前系统在撤回字幕、原录音、故事整理或个性化记忆授权时，会把活动通话写入停止状态并投递可靠停止任务。迁移后必须实现等价闭环：

1. 平台事务内写入撤回、通话停止意图、Outbox 和审计；
2. 在线设备通过心跳/SSE 命令立即关闭 SDK 会话；
3. 平台调用火山服务端终止或吊销接口兜底；
4. 未确认停止前禁止新建会话和工具访问；
5. 超时进入阻断告警和人工处置，而不是静默标记完成。

9.2 双轨录音

这是迁移中最可能发生范围变化的功能。PoC 必须确认：

• 能否取得送入 SDK 前的近端 PCM；
• 能否取得 SDK 解码后、播放前的远端 PCM；
• 打断、重连、丢包隐藏和采样率变化后时间轴能否对齐；
• SDK 是否允许在本地进行受授权的录制；
• 若使用火山云端录制，能否满足近/远轨分离、短期访问、删除和审计要求。

如不能取得远端 PCM，不能把混音录音冒充现有双轨录音。第一阶段应明确限定为 transcript_only，待产品接受范围变更或供应商能力补齐后再开放录音。

9.3 删除和凭证吊销

主体隐私删除增加两个子任务：

• 删除或匿名化火山侧与该设备/会话相关的可识别数据；
• 吊销设备智能体凭证和 License 绑定，并保存最小删除证明。

供应商无删除/吊销 API 时，需要人工控制台证据和对账任务，但该方式不适合大规模量产。

10. 用量、费用与 License

现有七类用量可保留，但新增来源维度：

source = provider_callback | device_session | provider_bill
runtime = legacy_voicechat | volc_hardware_agent

建议新增类别：

• HARDWARE_AGENT_LICENSE：设备 License 购买、激活、到期和转移；
• HARDWARE_AGENT_VOICE：AI 对话时长；
• HARDWARE_AGENT_MODEL：模型推理额度；
• 视频、声音复刻、联网问答等扩展资源按实际开通单独归类。

设备上报只用于实时额度预估，最终账单以火山账单/用量接口为准，并执行会话、设备、账期三级对账。火山产品页显示 License 按设备提供不同对话时长和模型额度，实际采购价格、超额规则、License 回收和换机政策必须在合同中冻结。火山硬件智能体产品页

11. 灰度迁移步骤

阶段 0：供应商能力封板

在编码前取得正式 SDK、API、License 和数据处理条款，完成第 13 节问题闭环。输出一份签字的能力矩阵，未确认项不能用口头承诺替代。

阶段 1：独立真机 PoC

• 1 个测试产品、1 个 Bot、3 台候选板；
• 跑通高质量 SDK 初始化、动态注册、建连、打断、重连、字幕和结束；
• 验证近/远端 PCM、强制停话、凭证吊销、License 更换；
• 暂不连接生产家庭/长者数据。

阶段 2：平台双运行时

• 新增运行时抽象、表和 /device/v3；
• 旧 v2/RTC 链路保持不变；
• 新设备只接固定 Bot，先打通授权、状态、字幕、内容处理和诊断；
• 火山配置先由人工控制台维护，平台保存摘要和漂移检查。

阶段 3：个性化与工具

• 接入动态会话参数和冻结背景；
• 接入平台记忆 MCP/Function Calling；
• 接入角色、模型、音色、Bot 的发布和回滚；
• 接入用量、License、隐私删除和供应商对账。

阶段 4：灰度试点

• 内部设备 -> 友好家庭 -> 小比例真实家庭；
• 每个设备的运行时由不可变灰度版本决定；
• 出现阻断问题时只切回 legacy_rtc，不修改历史通话运行时；
• 灰度期间两个运行时分别统计成功率、首响、打断、重连、字幕、费用和投诉。

阶段 5：主链切换与退役

只有新链路连续通过真机、隐私、费用和运行恢复门禁后，才把新出厂设备默认设为硬件智能体。旧 StartVoiceChat 代码、RTC Token 签发和模板不能立即删除，至少保留到全部在役设备完成升级或退出支持期。

12. 验收与回滚门禁

建议新的真机最小矩阵至少覆盖 3 台量产候选设备、6 通会话：

1. 正常完整通话；
2. 用户打断和 Agent 被打断；
3. Wi-Fi/蜂窝或批准网络切换恢复；
4. 平台受控停止；
5. 活动通话中授权撤回；
6. 设备断电重启后的字幕队列恢复和资源回收。

每通必须核对：

• 平台通话、火山会话、设备和 Bot 关联唯一；
• 音频上行、下行、首响、打断和恢复符合现场冻结标准；
• 最终字幕完整、顺序稳定、重放不重复；
• 背景和工具调用严格限制在当前租户、长者和通话；
• 结束后 SDK、License 占用、平台租约和工具令牌全部释放；
• 设备、平台、火山、字幕、用量和隐私证据引用完整。

建议上线 SLO 在试点前冻结，不在代码中写死。至少包含：建连成功率、首次回复时延、打断成功率、异常重连成功率、字幕完整率、停止收敛时延、重复计费率、供应商账单差异和凭证吊销生效时延。

回滚规则：

• 回滚只影响新会话；活动会话按原运行时完成或受控停止；
• 数据库中的 runtime_type 和配置摘要不可改写；
• 设备切回旧运行时前必须确认旧 RTC SDK 和配置仍在；
• 无法强制停话、出现跨租户工具访问、删除不收敛或凭证泄露时，立即停止硬件智能体新会话灰度。

13. 必须向火山确认的问题

以下问题未得到书面答案前，不建议承诺完整替换日期：

1. 是否提供按设备或会话的服务端强制终止接口？设备离线时多久生效？
2. device_secret 是否支持轮换、吊销、批量禁用和换板迁移？
3. 产品、设备、Bot 绑定和 License 是否都有 OpenAPI，而不是只能操作控制台？
4. 是否有服务端会话开始、结束、最终字幕、错误和用量回调？签名和重放保护是什么？
5. 是否允许传入平台生成的 conversation_id/dialog_id 并在回调和账单中原样返回？
6. 动态会话参数可以覆盖哪些 Bot 配置？何时生效？是否保证收到 session.updated 后再开始识别？
7. 高质量 SDK 是否同时提供近端输入 PCM 和远端播放 PCM 回调？采样率、声道和时间戳如何定义？
8. Function Calling/MCP 的服务端鉴权、超时、重试、幂等和最大正文限制是什么？
9. License 的激活、到期、换机、回收、离线宽限和超额计费规则是什么？
10. 能否按设备、Bot、会话、租户标签导出用量并与账单对账？
11. 会话音频、字幕、日志和模型上下文分别保留多久？如何导出和删除？数据地域在哪里？
12. SDK 支持的芯片、编译器、RTOS/Linux、RAM/Flash/CPU、AEC/AGC/ANS、网络端口和证书更新要求是什么？
13. 高质量和低负载方案能否在同一产品/设备上切换？切换是否会改变 Bot、License、回调和计费语义？
14. 量产并发、建连 QPS、设备数、Bot 数和回调吞吐的配额如何申请和压测？

14. 主要风险

风险	影响	控制措施
产品级 Secret 被固件提取	同产品设备可被仿冒或批量注册	一次性安全注册、设备独享 Secret、安全存储、吊销演练
火山控制台配置漂移	平台记录与实际 Bot 行为不一致	平台配置摘要、定时对账、变更工单、生产禁止无审计手改
只能由设备报告会话结束	授权撤回时不能服务端强制停止	以供应商强停/吊销能力作为上线硬门槛
字幕只有设备单路回传	断电或固件故障造成内容缺口	本地加密可靠队列、服务端回调双源、终稿补传和差异告警
SDK 无远端 PCM	双轨录音功能无法等价迁移	PoC 提前验证；不满足时明确限定 transcript_only
License 与内部设备解绑不同步	换机失败、成本浪费或越权使用	License 台账、绑定状态机、每日对账和售后流程
Bot 数量或动态参数受限	现有多租户灰度模型无法直接复制	少量基础 Bot + 会话动态参数；配置版本与供应商摘要冻结
工具调用越权或重复	读取他人记忆或执行重复动作	会话范围令牌、服务端反查、Schema、幂等、确认和审计

15. 评审建议

甲方方案评审时可以把范围分成三层：

• 必须等价迁移：正常语音、打断、设备绑定、授权门禁、通话状态、最终字幕、摘要/故事、人工记忆、额度、诊断和受控停止；
• 需要供应商能力确认：服务端强停、设备凭证吊销、字幕/用量服务端回调、动态会话参数、MCP 鉴权；
• 可能需要范围调整：双轨录音、三种旧 engine_mode、RTC 房间级诊断和旧 VoiceChat 模板。

推荐先让甲方确认“硬件对话智能体只替换语音会话执行层，现有业务平台继续作为控制面和数据主库”。确认这条边界后，再进入 SDK PoC 和接口改造，能避免后续把火山控制台误当成整个业务平台替代品。