414 lines
51 KiB
Markdown
414 lines
51 KiB
Markdown
# 原始需求来源段落清单
|
||
|
||
> 此文件由`scripts/extract-requirements.ps1`从原始DOCX机械提取，用于稳定引用来源，不替代原需求文档。`Pxxxx`是`word/document.xml`正文段落的零基顺序号；空段落保留编号但不输出正文。
|
||
|
||
- 来源文件：数据采集终端-云端系统研发需求规格说明书(1).docx
|
||
- SHA-256：`bd009e3de1aebe07a4b50c3ead29ff840d6dc9bc0d9ade0ebb9faa94d45fca23`
|
||
- 正文段落总数：517
|
||
- 非空段落数：402
|
||
|
||
## 非空段落
|
||
|
||
- `P0000` [Normal] 研发需求规格｜版本 1.2｜2026-08-21
|
||
- `P0001` [Normal] 数据采集终端
|
||
- `P0002` [Normal] 云端智能服务与网页管理平台研发需求规格说明书
|
||
- `P0003` [Normal] 硬件终端使用流程、SaaS平台业务开发、Agent编排与大模型优化
|
||
- `P0006` [Normal] 文件使用范围：项目内部与受邀供应商
|
||
- `P0008` [heading 1] 编写说明
|
||
- `P0009` [Normal] 本文件用于业务方、硬件与固件团队、SaaS平台业务开发人员、Agent编排与大模型优化人员、测试人员和运维人员共同确认研发内容。文档先解释硬件终端怎样被使用，再说明一次通话怎样经过云端形成字幕、故事和记忆，最后分别列出两个云端角色的研发任务、交接方式和验收要求。
|
||
- `P0010` [Normal] 全文尽量使用完整、直白的中文表达。SaaS平台业务开发是指网页业务系统、账号权限、设备和数据管理等工作；Agent编排与大模型优化是指语音智能体的启动、通话状态、背景资料、记忆、提示词和内容整理等工作。接口路径、程序字段、状态值和第三方产品名称必须保持准确，因此这些位置保留必要的英文或代码写法，并在旁边解释中文含义。
|
||
- `P0012` [heading 1] 目录
|
||
- `P0014` [heading 1] 0. 研发启动说明
|
||
- `P0015` [Normal] 本章把项目目的、已经确定的技术关系、两个云端角色的分工和交付顺序集中说明。后续架构设计、开发报价、人员安排、任务拆分和验收均以本章为共同基线。
|
||
- `P0016` [heading 2] 0.1 项目要解决的问题
|
||
- `P0017` [Normal] 数据采集终端面向长者的日常语音交流。长者通过带听筒的固定式设备与语音智能体自然聊天，家庭用户通过网页完成设备绑定、授权设置和内容核对。云端工作的核心价值，是把硬件的一次摘机通话安全地连接到语音智能体，并把通话结果整理为可查看、可核对、可继续使用的数据。
|
||
- `P0018` [Normal] 云端系统需要同时解决三类问题：第一，设备能否安全、稳定地开始和结束一次通话；第二，语音智能体能否根据长者背景和已确认记忆自然交流；第三，通话后的字幕、录音、故事和记忆能否被家庭用户清楚地管理、修订和删除。
|
||
- `P0019` [heading 2] 0.2 已经确定的关键方案
|
||
- `P0021` [heading 2] 0.3 两个云端角色的分工结论
|
||
- `P0024` [heading 2] 0.4 交付顺序
|
||
- `P0026` [heading 1] 1. 产品与硬件终端背景
|
||
- `P0027` [Normal] 云端研发人员需要先理解硬件端实际怎样被使用。数据采集终端不是普通网页聊天入口，而是一台长期放在长者生活环境中的固定式语音设备。长者日常不需要打开网页或输入账号，主要通过听筒完成交流；网页更多由家庭用户负责设置和核对。
|
||
- `P0028` [heading 2] 1.1 硬件终端是什么
|
||
- `P0029` [Normal] 本项目中的数据采集终端采用带听筒的固定式语音交互形态。听筒中的话筒采集长者声音，受话器播放语音智能体回答；叉簧或等效的开始/结束触发用于识别摘机和挂断；设备通过 Wi-Fi 连接自建云端和火山引擎实时音视频服务。
|
||
- `P0030` [Normal] 设备端负责采集和播放实时语音、保存必要的本地状态、执行云端下发的非敏感配置，并在授权有效时将长者声音和智能体声音分别保存为加密录音分片。自建云端负责控制和业务数据，不承担实时语音转发。
|
||
- `P0032` [Normal] 图 1 硬件终端、两个云端角色和第三方语音服务之间的关系
|
||
- `P0033` [heading 2] 1.2 硬件端主要组成和作用
|
||
- `P0035` [heading 2] 1.3 家庭首次配置流程
|
||
- `P0036` [Normal] 1. 设备通电并完成 Wi-Fi 配置，使用每台设备独立的身份访问云端，取得服务器时间、最低固件要求和基础运行配置。
|
||
- `P0037` [Normal] 2. 家庭用户登录网页管理平台，创建家庭和长者档案，填写称呼、语言、交流偏好、生活背景和禁聊主题。
|
||
- `P0038` [Normal] 3. 家庭用户分别确认最终字幕、原录音、故事整理、个性化记忆和家庭协作等授权。
|
||
- `P0039` [Normal] 4. 家庭用户在网页中输入一次性设备绑定码，把设备绑定到指定家庭和长者。
|
||
- `P0040` [Normal] 5. SaaS角色验证设备是否在线、是否已经被其他家庭绑定，并保存当前绑定关系和历史记录。
|
||
- `P0041` [Normal] 6. 设备下一次读取配置时获得新的绑定和运行配置，网页显示设备在线状态、固件版本和最后同步时间。
|
||
- `P0042` [heading 2] 1.4 长者日常通话流程
|
||
- `P0044` [Normal] 图 2 一次日常通话中各方的主要动作
|
||
- `P0045` [Normal] 1. 长者拿起听筒。设备识别摘机动作，并向云端请求创建本次通话。
|
||
- `P0046` [Normal] 2. SaaS角色检查设备身份、当前绑定长者、分项授权、设备状态和使用额度，并向Agent角色提供本次启动所需的业务资料。
|
||
- `P0047` [Normal] 3. Agent角色创建通话记录，整理本次可以使用的长者背景资料和已确认记忆，选择语音处理方式。
|
||
- `P0048` [Normal] 4. Agent角色为设备生成实时音视频房间资料和短期入房凭证，设备使用这些资料加入指定房间。
|
||
- `P0049` [Normal] 5. 设备确认已经进入房间后，Agent角色才启动豆包语音智能体，避免设备未入房时提前产生计费和遗留任务。
|
||
- `P0050` [Normal] 6. 长者通过话筒说话，豆包语音智能体理解并回答，设备通过受话器播放回答。实时语音不经过自建应用服务器。
|
||
- `P0051` [Normal] 7. 通话期间，设备周期上报网络、实时音视频、本地录音队列和设备状态；Agent角色维护本次通话的短期租约和供应商任务状态。
|
||
- `P0052` [Normal] 8. 长者挂断后，设备请求停止；Agent角色停止语音智能体并回收任务，SaaS角色更新页面上的通话完成状态。
|
||
- `P0053` [heading 2] 1.5 通话结束后发生什么
|
||
- `P0054` [Normal] 1. Agent角色接收供应商返回的最终字幕、状态和用量，按说话人和时间整理为每轮对话。
|
||
- `P0055` [Normal] 2. 在授权有效时，Agent角色生成摘要、可继续交流的话题、故事候选和事实候选，并保留对应的原始字幕来源。
|
||
- `P0056` [Normal] 3. SaaS角色在网页中展示候选内容，家庭用户可以确认、修改或拒绝。
|
||
- `P0057` [Normal] 4. 经过人工确认且允许用于个性化交流的内容成为已确认记忆；Agent角色在下一次通话中按授权检索和使用。
|
||
- `P0058` [Normal] 5. 在原录音保存授权有效时，设备在空闲且网络符合要求时直接上传两条录音轨道；SaaS角色负责校验、播放授权、下载、分享、导出和删除。
|
||
- `P0059` [heading 2] 1.6 异常情况下的用户体验原则
|
||
- `P0060` [Normal] • 设备未绑定、授权不足或固件低于最低安全版本时，设备不能进入看似正常但实际无法工作的通话状态，应获得明确错误并通过设备既有提示方式告知用户。
|
||
- `P0061` [Normal] • 网络暂时不可用时，设备可以进行有限次数重试，但不能重复创建多次通话或多个供应商语音任务。
|
||
- `P0062` [Normal] • 设备已经入房但智能体启动失败时，Agent角色应停止并清理本次通话；设备收到可识别的失败状态后退出通话。
|
||
- `P0063` [Normal] • 设备在通话中断网、断电或重启时，Agent角色通过租约和后台检查回收供应商任务；设备恢复联网后上报最后状态。
|
||
- `P0064` [Normal] • 设备本地存在待上传录音时，SaaS角色应在网页中显示上传队列和失败原因；只有云端确认文件完整后，设备才延迟删除本地密文。
|
||
- `P0065` [heading 1] 2. 从一次通话看整个系统怎样工作
|
||
- `P0066` [Normal] 本章把硬件端、SaaS角色、Agent角色、火山引擎与豆包以及云端文件存储放在同一条业务链中说明。阅读者可以先理解语音走哪条链路、控制信息走哪条链路，再进入后续的角色需求。
|
||
- `P0067` [heading 2] 2.1 五个参与部分
|
||
- `P0069` [heading 2] 2.2 三条不同的数据链路
|
||
- `P0072` [Normal] 图 3 两个云端角色共同形成“对话—核对—记忆—再对话”闭环
|
||
- `P0073` [heading 2] 2.3 一次通话的数据从哪里来、到哪里去
|
||
- `P0075` [heading 2] 2.4 必须遵守的系统关系
|
||
- `P0076` [Normal] • 实时语音不得进入SaaS业务接口、Agent控制接口、日志系统或自建应用服务器磁盘。
|
||
- `P0077` [Normal] • 设备上传录音时直接访问云端文件存储；SaaS业务接口只签发短期上传授权并校验上传结果。
|
||
- `P0078` [Normal] • SaaS网页不直接调用火山引擎或豆包接口；第三方接口细节统一由Agent角色的供应商对接模块封装。
|
||
- `P0079` [Normal] • 每次通话只关联一个客户组织、一个家庭、一个长者、一台设备和一个供应商语音任务。
|
||
- `P0080` [Normal] • PostgreSQL是业务数据的最终依据；Redis只保存租约、在线状态、限流和短期缓存。
|
||
- `P0081` [Normal] • 跨进程后台任务先可靠写入数据库再执行；重复执行不能生成重复内容、重复录音记录或重复费用。
|
||
- `P0082` [Normal] • 每类业务数据只设一个主责角色；另一个角色通过内部接口读取或提交结果，不直接修改对方模块负责的数据。
|
||
- `P0083` [heading 1] 3. SaaS角色与Agent角色怎样协同
|
||
- `P0084` [Normal] 两个角色的划分以业务责任为主，而不是简单按照前端和后端划分。SaaS角色负责稳定的业务规则、网页和数据管理；Agent角色负责一次实时对话的运行控制和模型效果。两者必须在通话启动、结果交付、人工核对和记忆回用等位置明确交接。
|
||
- `P0085` [heading 2] 3.1 一句话理解两个角色
|
||
- `P0088` [heading 2] 3.2 SaaS平台业务开发的责任边界
|
||
- `P0090` [heading 2] 3.3 Agent编排与大模型优化的责任边界
|
||
- `P0092` [heading 2] 3.4 五个必须明确的交接点
|
||
- `P0094` [heading 2] 3.5 数据主责和内部接口规则
|
||
- `P0097` [heading 2] 3.6 联调和评审机制
|
||
- `P0098` [Normal] • 两个角色共同维护一份接口和数据字典，先冻结创建通话、授权快照、字幕、候选内容、已确认记忆和停止动作的内部结构。
|
||
- `P0099` [Normal] • 每个交接点至少提供成功、超时、重复、乱序、授权撤回和删除中的典型测试样例。
|
||
- `P0100` [Normal] • SaaS角色提供模拟的长者档案、授权、绑定和人工核对结果；Agent角色提供模拟供应商、字幕回调和机器候选。
|
||
- `P0101` [Normal] • 任何破坏内部接口或数据含义的改动，必须先更新接口说明、迁移影响和兼容方案，再合并代码。
|
||
- `P0102` [Normal] • 阶段验收采用端到端业务场景，不以“各自模块单独演示成功”代替两角色联调。
|
||
- `P0103` [heading 1] 4. 公共技术架构与代码组织
|
||
- `P0104` [Normal] 两个角色共享同一套数据库、缓存、云端文件存储、部署和监控基础设施。公共架构应让两人可以并行开发，同时保证数据边界、接口契约和异常恢复一致。
|
||
- `P0105` [heading 2] 4.1 推荐的整体架构
|
||
- `P0107` [heading 2] 4.2 默认技术方案
|
||
- `P0108` [Normal] 以下方案作为外包交付的默认基线。外包团队可以提出成熟度相当的替代方案，但应在启动评审中同时说明团队能力、开发成本、迁移影响、运维影响和回退方式，并取得业务方书面确认。
|
||
- `P0110` [heading 2] 4.3 建议的代码目录和主责角色
|
||
- `P0112` [heading 2] 4.4 工程实现规则
|
||
- `P0113` [Normal] • 首期采用模块化单体。不同业务模块通过明确的程序接口协作，不允许一个模块直接修改另一个模块的数据表。
|
||
- `P0114` [Normal] • 数据库事务不得跨越火山引擎、云端文件存储、用户登录服务或大模型服务的网络调用，避免长事务和无法回滚。
|
||
- `P0115` [Normal] • 调用外部系统前先保存要执行的业务意图，调用后再保存结果。网络超时或进程重启后，可以继续确认状态或安全重试。
|
||
- `P0116` [Normal] • 配置、数据库升级脚本、接口文档、前后端字段类型、测试样例和运维文档必须与代码版本同步。
|
||
- `P0117` [Normal] • 生产长期密钥不得进入代码仓库、容器镜像、普通环境文件、业务数据库、日志或前端构建文件。
|
||
- `P0118` [heading 2] 4.5 两角色共同遵守的接口规则
|
||
- `P0119` [Normal] • 模块接口的输入和输出使用明确的业务名称，不把火山引擎原始字段直接暴露给SaaS模块。
|
||
- `P0120` [Normal] • SaaS模块向Agent模块提供的授权和长者资料必须带版本、来源和有效状态；Agent不得自行猜测缺失授权。
|
||
- `P0121` [Normal] • Agent模块产生的字幕、摘要和候选内容必须带通话编号、长者编号、来源轮次和生成版本；SaaS不得只保存脱离来源的正文。
|
||
- `P0122` [Normal] • 任何状态变更先写入本模块的业务记录，再调用外部系统；网络结果未知时通过同一业务编号查询或对账。
|
||
- `P0123` [Normal] • 模块之间的写操作必须幂等；重复请求、重复通知和后台重试不得造成双通话、双记忆或重复删除。
|
||
- `P0124` [heading 1] 5. SaaS平台业务开发需求
|
||
- `P0125` [Normal] SaaS平台业务开发负责网页业务系统、设备管理和数据治理。这个角色既包括React网页，也包括与账号、家庭、长者、授权、设备、录音、故事核对和隐私处理有关的后端业务。
|
||
- `P0126` [heading 2] 5.1 页面结构
|
||
- `P0128` [heading 2] 5.2 登录、家庭和成员
|
||
- `P0129` [heading 3] 5.2.1 使用标准网页登录 〔首期〕
|
||
- `P0131` [heading 3] 5.2.2 管理家庭、成员邀请和角色 〔首期〕
|
||
- `P0133` [heading 2] 5.3 长者资料与分项授权
|
||
- `P0134` [heading 3] 5.3.1 创建和维护长者档案 〔首期〕
|
||
- `P0136` [heading 3] 5.3.2 分别管理不同的数据授权 〔首期〕
|
||
- `P0138` [heading 2] 5.4 设备身份、绑定和转移
|
||
- `P0139` [heading 3] 5.4.1 每台设备使用独立身份访问云端 〔首期〕
|
||
- `P0141` [heading 3] 5.4.2 使用一次性绑定码绑定或转移设备 〔首期〕
|
||
- `P0143` [heading 3] 5.4.3 在网页中查看设备并完成绑定、解绑或转移申请 〔首期〕
|
||
- `P0145` [heading 2] 5.5 设备状态、配置、命令和固件
|
||
- `P0146` [heading 3] 5.5.1 维护设备在线状态和配置同步状态 〔首期〕
|
||
- `P0148` [heading 3] 5.5.2 在网页中查看设备详情并编辑非敏感配置 〔首期〕
|
||
- `P0150` [heading 3] 5.5.3 下发受控命令并管理固件升级 〔家庭试点前〕
|
||
- `P0152` [heading 3] 5.5.4 在网页中查看命令和固件升级结果 〔家庭试点前〕
|
||
- `P0154` [heading 2] 5.6 通话、字幕和网页展示
|
||
- `P0155` [heading 3] 5.6.1 查看通话列表和通话详情 〔首期〕
|
||
- `P0157` [heading 3] 5.6.2 按授权播放两条录音轨道 〔首期〕
|
||
- `P0159` [heading 2] 5.7 录音上传、校验和访问
|
||
- `P0160` [heading 3] 5.7.1 按录音分片签发短期上传地址 〔首期〕
|
||
- `P0162` [heading 3] 5.7.2 上传完成后校验录音 〔首期〕
|
||
- `P0164` [heading 3] 5.7.3 播放和下载必须单独授权 〔首期〕
|
||
- `P0166` [heading 2] 5.8 故事核对和已确认记忆管理
|
||
- `P0167` [heading 3] 5.8.1 核对故事和事实候选 〔首期〕
|
||
- `P0169` [heading 3] 5.8.2 管理已确认记忆 〔首期〕
|
||
- `P0171` [heading 2] 5.9 分享、导出、撤回和删除
|
||
- `P0172` [heading 3] 5.9.1 按具体资源和具体权限分享 〔家庭试点前〕
|
||
- `P0174` [heading 3] 5.9.2 提交数据访问、导出、更正、撤回和删除请求 〔首期〕
|
||
- `P0176` [heading 3] 5.9.3 实时推送状态变化但不推送敏感正文 〔首期〕
|
||
- `P0178` [heading 2] 5.10 内部运营、配置发布、费用和告警
|
||
- `P0179` [heading 3] 5.10.1 按脱敏信息处理设备和通话故障 〔家庭试点前〕
|
||
- `P0181` [heading 3] 5.10.2 管理配置发布、费用和告警 〔家庭试点前〕
|
||
- `P0183` [heading 3] 5.10.3 按通话统计用量、费用和额度 〔首期〕
|
||
- `P0185` [heading 2] 5.11 SaaS角色整体验收要求
|
||
- `P0186` [Normal] • 家庭用户能够从创建长者、设置授权、绑定设备一直完成到查看通话、核对故事和管理已确认记忆的完整流程。
|
||
- `P0187` [Normal] • 同一用户在不同家庭、不同长者和不同资源之间的权限边界清楚，越权请求不泄露资源是否存在。
|
||
- `P0188` [Normal] • 设备在线状态、配置下发、录音上传、导出和删除等异步过程都有明确的处理中、成功和失败状态。
|
||
- `P0189` [Normal] • 所有网页操作在无数据、加载中、权限不足、网络失败和并发修改时都有可理解的页面反馈。
|
||
- `P0190` [Normal] • SaaS角色向Agent角色提供的长者、授权、绑定、配置和已确认记忆都带稳定编号、版本和有效状态。
|
||
- `P0191` [heading 1] 6. Agent编排与大模型优化需求
|
||
- `P0192` [Normal] Agent编排与大模型优化负责一次语音通话怎样被创建、启动、运行、停止和整理。这个角色既包含稳定的服务端状态控制，也包含提示词、对话策略、记忆使用、模型路由、摘要和故事抽取的持续优化。
|
||
- `P0193` [heading 2] 6.1 角色的输入和输出
|
||
- `P0195` [heading 2] 6.2 一次通话的状态和完整生命周期
|
||
- `P0196` [heading 3] 6.2.1 创建通话并预留实时音视频房间 〔首期〕
|
||
- `P0198` [heading 3] 6.2.2 设备确认入房后再启动语音智能体 〔首期〕
|
||
- `P0200` [heading 3] 6.2.3 通话期间保活并下发非实时动作 〔首期〕
|
||
- `P0202` [heading 3] 6.2.4 主动结束通话并收敛到最终状态 〔首期〕
|
||
- `P0204` [heading 3] 6.2.5 后台自动检查并修复卡住的通话 〔首期〕
|
||
- `P0206` [heading 2] 6.3 语音处理方式与供应商对接
|
||
- `P0208` [heading 3] 6.3.1 云端签发短期入房凭证 〔首期〕
|
||
- `P0210` [heading 3] 6.3.2 把火山引擎与豆包的接口细节集中封装 〔首期〕
|
||
- `P0212` [heading 3] 6.3.3 每次通话选择一种语音处理方式 〔首期〕
|
||
- `P0214` [heading 3] 6.3.4 管理智能体人设、音色、模型和路由配置 〔家庭试点前〕
|
||
- `P0216` [heading 2] 6.4 长者背景资料、记忆检索与长期记忆
|
||
- `P0217` [heading 3] 6.4.1 通话开始前整理最小且必要的长者背景资料 〔首期〕
|
||
- `P0219` [heading 3] 6.4.2 使用自有数据库检索已确认记忆 〔首期〕
|
||
- `P0221` [heading 3] 6.4.3 验证并可选使用供应商原生记忆 〔家庭试点前〕
|
||
- `P0223` [heading 3] 6.4.4 通话过程中按需要调用自有记忆检索工具 〔家庭试点前〕
|
||
- `P0225` [heading 2] 6.5 供应商状态通知、最终字幕与会话摘要
|
||
- `P0226` [heading 3] 6.5.1 可靠接收供应商状态通知 〔首期〕
|
||
- `P0228` [heading 3] 6.5.2 保存最终字幕并标记每轮对话 〔首期〕
|
||
- `P0230` [heading 3] 6.5.3 生成通话摘要和下次可继续的话题 〔首期〕
|
||
- `P0232` [heading 2] 6.6 故事、事实候选与已确认记忆
|
||
- `P0233` [heading 3] 6.6.1 从最终字幕整理故事和事实候选 〔首期〕
|
||
- `P0235` [heading 3] 6.6.2 人工核对后生成正式记忆 〔首期〕
|
||
- `P0237` [heading 2] 6.7 面向长者的对话策略优化
|
||
- `P0238` [heading 3] 6.7.1 让语音智能体说得清楚、听得懂并愿意继续聊 〔首期〕
|
||
- `P0240` [heading 3] 6.7.2 保持身份、人设和交流边界一致 〔首期〕
|
||
- `P0242` [heading 3] 6.7.3 调整回答时延、打断和语音处理方式 〔家庭试点前〕
|
||
- `P0244` [heading 2] 6.8 摘要、故事和记忆质量优化
|
||
- `P0245` [heading 3] 6.8.1 摘要和开放话题要忠于原始对话 〔首期〕
|
||
- `P0247` [heading 3] 6.8.2 故事和事实候选要可核对、可修改 〔首期〕
|
||
- `P0249` [heading 3] 6.8.3 已确认记忆的检索和使用要准确 〔首期〕
|
||
- `P0251` [heading 2] 6.9 Agent评测、发布和持续优化
|
||
- `P0252` [heading 3] 6.9.1 建立可重复的评测集和质量指标 〔首期〕
|
||
- `P0254` [heading 3] 6.9.2 配置发布、灰度和回滚 〔家庭试点前〕
|
||
- `P0256` [heading 3] 6.9.3 建立从用户核对结果到模型优化的反馈闭环 〔家庭试点前〕
|
||
- `P0258` [heading 2] 6.10 Agent角色整体验收要求
|
||
- `P0259` [Normal] • 真实设备连续完成多次创建、入房、激活、对话、挂断和异常恢复，供应商侧无遗留语音任务。
|
||
- `P0260` [Normal] • 三种语音处理方式在真实账号下均有标准启动请求、状态通知样例、时延和成本对比。
|
||
- `P0261` [Normal] • 每次通话可以追溯使用的长者资料、已确认记忆、人设、提示词、音色、模型和路由版本。
|
||
- `P0262` [Normal] • 最终字幕、摘要、故事和事实候选均保留来源；机器候选不会自动成为正式记忆。
|
||
- `P0263` [Normal] • 长者友好对话、记忆准确、打断、敏感信息和提示注入测试达到项目设定的质量门槛。
|
||
- `P0264` [heading 1] 7. 硬件、SaaS与Agent接口及联调
|
||
- `P0265` [Normal] 本章面向硬件与固件团队、SaaS开发人员、Agent开发人员和联调测试人员。接口路径、字段和程序状态必须保持准确，因此保留必要的英文代码，并增加每个角色在接口中的具体动作。
|
||
- `P0266` [heading 2] 7.1 设备接口中的责任分配
|
||
- `P0268` [heading 2] 7.2 创建通话请求示例
|
||
- `P0271` [heading 2] 7.3 创建通话响应示例
|
||
- `P0274` [heading 2] 7.4 通话状态
|
||
- `P0276` [heading 2] 7.5 三方联调要求
|
||
- `P0277` [Normal] • 项目团队交付可运行的模拟设备。模拟设备能够执行启动、读取配置、创建通话、确认入房、发送心跳、停止、断网、重复请求、字幕补交和录音上传。
|
||
- `P0278` [Normal] • Agent角色交付模拟火山引擎服务和可重复播放的脱敏状态通知样例，覆盖任务开始、最终字幕、智能体开始回答、被打断、用量、错误和停止。
|
||
- `P0279` [Normal] • 硬件团队提供设备能力表、音频编码与采样率、智能体用户订阅方式、心跳字段、两条录音轨道分片清单格式和设备命令结果格式。
|
||
- `P0280` [Normal] • 接口变更先更新 OpenAPI 接口说明和兼容性说明。会导致旧固件无法工作的变更使用新的接口版本，不能依赖固件 User-Agent 猜测兼容方式。
|
||
- `P0281` [Normal] • 设备不根据 engine_mode 改变实时音视频采集和播放逻辑。该字段只用于云端诊断、成本统计和通话记录。
|
||
- `P0282` [Normal] • 联调过程中，双方共同维护问题清单，记录问题现象、设备编号、通话编号、发生时间、日志关联编号、责任方、解决结果和回归结论。
|
||
- `P0283` [heading 2] 7.6 必须联合验证的交接场景
|
||
- `P0284` [Normal] • SaaS判定设备未绑定、授权不足或额度达到时，Agent不创建房间和供应商任务，设备获得稳定错误码。
|
||
- `P0285` [Normal] • SaaS校验通过但Agent准备背景资料失败时，本次通话进入可诊断失败状态，网页和设备看到同一结果。
|
||
- `P0286` [Normal] • Agent已经创建房间但设备未入房时，预留到期后自动清理，不产生供应商语音任务。
|
||
- `P0287` [Normal] • 家庭用户在通话中撤回更严格授权或运营人员停止通话时，SaaS生成操作请求，Agent停止任务并向设备下发动作。
|
||
- `P0288` [Normal] • Agent写入故事候选后，SaaS页面可以跳转到字幕来源；家庭用户确认后，Agent在下一次通话中能检索新记忆。
|
||
- `P0289` [Normal] • 设备上传录音失败不影响字幕和故事页面；录音完成校验后，网页状态和设备本地删除动作最终一致。
|
||
- `P0290` [heading 1] 8. 数据如何保存、使用和删除
|
||
- `P0291` [Normal] 本章说明从最终字幕到正式记忆的处理过程，以及账号、家庭、长者、设备、通话、录音和隐私请求等数据对象之间的关系。程序表名和字段名只作为开发参考，业务含义均使用中文说明。
|
||
- `P0293` [Normal] 图 4 从原始对话到可用于后续交流的记忆
|
||
- `P0294` [heading 2] 8.1 核心数据对象和主责角色
|
||
- `P0296` [heading 2] 8.2 通用数据规则
|
||
- `P0297` [Normal] • 所有业务编号使用不可猜测的随机编号。所有客户组织业务数据明确保存客户组织编号。
|
||
- `P0298` [Normal] • 客户组织编号、长者编号和资源权限必须从登录信息和服务端关系中推导，不能相信浏览器或设备自行上报的客户组织边界。
|
||
- `P0299` [Normal] • 时间统一保存为协调世界时，并带完整时区格式。设备同时上报单调时钟，用于对齐录音和字幕时间。
|
||
- `P0300` [Normal] • 授权、故事、记忆、配置和费用均采用版本化保存。逻辑删除、法律或审计保留、最终物理清除分别建模。
|
||
- `P0301` [Normal] • 短期入房凭证、云端文件存储短期上传或下载地址、供应商长期密钥不得写入业务数据库。
|
||
- `P0302` [Normal] • 数据库字段、云端文件存储路径、向量索引附加信息和缓存键都必须包含或可推导明确的客户组织和长者边界。
|
||
- `P0303` [Normal] • 任何模型生成内容都要保存来源和生成版本。没有来源的机器内容不能进入人工确认流程。
|
||
- `P0304` [heading 2] 8.3 分项授权及撤回后的处理
|
||
- `P0306` [heading 2] 8.4 每次通话的数据保存方式
|
||
- `P0308` [heading 2] 8.5 数据生命周期的共同原则
|
||
- `P0309` [Normal] • 原始字幕先经过授权和敏感信息检查，再生成摘要、故事或事实候选。
|
||
- `P0310` [Normal] • 候选内容只有在有权限的家庭用户确认后，才能成为正式记忆。
|
||
- `P0311` [Normal] • 正式记忆仍然保留来源、确认人、版本和敏感级别，不能与原始来源脱离。
|
||
- `P0312` [Normal] • 撤回授权、停用、修订或删除后，新通话立即停止使用旧内容；后台继续清理数据库、对象和外部索引。
|
||
- `P0313` [Normal] • 任何后台清理都应显示处理中、成功或部分失败状态，不能仅凭数据库软删除就向用户显示全部完成。
|
||
- `P0314` [heading 1] 9. 接口通用规则、状态通知和错误提示
|
||
- `P0315` [Normal] 本章列出所有接口共同遵守的规则，以及网页管理接口、服务器推送事件和稳定错误码。接口路径与程序错误码必须保持精确，因此在中文解释旁保留原始代码。
|
||
- `P0316` [heading 2] 9.1 所有接口共同遵守的规则
|
||
- `P0317` [Normal] • 网页管理接口统一使用“/api/v1”作为基础路径；设备通信接口统一使用“/device/v2”；供应商状态通知接口统一使用“/callbacks/v1”。
|
||
- `P0318` [Normal] • 请求和响应使用 JSON。错误响应使用统一格式，至少包含稳定错误码、中文说明、请求关联编号、是否可以重试和必要的字段级错误详情。
|
||
- `P0319` [Normal] • 会产生写入、启动、停止、导出或删除等外部影响的 POST 请求，必须携带“Idempotency-Key（重复请求识别码）”。服务端在有效窗口内保存结果，并检查同一识别码的请求内容是否一致。
|
||
- `P0320` [Normal] • 列表接口使用不透明的下一页标记（程序字段 cursor）和每页数量。默认每页 20 条，最大值由具体接口说明。
|
||
- `P0321` [Normal] • 修改资源时使用版本标记（ETag/If-Match）或显式版本号。发现多人并发修改时返回冲突，不静默覆盖。
|
||
- `P0322` [Normal] • “X-Request-Id”只用于串联日志和故障排查，不能作为身份认证或重复请求凭据。
|
||
- `P0323` [Normal] • OpenAPI 接口文件是前后端和设备端的接口事实来源。持续集成自动检查字段类型生成和破坏性变更。
|
||
- `P0324` [Normal] • 接口响应不返回云端文件存储桶名称、内部数据库主键、供应商长期密钥、完整供应商原始错误、完整提示词或永久录音地址。
|
||
- `P0325` [heading 2] 9.2 网页管理接口资源
|
||
- `P0327` [heading 2] 9.3 网页状态通知事件
|
||
- `P0329` [heading 2] 9.4 稳定错误码
|
||
- `P0331` [heading 1] 10. 安全、隐私与权限要求
|
||
- `P0332` [heading 2] 10.1 各类凭证放在哪里
|
||
- `P0335` [heading 2] 10.2 用户、家庭、长者和资源权限
|
||
- `P0336` [Normal] • 用户身份通过标准身份服务确认。访问一个资源时，同时检查用户是否属于当前客户组织、在家庭中的角色、对该长者是否具有代理或管理权限，以及是否获得具体资源的分享授权。
|
||
- `P0337` [Normal] • 家庭所有者或管理员不自动获得原录音访问权。收听和下载必须分别有明确授权。
|
||
- `P0338` [Normal] • 设备只能访问自身当前绑定长者的通话、配置、录音上传和遥测资源。设备不能按任意长者编号请求数据。
|
||
- `P0339` [Normal] • 内部运营入口启用强制多因素认证、最小权限、临时权限提升和完整审计。客服默认看不到字幕正文和原录音。
|
||
- `P0340` [Normal] • 云端文件存储访问和向量检索使用与业务接口相同的客户组织和长者边界，不能只在网页层判断权限。
|
||
- `P0341` [Normal] • 所有管理动作、授权、播放、下载、故事确认、配置发布、设备吊销和长期密钥轮换都写入审计。
|
||
- `P0342` [heading 2] 10.3 数据保护
|
||
- `P0343` [Normal] • 所有网络接口使用 TLS 1.2 或更高版本。设备接口使用双向证书认证或经过批准的每设备独立请求签名。
|
||
- `P0344` [Normal] • PostgreSQL、数据库备份和云端文件存储使用云端密钥管理服务加密；云端文件存储桶禁止公开读取。
|
||
- `P0345` [Normal] • 日志默认不记录姓名全文、完整字幕、完整提示词、Wi-Fi 密码或详细网络信息、短期入房凭证、云端文件存储短期地址和完整文件路径。
|
||
- `P0346` [Normal] • 高敏感数据进入模型或故事整理前执行识别、最小化和策略过滤。对于验证码、账户信息和敏感医疗数据，默认不进入普通故事内容。
|
||
- `P0347` [Normal] • 导出文件加密存储，只提供短期下载地址，到期自动清理；每次下载生成访问审计。
|
||
- `P0348` [Normal] • 数据删除覆盖 PostgreSQL 正文、缓存、云端文件存储、pgvector、自有或供应商记忆索引和导出文件，并通过对账确认各处结果。
|
||
- `P0349` [heading 2] 10.4 安全开发要求
|
||
- `P0350` [Normal] • 持续集成自动执行密钥泄露扫描、静态代码安全检查、依赖漏洞与许可证检查、软件材料清单、容器镜像和基础设施配置检查。
|
||
- `P0351` [Normal] • 所有外部输入限制请求体大小、数组长度、字符串长度和嵌套深度。JSON、供应商通知、录音分片清单和文件元数据都必须按结构规则校验。
|
||
- `P0352` [Normal] • 按设备、用户、客户组织和网络地址分别限流。启动语音智能体的请求还要受到供应商每秒请求数和同时任务数保护。
|
||
- `P0353` [Normal] • 生产环境的对外访问白名单只允许火山引擎与豆包、云端文件存储、用户登录服务、时间服务和必要监控目标。
|
||
- `P0354` [Normal] • 上线前必须完成客户组织越权、云端文件存储越权、供应商通知重放、提示注入、长期密钥泄露和遗留语音任务专项测试。
|
||
- `P0355` [heading 1] 11. 性能、可靠性与兼容性要求
|
||
- `P0357` [heading 2] 11.1 服务指标
|
||
- `P0359` [heading 2] 11.2 可靠性
|
||
- `P0360` [Normal] • 供应商状态通知和所有后台任务按“可能重复送达”设计，业务处理必须支持重复执行而不产生重复副作用。
|
||
- `P0361` [Normal] • 启动、停止、录音上传、数据导出、数据删除和设备命令均支持安全重试，并有最终状态对账。
|
||
- `P0362` [Normal] • 接口服务单实例重启、Redis 重启和后台任务进程重启不能产生双重供应商任务或永久卡住的通话。
|
||
- `P0363` [Normal] • 数据库结构升级应可以回滚，或提供明确的前向修复方案；生产发布支持滚动更新。
|
||
- `P0364` [Normal] • 供应商故障时，云端暂停创建新的供应商任务，继续回收已知任务，保持历史网页数据可访问并产生告警。
|
||
- `P0365` [heading 2] 11.3 首期压力测试基线
|
||
- `P0366` [Normal] 实时语音和大文件不经过自建应用服务器，因此压力测试重点是通话状态、供应商通知、数据库、网页状态推送和后台任务。下表是最低验收负载，正式生产容量在启动阶段根据设备注册数、日活跃设备数和同时通话数再确认。
|
||
- `P0368` [heading 2] 11.4 可维护性和兼容性
|
||
- `P0369` [Normal] • 后端核心模块单元测试覆盖率目标不低于 70%；通话状态、权限、删除和供应商对接的关键分支不低于 85%。
|
||
- `P0370` [Normal] • 接口说明、数据库升级脚本、配置结构和状态通知结构均进行版本控制和兼容性检查。
|
||
- `P0371` [Normal] • 日志、指标和调用链统一使用请求关联编号、设备编号、通话编号、供应商任务编号和录音上传批次编号，便于跨系统排查。
|
||
- `P0372` [Normal] • 网页前端支持最近两个主流版本的 Chrome、Edge 和 Safari；核心页面适配 1280 像素以上桌面，并兼顾平板。
|
||
- `P0373` [Normal] • 首期语言为中文；时间、时区和文案结构应支持后续增加其他语言。
|
||
- `P0374` [heading 1] 12. 云资源、部署与运行维护要求
|
||
- `P0375` [heading 2] 12.1 环境划分
|
||
- `P0377` [heading 2] 12.2 起步资源配置
|
||
- `P0379` [heading 2] 12.3 配置和长期密钥管理
|
||
- `P0380` [Normal] • 开发、上线前验证和生产环境分别使用独立的火山引擎应用编号、接口凭证、状态通知地址、数据库和云端文件存储桶。
|
||
- `P0381` [Normal] • 配置分为普通技术配置、受控业务配置和长期密钥。普通配置可以随代码版本管理；长期密钥只保存引用，不保存明文。
|
||
- `P0382` [Normal] • 供应商配置、人设、音色、语音处理路由、额度和数据保留策略使用发布版本，支持审计和回滚。
|
||
- `P0383` [Normal] • 轮换长期密钥不需要重新构建容器镜像。轮换步骤、验证方式和回退方式写入运维手册。
|
||
- `P0384` [heading 2] 12.4 监控与告警
|
||
- `P0386` [Normal] • 告警至少覆盖供应商不可用、语音任务启动或停止异常、遗留任务、数据库或 Redis 故障、证书过期、供应商通知积压、删除超期、录音上传失败和费用异常增长。
|
||
- `P0387` [Normal] • 分别提供业务仪表盘、技术仪表盘和安全仪表盘。告警信息包含对应运维手册链接和设备、通话或请求关联编号。
|
||
- `P0388` [heading 2] 12.5 备份、恢复与故障演练
|
||
- `P0389` [Normal] • PostgreSQL 使用自动备份和时间点恢复，并定期在隔离环境中实际恢复验证。
|
||
- `P0390` [Normal] • 云端文件存储启用版本、生命周期和删除保护策略；正式删除流程必须能够按确认规则清除历史版本。
|
||
- `P0391` [Normal] • Redis 按可重新生成的缓存处理，不能作为唯一业务证据。
|
||
- `P0392` [Normal] • 每次正式发布前后保留数据库升级备份点。项目至少完成数据库恢复、长期密钥轮换、供应商故障和隐私删除四类演练。
|
||
- `P0393` [heading 1] 13. 测试、验收与上线条件
|
||
- `P0394` [heading 2] 13.1 测试层次
|
||
- `P0396` [heading 2] 13.2 必须通过的业务场景
|
||
- `P0397` [Normal] 1. 真实或模拟设备能够完成“创建通话—进入房间—确认入房—启动智能体—双向交流—挂断—停止任务—通话完成”的完整流程，设备、供应商和数据库状态一致。
|
||
- `P0398` [Normal] 2. 创建、确认入房、发送心跳和停止请求分别重复发送时，不产生双通话、双供应商任务、重复用量或错误最终状态。
|
||
- `P0399` [Normal] 3. 设备进入房间失败或房间预留过期时，供应商语音任务不会提前启动。
|
||
- `P0400` [Normal] 4. 启动语音智能体接口超时且结果未知时，云端保持同一供应商任务编号，通过状态通知或查询确认结果，不盲目创建新任务。
|
||
- `P0401` [Normal] 5. 设备突然断电、断网或退出房间后，后台自动停止并回收供应商语音任务。
|
||
- `P0402` [Normal] 6. 端到端语音、端到端语音加记忆工具、语音识别—大模型—语音合成三段式可以按新通话切换，终端入房和音频采播方式保持一致。
|
||
- `P0403` [Normal] 7. 供应商状态通知重复、延迟或乱序到达时，最终字幕、通话状态和用量不重复并最终一致。
|
||
- `P0404` [Normal] 8. 两位长者交替通话时，长者背景资料、记忆检索、故事候选和来源字幕不串用。
|
||
- `P0405` [Normal] 9. 分别撤回最终字幕、原录音、故事整理、个性化记忆和家庭协作授权后，各相关处理立即采用更严格策略。
|
||
- `P0406` [Normal] 10. 长者声音和智能体声音录音分片出现重复上传、漏传、错误校验值、过期上传地址或云端文件存储延迟可见时，均有明确且最终一致的结果。
|
||
- `P0407` [Normal] 11. 没有录音访问授权的家庭所有者、管理员、编辑者和查看者均无法播放或下载原录音。
|
||
- `P0408` [Normal] 12. 故事候选没有来源时不能确认；人工修改保留版本；被拒绝的候选不进入正式记忆。
|
||
- `P0409` [Normal] 13. 删除请求覆盖数据库正文、云端文件存储、自有向量索引、供应商记忆和导出文件，并能查看每个子系统的失败和重试。
|
||
- `P0410` [Normal] 14. 被吊销设备、过期入房凭证、错误房间和错误用户无法建立有效通话。
|
||
- `P0411` [Normal] 15. 火山引擎或豆包服务故障时，系统暂停新任务，回收已知任务，历史网页数据仍可访问并产生告警。
|
||
- `P0412` [Normal] 16. 生产长期密钥不出现在代码仓库、容器镜像、日志、错误响应、网页前端和业务数据库中。
|
||
- `P0413` [heading 2] 13.3 上线条件
|
||
- `P0414` [Normal] • 所有首期需求、验收用例、缺陷和遗留风险已经形成可追踪对应关系，阻断级缺陷为 0。
|
||
- `P0415` [Normal] • 使用真实火山引擎账号完成短期入房凭证、启动、更新、停止、三种语音处理方式、字幕与状态通知、用量和配额验证。
|
||
- `P0416` [Normal] • 接口说明、数据库升级、配置、运维手册、监控、告警、备份恢复和安全扫描全部通过持续集成检查。
|
||
- `P0417` [Normal] • 客户组织隔离、录音越权、供应商通知重放、遗留任务回收和隐私删除专项测试通过。
|
||
- `P0418` [Normal] • 生产域名、证书、长期密钥、用户登录、云端文件存储、备份、告警接收人和应急联系人已经配置。
|
||
- `P0419` [Normal] • 业务方、外包团队和硬件团队完成联合验收，并签署上线检查清单。
|
||
- `P0420` [heading 2] 13.4 两个角色分别需要提供的验收证据
|
||
- `P0422` [heading 2] 13.5 新增的Agent质量验收场景
|
||
- `P0423` [Normal] 17. 长者说话较慢、停顿较长或重复表达时，智能体不会频繁抢话，并能自然确认不清楚的信息。
|
||
- `P0424` [Normal] 18. 智能体一次只推进一个主要问题，回答长度适合听筒收听；被打断后不继续播放已经失效的长回答。
|
||
- `P0425` [Normal] 19. 已确认记忆、机器候选和模型推断被清楚区分；不存在把未确认内容说成过去事实的情况。
|
||
- `P0426` [Normal] 20. 故事和事实候选的关键内容均可追溯到字幕；家庭用户高频修改和拒绝的问题可以按模型版本统计。
|
||
- `P0427` [Normal] 21. 提示词、人设、音色、模型和路由的新版本经过评测、灰度和回滚验证，错误配置不能直接影响全部设备。
|
||
- `P0428` [heading 1] 14. 外包交付内容与协作规则
|
||
- `P0429` [Normal] 交付物既要覆盖每个角色独立负责的代码和文档，也要覆盖两个角色的内部接口、端云联调和共同运维。验收时不能只检查网页或只检查语音通话，需要证明完整业务闭环可以复现。
|
||
- `P0430` [heading 2] 14.1 按角色划分的交付物
|
||
- `P0432` [heading 2] 14.2 通用交付内容
|
||
- `P0434` [heading 2] 14.3 代码、账号和资产归属
|
||
- `P0435` [Normal] • 代码仓库、持续集成与部署账号、云资源账号和域名由业务方控制。外包人员使用实名、最小权限账号。
|
||
- `P0436` [Normal] • 所有第三方依赖列明许可证、版本和用途。未经批准，不得引入限制商业使用或来源不明的组件。
|
||
- `P0437` [Normal] • 所有配置和文档纳入项目仓库管理。个人网盘、个人云账号和个人长期密钥不得进入正式交付链路。
|
||
- `P0438` [Normal] • 交付完成时移除外包人员个人权限，并完成生产权限、密钥管理、用户登录、监控和告警接收人的正式移交。
|
||
- `P0439` [heading 2] 14.4 变更和评审
|
||
- `P0440` [Normal] • 架构、权限、数据保留、接口不兼容变更、外部供应商和新增付费服务必须提交变更单。
|
||
- `P0441` [Normal] • 变更单至少说明变更原因、影响范围、兼容性、数据迁移、费用、安全、测试和回退方案。
|
||
- `P0442` [Normal] • 每个研发阶段进行代码、接口、数据和安全评审，评审结论和待办事项进入项目跟踪系统。
|
||
- `P0443` [Normal] • 演示通过不能替代自动化测试、正式文档、异常清理路径和真实账号验证证据。
|
||
- `P0444` [heading 2] 14.5 单项任务完成标准
|
||
- `P0445` [Normal] • 需求编号已经关联对应代码、测试、接口或配置变更。
|
||
- `P0446` [Normal] • 正常、超时、重试、重复、乱序、撤回、删除和清理路径均有测试结果。
|
||
- `P0447` [Normal] • 日志、指标和调用链可以定位问题，同时不泄露个人数据和长期密钥。
|
||
- `P0448` [Normal] • 数据库升级、回滚或前向修复、接口说明、项目说明和运维手册已经同步更新。
|
||
- `P0449` [Normal] • 代码完成评审，持续集成全部通过，阻断级安全问题为 0。
|
||
- `P0450` [Normal] • 功能已经部署到目标环境，并通过业务方可以独立复现的验收步骤。
|
||
- `P0451` [heading 1] 15. 研发阶段与首批任务
|
||
- `P0452` [heading 2] 15.1 两个角色并行推进的研发阶段
|
||
- `P0454` [heading 2] 15.2 硬件联调最小闭环
|
||
- `P0455` [heading 3] 15.2.1 目标
|
||
- `P0456` [Normal] 优先打通真实设备与云端之间的会前握手和实时语音闭环。设备先从自建云端取得本次通话编号、房间资料、短期入房凭证、需要订阅的智能体用户编号和控制参数；设备确认已经进入房间后，云端再启动豆包语音智能体。该阶段按可验证完成条件验收，不以固定周数作为完成判断。
|
||
- `P0457` [heading 3] 15.2.2 本阶段建设内容
|
||
- `P0458` [Normal] • 一套可以持续部署的共享开发环境，包括SaaS业务服务、Agent编排服务、PostgreSQL、Redis、供应商状态通知接收服务、模拟供应商、模拟设备和最小联调工作台。
|
||
- `P0459` [Normal] • 设备独立身份、设备启动信息、基础配置版本、服务器时间同步、设备能力表、最低固件策略和请求审计。
|
||
- `P0460` [Normal] • 两阶段通话启动：先创建通话并下发房间资料，设备成功进入房间后再确认入房并启动语音智能体。
|
||
- `P0461` [Normal] • 真实语音链路先使用固定的端到端语音模式、单一音色和单一供应商配置，验证设备、实时音视频和语音智能体的稳定配合；程序字段保留后续切换能力。
|
||
- `P0462` [Normal] • 最小长者背景资料，包括固定智能体人设、安全规则、测试长者称呼、少量测试背景和本次交流目标。
|
||
- `P0463` [Normal] • 完整任务控制，包括启动、停止、心跳、短期租约、超时、供应商状态通知、后台异常回收和统一错误提示。
|
||
- `P0464` [Normal] • 联调可观测性：请求关联编号、设备编号、通话编号、房间编号和供应商任务编号在日志和工作台中可以互相定位，同时不显示完整短期凭证。
|
||
- `P0465` [heading 3] 15.2.3 会前握手和语音启动步骤
|
||
- `P0466` [Normal] 1. 设备开机后使用独立身份访问“GET /device/v2/bootstrap”，上报型号、固件版本和设备时间，完成服务器时间同步、设备状态和最低固件版本检查。
|
||
- `P0467` [Normal] 2. 设备访问“GET /device/v2/config”，提交当前配置版本和能力信息，获取实时音视频编码、采样率、心跳间隔、上传策略和其他非敏感运行配置。
|
||
- `P0468` [Normal] 3. 用户拿起听筒后，设备携带“Idempotency-Key（重复请求识别码）”调用“POST /device/v2/conversations”，请求创建本次通话。
|
||
- `P0469` [Normal] 4. SaaS角色检查设备状态、长者绑定、测试授权、同时通话限制和额度；Agent角色继续创建通话，生成通话编号、房间编号、设备用户编号、智能体用户编号和固定供应商任务编号。
|
||
- `P0470` [Normal] 5. Agent角色整理最小长者背景资料，并使用实时音视频应用密钥为指定房间和用户生成短期入房凭证。响应中不包含应用密钥、火山引擎访问密钥或豆包长期凭证。
|
||
- `P0471` [Normal] 6. 设备按照响应中的应用编号、房间编号、设备用户编号和短期入房凭证加入实时音视频房间，开始发送麦克风语音，并订阅智能体用户编号。
|
||
- `P0472` [Normal] 7. 设备收到“加入房间成功”事件后，调用“POST /device/v2/conversations/{id}/activate”，上报加入时间、实时音视频状态和当前配置版本。云端可以结合火山引擎房间通知二次核验。
|
||
- `P0473` [Normal] 8. Agent角色把通话从“房间资料已下发”改为“正在启动智能体”，使用创建通话时固定的供应商任务编号调用 StartVoiceChat，成功后进入“通话中”。
|
||
- `P0474` [Normal] 9. 通话期间设备定期发送心跳，上报实时音视频、网络、固件、本地录音队列和设备状态；SaaS角色与Agent角色合并返回续租、配置更新、短期凭证续签或停止动作。
|
||
- `P0475` [Normal] 10. 用户挂断后，设备调用停止接口。Agent角色重复执行也安全地调用 StopVoiceChat，并等待供应商通知或查询把通话改为“已完成”。设备失联、房间预留过期或租约超时由后台自动回收。
|
||
- `P0476` [heading 3] 15.2.4 握手关键字段
|
||
- `P0478` [heading 3] 15.2.5 联调工作台和交付件
|
||
- `P0479` [Normal] • 最小联调工作台显示设备在线状态、固件、配置版本、当前通话、通话状态、短期凭证签发与过期时间、实时音视频状态、智能体状态、供应商通知和最近错误；不显示完整短期凭证。
|
||
- `P0480` [Normal] • 支持按设备编号、通话编号、房间编号、供应商任务编号和请求关联编号查询；有权限人员可以执行停止、状态对账和测试配置刷新。
|
||
- `P0481` [Normal] • 交付设备通信接口 OpenAPI、请求响应样例、设备接入说明、通话状态说明、错误码、测试设备证书发行说明和可运行模拟设备。
|
||
- `P0482` [Normal] • 交付真实火山引擎账号的脱敏标准请求响应、状态通知样例、环境配置清单、日志字段、监控仪表盘和联调故障排查手册。
|
||
- `P0483` [Normal] • 硬件团队提供设备能力表、实时音视频加入房间成功和失败事件、心跳字段、挂断原因、本地时间和固件版本；双方共同维护联调问题清单。
|
||
- `P0484` [heading 3] 15.2.6 验收标准
|
||
- `P0485` [Normal] • 一台真实设备可以完成设备启动、读取配置、创建通话、加入实时音视频房间、确认入房、实时双向语音、发送心跳、挂断、停止和任务回收的完整闭环。
|
||
- `P0486` [Normal] • 设备、接口响应、网页、日志、数据库和容器镜像中不存在实时音视频应用密钥、火山引擎访问密钥、豆包长期凭证或完整短期入房凭证。
|
||
- `P0487` [Normal] • 错误房间、错误用户、过期短期凭证和被吊销设备无法进入有效通话；正常凭证可以在有效期内入房。
|
||
- `P0488` [Normal] • 创建、确认入房、心跳和停止请求重复发送时，不产生双通话、双供应商任务、重复计量或错误最终状态。
|
||
- `P0489` [Normal] • 真实设备连续完成至少 10 次通话；每次供应商任务、房间、租约和通话状态最终完成，无遗留的“通话中”或“正在停止”任务。
|
||
- `P0490` [Normal] • 设备创建通话后未入房、入房后未确认、通话中断网、设备重启和云端重启时，均能超时回收或恢复，并形成可以定位的错误记录。
|
||
- `P0491` [Normal] • 联调工作台能够追踪握手各步骤耗时、启动和停止结果、供应商通知和错误码；硬件人员可以独立按照文档复现完整流程。
|
||
- `P0492` [Normal] • 最小长者背景资料正确带入测试称呼、背景和本次交流目标，证明背景资料由云端整理并随本次通话生效。
|
||
- `P0494` [heading 2] 15.3 首批可以立即启动的任务
|
||
- `P0496` [heading 1] 16. 启动前需要确认的事项
|
||
- `P0497` [Normal] 以下事项不影响代码仓库、通话状态、核心数据对象、模拟供应商和网页基础框架启动，但涉及真实账号、生产部署和用户数据的功能应在对应研发阶段开始前确认。
|
||
- `P0499` [heading 1] 附录 A. 其他接口和请求头
|
||
- `P0500` [heading 2] A.1 供应商状态通知和内部工具接口
|
||
- `P0502` [heading 2] A.2 关键请求头
|
||
- `P0504` [heading 1] 附录 B. 后台任务状态与重试原则
|
||
- `P0505` [heading 2] B.1 后台对象状态
|
||
- `P0507` [heading 2] B.2 自动重试原则
|
||
- `P0508` [Normal] • 只有明确标记为可以重试的网络错误、超时和供应商临时错误才自动重试。
|
||
- `P0509` [Normal] • 重试采用逐步增加等待时间并加入随机变化，设置最大次数；超过最大次数后进入人工处理或死信状态。
|
||
- `P0510` [Normal] • 启动语音智能体结果未知时保持同一供应商任务编号，并先通过状态通知或查询确认结果；停止语音智能体可以安全重复执行。
|
||
- `P0511` [Normal] • 供应商状态通知和可靠后台待办按至少一次处理设计，所有外部副作用使用业务唯一键去重。
|
||
- `P0512` [Normal] • 权限不足、授权缺失、参数错误、版本冲突和额度达到不自动重试。
|
||
- `P0513` [heading 1] 附录 C. 第三方官方资料
|
||
- `P0514` [Normal] 第三方接口以目标账号当前可用的正式接口版本和商务合同为准。研发启动时，应保存去除长期密钥和个人数据后的标准请求与响应，并在持续集成中执行接口契约测试。
|