Files
CyberGril/scripts/gen_hel877_sdk_check.py
T
施工员2号 aba2aebeb0 HEL-877: wire the audited .12 voice base into the one CyberGril chat chain as backend-only code (no deploy, no real voice call) - new independent src/cybergril/voice module: session+router add POST /api/voice/session / DELETE end / GET honest status on the unified instance (server-side room + dedicated cybergril-voice-agent dispatch + short-TTL join token via zero-new-dependency livekit_wire HS256/Twirp matching the installed SDK's wire format verified claim-for-claim on the .12 agent venv stdin-only; keys never reach the browser; unconfigured/no-profile/TTS-down refuse honestly and capabilities.voice stays false), chat_api_client speaks the exact real.ts RealChatAdapter protocol (per-turn health epoch, bounded 409 resync, robust incremental SSE parsing across multibyte/CRLF/multi-data chunk splits, fixed turn_id idempotency, immediate HTTP-stream close on barge-in without waiting for the next ASR final), llm_chat_api is a livekit llm.LLM adapter whose only backend is POST /api/chat so persona/mood/dyad/memory/life-sharing/budget gates and the one same-turn chat_lock govern text and voice identically (phi spoken verbatim via ChatChunk, never archived, no receipt), receipt.py confirms a sharing receipt only after real SDK playback completion with every negative (interrupted/failed/mid-playout/phi/incomplete/stale-epoch) fail-closed and exactly once per turn, stt_funasr/tts_cosyvoice reuse the proven .12 adapters verbatim with provenance, worker.py assembles the dedicated worker (independent voice_state_cybergril.json so D1 stays undecided, no second persona, cg.subtitle data-channel contract for the visual lead, CG-011 proactive seam left as an explicit no-op hook, built-in health port 8082); app.py keeps a minimal registration with voice_service injection for isolated tests; deployment drafts only (config/voice.example.yaml, worker.env.example, restart_cybergril.sh.example with exact-pattern process matching, serve_dual_8360_8361.py keeping HTTP 8360 and the HTTPS voice entry on ONE process sharing state/locks, runbook-hel877-voice.md contract+startup+rollback incl. the >=6GB GPU precondition and the do-not-copy historical fuser warning) - verification: 281 pytest pass on 3.11 venv + requirements.lock after merging the chief engineer's mid-flight HEL-874 rework e978e87 in full (parallel work preserved), verify_hel877_voice_chain.py 8/8 offline full-chain incl. socket-level barge-in fail-close and text/voice mutual same-gate cancellation, real-SDK check on the .12 livekit-agents 1.8.8 venv 8/8 ALL PASS via SSH stdin with zero writes zero network, dual-port single-process smoke on loopback 18360/18361 with a throwaway self-signed cert then stopped, ruff clean on all new code, dual-target requirement checks pass vs origin/hel-870-assembly (current tip e978e87) and origin/main with handoff-HEL-877.json; zero real LLM/embed/TTS/ASR requests, no mic/camera, no downloads/installs, no service start/stop, no 4080 access, no third-account or profile writes, web/ untouched, not merged, not deployed
Co-authored-by: multica-agent <github@multica.ai>

## HEL-877 交付摘要(R5 后台施工,未部署未合并)

- 新独立模块 src/cybergril/voice/:专属 livekit worker(agent_name=cybergril-voice-agent,复用 .12 FunASR/CosyVoice/silero 底座,不 fork 不另搭平台,无第二人格/记忆,不直连 LLM);llm_chat_api 适配器与文字前端 real.ts 同协议走 POST /api/chat(epoch 409 有界重同步、SSE 分片、turn_id 幂等、打断即断流);/api/voice/session 建房+专属派发+短时限 token 全服务端(密钥不进浏览器;缺配置/无档案/TTS 停机诚实拒绝;capabilities.voice 不伪造);receipt 仅在 SDK 真实播放完成后确认(打断/失败/φ 轮/旧 epoch 全 fail-closed)。
- 部署草案:/opt/voice-agent-cybergril 目录、worker 健康端口 8082、HTTP 8360 + HTTPS 8361 同进程双入口(deploy/voice/serve_dual_8360_8361.py,共用同一状态/锁)、启动顺序含 TTS GPU≥6GB 前置与回滚;本卡未执行任何启停。契约(开关/字幕/失败/打断/挂断 + CG-011 主动开口接缝)见 docs/runbook-hel877-voice.md §3。
- 自测(零真实请求):281 pytest 全过(含语音 25 例:socket 级打断断流、SSE 边界、重放零调用、文字/语音同门互打断、回执全负例、token 房间隔离);scripts/verify_hel877_voice_chain.py 8/8;.12 agent venv(livekit-agents 1.8.8)真 SDK 检查 8/8(stdin-only 零写入零网络);双端口同进程本地冒烟通过;ruff 干净;需求检查双目标通过(含 handoff-HEL-877.json)。
- 施工中总工 HEL-874(e978e87)推上同分支,本卡已完整并入,不覆盖并行成果。未验证如实列明:端到端语音(TTS 停机/GPU 3.9GB<5.6GB)、真 LiveKit server 的 dispatch/delete、移动端实机——待接线/审核卡真机验收,未经真实验收不称 R5 完成。
2026-10-26 22:42:19 +08:00

202 lines
8.6 KiB
Python

#!/usr/bin/env python3
"""Generate the HEL-877 real-SDK compatibility check for the .12 agent venv.
Embeds the repo voice-module sources in a self-contained stdin script (no files
written to .12, no network, no service touched) and runs it with
/opt/voice-agent/agent/venv/bin/python (livekit-agents 1.8.8, livekit 1.1.20).
"""
from __future__ import annotations
import base64
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
MODULES = ["chat_api_client", "receipt", "llm_chat_api"]
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"<cybergril.voice.{name}>", "exec"), mod.__dict__)
setattr(voice, name, mod)
import httpx
from livekit.agents import llm as lk_llm
from livekit.agents.llm import LLM, LLMStream, ChatChunk, ChoiceDelta
ok = []
# 1. real-SDK subclass contracts
llm_mod = sys.modules["cybergril.voice.llm_chat_api"]
assert issubclass(llm_mod.CyberGrillLLM, LLM), "CyberGrillLLM must subclass the real llm.LLM"
assert issubclass(llm_mod.ChatApiLLMStream, LLMStream)
ok.append("CyberGrillLLM/ChatApiLLMStream subclass real livekit-agents 1.8.8 LLM/LLMStream")
# 2. real ChatContext -> latest_user_text
ctx = lk_llm.ChatContext()
ctx.add_message(role="assistant", content="早些的一句")
ctx.add_message(role="user", content="真实SDK链路你好")
assert llm_mod.latest_user_text(ctx) == "真实SDK链路你好"
ok.append("latest_user_text reads a real ChatContext (items/role/text_content)")
# 3. full turn through the real LLMStream machinery with fake SSE
FINAL = "真实链路上的一句完整回复。"
sse = (
'data: {"t":"chat.delta","epoch":1,"turn_id":null,"delta":"真实链路上"}\n\n'
'data: {"t":"chat.delta","epoch":1,"turn_id":null,"delta":"的一句完整回复。"}\n\n'
'data: {"t":"chat.final","epoch":1,"turn_id":null,"utterance":{"text":"' + FINAL + '"},'
'"receipt":{"message_id":9,"turn_id":null,"epoch":1,"token":"' + "k" * 48 + '","text_hash":"' + "h" * 64 + '"}}\n\n'
).encode()
def handler(request: httpx.Request) -> httpx.Response:
if request.url.path == "/api/health":
return httpx.Response(200, json={"epoch": 1})
return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=sse)
receipt_ok = {}
async def round_trip():
client = llm_mod.ChatApiClient("http://x", transport=httpx.MockTransport(handler))
adapter = llm_mod.CyberGrillLLM("http://x", client=client)
stream = adapter.chat(chat_ctx=ctx)
chunks = []
async for chunk in stream:
assert isinstance(chunk, ChatChunk) and chunk.delta and chunk.delta.content
chunks.append(chunk.delta.content)
assert "".join(chunks) == FINAL, chunks
assert stream.completed and stream.receipt and stream.receipt["message_id"] == 9
receipt_ok["text"] = stream.text
receipt_ok["receipt"] = stream.receipt
asyncio.run(round_trip())
assert receipt_ok["text"] == FINAL
ok.append("fake-SSE turn through real LLMStream emits ChatChunks, final text and receipt")
# 4. phi error turn: spoken verbatim, no receipt
phi_sse = (
'data: {"t":"chat.error","epoch":1,"turn_id":null,"phi":"她这会儿没接上话,稍后再试试。你写的话还在。","retryable":true}\n\n'
).encode()
def phi_handler(request: httpx.Request) -> httpx.Response:
if request.url.path == "/api/health":
return httpx.Response(200, json={"epoch": 1})
return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=phi_sse)
async def phi_turn():
adapter = llm_mod.CyberGrillLLM("http://x",
client=llm_mod.ChatApiClient("http://x", transport=httpx.MockTransport(phi_handler)))
stream = adapter.chat(chat_ctx=ctx)
spoken = []
async for chunk in stream:
spoken.append(chunk.delta.content)
assert "".join(spoken) == "她这会儿没接上话,稍后再试试。你写的话还在。"
assert stream.error_phi and not stream.completed and stream.receipt is None
asyncio.run(phi_turn())
ok.append("chat.error phi is spoken verbatim via ChatChunk and carries no receipt")
# 5. token claims parity with the real livekit.api.AccessToken
from livekit import api
import jwt as pyjwt
wire = sys.modules["cybergril.voice.livekit_wire"]
mine = wire.mint_token("devkey", "s3cret", identity="user-ab", name="用户",
room="cg-voice-test", room_join=True, ttl_seconds=300, now=1700000000.0)
sdk_token = (api.AccessToken("devkey", "s3cret").with_identity("user-ab").with_name("用户")
.with_grants(api.VideoGrants(room_join=True, room="cg-voice-test",
can_publish=True, can_subscribe=True))
.to_jwt())
mine_claims = pyjwt.decode(mine, "s3cret", algorithms=["HS256"], options={"verify_exp": False})
sdk_claims = pyjwt.decode(sdk_token, "s3cret", algorithms=["HS256"], options={"verify_exp": False})
assert mine_claims["video"] == sdk_claims["video"], (mine_claims["video"], sdk_claims["video"])
assert mine_claims["iss"] == sdk_claims["iss"] and mine_claims["sub"] == sdk_claims["sub"]
assert set(mine_claims) == set(sdk_claims), (sorted(mine_claims), sorted(sdk_claims))
ok.append("mint_token claims byte-parity with livekit.api.AccessToken (video/iss/sub/keys)")
# 6. server token decodes as the SDK Service._auth_header shape
server_tok = wire.mint_server_token("devkey", "s3cret", ttl_seconds=60, now=1700000000.0)
sc = pyjwt.decode(server_tok, "s3cret", algorithms=["HS256"], options={"verify_exp": False})
assert sc["iss"] == "devkey" and sc["sub"] == "" and "video" not in sc
ok.append("mint_server_token matches SDK no-grant auth header claims")
# 7. SpeechHandle/worker API surface used by worker.py exists on the real SDK
from livekit.agents.voice.speech_handle import SpeechHandle
for attr in ("wait_for_playout", "interrupted", "exception", "add_done_callback"):
assert hasattr(SpeechHandle, attr), attr
from livekit.agents.voice.events import UserInputTranscribedEvent
assert "is_final" in UserInputTranscribedEvent.model_fields
ok.append("worker.py SDK surface (SpeechHandle, UserInputTranscribedEvent.is_final) present")
# 8. barge-in cancellation closes the SSE response immediately
state = {"response": None}
async def slow_body():
yield 'data: {"t":"chat.delta","epoch":1,"turn_id":null,"delta":"开头"}\n\n'.encode()
await asyncio.sleep(30)
yield 'data: {"t":"chat.final","epoch":1,"turn_id":null}\n\n'.encode()
class TrackingTransport(httpx.MockTransport):
async def handle_async_request(self, request):
response = await super().handle_async_request(request)
if request.url.path == "/api/chat":
state["response"] = response
return response
def slow_handler(request: httpx.Request) -> httpx.Response:
if request.url.path == "/api/health":
return httpx.Response(200, json={"epoch": 1})
return httpx.Response(200, headers={"content-type": "text/event-stream"},
content=slow_body())
async def cancel_case():
adapter = llm_mod.CyberGrillLLM("http://x",
client=llm_mod.ChatApiClient("http://x", transport=TrackingTransport(slow_handler)))
stream = adapter.chat(chat_ctx=ctx)
task = asyncio.create_task(stream._run())
await asyncio.sleep(0.2) # first delta consumed
assert state["response"] is not None and not state["response"].is_closed
task.cancel()
try:
await task
except asyncio.CancelledError:
pass
assert state["response"].is_closed, "adapter must close the HTTP stream on barge-in"
asyncio.run(cancel_case())
ok.append("barge-in task cancel closes the in-flight HTTP stream immediately")
print("HEL-877 real-SDK check on livekit-agents", end=" ")
import importlib.metadata as md
print(md.version("livekit-agents") + ":", "ALL PASS")
for line in ok:
print(" OK", line)
'''
def main() -> int:
sources = {}
for name in MODULES + ["livekit_wire"]:
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/_hel877_sdk_check_payload.py"
out.write_text(script, encoding="utf-8")
print(out)
return 0
if __name__ == "__main__":
import json
sys.exit(main())