Files
CyberGril/docs/rework/hel911/summary.md
T
施工员2号andmultica-agent 4a38106eef HEL-911: fix AgentHandoff/shutdown seams, attribute & fix the 3.66s pre-generation wait
- worker _on_item: filter conversation_item_added by the real 1.8.8 item
  discriminator (ChatMessage | AgentHandoff | _TypeDiscriminator); only
  assistant str-part body feeds the echo filter (HEL-910 AttributeError)
- bind_interrupt_channel unload: async (JobContext shutdown callbacks are
  awaited), idempotent, disconnect-safe; interrupt/receipt/budget paths
  untouched (HEL-910 TypeError await None)
- TURN_HANDLING: explicit turn_detection=None — 1.8.8 silently installs an
  English EOU TurnDetector whose unlikely verdicts on Chinese finals push
  endpointing to max_delay=6.0 (measured 3.667/3.654s HEL-910 call2; offline
  A/B on the real SDK: baseline 3.704s vs fixed 0.004s). Endpointing
  0.8/6.0 kept verbatim; no VAD/buffer_turn/semantic change
- scripts/gen_hel911_wait_repro.py: offline reproduction harness (real
  AgentSession + real silero VAD + HEL-910 wav and measured timings)
- tests: +3 real-SDK checks (11/11 on .12 agent venv; prior 8 regressions
  kept, unload call sites await the new protocol)
- hel910_call1.mjs reliability: segmented probe/recorder dumps to disk,
  timing-A trigger requires the server-committed voice turn row (not a
  we-sent-it proxy); node --check only, no real run
- window-record.md §9: appended factual corrections (companion 9 not 18,
  turn_start +6.099 not +4.10, assistant_final is the playout/receipt gate,
  post-window ListRooms token failure is not empty-room evidence); original
  record untouched
- docs/rework/hel911/summary.md + handoff-HEL-911.json; requirement checks
  pass vs origin/main and 407fc81

Co-authored-by: multica-agent <github@multica.ai>
2026-10-29 21:25:25 +08:00

9.5 KiB
Raw Blame History

HEL-911 · 修好通话收尾报错并查清开口等待(2026-10-29)

起点:agent/agent/ab943ea62162 @ 407fc81(含完整 958c696 产品与 HEL-910 证据, SHA 已核)。需求基准 v1.12/60 项;关联 CG-006/010/013–016/018–021、AM-001、 GOV-001–006、DEL-001;本卡无需求变更。全程真实 cap=0:零 LLM/ASR/TTS/嵌入/ 登记/试听调用,未建任何房间/窗口,未恢复任何本窗服务;仅只读复用 .12 /opt/voice-agent/agent/venv(livekit-agents 1.8.8 实物)与既有 wav 证据做离线证明。

1. 两个 SDK 接缝错误的修复(真实 1.8.8 驱动验证)

1.1 conversation_item_added 的非 ChatMessage 项目崩溃(worker.py _on_item)

  • 事实:1.8.8 的 ConversationItemAddedEvent.item 是 ChatMessage | AgentHandoff | _TypeDiscriminator(voice/events.py:419)。会话启动即入 一条 AgentHandoff(无 role/content),旧代码直取 ev.item.role 抛 AttributeError——HEL-910 两轮通话 worker.log 实录,每通各一次。
  • 修复(src/cybergril/voice/worker.py _on_item):按 SDK 判别字段 item.type == "message" 过滤,再按 role == "assistant" 取纯 str 部件正文 (ChatContent = str | ImageContent | AudioContent | CacheBreakpoint, llm/chat_context.py:459)。用户消息、AgentHandoff、unknown 项不更新 agent_recent_text;正常 assistant 正文继续喂回声过滤,语义不变。
  • 验证:tests/test_sdk_livekit_hel908.py test_conversation_item_added_filters_non_message_items——真 SDK 真 pydantic 模型 驱动:AgentHandoff / _TypeDiscriminator / user 消息 / 混合 content 的 assistant 消息四例,前三种不碰状态,第四种只取正文。

