- 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>
9.5 KiB
9.5 KiB
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-579turn_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 --standalone11/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:继续主卡承接。