Files
CyberGril/docs/rework/hel908/summary.md
T
xiaomoandmultica-agent 958c6962fb HEL-908 R1/R2 rework (HEL-909 review): whole-turn reasoning gate + cg.interrupt data channel
R1 — reasoning separation truly closed. The streaming hold leaked wholesale
on real token arrival (review A1: 'private reasoning '*20 beyond the 128-char
bound, no sentence ender; review A2: a Chinese sentence ender released the
hold) AND the adapter consumed the stray closer, so the app-level turn split
could never recover — the previous 'persistence and receipt always clean'
claim was false and is retracted. Per the engineering ruling the adapter now
has two explicit endpoint modes (GOV-006, no heuristics, no new engine):
buffer_turn (TurnReasoningGate) emits NOTHING during generation, splits the
whole turn at stream end and only then delivers the clean visible text; it
is set explicitly for all tiers in config/models.yaml (first visible text
waits for the full generation; cancelled/timed-out turns emit nothing and
end exactly as before — recorded and test-pinned, low latency NOT claimed).
stream (default, backward compatible) keeps explicit-tag/field semantics and
passes stray closers through unmodified so the turn-level split keeps its
signal. Both review strings and the recorded id=12 stream replay clean at
every chunk size through the real adapter and the real app into chat.delta,
the archive and the receipt; normal zh/en preserved byte-for-byte; unclosed
explicit thinking still fails honestly.

R2 — an authoritative interrupt when the LLM already finalized and TTS is
still playing (review evidence C: zero interrupts, old audio played out).
The page's existing hush() entry (ChatPanel untouched) now also publishes
{"v":1} on the room's own reliable data channel topic cg.interrupt
(fire-and-forget: a dropped publish never blocks or breaks the text send);
the worker subscribes data_received, validates topic/sender/payload and
calls session.interrupt(force=True) — the SDK's own programmatic interrupt,
force confirmed against the installed 1.8.8 source (non-force raises
RuntimeError on allow_interruptions=False speech). Failures log loudly; the
listener is unloaded via add_shutdown_callback; the server-cancel path in
llm_chat_api also interrupts with force and logs failures.

Verification (offline, zero real requests): real-SDK harness 8/8 including a
real SpeechHandle with a genuinely pending playout wait released by the
cg.interrupt message after a clean chat.final (evidence-C shape) plus the
full validation matrix; .venv311 full suite 480 passed / 8 skipped (2
test_r3 failures pre-exist at 5625de6); web npm ci from the existing lock,
typecheck 0 errors, lint 0 errors + 1 pre-existing warning, vitest 148/148,
build ok; ruff clean; check_requirements vs origin/main and b8ec832 with the
corrected handoff.

Co-authored-by: multica-agent <github@multica.ai>
2026-10-28 22:21:16 +08:00

11 KiB
Raw Blame History

HEL-908 · 定点返修记录:交谈打断丢字 + 内部思考外泄(2026-10-28)

授权:本卡 HEL-908(主卡 HEL-797 定点返修;2026-10-28 HEL-909 集中返修一次)。 全部验证离线、零真实请求、零部署。 施工基准:agent/agent/47adf6961f8a @ 5625de6606…(完整 SHA 已核); 第一轮交付 b8ec832;HEL-909 审核不通过后在同分支追加本轮提交。 需求基准 v1.12/60 项,两轮均零需求变更。

0. 结论速览(第二轮后)

项 结果
问题1:文字打断丢字 / 旧轮复活 / 旧语音约32秒 ✅ 第一轮已修(HEL-909 复核通过,含真实 SDK 证据)
R1:隐式思考整段进流式/落库/receipt(HEL-909 不通过项) ✅ 已按裁定改为显式整轮缓冲模式(buffer_turn),评审复现串 A1/A2 逐字/小块经真实适配器→真实 app→落库/receipt 全干净
R2:LLM 已 final、TTS 仍在播时文字无法停旧声(HEL-909 不通过项) ✅ 网页既有 hush() 入口经房间数据通道发 cg.interrupt(reliable),worker 订阅→session.interrupt(force=True)(LiveKit 既有打断),真实 SDK 播放等待取消证明 8/8
第一轮交付中“落库与 receipt 始终干净”的表述 ❌ 不实,已删除(原流式 hold 方案在中文句号/超128字符形状下整段泄漏且 closer 被适配层提前删除,轮级 split 无法兜底——HEL-909 A1/A2 证实)
既有有限重试/幂等重放/receipt 校验 ✅ 未破坏(专项测试持续通过)
真实端到端复测(真人/真房间/时延) ⛔ 未做,交回总管按授权窗口安排

1. 问题1根因与修复(第一轮,HEL-909 复核通过)