1.2 shutdown 回调的异步协议(worker.py bind_interrupt_channel)

  • 事实:JobContext.add_shutdown_callback 把无参回调包成 await callback() (job.py:633-643),job 关停逐个 await(ipc/job_proc_lazy_main.py:493)。旧的同步 def unload() -> None 因此在关停路径抛 TypeError: object NoneType can't be used in 'await' expression(HEL-910 实录)。
  • 修复:unload 改为协程;幂等(重复 shutdown/多次调用安全);房间未连接/已断连 不抛。session.interrupt(force=True)、回执/预算停机路径一字未动。
  • 验证:test_shutdown_callback_protocol_real_jobcontext_wrapper——用真 JobContext.add_shutdown_callback 方法做包装(仅缺 job 进程管线),按 job_proc_lazy_main 的原样 await 驱动:新协程通过;旧的同步形状经同一包装复现出 生产那条 TypeError(反向证据);重复 await 幂等;卸载后真 rtc.Room 再收 cg.interrupt 消息监听已摘除。既有三项 R2 通道测试同步改为 await unload(), 校验/未启动/卸载语义全部保持。

2. 9.5 秒等待分段核对(已有证据 + 实际 SDK 源码 + 离线复现)

2.1 按真实时刻重建的分段(call2 q1/q2,同钟 marks)

分段 q1 实测 构成(已证)
回放结束 → ASR 终稿 +2.432s silero 端点 ~0.7s(含 min_silence 0.55s)+ FunASR 2pass 离线纠错往返 + 适配器 0.6s 去抖合并(stt_funasr.py emit_merged_final)
ASR 终稿 → 生成开始(turn_start) +3.667s(q2 +3.654s) 本卡查清,见 2.2——默认英文 EOU TurnDetector 把 endpointing 顶到 max_delay=6.0
生成开始 → 服务端首条 delta ~1.42s 服务端整轮缓冲生成(buffer_turn 已知代价,换零思考泄漏;DB 行 14 ts=+7.511 与 assistant_interim +7.514 同刻)
首条 delta → 第一有声帧 ~2.0s CosyVoice3 首包实测 1.614s(worker.log:220 [tts] first audio after 1.614s)+ 播放管线 ~0.4s
(收尾)assistant_final 字幕 +12.102s 播放收尾/回执门,非首次全文生成/落库时刻(纠偏,见 §4)

2.2 user_final → turn_start 的 3.66s:成因与修复(离线 A/B 证实)

  • 成因:livekit-agents 1.8.8 在 turn_handling 未显式给 turn_detection 键时 默认构造 inference.TurnDetector()(voice/agent_session.py:576-579 turn_handling.get("turn_detection", inference.TurnDetector());自托管回落本地 v1-mini 英文 EOU 模型)。worker 只配了 endpointing,于是这个英文模型对中文 终稿做端点预测;其"不太像说完"判定走 audio_recognition.py _bounce_eou_task 的 end_of_turn_probability < unlikely_threshold → endpointing_delay = max_delay 路径,把等待顶到 6.0s: extra_sleep = 6.0 + 说话结束锚点(≈+0.14) − 终稿时刻(≈+2.45) ≈ 3.69s——与两轮 实测 3.667/3.654s 对上(_run_eou_detection(stt) 内锚点体检打印实录)。
  • 离线复现(scripts/gen_hel911_wait_repro.py,.12 真 SDK + 真 silero VAD + HEL-910 实际回放 wav 按实测时间脚本化 STT/LLM/TTS,零外呼):
    • BASELINE(复刻旧配置,默认 TurnDetector 在):终稿 +2.443 → llm.chat +6.142 (3.699s,复现实测 3.667/3.654);VAD 端点 +0.712;首声 +9.18——与生产 9.5s 形状一致。
    • 修复后(显式 turn_detection: None):终稿 +2.439 → llm.chat +2.444 (0.005s);首声 +5.48。
  • 修复(worker.py TURN_HANDLING):显式 "turn_detection": None。轮次边界回到 本会话自己配置的 VAD endpointing(min 0.8 / max 6.0 原样保留),不降 VAD 阈值、 不动 buffer_turn、不改模型/网关/认证;短轮次行为不变(call2"盯着"轮原本就在终稿后 8ms 提交——其终稿晚于 说话结束+0.8s,min_delay 锚点已过)。附带收益:不再预载 v1-mini 本地权重(~244MB/进程)。
  • 回归:test_turn_handling_disables_default_english_eou_detector 断言真 SDK 下 默认会装探测器(若 SDK 行为变更该前置断言会失败,提示重新归因)、worker 配置下为 None、endpointing 参数逐字未动。
  • 未承诺:首声总时延 9.5s → 约 5.9s 是离线推算;需真实窗口复测确认,本卡 cap=0 未跑真实通话。

