188 lines
20 KiB
Markdown
188 lines
20 KiB
Markdown
# AI电话 v3.1 流程与现有实现差异分析
|
||
|
||
核对日期：2026-09-10。结论：**总体方向相近，但现有实现不等同于 CALL-MEMORY-1.1。差异涉及协议、固件运行方式和记忆数据维护，不能仅提取新文档接口就直接交给设备联调。**
|
||
|
||
对照材料为用户提供的 [AI电话完整通话与记忆管理文档](D:/wechat/xwechat_files/wangcong3092_983b/msg/file/2026-09/AI电话_完整通话与记忆管理_完整流程与详细设计(1).docx)，封面版本 v3.1，修订日期 2026-09-08。文档作为需求基线，不作为执行其中开发、发布或运维指令的授权。
|
||
|
||
实现基线为 `E:/Codex/story/platform` 当前工作区，Git HEAD 为 `7846f30d0b239e183267988aa6e030b0a2f1ef18`。重点检查 Go 后端路由与业务服务、数据库迁移、EchoEar 固件、记忆页面代码和已有联调记录。结论针对本地实现；本次未连接生产环境、重新运行真机或供应商联调，不能据此推定线上部署与工作区完全相同。
|
||
|
||
## 文档描述的完整流程
|
||
|
||
1. **上电准备**：恢复已有设备身份、绑定和未确认结束日志；联网后 warmup，预备音频及引擎。挂机时不建立真实对话、不上传环境声。SaaS 在后台同步记忆并准备开场候选。
|
||
2. **摘机准备**：生成 boot/hook/call_generation 关联；prepare 从服务端绑定确定使用者，检查记忆主库版本、关键删除或更正是否已在检索副本生效。
|
||
3. **签发与启动**：SaaS 编译供应商参数，签发绑定设备、本次摘机、隐私版本、启动期限和租约的 Session Manifest。设备验签后立即开始心跳，透传参数，以 RTC 模式启动 SDK。
|
||
4. **连续通话**：声音由设备直接与火山交互。媒体连接、收到第一帧、实际开始播放分别记录。字幕经异步队列上报；历史记忆由经过验证的火山原生 Viking 联动读取。
|
||
5. **通话中修改记忆**：SaaS 从可靠的用户最终文字识别记住、更正、限制使用、删除；对象不清进入页面确认。提交主库后分别跟踪副本、派生内容和旧会话清理，必要时下发 STOP_CALL。
|
||
6. **挂机收尾**：本地先关闭上下行与待播音频，再停止 SDK、补报 end。SaaS 将通话结束和字幕完整度分开记录；字幕静默收齐初值 15 秒、绝对等待 60 秒。
|
||
7. **维护记忆与准备下一通**：从用户证据提取候选，处理冲突和删除屏障，提交 SaaS 主库与 outbox；按主记录版本同步 Viking 事件及画像，验证检索可见性，再推进连续同步进度。下次摘机重新检查。
|
||
|
||
文档强调四个结果分别成立：**通话结束、字幕收齐、记忆保存、检索可见**。普通新增同步慢可以按安全模式继续；更正、删除和权限变化不能沿用不安全的旧资料。
|
||
|
||
## 现有流程
|
||
|
||
当前 EchoEar 主路径为：
|
||
|
||
```text
|
||
上电恢复平台及火山凭据，尝试补报上次未结束会话，初始化音频与引擎
|
||
→ 触摸或唤醒触发对话
|
||
→ bootstrap + config + POST /device/v3/agent-sessions
|
||
→ 后端冻结使用者、授权和上下文，返回 runtime + session_config
|
||
→ 固件组装 session.update，使用 VOLC_MODE_WS 启动
|
||
→ session.created/updated 后上报 session_started
|
||
→ 通过 session_updated 周期续期，异步上传最终字幕
|
||
→ volc_stop + session_ended/session_failed，清理播放器
|
||
→ SaaS 摘要/故事/候选处理
|
||
→ 另一路将通话文字 AddSession 到 Viking 自动抽取
|
||
```
|
||
|
||
入口依据：[固件创建会话](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:558)、[SDK 启动与退出](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:389)、[后台任务装配](E:/Codex/story/platform/internal/app/app.go:427)。
|
||
|
||
## 可以复用的实现
|
||
|
||
| 能力 | 已有实现 | 对齐程度 |
|
||
|---|---|---|
|
||
| 设备认证与服务端确定使用者 | HMAC、防重放、设备有效绑定；会话保存 subject_id 和授权快照 | 方向一致，认证报文及绑定代数协议不同 |
|
||
| 音频与业务链路分开 | 设备直接调用火山 SDK，平台接收控制信息与文字 | 方向一致，EchoEar 实际使用 WS |
|
||
| 共享助手和用户记忆范围 | Bot 配置、稳定助手标识、租户与使用者派生的 Viking user_id | 已有基础，不能替代供应商侧防篡改授权验证 |
|
||
| 异步文字上报 | SDK 回调投递内存队列，业务任务发 HTTPS，后端事务保存并去重 | 主思路一致，缺修订、缺口和持久重试协议 |
|
||
| 结束恢复 | NVS 保存待结束会话，重启补报；后端支持结束状态及迟到最终文字 | 已有基础，缺未取得 SID 的取消及独立远端停止证明 |
|
||
| 后台摘要与人工记忆维护 | 用户文字来源、摘要、故事、候选、人工确认、记忆版本、编辑/停用/删除、索引 outbox | 已有基础，与 Viking 自动抽取副本未统一 |
|
||
|
||
证据：[会话归属与上下文快照](E:/Codex/story/platform/internal/orchestration/repository.go:293)、[字幕保存与原会话归属](E:/Codex/story/platform/internal/orchestration/transcript_batch.go:127)、[仅用户文字参与抽取](E:/Codex/story/platform/internal/extraction/processor.go:94)、[人工记忆维护](E:/Codex/story/platform/internal/saas/content_service.go:568)。
|
||
|
||
## 关键差异及影响
|
||
|
||
### 1 设备接口与认证不兼容
|
||
|
||
文档附件 B 定义七个 `POST /api/v1/device/calls/*` 接口；当前注册的是 `/device/v2/*` 和 `/device/v3/agent-sessions*`。这七个新路径没有注册。
|
||
|
||
认证也不只是换路径：
|
||
|
||
| 项目 | v3.1 文档 | 当前实现 |
|
||
|---|---|---|
|
||
| 时间 | `X-Timestamp-Ms`，Unix 毫秒 | `X-Device-Timestamp`，RFC3339 |
|
||
| 签名入口 | `Authorization: Device-HMAC-SHA256 ...` | `X-Device-Signature` |
|
||
| 签名内容 | DEVREQ1 开头的九行，含设备、密钥版本、请求 ID | 方法、含查询串的 RequestURI、时间、nonce、body hash 五行 |
|
||
| 签名编码 | 小写十六进制 | 无填充 Base64url |
|
||
| 响应 | `ok/code/request_id/server_time_ms/data` | `request_id/data/error` |
|
||
|
||
现有 HMAC 本身已经实现，但不兼容文档的线协议。直接按文档开发新固件会遇到路由或验签失败。
|
||
|
||
证据：[设备路由](E:/Codex/story/platform/internal/httpapi/router.go:308)、[认证头及验签](E:/Codex/story/platform/internal/deviceauth/verifier.go:22)、[当前签名算法](E:/Codex/story/platform/internal/deviceauth/verifier.go:142)、[响应封装](E:/Codex/story/platform/internal/httpapi/response.go:8)。
|
||
|
||
### 2 固件实际使用 WS 而文档固定 RTC
|
||
|
||
文档附件 C 要求 `mode=RTC`，映射 `VOLC_MODE_RTC`。当前 EchoEar 能力声明只有 `low_load`，实际 `volc_start` 参数写的是 `VOLC_MODE_WS`。
|
||
|
||
后端保留 high_quality/low_load 两类能力，并不等于当前固件已经按 RTC 流程运行。切换需要核对 RTC 参数通道、字幕格式、首音频、打断和 stop 行为，不能只改枚举后视为完成。
|
||
|
||
证据：[固件能力声明](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:569)、[实际 SDK 模式](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:439)、[后端传输校验](E:/Codex/story/platform/internal/orchestration/repository.go:614)。
|
||
|
||
### 3 没有新版会话清单及摘机取消机制
|
||
|
||
文档要求 `boot_id + hook_event_id` 唯一业务键，独立 `call_generation`、`binding_generation`、`media_attempt_id`，以及 `manifest_b64/manifest_mac`。即使 end 先于 prepare 到达，也要保存取消记录，阻止晚到 prepare 启动。
|
||
|
||
当前创建请求使用 `Idempotency-Key`，返回 `session_nonce/config_digest/runtime/session_config`；具有请求幂等和配置摘要，但没有上述清单结构、按摘机取消、清单撤销及代数校验。当前摘要也不是文档要求的清单 HMAC。尚未取得 conversation_id 时没有等价的结束入口。
|
||
|
||
证据：[请求与响应结构](E:/Codex/story/platform/internal/orchestration/types.go:95)、[创建幂等入口](E:/Codex/story/platform/internal/orchestration/hardware_agent.go:31)、[固件响应处理](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:584)。
|
||
|
||
### 4 心跳起点与本地租约停止不同
|
||
|
||
文档要求验清单后立即开始心跳，与 SDK 启动并行；默认周期 5 秒、租约不超过 45 秒。失联时固件依本地保守截止关闭音频；迟到许可不能复活会话。
|
||
|
||
当前固件在上报 session_started 后设置下一次心跳，通过 `session_updated` 续期。默认周期为 15 秒；后端租约按 `HeartbeatInterval × 5` 计算，默认对应 75 秒。心跳网络失败时固件记录错误并再次尝试，没有看到该路径维护本地授权截止或到期静音。
|
||
|
||
这意味着现有服务端超时回收不能等同于文档要求的设备本地有界停止。
|
||
|
||
证据：[固件续期逻辑](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:693)、[启动成功后才轮询](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:459)、[后端租约](E:/Codex/story/platform/internal/orchestration/hardware_agent.go:205)、[默认周期](E:/Codex/story/platform/internal/config/config.go:479)。
|
||
|
||
### 5 供应商参数由固件拼装且开场配置未形成文档流程
|
||
|
||
文档要求 SaaS 基于已验证 provider_profile 编译完整 `vendor_params_json`，设备只透传；热上下文与欢迎语分别产生，且附事实依赖版本。
|
||
|
||
目前后端返回 authorized_context 等结构化字段，固件自行拼接固定话术、LLMConfig、S2SConfig、MemoryConfig 与回调参数。平台虽然有资料、最近摘要、open_topic 和上下文快照，但未形成独立欢迎语、开场候选依赖失效及 provider_profile 能力证据驱动的编译流程。
|
||
|
||
当前上下文对部分字段按字符数裁剪，也未体现文档要求的按完整事实删减并保留否定、日期和条件的规则。
|
||
|
||
证据：[端侧参数组装](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:457)、[上下文与摘要选择](E:/Codex/story/platform/internal/orchestration/repository.go:388)、[开场续聊与裁剪](E:/Codex/story/platform/internal/orchestration/companion_context.go:19)。
|
||
|
||
### 6 Viking 写入路线与文档有实质冲突
|
||
|
||
文档第 11 章要求 SaaS 是记忆事实维护方，Viking 保存已核验主库记录的检索副本。默认不让两边根据原始字幕各自抽取和维护同一份记忆。
|
||
|
||
当前工作器在内容抽取任务中先排入独立 Viking 同步任务；Viking 服务读取 conversation_turn 中的用户和 AI 最终文字，再调用 `/api/memory/session/add`，并设置 `extract_memory_type` 让 Viking 抽取事件及画像。这条任务不以 SaaS curated_memory 提交完成为前置条件。
|
||
|
||
因此当前是“平台内容整理 + Viking 会话自动抽取”两条路径。它不能保证平台更正、停用或删除某条人工记忆后，Viking 独立生成的事件和画像同步发生相同变化。
|
||
|
||
证据：[工作器装配](E:/Codex/story/platform/internal/app/app.go:427)、[同步数据取自通话文字](E:/Codex/story/platform/internal/vikingmemory/service.go:175)、[AddSession 及抽取类型](E:/Codex/story/platform/internal/vikingmemory/client.go:127)。
|
||
|
||
### 7 单条记忆修改删除未贯通 Viking 及旧会话
|
||
|
||
当前平台已经有 `UpdateMemory/RequestMemoryDeletion`、版本比较、本地索引失效和删除任务。另有 `providermemory` 适配器，调用自定义 `/v1/memories:upsert`，它与 `vikingmemory` 是独立模块，不能把前者的完成视为 Viking 原生事件/画像已清理。
|
||
|
||
已有接入说明明确指出：单条本地 curated memory 删除不会删除独立抽取的 Viking 事件/画像，统一管理界面尚未实现。文档要求的 source_suppression、单条投影映射、派生摘要清理及防旧源重抽取尚未贯通。
|
||
|
||
此外，本次在相关源码和迁移中没有找到 `privacy_epoch`、已签发清单撤销目标、对应 `STOP_CALL` 及分阶段本地静音/SDK 停止回执。已有通话停止和授权撤回能力不能替代文档附件 L 的完整机制。
|
||
|
||
证据：[单条删除入口](E:/Codex/story/platform/internal/saas/content_service.go:705)、[本地删除处理](E:/Codex/story/platform/internal/memorylifecycle/delete_processor.go:32)、[独立 provider 适配器](E:/Codex/story/platform/internal/providermemory/client.go:59)、[Viking 已知限制](E:/Codex/story/platform/docs/viking-memory-integration.md:23)。
|
||
|
||
### 8 没有通话前同步水位与关键变更拦截
|
||
|
||
文档要求用户级 memory_revision、viking_visible_revision、关键积压和 EMPTY/IN_SYNC/LAGGING_NORMAL/LAGGING_CRITICAL 等状态。供应商写入成功后还要验证检索可见，且中间版本失败不能被后续成功版本跳过。
|
||
|
||
当前 NativeAccessForDevice 主要检查当前绑定和授权，再返回用户过滤配置；AddSession 成功后记录审计摘要。未看到针对主库记忆版本的连续可见进度、关键删除拦截、NATIVE_VIKING/HOT_ONLY/OFF 模式及关闭旧记忆的验证机制。Viking 获取配置失败当前可仅记录警告后继续创建，这与按关键积压判断是否允许启动不同。
|
||
|
||
证据：[创建时 Viking 处理](E:/Codex/story/platform/internal/orchestration/hardware_agent.go:46)、[原生范围配置](E:/Codex/story/platform/internal/vikingmemory/service.go:84)、[写入与审计](E:/Codex/story/platform/internal/vikingmemory/service.go:208)。
|
||
|
||
### 9 字幕可靠性及结束状态未达到新版要求
|
||
|
||
已实现最终字幕上报、事务落库、重复检测和结束后补入，但当前 turn_key/sequence_no 的同一条内容变化会冲突；没有文档要求的 utterance_id/source_revision 修订和分片结构。
|
||
|
||
固件当前使用 8 项内存消息队列，满时记日志；上报失败后释放消息，未看到对应的持久重试与 GAP_DECLARED。端侧上报把 interrupted 固定为 false，不能据此证明 AI 的整句话已播放。
|
||
|
||
后端 session_ended 会直接完成业务状态并排入抽取，没有独立 DRAINING/COMPLETE/PARTIAL 状态及文档的 15/60 秒收齐窗口。固件退出时先设置 is_stop，但播放器停止在 SDK stop 和网络结束上报之后，未实现文档要求的先立即清空待播内容、分别报告停止证据的顺序。
|
||
|
||
证据：[字幕结构与冲突规则](E:/Codex/story/platform/internal/orchestration/transcript_batch.go:24)、[端侧上报与失败处理](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:713)、[队列及满队列处理](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:330)、[结束与抽取](E:/Codex/story/platform/internal/orchestration/hardware_agent.go:214)、[退出顺序](E:/Codex/story/platform/firmware/echoear-platform-agent/components/application/service/conv_service/src/volc_conv.c:483)。
|
||
|
||
### 10 语音记忆变更确认与事项进度需要补充
|
||
|
||
当前人工记忆编辑能力不等同于文档第 8 章：尚未找到从用户最终文字生成 intent/mutation、来源动作去重、NEEDS_CONFIRMATION、resolve/confirm 冻结方案、六阶段处理进度、PLAY_LOCAL_NOTICE 的整套实现。
|
||
|
||
现有 open_topic 是摘要中的续聊线索；没有文档的稳定 OPEN_ITEM 标识、OPEN/COMPLETED/CANCELLED/UNKNOWN 及计划修订状态机。因此“第一通提计划、第二通报告完成、第三通不再追问”的结果尚不能由当前数据流程保证。
|
||
|
||
证据：[现有记忆页面 API](E:/Codex/story/platform/internal/httpapi/router.go:267)、[现有摘要与 open_topic](E:/Codex/story/platform/internal/extraction/processor.go:284)、[续聊线索选择](E:/Codex/story/platform/internal/orchestration/companion_context.go:70)。
|
||
|
||
## 设备接口对应关系
|
||
|
||
下表只用于说明差异，**不是 CALL-MEMORY-1.1 已实现接口文档**。文档七个接口均为 POST，统一前缀 `/api/v1/device/calls/`。当前对应功能不代表字段、鉴权、幂等和状态语义兼容。
|
||
|
||
| 文档接口 | 当前近似入口或调用 | 主要缺口 |
|
||
|---|---|---|
|
||
| CA01 `warmup` | `GET /device/v2/bootstrap`、`GET /device/v2/config` | 专门 warmup、绑定代数和 provider_profile 准备状态 |
|
||
| CA02 `prepare` | `POST /device/v3/agent-sessions` | 摘机唯一键、签名清单、记忆进度校验、取消先到处理 |
|
||
| CA03 `events` | `POST /device/v3/agent-sessions/{id}/events` 及 `/{id}/turns:batch` | 统一事件批次、逐条 ACK、连续序号、字幕修订/缺口/播放事件 |
|
||
| CA04 `heartbeat` | EchoEar 发送 `session_updated` 到 v3 events；后端另有 v2 conversations heartbeat | 清单后立即心跳、manifest/media/privacy 绑定、绝对租约、本地到期关闭 |
|
||
| CA05 `end` | EchoEar 发送 `session_ended/session_failed`；后端另有 `POST /device/v2/conversations/{id}/stop` | 无 SID 取消、原摘机标识、local_audio_stopped、独立 sdk_stop_status/remote_state |
|
||
| CA06 `status` | `GET /device/v2/conversations/{id}` | boot/hook 查询、清单状态、字幕状态、隐私版本及命令 |
|
||
| CA07 `command-acks` | `POST /device/v2/commands/{id}/ack` | 当前通话代数、MANIFEST_DISCARDED/LOCAL_AUDIO_OFF/SDK_STOPPED 与提示回执 |
|
||
|
||
当前已注册入口见 [router.go](E:/Codex/story/platform/internal/httpapi/router.go:308)。EchoEar 真实调用需以 [platform_client.c](E:/Codex/story/platform/firmware/echoear-platform-agent/main/platform_client.c:611) 为准，不能把后端存在的 v2 能力自动算成当前固件已使用。
|
||
|
||
## 建议的对齐顺序
|
||
|
||
1. **先冻结设备契约与真实供应商组合**：明确按文档 RTC 路线升级；核验动态上下文、原生检索、关闭路径、字幕归属和用户范围授权。文档附件 H 本身也把这些列为待实测能力，不能因代码中存在 MemoryConfig 字段就判定通过。
|
||
2. **补齐启动与撤销协议**：设备 HMAC 契约、warmup/prepare、摘机幂等与取消、Session Manifest、双代数、媒体尝试、首次心跳、本地租约、STOP_CALL 和停止证明。
|
||
3. **统一记忆主库和 Viking 投影**：以 SaaS 主记录为维护入口，补逐条映射、版本、关键积压、可见性、删除防复活及旧会话撤销；解决当前独立 AddSession 抽取与人工维护脱节。
|
||
4. **完善记录和管理交互**：字幕修订与持久重试、收齐状态、变更确认及阶段进度、固定提示能力、OPEN_ITEM 与开场候选失效。
|
||
5. **再形成正式设备接口交付件**：同步 OpenAPI、设备请求/响应、签名测试向量、重试/错误规则、事件/命令回执和真实板卡联调结果。
|
||
|
||
优先回归文档 T04～T07、T12～T14、T20～T31、T39～T48；供应商验证重点为 H02/H03/H05/H06/H12。此处是建议验收范围，不表示本次已执行或通过。
|
||
|
||
## 核对方法和边界
|
||
|
||
- 完整读取了 Word 正文、表格及附件 A～L，并查看了全部 10 张内嵌流程图。
|
||
- 使用实际路由、结构体、调用顺序和持久化代码验证主要差异，并检索相关后端、迁移、固件及前端是否存在新版核心协议字段。
|
||
- 现有运行记录作为历史证据；其中明确保留了真机重启后实际回忆等待验证项。本次没有把旧记录扩大为新版本验收结论。
|
||
- 当前环境的文档渲染器缺少 `soffice.exe`，未取得可核验页码，因此文档依据采用章节/附件定位；未改写或重新导出用户的 Word 文件。
|
||
- 本次只新增这份分析，不修改业务代码；未运行生产调用、设备刷写或发布操作。已有工作区修改保留。
|