事实链:worker.log:108 的 SDK 重试警告在文字 POST 后 13ms——取消发生在首 delta 前 (output_sent=False),服务端取消收尾无终态帧,worker 把它当连接错误,livekit-agents 1.8.8 LLMStream._main_task 静默重试同一 turn_id,重试重新激活已取消轮、反杀新文字轮、 重新生成整段语音播完(DB id=5/6/8;t0 后 32.0 秒音频)。原报告“_retry_on_chunk_sent 守卫从未生效”的推断不成立:守卫只在已有输出后适用(.12 实装源码核对一致)。

修复(双侧):服务端取消显式下发 chat.cancelled 终态帧;cancelled 轮永久拒绝 重新激活(failed 轮仍可重试);worker 以 SDK 自身 499 路径正常结束不重试, SpeechHandle.interrupt() 停掉已缓存音频;server_cancelled 重入闸零网络短路。

2. R1:思考分流(第二轮重做)

第一轮方案为何被否:流式 hold(128 字符/中文句末解除)在真实 token 到达方式下 必现泄漏——'private reasoning '*20+'</think>回答。'(超128、无句末标点)与 '我先想一下。内部思考</think>回答。'(中文句号解除 hold)都会把思考整段放出,且 stray closer 被适配层删除后,app 的轮级 split_reasoning 永远剥不掉前缀;第一轮交付 声称“落库与 receipt 始终干净”不成立(HEL-909 A1/A2/A7,本卡已在修复前离线复现同结果)。

本轮方案(按总管工程裁定:确定的整轮缓冲,不再用长度/标点/英文片段当判据):

  • providers/llm/reasoning.py 两个显式模式:
    • TurnReasoningGate(buffer_turn):生成期间不外发任何内容,流结束后 split_reasoning 整轮分离,一次性下发干净正文;reasoning_content 字段增量仍走 LLMDelta.reasoning 诊断通道(绝不持久化/下发/播报)。
    • ReasoningSeparator(stream,默认、向后兼容):仅滤显式 <think> 块(跨 chunk 安全);stray closer 原样透传(第一轮的“提前删除 closer”正是缺陷根源,透传保住 信号让 app 轮级 split 可兜底)。不再有任何 hold 启发式。
  • 端点模式显式化:config/models.yaml 三档显式 reasoning: buffer_turn (LLMConfig.reasoning 字面量校验,未配置=既有 stream 语义,其他部署不受影响)。
  • 验证:A1/A2/记录流(id=12)按 1~1000 任意分块经真实 OpenAICompatLLM → 真实 app回放 ——chat.delta、落库行、chat.final、receipt text_hash 全部只绑干净正文;正常中英文 逐字节保留;未闭合显式思考→空正文→诚实 chat.error;stream 模式显式块/字段/跨 chunk 语义保持。
  • 等待代价(如实记录):buffer_turn 下首个可见正文要等整轮生成完成(生成中零 chat.delta;字幕与 TTS 首包不再先于全文);取消/超时行为:被取消轮照常 chat.cancelled 收尾(零泄漏),stream_timeout(60s)超时照常 chat.error 诚实失败。低延迟未实测、 也不宣称。
  • 边界(如实):无 closer、无 reasoning 字段、无开头标签的推理在任何客户端模式下都 无法与正文区分,只有上游自行分流可解;本轮保证的是已实证“带 closer”的形状绝不进入 chat.delta/字幕/TTS/落库/receipt。

3. R2:LLM 已 final、TTS 仍在播时的权威打断(第二轮新增)

缺口(HEL-909 evidence C):第一轮唯一打断点在“仍活跃 SSE 收到 cancelled”;旧轮 拿到 final 后服务端已清 active,播放句柄仍 pending 时新文字没有任何权威打断路径——旧语音 照旧播完。

修复(复用 LiveKit 既有通道与打断,无第二套调度器):

  • web(仅 web/src/voice/session.ts + livekit.ts 纯传输接线):VoiceRoom 增 interrupt();既有 hush()(ChatPanel 文字发送时的既有入口,零界面改动)在本地静音 反馈之外经 localParticipant.publishData('{"v":1}', {reliable:true, topic:'cg.interrupt'}) 发出本通打断消息——fire-and-forget,publish 未完成/失败/断线不产生未处理异常、不阻塞 文字发送(失败丢弃:本地静音与服务端轮次门仍在)。本通绑定由房间隔离天然成立。
  • worker(worker.py 新增 bind_interrupt_channel):订阅本房间 data_received; 校验 topic 精确 cg.interrupt、发送者为远端用户参与者(服务端/自身来源忽略)、载荷 {"v":1} 精确匹配;通过即 session.interrupt(force=True)(SDK 现成 programmatic 打断;AgentActivity.interrupt 实装源码核 对 force 透传到 _current_speech.interrupt (force=…),真实句柄在 allow_interruptions=False 且非 force 时抛 RuntimeError——故 force)。失败大声留痕(print 落 worker.log),不静默假装成功;add_shutdown_callback 注册卸载,会话结束移除监听。llm_chat_api._interrupt_owner 同步改为 force=True+留痕。
  • 真实 SDK 证明(8/8,agent venv 1.8.8):真实 SpeechHandle(allow_interruptions= False,覆盖 force 语义)+ 真实 pending 播放等待(wait_if_not_interrupted)——完整轮 (chat.final 干净结束、无取消路径触碰句柄=评审 C 形状)后注入 cg.interrupt 数据消息, 播放等待被真实 interrupt 释放、句柄 interrupted;校验矩阵(错误 topic/服务端来源/自身/ 坏载荷/错版本)全部不触发;卸载后不再触发;session 未运行时大声失败不崩溃。非 Spy 计数:打断走真实句柄的真实 interrupt 语义(HandleSessionBridge 只站在 AgentSession.interrupt 的位置,其到句柄的转发按实装源码核对)。
  • app 集成记录:完整语音轮之后文字轮即普通轮(无任何行被取消、无 phantom 行)—— 该时序在 app 缝合面正常,缺的只是 worker 侧通道,本轮已闭合。

