diff --git a/docs/requirements/handoff-HEL-879.json b/docs/requirements/handoff-HEL-879.json index 5f5be71..1c75eea 100644 --- a/docs/requirements/handoff-HEL-879.json +++ b/docs/requirements/handoff-HEL-879.json @@ -1,73 +1,73 @@ { - "baseline_version": "1.11", - "read_commit": "c121c42e39174e0f627f129e7f7e5700f33acf26", - "task": "HEL-879 双职责一次交付:A) HEL-896 发布工具四项有限收口(总管独立复核清单)——①归档一致性强制:checkpoint busy 或源/快照行数不一致一律 CLI 非0、不形成可交付包,verify 拒绝 rows_match=False 旧包并按源路径映射做真实回退演练(解包隔离目录、实开各库核行数与哈希),自测 9/9 先复现旧失败形状再证修复;②目录内真实 SQLite(history_root/mem0_public_history.db 等)停服口径递归走 checkpoint+逐表核对,在线模式仅显式单库 backup API、含 SQLite 目录直接拒绝;③提前封账可执行:PersistentBudget.sealed()/seal() 原子写封账标记(真实用量保留不伪造不清零),acquire 首查封账(budget_sealed:51/55),跨重启/backup 归档恢复均拒绝、重复 seal 幂等、无解封路径,tools/seal_budget_hel879.py 为显式关闭命令,S6 负例(51/55 提前收尾、误重启、归档恢复、日顶有余量仍拒)并入 verify_budget_split 10/10;④安装入口唯一:hel895-release-candidate.md §2 全 offline 自足安装、§4 五步固定 SDK 入口(tarball 哈希→固定源构建→cp311 备产→仅本地轮→co-import),hel874-release.md §2/§4 标注被取代,mem0-stack.lock 的 mem0ai 行只作版本记录,audit 工具 head 动态化+证据目录可重定向,新证据 docs/rework/hel879/{sdk-audit,release-artifacts.json}。B) 统一语音候选隔离整合:hel-879-assembly 分支 = c121c42 + 发布收口(01ff919) + 语音后台 aba2aeb + 语音前端 c61d9c9(原作者 web/src 逐字节保留,CSS 哈希变化仅原作者 components.css +21 行),语音适配器测试对齐主线 HEL-882 硬闸(engineering_budget,不改产品门),全电池在该 head 实跑:pytest 324/324(299 主线+25 语音)、ruff 干净、web typecheck 0 错/lint 0 错1既有警告/vitest 88/88/build 通过、真实服务浏览器 9/9(零权限调用、零非回环出站,证据 docs/rework/hel879/browser/)、verify_hel877_voice_chain 8/8、.12 真SDK stdin 检查 8/8 ALL PASS(零写入零网络)、check_release_offline R1-R7、固定SDK回归 16/16+12/12+6/6+7/7+12/12。零真实 LLM/嵌入/ASR/TTS、零下载、零麦克风、未启动/停止任何服务、不部署、不合并 PR、PR#11 与 hel-870-assembly 未动、权威账与冻结未写、真实 cap 保持 0;2026-10-27 剩余收口(总管 b4dadd8 复核三项):A) 房间自动到期与共享上限——清理所有者观察活跃会话截止时间与欠账,无人再发请求也会到期转债真实删房;显式挂断与后台共用同一持久尝试/年龄上限与状态(_sessions 不再旁路),超限 CleanupAbandoned→503+准确状态、绝不回完成 404,成功同清 sessions/debts,重启续同一上限,关闭不留协程;B) 排队话轮确切归属——CyberGrillLLM.chat 读 livekit-agents 1.8.8 自身 agents_speech_handle ContextVar(_create_speech_task 源级核实),流绑定到创建它的那个 SpeechHandle,无归属/未登记 fail-closed 不绑,新 speech 不再退役旧 pending(总管交错反例 H1/H2/S1/S2 修正),say/主动生成不吞用户轮流;C) 交前端的版本化字幕契约 v2——信封 v/seq、确切 speech_id/turn_id/message_id、turn_start/interim/final/turn_end/turn_cancel 起止与取消、迟到/乱序双规则保护、主动播报同源 message_id 自带 proactive_start/end/cancel(不借回执分支),契约 docs/voice-subtitle-contract-v2.md + 录制样例 subtitle-samples/,总工未改 web/src(接线归 HEL-898 原视觉作者);另修 test_r2 lifespan 旧测试的双 portal 调用竞态确定性(原子冻结+阻塞,不抬超时不删断言)", - "requirement_ids": [ - "CG-006", - "CG-008", - "CG-009", - "CG-010", - "CG-011", - "CG-012", - "CG-013", - "CG-014", - "CG-015", - "CG-016", - "CG-018", - "CG-021", - "CG-023", - "CG-029", - "CG-030", - "CG-031", - "VIS-013", - "AM-001", - "AM-002", - "AM-003", - "UX-001", - "UX-005", - "UX-006", - "GOV-001", - "GOV-002", - "GOV-003", - "GOV-004", - "GOV-005", - "GOV-006", - "DEL-001" - ], - "deliverable": "分支 hel-879-assembly(独立候选,未入 PR#11):发布收口 tools/release_snapshot_hel896.py v2(强制一致性+回退演练)、src/cybergril/life/model.py 封账(sealed/seal/acquire 首查)、tools/seal_budget_hel879.py、tools/verify_budget_split_hel896.py S6、tools/audit_sdk_offline_hel896.py head 动态化、deploy/hel895-release-candidate.md §0/§2/§4/§5 唯一入口、deploy/hel874-release.md §2/§4 取代标注、deploy/mem0-stack.lock 注释收口、docs/budget-package-hel895.md §6.2 可执行封账;语音整合:aba2aeb 后台模块 + c61d9c9 前端(原作者视觉逐字节保留)合并入候选,测试对齐主线硬闸;证据 docs/rework/hel879/{release-snapshot/selftest.json,sdk-audit/,release-artifacts.json,browser/,release-check/,regression-*.json};HEL-879 返修(总管独立复核四 edges,78a5cfd 起):①deploy/voice/serve_dual_8360_8361.py 单属主生命周期(uvicorn lifespan=off,任一监听退出先停另一个再关库;app lifespan 重入门卫 fail-closed);②voice/session.py 房间归属清理账(删除成功才出账、失败保留可重试、到期转清理账真实删房、重启按持久账有界补偿仅本实例房间、404=已删幂等、路由失败 503 不冒充 404);③receipt.py TurnLedger 显式绑定(无生成的轮不吞下一轮流/回执,worker 先判打断/失败再消费);④tools/release_snapshot_hel896.py v3(三方计数直接相等、rows_match 只是额外约束、按源路径实际恢复到持久目标树、同名库无冲突映射、重复源拒绝);hatchling 勘误(uv v6/v7 有 1.32.4 缓存)+ 固定源离线构建 mem0ai-2.2.1 轮(sha256 698284b6…,未安装未联网);hel895 发布文档 §0 历史与当前分离、§4/§5 更新、budget §6.2.4 封账库不可抬 cap 重开勘正;runbook §3.3/§3.5/§3.6/§4.4/§4.5 与前端 session.ts 注释勘正(注释级,无逻辑/样式改动);CG-011 主动开口与 assistant_interim 增量字幕最小后台接缝(src/cybergril/voice/seam.py+worker/llm_chat_api 接线,主动开口默认关;接口与验收 docs/rework/hel879/voice-seam-interfaces.md);.12 真 SDK 检查扩展为 10 项(新增 worker 实际回调路径与 interim seam);回归 tests/test_voice_rework_hel879.py 17 例;剩余收口代码:voice/session.py(_cleanup_loop 观察活跃截止时间+共享上限+CleanupAbandoned)、voice/router.py(到顶 503+cleanup 状态)、voice/receipt.py TurnLedger 精确绑定重写、voice/llm_chat_api.py current_speech_handle/on_stream_started(stream,handle)/stream.speech_id、voice/worker.py 接线集中 bind_voice_session+make_voice_llm/speak_proactive_row(实际模块可加载)、voice/seam.py SubtitleBus+按 speech_id 隔离的 AssistantInterimPublisher、scripts/gen_hel877_sdk_check.py 真实 worker 模块驱动(#9 不再手抄)、scripts/gen_subtitle_samples_hel879.py 样例生成、docs/voice-subtitle-contract-v2.md、docs/runbook-hel877-voice.md §3.3/3.5/3.6 更新、tests/test_voice_rework_hel879.py 新增 A/B/C 用例", - "acceptance": [ - "归档负例:busy checkpoint(复现 checkpoint=(1,9,8))与行数不一致均失败且零残留产物;rows_match=False 旧包 verify 拒绝;停服口径目录内 SQLite 逐表核对(history=1);在线模式含 SQLite 目录拒绝;verify 输出源路径 rollback_plan", - "封账负例:51/55 提前收尾后任何类别拒绝 budget_sealed:51/55 且用量保持 51;误重启拒绝;backup 归档恢复拒绝;重复 seal 幂等(sealed_at 不变);拒绝不落账", - "seal_budget_hel879.py 端到端:封账→自检 acquire 被拒→CLI ok=true", - "整合后全电池:pytest 324/324、vitest 88/88、typecheck/lint/build、真实服务浏览器 9/9(含零权限/零非回环出站)、语音链 8/8、.12 真SDK 8/8、R1-R7、固定SDK五套回归全绿", - "原作者前端逐字节保留:git diff c61d9c9 HEAD -- web/src 为空;后台 voice 模块 diff aba2aeb 为空", - "返修edges:双端口同进程单次初始化(双端同 epoch、Store 单实例、监听全部退出后才关库且只关一次);删房失败→503 保留归属、重试真实再删(≥2 次尝试)、到期端到端真实删房(旧版 0 次);H1 无生成/H2 有 S2 交错时 H1 得 None、H2 得 S2(.12 真 SpeechHandle/SpeechCreatedEvent 实跑);rows_match=true+源2/快照1 的包 verify 拒绝;同名 ledger.db 快照不互相覆盖且恢复树按源路径各自落位", - "接缝验收(离线):assistant_interim 累积替换+reset 不跨轮;proactive 只选已落库 proactive=1 sent companion 行最新一条且本房间未念过;均不新增权限/出站", - "剩余收口A:recover→open→不再来任何请求,过 TTL 后后台自己删房(旧版 0 次);上限2后台到顶后再3次 end 零新增远端删除(旧版共5次)且 503 带 abandoned/attempts/room 状态不回 404;重启加载 2/2 债后 recover 与 end 均不再发删除;成功同清 sessions/debts;清理器无悬空协程", - "剩余收口B:.12 真 SDK 检查 #9 加载实际 worker 模块、真 AgentSession 注册回调实跑——双 handle 先排队后生成各得各流(总管交错反例)、say 夹在用户轮不吞流、无归属流 fail-closed 不开字幕轮、打断 turn_cancel 无 final 无回执;installed-SDK 源码级证据:_create_speech_task 设 ContextVar、speech_created 先于任务、llm_node 在其中调 llm.chat", - "剩余收口C:字幕契约 v2 信封/起止/取消/乱序保护落码并有录制样例;每 speech_id 生命周期 turn_start→interim→final→turn_end(或 cancel)逐字段断言;proactive_start/end/cancel 带同源 message_id", - "旧 flaky 确定性:test_lifespan_cancels_owned_generation_and_joins_task 连跑 12 次通过、全套连跑 3 次 350/350(修复=原子冻结+阻塞,超时与断言原样保留)" - ], - "deferred": [ - "真实通话验收(连续≥3轮、1秒开口打断、结束即停麦、无旧残音、断网清理、重开同档案):真实调用/D1音色/可信HTTPS设备路径/预算上限未获批,待主卡一次申请", - "会话到期/API重启后 LiveKit 房间与 worker 真实释放证据:_prune 仅删内存登记、end_session 有 delete_room,但『重启房间自然消亡』需真实环境验证,未测不冒充", - "R6 天气/素材/每日与手动完整备份、R7 有条件观察:继续主卡承接", - "固定 SDK 真缺下载(37 项+hatchling)与 A/B/C 预算授权:待总管主卡一次申请", - "产品 PR#4、旧小样 PR#6、新小样 PR#8、发布 PR#11 均未合并未替换正式界面", - "字幕 v2 的前端接线(web/src)归 HEL-898 原视觉作者:按 docs/voice-subtitle-contract-v2.md 实现,沿原认可槽位/动效,不改视觉;契约与提交经总管核对后启动", - "CG-011 会话中完整主动表达(现接缝=会话开启念已落库 proactive 留言≤1条,默认关)继续承接,不冒充完成" - ], - "requirement_changes": [], - "verification": [ - "docs/rework/hel879/release-snapshot/selftest.json(9/9,先复现旧失败形状再证修复)", - "docs/rework/hel896/budget-split/budget-split.json(10/10 含 S6 提前封账负例,本 head 重跑)", - "docs/rework/hel879/sdk-audit/ 与 release-artifacts.json(闭包 55/缺 41/可复用 3,tarball 哈希实测=lock,精确提交)", - "docs/rework/hel879/browser/real-browser.json(9/9 真实服务浏览器,零权限调用、零非回环出站)", - "docs/rework/hel879/release-check/hel882-release-check.json(R1-R7)与 regression-*.json(固定SDK 16/16、12/12、6/6、7/7、12/12)", - ".12 livekit-agents 1.8.8 真 SDK stdin 检查 8/8 ALL PASS(零写入零网络,输出在运行日志)", - "未验证:真机/Safari/真实通话/部署环境;工程检查不代表用户体验验收", - "docs/rework/hel879/sdk-check-hel879-remaining.log(.12 livekit-agents 1.8.8,实际 worker 模块驱动 11 项 ALL PASS)", - "docs/rework/hel879/subtitle-samples/*.jsonl(契约 v2 录制样例:正常轮/打断/主动播报)", - "全套 pytest 350/350 ×3(.venv311/Python 3.11.16,与既有交付同一解释器)" - ] + "baseline_version": "1.11", + "read_commit": "c121c42e39174e0f627f129e7f7e5700f33acf26", + "task": "HEL-879 双职责一次交付:A) HEL-896 发布工具四项有限收口(总管独立复核清单)——①归档一致性强制:checkpoint busy 或源/快照行数不一致一律 CLI 非0、不形成可交付包,verify 拒绝 rows_match=False 旧包并按源路径映射做真实回退演练(解包隔离目录、实开各库核行数与哈希),自测 9/9 先复现旧失败形状再证修复;②目录内真实 SQLite(history_root/mem0_public_history.db 等)停服口径递归走 checkpoint+逐表核对,在线模式仅显式单库 backup API、含 SQLite 目录直接拒绝;③提前封账可执行:PersistentBudget.sealed()/seal() 原子写封账标记(真实用量保留不伪造不清零),acquire 首查封账(budget_sealed:51/55),跨重启/backup 归档恢复均拒绝、重复 seal 幂等、无解封路径,tools/seal_budget_hel879.py 为显式关闭命令,S6 负例(51/55 提前收尾、误重启、归档恢复、日顶有余量仍拒)并入 verify_budget_split 10/10;④安装入口唯一:hel895-release-candidate.md §2 全 offline 自足安装、§4 五步固定 SDK 入口(tarball 哈希→固定源构建→cp311 备产→仅本地轮→co-import),hel874-release.md §2/§4 标注被取代,mem0-stack.lock 的 mem0ai 行只作版本记录,audit 工具 head 动态化+证据目录可重定向,新证据 docs/rework/hel879/{sdk-audit,release-artifacts.json}。B) 统一语音候选隔离整合:hel-879-assembly 分支 = c121c42 + 发布收口(01ff919) + 语音后台 aba2aeb + 语音前端 c61d9c9(原作者 web/src 逐字节保留,CSS 哈希变化仅原作者 components.css +21 行),语音适配器测试对齐主线 HEL-882 硬闸(engineering_budget,不改产品门),全电池在该 head 实跑:pytest 324/324(299 主线+25 语音)、ruff 干净、web typecheck 0 错/lint 0 错1既有警告/vitest 88/88/build 通过、真实服务浏览器 9/9(零权限调用、零非回环出站,证据 docs/rework/hel879/browser/)、verify_hel877_voice_chain 8/8、.12 真SDK stdin 检查 8/8 ALL PASS(零写入零网络)、check_release_offline R1-R7、固定SDK回归 16/16+12/12+6/6+7/7+12/12。零真实 LLM/嵌入/ASR/TTS、零下载、零麦克风、未启动/停止任何服务、不部署、不合并 PR、PR#11 与 hel-870-assembly 未动、权威账与冻结未写、真实 cap 保持 0;2026-10-27 剩余收口(总管 b4dadd8 复核三项):A) 房间自动到期与共享上限——清理所有者观察活跃会话截止时间与欠账,无人再发请求也会到期转债真实删房;显式挂断与后台共用同一持久尝试/年龄上限与状态(_sessions 不再旁路),超限 CleanupAbandoned→503+准确状态、绝不回完成 404,成功同清 sessions/debts,重启续同一上限,关闭不留协程;B) 排队话轮确切归属——CyberGrillLLM.chat 读 livekit-agents 1.8.8 自身 agents_speech_handle ContextVar(_create_speech_task 源级核实),流绑定到创建它的那个 SpeechHandle,无归属/未登记 fail-closed 不绑,新 speech 不再退役旧 pending(总管交错反例 H1/H2/S1/S2 修正),say/主动生成不吞用户轮流;C) 交前端的版本化字幕契约 v2——信封 v/seq、确切 speech_id/turn_id/message_id、turn_start/interim/final/turn_end/turn_cancel 起止与取消、迟到/乱序双规则保护、主动播报同源 message_id 自带 proactive_start/end/cancel(不借回执分支),契约 docs/voice-subtitle-contract-v2.md + 录制样例 subtitle-samples/,总工未改 web/src(接线归 HEL-898 原视觉作者);另修 test_r2 lifespan 旧测试的双 portal 调用竞态确定性(原子冻结+阻塞,不抬超时不删断言);2026-10-27 契约核准后 3 处实现时机收口(总管 3228b1e 复核,仅修实现时机,不改 v2 信封字段/事件种类、不动 web/src):①open_session 在真实建房 await 让出事件循环后于注册成功并持久化时重新唤醒/重建清理所有者(旧代码 pre-dispatch kick 的 cleaner 已空转退出:建房 20ms 真实 await、TTL25ms、等 120ms 无任何请求时 DELETE=0/过期登记仍在/cleaner=None;修后 DELETE=1/登记清/无悬空协程,新增真实让出建房负例与更短 TTL 唤醒负例,保留自动截止与共享上限机制不变);②speak_proactive_row 先取 say 同步返回的 SpeechHandle、立即发布 proactive_start 并注册该 handle 的 end/cancel 再按需等待(真实 SDK AgentSession.say 为同步函数、await handle=等整段播完,旧代码播完才发 start;.12 真SDK 验证播放中即可见 start、打断只有 cancel 不误发 end,v2 字段不变);③_after_playout 的 assistant_final 前置完整/合法同轮回执门(流未完整或无有效同轮 receipt/旧 epoch 一律只 turn_cancel,不再先发 final 后决定不确认;完整+合法回执路径 final 与 ack 均保留,φ/打断/失败/无归属 fail-closed 不变);.12 真SDK stdin 检查扩至 14/14 ALL PASS(新增:主动播报时机、主动播报打断、无回执不 final 三负例,实际 worker 模块回调路径),前后对照证据 docs/rework/hel879/timing-fix/ 与 docs/rework/hel879/sdk-check-hel879-timing.log;本轮回归:pytest 352/352(新增 2 项负例先在旧代码复现失败)、ruff(src/tests/tools) 0 错、verify_hel877_voice_chain 8/8、需求检查 4/4(origin/main 与 c121c42 各带/不带本 handoff);零真实 LLM/嵌入/ASR/TTS、零下载零安装、未部署未合并、PR#11 与 hel-870-assembly 未动、真实 cap 仍 0", + "requirement_ids": [ + "CG-006", + "CG-008", + "CG-009", + "CG-010", + "CG-011", + "CG-012", + "CG-013", + "CG-014", + "CG-015", + "CG-016", + "CG-018", + "CG-021", + "CG-023", + "CG-029", + "CG-030", + "CG-031", + "VIS-013", + "AM-001", + "AM-002", + "AM-003", + "UX-001", + "UX-005", + "UX-006", + "GOV-001", + "GOV-002", + "GOV-003", + "GOV-004", + "GOV-005", + "GOV-006", + "DEL-001" + ], + "deliverable": "分支 hel-879-assembly(独立候选,未入 PR#11):发布收口 tools/release_snapshot_hel896.py v2(强制一致性+回退演练)、src/cybergril/life/model.py 封账(sealed/seal/acquire 首查)、tools/seal_budget_hel879.py、tools/verify_budget_split_hel896.py S6、tools/audit_sdk_offline_hel896.py head 动态化、deploy/hel895-release-candidate.md §0/§2/§4/§5 唯一入口、deploy/hel874-release.md §2/§4 取代标注、deploy/mem0-stack.lock 注释收口、docs/budget-package-hel895.md §6.2 可执行封账;语音整合:aba2aeb 后台模块 + c61d9c9 前端(原作者视觉逐字节保留)合并入候选,测试对齐主线硬闸;证据 docs/rework/hel879/{release-snapshot/selftest.json,sdk-audit/,release-artifacts.json,browser/,release-check/,regression-*.json};HEL-879 返修(总管独立复核四 edges,78a5cfd 起):①deploy/voice/serve_dual_8360_8361.py 单属主生命周期(uvicorn lifespan=off,任一监听退出先停另一个再关库;app lifespan 重入门卫 fail-closed);②voice/session.py 房间归属清理账(删除成功才出账、失败保留可重试、到期转清理账真实删房、重启按持久账有界补偿仅本实例房间、404=已删幂等、路由失败 503 不冒充 404);③receipt.py TurnLedger 显式绑定(无生成的轮不吞下一轮流/回执,worker 先判打断/失败再消费);④tools/release_snapshot_hel896.py v3(三方计数直接相等、rows_match 只是额外约束、按源路径实际恢复到持久目标树、同名库无冲突映射、重复源拒绝);hatchling 勘误(uv v6/v7 有 1.32.4 缓存)+ 固定源离线构建 mem0ai-2.2.1 轮(sha256 698284b6…,未安装未联网);hel895 发布文档 §0 历史与当前分离、§4/§5 更新、budget §6.2.4 封账库不可抬 cap 重开勘正;runbook §3.3/§3.5/§3.6/§4.4/§4.5 与前端 session.ts 注释勘正(注释级,无逻辑/样式改动);CG-011 主动开口与 assistant_interim 增量字幕最小后台接缝(src/cybergril/voice/seam.py+worker/llm_chat_api 接线,主动开口默认关;接口与验收 docs/rework/hel879/voice-seam-interfaces.md);.12 真 SDK 检查扩展为 10 项(新增 worker 实际回调路径与 interim seam);回归 tests/test_voice_rework_hel879.py 17 例;剩余收口代码:voice/session.py(_cleanup_loop 观察活跃截止时间+共享上限+CleanupAbandoned)、voice/router.py(到顶 503+cleanup 状态)、voice/receipt.py TurnLedger 精确绑定重写、voice/llm_chat_api.py current_speech_handle/on_stream_started(stream,handle)/stream.speech_id、voice/worker.py 接线集中 bind_voice_session+make_voice_llm/speak_proactive_row(实际模块可加载)、voice/seam.py SubtitleBus+按 speech_id 隔离的 AssistantInterimPublisher、scripts/gen_hel877_sdk_check.py 真实 worker 模块驱动(#9 不再手抄)、scripts/gen_subtitle_samples_hel879.py 样例生成、docs/voice-subtitle-contract-v2.md、docs/runbook-hel877-voice.md §3.3/3.5/3.6 更新、tests/test_voice_rework_hel879.py 新增 A/B/C 用例", + "acceptance": [ + "归档负例:busy checkpoint(复现 checkpoint=(1,9,8))与行数不一致均失败且零残留产物;rows_match=False 旧包 verify 拒绝;停服口径目录内 SQLite 逐表核对(history=1);在线模式含 SQLite 目录拒绝;verify 输出源路径 rollback_plan", + "封账负例:51/55 提前收尾后任何类别拒绝 budget_sealed:51/55 且用量保持 51;误重启拒绝;backup 归档恢复拒绝;重复 seal 幂等(sealed_at 不变);拒绝不落账", + "seal_budget_hel879.py 端到端:封账→自检 acquire 被拒→CLI ok=true", + "整合后全电池:pytest 324/324、vitest 88/88、typecheck/lint/build、真实服务浏览器 9/9(含零权限/零非回环出站)、语音链 8/8、.12 真SDK 8/8、R1-R7、固定SDK五套回归全绿", + "原作者前端逐字节保留:git diff c61d9c9 HEAD -- web/src 为空;后台 voice 模块 diff aba2aeb 为空", + "返修edges:双端口同进程单次初始化(双端同 epoch、Store 单实例、监听全部退出后才关库且只关一次);删房失败→503 保留归属、重试真实再删(≥2 次尝试)、到期端到端真实删房(旧版 0 次);H1 无生成/H2 有 S2 交错时 H1 得 None、H2 得 S2(.12 真 SpeechHandle/SpeechCreatedEvent 实跑);rows_match=true+源2/快照1 的包 verify 拒绝;同名 ledger.db 快照不互相覆盖且恢复树按源路径各自落位", + "接缝验收(离线):assistant_interim 累积替换+reset 不跨轮;proactive 只选已落库 proactive=1 sent companion 行最新一条且本房间未念过;均不新增权限/出站", + "剩余收口A:recover→open→不再来任何请求,过 TTL 后后台自己删房(旧版 0 次);上限2后台到顶后再3次 end 零新增远端删除(旧版共5次)且 503 带 abandoned/attempts/room 状态不回 404;重启加载 2/2 债后 recover 与 end 均不再发删除;成功同清 sessions/debts;清理器无悬空协程", + "剩余收口B:.12 真 SDK 检查 #9 加载实际 worker 模块、真 AgentSession 注册回调实跑——双 handle 先排队后生成各得各流(总管交错反例)、say 夹在用户轮不吞流、无归属流 fail-closed 不开字幕轮、打断 turn_cancel 无 final 无回执;installed-SDK 源码级证据:_create_speech_task 设 ContextVar、speech_created 先于任务、llm_node 在其中调 llm.chat", + "剩余收口C:字幕契约 v2 信封/起止/取消/乱序保护落码并有录制样例;每 speech_id 生命周期 turn_start→interim→final→turn_end(或 cancel)逐字段断言;proactive_start/end/cancel 带同源 message_id", + "旧 flaky 确定性:test_lifespan_cancels_owned_generation_and_joins_task 连跑 12 次通过、全套连跑 3 次 350/350(修复=原子冻结+阻塞,超时与断言原样保留)" + ], + "deferred": [ + "真实通话验收(连续≥3轮、1秒开口打断、结束即停麦、无旧残音、断网清理、重开同档案):真实调用/D1音色/可信HTTPS设备路径/预算上限未获批,待主卡一次申请", + "会话到期/API重启后 LiveKit 房间与 worker 真实释放证据:_prune 仅删内存登记、end_session 有 delete_room,但『重启房间自然消亡』需真实环境验证,未测不冒充", + "R6 天气/素材/每日与手动完整备份、R7 有条件观察:继续主卡承接", + "固定 SDK 真缺下载(37 项+hatchling)与 A/B/C 预算授权:待总管主卡一次申请", + "产品 PR#4、旧小样 PR#6、新小样 PR#8、发布 PR#11 均未合并未替换正式界面", + "字幕 v2 的前端接线(web/src)归 HEL-898 原视觉作者:按 docs/voice-subtitle-contract-v2.md 实现,沿原认可槽位/动效,不改视觉;契约与提交经总管核对后启动", + "CG-011 会话中完整主动表达(现接缝=会话开启念已落库 proactive 留言≤1条,默认关)继续承接,不冒充完成" + ], + "requirement_changes": [], + "verification": [ + "docs/rework/hel879/release-snapshot/selftest.json(9/9,先复现旧失败形状再证修复)", + "docs/rework/hel896/budget-split/budget-split.json(10/10 含 S6 提前封账负例,本 head 重跑)", + "docs/rework/hel879/sdk-audit/ 与 release-artifacts.json(闭包 55/缺 41/可复用 3,tarball 哈希实测=lock,精确提交)", + "docs/rework/hel879/browser/real-browser.json(9/9 真实服务浏览器,零权限调用、零非回环出站)", + "docs/rework/hel879/release-check/hel882-release-check.json(R1-R7)与 regression-*.json(固定SDK 16/16、12/12、6/6、7/7、12/12)", + ".12 livekit-agents 1.8.8 真 SDK stdin 检查 8/8 ALL PASS(零写入零网络,输出在运行日志)", + "未验证:真机/Safari/真实通话/部署环境;工程检查不代表用户体验验收", + "docs/rework/hel879/sdk-check-hel879-remaining.log(.12 livekit-agents 1.8.8,实际 worker 模块驱动 11 项 ALL PASS)", + "docs/rework/hel879/subtitle-samples/*.jsonl(契约 v2 录制样例:正常轮/打断/主动播报)", + "全套 pytest 350/350 ×3(.venv311/Python 3.11.16,与既有交付同一解释器)" + ] } \ No newline at end of file diff --git a/docs/rework/hel879/sdk-check-hel879-timing.log b/docs/rework/hel879/sdk-check-hel879-timing.log new file mode 100644 index 0000000..a0a63a2 --- /dev/null +++ b/docs/rework/hel879/sdk-check-hel879-timing.log @@ -0,0 +1,15 @@ +HEL-877/879 real-SDK check on livekit-agents 1.8.8: ALL PASS + OK CyberGrillLLM/ChatApiLLMStream subclass real livekit-agents 1.8.8 LLM/LLMStream + OK latest_user_text reads a real ChatContext (items/role/text_content) + OK fake-SSE turn through real LLMStream emits ChatChunks, final text and receipt + OK chat.error phi is spoken verbatim via ChatChunk and carries no receipt + OK mint_token claims byte-parity with livekit.api.AccessToken (video/iss/sub/keys) + OK mint_server_token matches SDK no-grant auth header claims + OK worker.py SDK surface (SpeechHandle, UserInputTranscribedEvent.is_final) present + OK barge-in task cancel closes the in-flight HTTP stream immediately + OK installed-SDK source verified: speech tasks set agents_speech_handle around the pipeline; speech_created precedes the task; llm_node calls llm.chat inside it + OK ACTUAL worker module loaded; its registered callbacks driven on a real AgentSession: both-queued delayed generations bind exactly (manager interleaving), say never steals a stream, unattributed fails closed, interrupt cancels without final/receipt + OK assistant_interim seam: real LLMStream deltas feed per-speech_id v2 payloads (replace semantics); unattributed streams feed nothing + OK speak_proactive_row publishes proactive_start while the real SpeechHandle is still playing (sync-say shape), end/cancel on the handle's done callback + OK interrupted proactive row emits proactive_cancel(reason=interrupted), never proactive_end + OK incomplete/no-receipt attributed stream: actual worker callbacks emit turn_start -> turn_cancel only, no assistant_final, no ack diff --git a/docs/rework/hel879/timing-fix/delayed-dispatch-after.json b/docs/rework/hel879/timing-fix/delayed-dispatch-after.json new file mode 100644 index 0000000..91c80e6 --- /dev/null +++ b/docs/rework/hel879/timing-fix/delayed-dispatch-after.json @@ -0,0 +1 @@ +{"remote_delete_count_after_ttl": 1, "expired_but_registered": false, "cleanup_owner_present": false} diff --git a/docs/rework/hel879/timing-fix/delayed-dispatch-before.json b/docs/rework/hel879/timing-fix/delayed-dispatch-before.json new file mode 100644 index 0000000..39d25f7 --- /dev/null +++ b/docs/rework/hel879/timing-fix/delayed-dispatch-before.json @@ -0,0 +1 @@ +{"remote_delete_count_after_ttl": 0, "expired_but_registered": true, "cleanup_owner_present": false} diff --git a/docs/rework/hel879/timing-fix/sdk-probe-after.json b/docs/rework/hel879/timing-fix/sdk-probe-after.json new file mode 100644 index 0000000..12a0784 --- /dev/null +++ b/docs/rework/hel879/timing-fix/sdk-probe-after.json @@ -0,0 +1 @@ +{"proactive_before_playout_finishes": {"handle_done": false, "events": ["proactive_start"]}, "proactive_after_playout_finishes": ["proactive_start", "proactive_end"], "proactive_payload_fields": {"v": 2, "kind": "proactive_start", "role": "assistant", "text": "offline sample", "speech_id": "speech_f28fdeb15e01", "message_id": 7}, "no_receipt_incomplete_actual_worker_events": ["turn_start", "turn_cancel"], "no_receipt_incomplete_confirmed": [], "complete_with_receipt_actual_worker_events": ["turn_start", "assistant_final", "turn_end"], "complete_with_receipt_confirmed": ["ok-turn"]} diff --git a/docs/rework/hel879/timing-fix/sdk-probe-before.json b/docs/rework/hel879/timing-fix/sdk-probe-before.json new file mode 100644 index 0000000..abeed15 --- /dev/null +++ b/docs/rework/hel879/timing-fix/sdk-probe-before.json @@ -0,0 +1 @@ +{"proactive_before_playout_finishes": {"handle_done": false, "events": []}, "proactive_after_playout_finishes": ["proactive_start", "proactive_end"], "proactive_payload_fields": {"v": 2, "kind": "proactive_start", "role": "assistant", "text": "offline sample", "speech_id": "speech_2880d36ea013", "message_id": 7}, "no_receipt_incomplete_actual_worker_events": ["turn_start", "assistant_final", "turn_end"], "no_receipt_incomplete_confirmed": [], "complete_with_receipt_actual_worker_events": ["turn_start", "assistant_final", "turn_end"], "complete_with_receipt_confirmed": ["ok-turn"]} diff --git a/docs/rework/hel879/timing-fix/summary.md b/docs/rework/hel879/timing-fix/summary.md new file mode 100644 index 0000000..8429fa8 --- /dev/null +++ b/docs/rework/hel879/timing-fix/summary.md @@ -0,0 +1,37 @@ +# HEL-879 契约核准后 3 处实现时机收口(2026-10-27) + +核对对象:`hel-879-assembly @ 3228b1e0d7f822b7030f945e285eac74126771aa`(总管《HEL-879-契约核准与接续.md》)。 +本轮只修 3 处实现与已定契约 v2 不一致的问题:不改 `v` 信封字段、不改事件种类、不动 `web/src`、不重做已过绑定/备份/预算。 + +## 修前复现(全部先复现失败,与总管证据一致) + +| # | 发现 | 修前证据 | +|---|------|----------| +| 1 | `open_session` 只在 `await create_dispatch` 前 kick;建房真实让出事件循环后 cleaner 空转退出,注册后无人再观察截止时间 | `delayed-dispatch-before.json`:`{"remote_delete_count_after_ttl": 0, "expired_but_registered": true, "cleanup_owner_present": false}`(与总管 delayed-dispatch.json 逐字段一致) | +| 2 | `speak_proactive_row` 旧写法 `handle = await session.say(...)`;真实 SDK `say` 为同步函数、`await handle`=等整段播完 → 播完才发 proactive_start | `sdk-probe-before.json`:`proactive_before_playout_finishes.events=[]`,播完后才 `["proactive_start","proactive_end"]` | +| 3 | `_after_playout` 先按 `stream.text` 发 final/end 再查回执;注入 text 非空、completed=False、receipt=None 的确切归属流 → `turn_start→assistant_final→turn_end`,与 v2「无完整同轮回执只 cancel」相反 | 同上:`no_receipt_incomplete_actual_worker_events=["turn_start","assistant_final","turn_end"]`(实际 worker `bind_voice_session` 回调路径,真实 AgentSession/SpeechHandle) | + +新增专项测试在**未修复代码上先跑失败**(repro-first): +`tests/test_voice_rework_hel879.py::test_open_session_with_real_dispatch_yield_re_kicks_cleanup`、 +`::test_second_registration_wakes_a_sleeping_cleaner_for_earlier_deadline` → 修前 2 failed / 修后 2 passed。 + +## 修复(精确小修) + +1. `src/cybergril/voice/session.py` `open_session`:注册成功并 `_persist_state()` 之后**重新 `_kick_cleanup()`**——建房 await 期间旧 cleaner 可能已因「无可观察对象」退出,新截止时间需要新的所有者;自动截止、共享上限、重启补偿、有界放弃全部保留。测试用**真正让出事件循环**的建房替身(`asyncio.sleep(0.02)`),不再只用立即返回的 MockTransport 替身。 +2. `src/cybergril/voice/worker.py` `speak_proactive_row`:先取 handle(`iscoroutine` 只解包 await 型替身——真实 SpeechHandle 自身可 await,不能误等)、**立即**发布 `proactive_start`、注册该 handle 的 `proactive_end/proactive_cancel`,再按需等待这一条播完(逐条顺序念保留)。 +3. `src/cybergril/voice/worker.py` `_after_playout`:`assistant_final` 前置必要门——流 `completed` 且 `should_ack`(合法同轮 receipt、非旧 epoch)才 `finish`+`confirm`;未完整/无回执/旧 epoch 一律只 `turn_cancel`(reason=incomplete/no-receipt),**绝不先发 final 再决定不确认**;φ/打断/失败/无归属 fail-closed 原样保留,完整+合法回执路径的 final 与 ack 均保留。 + +## 修后验证 + +- 本地:`delayed-dispatch-after.json`:`{"remote_delete_count_after_ttl": 1, "expired_but_registered": false, "cleanup_owner_present": false}`(cleaner 在全部结清后按设计自行退出,无悬空协程)。 +- `.12` 真 SDK(stdin 嵌入当前源码,零写入零网络,`/opt/voice-agent/agent/venv` livekit-agents 1.8.8)`sdk-probe-after.json`: + - `proactive_before_playout_finishes={"handle_done": false, "events": ["proactive_start"]}`(播放中即可见 start); + - 播完 `["proactive_start","proactive_end"]`,字段 `v/kind/role/text/speech_id/message_id` 与 v2 完全一致; + - `no_receipt_incomplete=["turn_start","turn_cancel"]`、`confirmed=[]`; + - 完整+合法回执路径 `["turn_start","assistant_final","turn_end"]` + ack 保留。 +- 真SDK回归并入常驻检查 `scripts/gen_hel877_sdk_check.py`(**14/14 ALL PASS**,`../sdk-check-hel879-timing.log`):新增「主动播报时机」「主动播报打断只有 cancel」「无回执不 final」三负例,均驱动实际 worker 模块注册的真实回调。 +- 产品套件:pytest **352/352**(3 次连跑);ruff(src/tests/tools) **0 错**;`verify_hel877_voice_chain.py` **8/8**;需求检查 **4/4**(origin/main 与 c121c42 各带/不带 handoff-HEL-879.json)。字幕样例 `subtitle-samples/` 与 v2 契约文档无需再生成(字段与生命周期未变)。 + +## 边界 + +零真实 LLM/嵌入/ASR/TTS/麦克风;.12 仅 SSH stdin 执行只读检查(零写入零网络,stderr 仅既有 jwt 弱密钥告警);零下载零安装;未部署、未合并;PR#11 与 `hel-870-assembly` 未动;权威账/冻结/共享服务/队员配置未碰;真实 cap 仍 0。R5 真机、完整 CG-011、R6/R7 继续承接,无需求变更(v1.11/60 项)。 diff --git a/scripts/gen_hel877_sdk_check.py b/scripts/gen_hel877_sdk_check.py index 0491f89..2463e44 100644 --- a/scripts/gen_hel877_sdk_check.py +++ b/scripts/gen_hel877_sdk_check.py @@ -15,6 +15,15 @@ emitted before the task starts; (b) runtime — generations started inside that ContextVar bind exactly, including the manager's both-queued-then-delayed interleaving, a say speech sandwiched between user turns, an unattributed generation (fail-closed) and an interrupted turn (cancel, no receipt). + +HEL-879 timing closure (contract-approval round): the real SDK's +AgentSession.say is a SYNC method returning an awaitable SpeechHandle (awaiting +it awaits the whole playout) — speak_proactive_row must publish +proactive_start DURING the playout with end/cancel on the handle's done +callback; and a clearly-attributed but incomplete/no-receipt stream must close +the subtitle turn with turn_cancel ONLY (contract v2: no complete same-turn +receipt means no assistant_final), while the complete+receipt path keeps +final AND the ack. """ from __future__ import annotations @@ -372,6 +381,95 @@ asyncio.run(interim_seam()) ok.append("assistant_interim seam: real LLMStream deltas feed per-speech_id v2 " "payloads (replace semantics); unattributed streams feed nothing") +# 11. HEL-879 timing closure: proactive_start DURING the playout on the real +# sync-say shape (a bare handle.__await__ would wait out the whole play). +async def proactive_timing_case(): + events: list[dict] = [] + h = SpeechHandle.create() + class SyncSay: + def say(self, *args, **kwargs): # real SDK shape: sync -> handle + asyncio.get_running_loop().call_later(.06, h._mark_done) + return h + task = asyncio.create_task(worker_mod.speak_proactive_row( + SyncSay(), seam_mod.SubtitleBus(events.append), + {"id": 7, "text": "offline sample"})) + await asyncio.sleep(.015) + assert h.done() is False + assert [e["kind"] for e in events] == ["proactive_start"], events + await task + await asyncio.sleep(.015) + assert [e["kind"] for e in events] == ["proactive_start", "proactive_end"] + start = events[0] + assert (start["v"], start["role"], start["message_id"], start["text"]) == \ + (2, "assistant", 7, "offline sample") + assert start["speech_id"] == h.id + +asyncio.run(proactive_timing_case()) +ok.append("speak_proactive_row publishes proactive_start while the real " + "SpeechHandle is still playing (sync-say shape), end/cancel on the " + "handle's done callback") + +# 11b. an interrupted proactive row closes with cancel, never end +async def proactive_interrupt_case(): + events: list[dict] = [] + h = SpeechHandle.create() + class SyncSay: + def say(self, *args, **kwargs): + return h + task = asyncio.create_task(worker_mod.speak_proactive_row( + SyncSay(), seam_mod.SubtitleBus(events.append), + {"id": 8, "text": "被打断的主动留言"})) + await asyncio.sleep(.005) # start emitted, done callback registered + h.interrupt() + h._mark_done() + await task + await asyncio.sleep(.02) + assert [e["kind"] for e in events] == ["proactive_start", "proactive_cancel"], events + assert events[-1]["reason"] == "interrupted" + +asyncio.run(proactive_interrupt_case()) +ok.append("interrupted proactive row emits proactive_cancel(reason=interrupted), " + "never proactive_end") + +# 12. HEL-879 timing closure: a clearly-attributed but INCOMPLETE/no-receipt +# stream through the ACTUAL bind_voice_session callbacks must close the +# subtitle turn with turn_cancel ONLY — no assistant_final, no ack (v2). +async def no_receipt_incomplete_case(): + events: list[dict] = [] + session = AgentSession() + ledger = receipt_mod.TurnLedger() + bus = seam_mod.SubtitleBus(events.append) + interim = seam_mod.AssistantInterimPublisher(bus) + confirmed: list[str] = [] + async def epoch(): + return 1 + class Receipts: + async def confirm(self, *args): + confirmed.append(args[0]) + return True + llm = types.SimpleNamespace(client=types.SimpleNamespace(current_epoch=epoch)) + worker_mod.bind_voice_session(session, llm=llm, ledger=ledger, interim=interim, + bus=bus, stt=types.SimpleNamespace(), + receipts=Receipts()) + h = SpeechHandle.create() + session.emit("speech_created", SpeechCreatedEvent( + user_initiated=True, source="generate_reply", speech_handle=h, + created_at=1.0)) + stream = types.SimpleNamespace( + speech_id=h.id, error_phi=None, text="partial without receipt", + turn_id="incomplete", receipt=None, completed=False) + ledger.note_stream(stream, h) + interim.begin(h.id) + h._mark_done() + await asyncio.sleep(.06) + assert [e["kind"] for e in events] == ["turn_start", "turn_cancel"], events + assert events[-1]["reason"] == "incomplete" + assert confirmed == [] + +asyncio.run(no_receipt_incomplete_case()) +ok.append("incomplete/no-receipt attributed stream: actual worker callbacks emit " + "turn_start -> turn_cancel only, no assistant_final, no ack") + print("HEL-877/879 real-SDK check on livekit-agents", end=" ") import importlib.metadata as md print(md.version("livekit-agents") + ":", "ALL PASS") diff --git a/scripts/gen_hel879_timing_probe.py b/scripts/gen_hel879_timing_probe.py new file mode 100644 index 0000000..d09224f --- /dev/null +++ b/scripts/gen_hel879_timing_probe.py @@ -0,0 +1,155 @@ +#!/usr/bin/env python3 +"""Generate the HEL-879 timing-fix probe for the .12 agent venv (real SDK). + +Reproduces the manager's two worker-side findings from the contract-approval +round (sdk-say / sdk-extra payloads), against WHATEVER sources are in the tree +when run — same script is used before AND after the fix: + + 1. speak_proactive_row on the REAL SDK shape: AgentSession.say is a SYNC + method returning an awaitable SpeechHandle (awaiting it awaits the whole + playout), so proactive_start must be published while the handle is still + playing (before done), with end/cancel on the handle's own done callback. + 2. _after_playout through the ACTUAL bind_voice_session callbacks on a real + AgentSession: a clearly-attributed stream with text but completed=False + and receipt=None must NOT produce assistant_final — contract v2 says no + complete same-turn receipt means cancel, never final. The complete+receipt + path must still produce final AND the ack (checked in the same probe). + +Embeds repo voice-module sources in a self-contained stdin script; no files +written on .12, no network, no service touched. +""" +from __future__ import annotations + +import base64 +import json +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +MODULES = ["chat_api_client", "receipt", "seam", "llm_chat_api", + "stt_funasr", "tts_cosyvoice", "worker"] + +TEMPLATE = r''' +import asyncio, base64, json, sys, types + +SOURCES = json.loads(base64.b64decode("__B64__")) + +pkg = types.ModuleType("cybergril"); pkg.__path__ = [] +voice = types.ModuleType("cybergril.voice"); voice.__path__ = [] +sys.modules["cybergril"] = pkg +sys.modules["cybergril.voice"] = voice +for name, src in SOURCES.items(): + mod = types.ModuleType(f"cybergril.voice.{name}") + mod.__package__ = "cybergril.voice" + sys.modules[f"cybergril.voice.{name}"] = mod + exec(compile(src, f"", "exec"), mod.__dict__) + setattr(voice, name, mod) + +from livekit.agents import AgentSession +from livekit.agents.voice.speech_handle import SpeechHandle +from livekit.agents.voice.events import SpeechCreatedEvent + +w = voice.worker +out = {} + +# --- 1. proactive say timing on the REAL SpeechHandle shape ------------------- +async def proactive_case(): + events = [] + h = SpeechHandle.create() + class Say: + def say(self, *args, **kwargs): # real SDK: sync, returns SpeechHandle + asyncio.get_running_loop().call_later(.06, h._mark_done) + return h + task = asyncio.create_task(w.speak_proactive_row( + Say(), voice.seam.SubtitleBus(events.append), {"id": 7, "text": "offline sample"})) + await asyncio.sleep(.015) + out["proactive_before_playout_finishes"] = { + "handle_done": h.done(), + "events": [x["kind"] for x in events]} + await task + await asyncio.sleep(.015) + out["proactive_after_playout_finishes"] = [x["kind"] for x in events] + out["proactive_payload_fields"] = {k: events[0][k] for k in ("v", "kind", "role", "text", "speech_id", "message_id")} + +asyncio.run(proactive_case()) + +# --- 2. actual-worker no-receipt/incomplete stream --------------------------- +async def no_receipt_case(): + events = [] + session = AgentSession() + ledger = voice.receipt.TurnLedger() + bus = voice.seam.SubtitleBus(events.append) + interim = voice.seam.AssistantInterimPublisher(bus) + async def epoch(): return 1 + confirmed = [] + class Receipts: + async def confirm(self, *args): + confirmed.append(args[0]); return True + llm = types.SimpleNamespace(client=types.SimpleNamespace(current_epoch=epoch)) + w.bind_voice_session(session, llm=llm, ledger=ledger, interim=interim, + bus=bus, stt=types.SimpleNamespace(), receipts=Receipts()) + h = SpeechHandle.create() + session.emit("speech_created", SpeechCreatedEvent( + user_initiated=True, source="generate_reply", speech_handle=h, created_at=1.0)) + stream = types.SimpleNamespace( + speech_id=h.id, error_phi=None, text="partial without receipt", + turn_id="incomplete", receipt=None, completed=False) + ledger.note_stream(stream, h) + interim.begin(h.id) + h._mark_done() + await asyncio.sleep(.06) + out["no_receipt_incomplete_actual_worker_events"] = [x["kind"] for x in events] + out["no_receipt_incomplete_confirmed"] = list(confirmed) + +asyncio.run(no_receipt_case()) + +# --- 3. the complete+receipt path must keep final AND ack -------------------- +async def complete_case(): + events = [] + session = AgentSession() + ledger = voice.receipt.TurnLedger() + bus = voice.seam.SubtitleBus(events.append) + interim = voice.seam.AssistantInterimPublisher(bus) + async def epoch(): return 1 + confirmed = [] + class Receipts: + async def confirm(self, *args): + confirmed.append(args[0]); return True + llm = types.SimpleNamespace(client=types.SimpleNamespace(current_epoch=epoch)) + w.bind_voice_session(session, llm=llm, ledger=ledger, interim=interim, + bus=bus, stt=types.SimpleNamespace(), receipts=Receipts()) + h = SpeechHandle.create() + session.emit("speech_created", SpeechCreatedEvent( + user_initiated=True, source="generate_reply", speech_handle=h, created_at=1.0)) + receipt = {"message_id": 9, "turn_id": "ok-turn", "epoch": 1, + "token": "t" * 48, "text_hash": "z" * 64} + stream = types.SimpleNamespace( + speech_id=h.id, error_phi=None, text="her complete reply", + turn_id="ok-turn", receipt=receipt, completed=True) + ledger.note_stream(stream, h) + interim.begin(h.id) + h._mark_done() + await asyncio.sleep(.06) + out["complete_with_receipt_actual_worker_events"] = [x["kind"] for x in events] + out["complete_with_receipt_confirmed"] = list(confirmed) + +asyncio.run(complete_case()) + +print(json.dumps(out, ensure_ascii=False)) +''' + +def main() -> int: + sources = {} + for name in MODULES: + path = ROOT / "src/cybergril/voice" / f"{name}.py" + sources[name] = path.read_text(encoding="utf-8") + payload = base64.b64encode(json.dumps(sources).encode()).decode() + script = TEMPLATE.replace("__B64__", payload) + out = ROOT / "scripts/_hel879_timing_probe_payload.py" + out.write_text(script, encoding="utf-8") + print(out) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/cybergril/voice/session.py b/src/cybergril/voice/session.py index 8c45545..e1f105d 100644 --- a/src/cybergril/voice/session.py +++ b/src/cybergril/voice/session.py @@ -414,6 +414,11 @@ class VoiceSessionService: ) self._sessions[session.session_id] = session self._persist_state() + # Re-kick AFTER the registration exists: a real dispatch await yields + # the loop, and the earlier kick's cleaner may have already found + # nothing to watch and exited — the new deadline needs an owner again + # (HEL-879 timing fix: the cleaner died mid-dispatch with zero deletes). + self._kick_cleanup() return session def token_for(self, session: VoiceSession) -> str: diff --git a/src/cybergril/voice/worker.py b/src/cybergril/voice/worker.py index f5dcf82..d491a87 100644 --- a/src/cybergril/voice/worker.py +++ b/src/cybergril/voice/worker.py @@ -31,6 +31,8 @@ scripts/gen_hel877_sdk_check.py 不再手抄复刻)。 from __future__ import annotations import asyncio +import contextlib +import inspect import json import os from pathlib import Path @@ -148,13 +150,19 @@ def bind_voice_session(session: AgentSession, *, llm: CyberGrillLLM, interim.cancel(speech_id, "error_phi") outcomes[speech_id] = "error_phi" return - if stream.text: - interim.finish(speech_id, turn_id=stream.turn_id, text=stream.text) epoch = None try: epoch = await llm.client.current_epoch() except Exception: epoch = stream.receipt.get("epoch") if stream.receipt else None + # Contract v2 (HEL-879 timing fix): assistant_final means the archive + # really holds this turn — an incomplete stream, or one without a + # legal same-turn receipt (missing fields / stale epoch), closes with + # turn_cancel ONLY. The final is never sent first and retracted after. + if not getattr(stream, "completed", False): + interim.cancel(speech_id, "incomplete") + outcomes[speech_id] = "incomplete" + return if should_ack( played_to_end=True, interrupted=handle.interrupted, @@ -162,9 +170,11 @@ def bind_voice_session(session: AgentSession, *, llm: CyberGrillLLM, receipt=stream.receipt, current_epoch=epoch, ): + interim.finish(speech_id, turn_id=stream.turn_id, text=stream.text) await receipts.confirm(stream.turn_id, stream.receipt) outcomes[speech_id] = "acked" else: + interim.cancel(speech_id, "no-receipt") outcomes[speech_id] = "no-receipt" @session.on("speech_created") @@ -199,8 +209,17 @@ async def speak_proactive_row(session: AgentSession, bus: SubtitleBus, row: dict 字幕生命周期绑定在 say 返回的 SpeechHandle 上(proactive_start -> proactive_end/proactive_cancel),不借用任何回执分支。 + + 真实 SDK 的 AgentSession.say 是同步函数、返回可 await 的 SpeechHandle + (await 它=等整段播完,HEL-879 timing 修正):先取 handle、立刻发布 + proactive_start 并注册该 handle 的 end/cancel,再等这一条播完——start + 绝不能等声音播完后才发。await 型替身(测试桩)同样支持。 """ - handle = await session.say(row["text"], allow_interruptions=True) + result = session.say(row["text"], allow_interruptions=True) + # iscoroutine (NOT isawaitable): the real SpeechHandle itself defines + # __await__ (awaiting it = waiting out the playout) — only a coroutine + # from an await-style stand-in needs resolving to reach the handle. + handle = await result if inspect.iscoroutine(result) else result speech_id = getattr(handle, "id", "") bus.emit("proactive_start", role="assistant", text=row["text"], speech_id=speech_id, message_id=row["id"]) @@ -214,6 +233,11 @@ async def speak_proactive_row(session: AgentSession, bus: SubtitleBus, row: dict bus.emit("proactive_end", role="assistant", speech_id=sid, message_id=mid) handle.add_done_callback(_on_say_done) + # 逐条念:等 THIS 行播完再返回(替身 handle 不可 await 时直接返回; + # 播放中的异常已由 done 回调按 cancel 收口,这里不再向上抛)。 + if inspect.isawaitable(handle): + with contextlib.suppress(Exception): + await handle async def _maybe_open_proactive(session: AgentSession, room, bus: SubtitleBus, diff --git a/tests/test_voice_rework_hel879.py b/tests/test_voice_rework_hel879.py index 8a23390..2e945d2 100644 --- a/tests/test_voice_rework_hel879.py +++ b/tests/test_voice_rework_hel879.py @@ -432,6 +432,77 @@ async def test_cleaner_stays_alive_while_a_session_is_registered(): await service.aclose() +@pytest.mark.asyncio +async def test_open_session_with_real_dispatch_yield_re_kicks_cleanup(monkeypatch): + """总管契约核准轮第 1 项精确复现:建房 await 真正让出事件循环(真实 HTTP + 一定如此),pre-dispatch kick 的清理所有者在等待期间已空转退出;注册成功 + 并持久化之后必须重新唤醒/重建清理所有者——过 TTL 且不再来任何请求也能 + 到期转债并真实删房。旧代码:DELETE=0、过期登记仍在、cleaner=None。""" + deletes: list[str] = [] + dispatch_yielded = asyncio.Event() + + async def slow_create(*args, **kwargs): + await asyncio.sleep(0.02) # real HTTP always gives the loop a chance + dispatch_yielded.set() + return SimpleNamespace(dispatch_id="AD_delayed") + + async def slow_delete(*args, **kwargs): + deletes.append(kwargs["room"]) + + monkeypatch.setattr(livekit_wire, "create_dispatch", slow_create) + monkeypatch.setattr(livekit_wire, "delete_room", slow_delete) + service = _service(StandinLiveKit(), session_ttl_seconds=0.025) + try: + session = await service.open_session(epoch=1) + assert dispatch_yielded.is_set(), "dispatch await must really yield here" + # the registration's deadline has a live owner again right after open + assert service._cleaner is not None and not service._cleaner.done() + await asyncio.sleep(0.12) # past TTL with NO further request at all + assert deletes == [session.room] # exactly one delete, no duplicates + assert session.session_id not in service._sessions + assert service.cleanup_debt(session.session_id) is None + # settled: the cleaner exits by itself, no dangling coroutine + for _ in range(100): + if service._cleaner is None or service._cleaner.done(): + break + await asyncio.sleep(0.02) + assert service._cleaner is None or service._cleaner.done() + finally: + await service.aclose() + assert service._cleaner is None + + +@pytest.mark.asyncio +async def test_second_registration_wakes_a_sleeping_cleaner_for_earlier_deadline( + monkeypatch): + """注册后的 kick 也唤醒仍在睡眠的清理所有者:更短 TTL 的新会话不必等 + 旧会话的截止时间才被观察(min(deadlines) 立即重算)。""" + deletes: list[str] = [] + + async def create(*args, **kwargs): + await asyncio.sleep(0.02) + return SimpleNamespace(dispatch_id="AD_2") + + async def delete(*args, **kwargs): + deletes.append(kwargs["room"]) + + monkeypatch.setattr(livekit_wire, "create_dispatch", create) + monkeypatch.setattr(livekit_wire, "delete_room", delete) + service = _service(StandinLiveKit(), session_ttl_seconds=5.0, backoff=0.005) + try: + first = await service.open_session(epoch=1) # long TTL keeps cleaner sleeping + service.config.session_ttl_seconds = 0.025 + second = await service.open_session(epoch=1) # short TTL + real dispatch await + for _ in range(100): + if deletes: + break + await asyncio.sleep(0.02) + assert deletes == [second.room] + assert first.session_id in service._sessions # the long-TTL call is untouched + finally: + await service.aclose() + + @pytest.mark.asyncio async def test_end_after_abandoned_cap_sends_no_further_deletes(): """总管复核 A-2 精确复现:上限 2,后台到顶后再 3 次 end 不得再发删除