2.3 分段归因清单(已证 / 已修 / 需真实环境)

  • 已证(已有证据+源码+离线复现):2.432s(FunASR 链+去抖)、3.66s(默认英文 TurnDetector)、~1.4s(服务端整轮生成)、TTS 首包 1.614s、VAD 端点 ~0.7s。
  • 已修(离线定向验证通过,待真实复测收数字):3.66s 段(TURN_HANDLING)。
  • 需真实环境才能判断:修复后首声总时延的真实值;FunASR 离线纠错往返在真实麦克风 下的分布(当前只有工程回放样本);"经常>5s"与否需多样本。

3. 修复清单与验证记录

变更 文件 验证
_on_item 类型过滤 src/cybergril/voice/worker.py 真 SDK 4 例(§1.1)
unload 协程化+幂等 src/cybergril/voice/worker.py 真 JobContext 包装协议(§1.2)
显式禁用默认 TurnDetector src/cybergril/voice/worker.py(TURN_HANDLING) 离线 A/B + 真会话断言(§2.2)
等待链离线复现工具 scripts/gen_hel911_wait_repro.py(新增) BASELINE/FIXED 两模式跑通
测量工具可靠性修正 docs/rework/hel910/tools/hel910_call1.mjs node --check 通过(离线)
HEL-910 事实纠偏 docs/rework/hel910/window-record.md §9 追加 原文未回改
  • 真 SDK harness(.12 agent venv 1.8.8): tests/test_sdk_livekit_hel908.py --standalone 11/11(既有 8 项回归全保持 + 本卡 3 项新证)。
  • 产品测试套(.12 规范环境 .venv311 只读复用):480 passed / 11 skipped / 2 failed——两个 test_r3 基线/迁移失败与 HEL-908 记录一致(预先存在,前轮已留证)。 本地 py3.10 环境 75/81 通过、6 失败与基准 407fc81 干树完全同集合(环境差异,非本卡 引入)。
  • web 未动,未重建界面;ruff/lint 未配置进仓库流程,Python 语法经两环境实测导入通过。

4. HEL-910 交付说明纠偏(详见 window-record.md §9)

companion 实为 9 条(非 18);生成起点 +6.099s(非 +4.10);assistant_final 是播放收尾/回执门(非首次全文生成/落库,落库在 +7.511s);post-window.txt 的 ListRooms 实为 invalid authorization token,不能证明空房(总管已独立核实空房成立)。

5. 测量工具可靠性修正(仅必要项,离线验证,不执行真实窗口)

  • 分段落盘:hel910_call1.mjs 每 5s 把页内探针新增切片追加写 call1-probe-live.jsonl、录音分片即产即存 rec-part-NNNN.webm——驱动被超时杀掉 最多丢 5s 一段,不再整包丢失(HEL-910 第一通丢证模式)。node --check 通过。
  • 打断触发条件:时机A 不再以页面相位/己方发送为"服务端已激活"的代理,改为 服务端已把 U2 语音轮落成 chat 行(用户行出现在会话 DOM)+ 生成中相位双条件; 旧"发过 turn_start 即认为 API 已激活"的假设作废。

6. 未测 / 承接(如实)

  • 修复后首声真实数字、真实麦克风打断时延、可闻旧声中的回放打断正面样本、生成中 文字取消正面样本:需下轮真实工程窗口(门控与分段落盘已备好)。
  • FunASR 适配器 0.6s 去抖与 2pass 离线纠错往返是否可再压:属识别链参数,本卡不动 语义,留待与真实复测同窗评估。
  • 真实端点带 </think> 形状、真机/手机麦克风、Safari、完整 R1–R7:继续主卡承接。