4. 变更表(本轮追加)

文件 变更
src/cybergril/providers/llm/reasoning.py 重做:TurnReasoningGate(整轮缓冲)+ 无启发式 ReasoningSeparator(stray closer 透传);split_reasoning 保持
src/cybergril/providers/llm/openai_compat.py 显式 reasoning 模式参数(stream/buffer_turn,默认前者)
src/cybergril/config.py + think/wiring.py + config/models.yaml LLMConfig.reasoning 字面量 + 透传;三档显式 buffer_turn
src/cybergril/voice/worker.py 新增 bind_interrupt_channel(订阅/校验/force 打断/留痕/卸载),entrypoint 接线
src/cybergril/voice/llm_chat_api.py _interrupt_owner force=True+失败留痕
web/src/voice/session.ts / livekit.ts VoiceRoom.interrupt();hush() 附带发 cg.interrupt(纯传输接线,零视觉改动)
tests/test_reasoning_separation_hel908.py 重写为双模式(A1/A2/记录流任意分块、中英文保留、跨 chunk、字段、未闭合、stray 透传)
tests/test_rework_hel908.py A1/A2 经真实适配器→真实 app→落库/receipt 回放;evidence-C 时序 app 记录;adapter fixture 按 buffer_turn
tests/test_sdk_livekit_hel908.py +3 项 R2 真实 SDK 检查(共 8)
tests/test_voice_asr_usage.py FakeCtx 补 add_shutdown_callback/`room.on
web/tests/*.test.ts(5 个) VoiceRoom 桩补 interrupt();voice.test 断言 hush 时通道被调用

5. 验证(全部离线、零真实请求)

  • 规范环境 .venv311(只读复用):全量 480 passed / 8 skipped / 2 failed——两个 test_r3 基线/迁移失败在基准 5625de6 上同样失败(预先存在,前轮已留证)。
  • 真实 SDK harness(agent venv,livekit-agents 1.8.8):8/8(前轮 5 项回归全保持 + R2 三项新证)。
  • web:npm ci(既有锁文件+缓存,零新依赖/零 lock 变更);typecheck 0 错;lint 0 错 1 既有警告(ChatPanel.tsx:252 react-hooks,非本卡引入);vitest 148/148; build 成功。
  • ruff src/ tests/ 全绿;config/models.yaml 新键经 ModelsConfig 实际解析验证。
  • 本地环境(py3.10 与 lock 版本不一致):reasoning 69/69 与 ruff 本地跑通;app 级用例按 项目既有方式在 .12 规范环境执行。
  • 日志:tests-remote-r2.log(全量+SDK harness)、web-r2.log、 check-requirements.log(本轮重跑)。

6. 残留与未测(如实)

  1. buffer_turn 的首段等待代价:整轮生成完成前无任何可见正文(已在 §2 记录并测试固定 该行为);对长回复的字幕/TTS 起播延迟未在真实端到端测量——真实端点体验须授权窗口。
  2. 无 closer、无字段的推理不可识别(§2 边界);stream 模式下 stray closer 透传意味着 该模式端点若真出现隐式思考,字幕/TTS 会看到标记原文(落库/receipt 由轮级 split 清理) ——产品端点已配 buffer_turn,不受此影响。
  3. R2 真实房间端到端(页面 publish→worker 停播的实际时延、断线姿态)未测;离线证明是 真实 SDK 句柄/等待语义 + 实装源码核对,不冒充端到端毫秒指标。
  4. chat.cancelled 前端呈现(建议 #4)、ChatPanel 取消判定 limit(建议 #3)等非阻塞 建议未动(后者纯展示层;前者属界面核心,交视觉总监)。
  5. R1–R7 完整功能、真实用户麦克风、视频/口型、记忆长跑仍按获批依赖承接。