diff --git a/docs/requirements/handoff-HEL-906.json b/docs/requirements/handoff-HEL-906.json new file mode 100644 index 0000000..00266d5 --- /dev/null +++ b/docs/requirements/handoff-HEL-906.json @@ -0,0 +1,44 @@ +{ + "baseline_version": "1.12", + "read_commit": "0b804a49ef53eb3d251347c147d96a3f6aa5fe19", + "task": "HEL-906:补齐连续语音实际用量计数与测试准备(施工)。只补 HEL-905 复审明确列出的连续通话 ASR 实际用量/连接重试计数缺口:在 CyberGril 专属 worker/适配层复用现有 LiveKit/FunASR 接口,落地每通话与全窗口的实际送入 ASR 音频量与连接尝试/重连/失败计数;达到有限窗口上限时在发送前/建连前阻止并结束本通;上限为待用户批准的新一次性窗口,默认未布防=真实 cap=0(fail-closed,与 think/budget.py 同一先例)。旧 HEL-879 封账保持原样。零模型/嵌入/真实 ASR/TTS、零新增安装下载、不启动服务、不改共享 /opt/voice-agent、不改视觉、不合并 PR。", + "requirement_ids": [ + "CG-010", + "CG-018", + "CG-019", + "CG-020", + "CG-021", + "AM-001", + "GOV-001", + "GOV-002", + "GOV-003", + "GOV-004", + "GOV-005", + "GOV-006", + "DEL-001" + ], + "deliverable": "独立分支 hel-906-asr-usage-counting(基于 origin/hel-905-unified-review@0b804a4,源码提交 ecec9df):①src/cybergril/voice/asr_usage.py(仅标准库)——追加写 JSONL 账本(默认 /opt/voice-agent-cybergril/asr-usage.jsonl)、每通/全窗计数(音频按实际发送帧 样本数/采样率 计时、重发按重复计;连接=逐次尝试含失败、一句一连的正常重建不计 retry、接收侧死亡计 connection_died)、fail-closed 默认(无 CYBERGRIL_ASR_WINDOW_ID 即拒绝一切连接/音频)、触线在发送前/建连前拒绝(AsrWindowClosed)、账本重放恢复(同窗重启不重置预算、跨窗口互不影响)、只读汇总 CLI(python -m cybergril.voice.asr_usage);②stt_funasr.py 真实送数接缝——建连前 check_connect、建连结果落账、发送前 precheck_audio(越限帧零字节出站)、发送成功后 note_audio_sent、utterance 边界/流结束聚合落账、接收侧死亡标记;usage=None 时行为与本卡之前完全一致;③worker.py entrypoint 按 job 构造 guard(房间名为每通标识)、on_exhausted→ctx.shutdown 结束本通、启动日志输出窗口摘要;④tests/test_voice_asr_usage.py 17 项确定性离线测试(假 livekit/websockets SDK 驱动真实 _run 接缝+guard 单元);⑤docs/rework/hel902/r5-followup-package.md §4 前置缺口修掉:计数手段、布防变量、可复现验证命令、程序保证/仅能监看边界(跨进程 ≤5s 有界过冲、崩溃 ≤5s 少计、.12 真实栈联验仍待窗口前执行)、里程碑表登记本卡分支;本 handoff JSON", + "acceptance": [ + "计数口径:音频=实际发送帧样本数/采样率(48k 重采样后按 16k 输出帧计,测试验证两采样率精确合计);墙钟与事后成功流水不参与;同一帧重发按重复计", + "连接口径:每次建连尝试(含失败)逐条落账;正常说完一轮后的下一次建连不是 retry,只有失败/接收侧死亡/流异常之后的建连计 retry;每通 retry 上限建连前拒绝(测试驱动真实接缝验证拒绝始于建连之前、假 provider 未被触碰)", + "到线停机:全窗口音频上限触线时越限帧在发送前拒绝(出站字节恰至上限,一个字节不越线)、on_exhausted 恰好一次、worker 接线断言 ctx.shutdown 真被调用结束本通;未布防默认拒绝一切 ASR(真实 cap=0 的代码级落实)", + "历史与恢复:删房成功后 asr-usage.jsonl 逐通历史原样保留(测试用真实 VoiceSessionService 成功删房对照);同窗口重启 guard 重放恢复预算与逐通计数,不得重置;不同 window id 互不误停", + "确定性离线测试:静音数据帧计数、取消(不 flush 直接结束)、建连失败、重连、反复结束多通、不同采样率、触线前拒绝、落盘恢复、崩溃少计有界(≤flush 阈值如实声明)、接缝真被专属 worker 调用(entrypoint 注入断言)", + "补测包 §4:'待补阻塞'改为已落地机制+布防环境变量+可复现命令(pytest tests/test_voice_asr_usage.py、python -m cybergril.voice.asr_usage),首行状态与硬闸/监看界线同步更新,里程碑表登记本卡分支;窗口候选上限不放宽(≤2h/3通话/6开房/LLM20/60000tokens/嵌入0/登记3/预听10/通话TTS40段/ASR45分钟/每通重连6次/新增付费0)" + ], + "deferred": [ + "窗口前 .12 真实栈联验:用 scripts/gen_hel877_sdk_check.py 同法在真实 agent venv 加载本模块,确认真 SDK 帧率/重采样与 ctx.shutdown 真实行为(离线假件无法替代,未验证前不启动含连续通话步骤)", + "新一次性窗口仍待白栖知批准:未批前真实 cap=0,不启动、不预留出站;获批后由窗口负责人显式布防 CYBERGRIL_ASR_WINDOW_* 环境变量", + "跨进程并行通话的有界过冲(≤5s resync/flush 间隔)与崩溃少计(≤5s)属如实声明的监看边界,不冒充零误差硬闸;窗口负责人仍按 §4 盯账本合计", + "真机麦克风/文字打断帧级量测、LiveKit/worker 侧房间指标交叉核对:并入获批窗口执行,本卡不自行采麦/摄像头", + "前端浏览器/构建独立复跑(同锁 npm ci)仍为单独待批项;CG-009/R6 删除与完整备份恢复、R5 整体验收、R1–R7 完整功能继续承接;本卡通过≠自定义音色或连续语音用户验收" + ], + "requirement_changes": [], + "verification": [ + "pytest tests/test_voice_asr_usage.py -q:17/17 通过(venv311 复用,零安装)", + "语音区相关回归:test_voice_asr_usage+test_voice_session+test_voice_custom+test_voice_rework_hel904+test_voice_review_hel902+test_voice_chat_adapter+test_voice_rework_hel879 共 98/98 通过;按卡约定未重跑全量 380/12(作者证据保留)", + "ruff check 四个变更文件通过", + "需求检查:python3 scripts/check_requirements.py 对 origin/main 与 0b804a4 各带/不带本 handoff 四组通过", + "未验证(如实):真实 FunASR/LiveKit/CosyVoice 栈、真实麦克风、浏览器/手机画面——零真实调用,全部待获批窗口" + ] +} diff --git a/docs/rework/hel902/r5-followup-package.md b/docs/rework/hel902/r5-followup-package.md index f2624a2..7b67681 100644 --- a/docs/rework/hel902/r5-followup-package.md +++ b/docs/rework/hel902/r5-followup-package.md @@ -1,7 +1,7 @@ # HEL-902 补测包:自定义声音真机窗口申请材料(交总管集中请批) -状态:**材料基本备齐,其中连续通话 ASR 精确计数手段仍是待补阻塞(§4,窗口前 -须在 .12 验证,不通过则含连续通话的步骤不得启动);未获批前真实 cap=0; +状态:**材料备齐(连续通话 ASR 计数与到线停机已由 HEL-906 落地为可执行 +程序闸,见 §4;剩余仅窗口前 .12 真实栈联验);未获批前真实 cap=0; 本包只写材料,绝不执行**。所有上限为 **新的一次性窗口授权**,不复用、不重开 HEL-879 已封账(其 14/40 请求、 42717/500000 tokens、12/200 TTS 段保持封存,永不重开;剩余数≠新许可)。 @@ -29,6 +29,7 @@ | 后台返修 HEL-904 | `07dda2b`(分支 `agent/2/f337aae1f551`) | 已并入统一复审分支 | | 前端返修 HEL-903 | `088ac62`(分支 `hel-903-preserved`,源码 `51669aa` 11 文件逐字节一致) | 已并入统一复审分支 | | **最终已验证 head** | **`03cec26`**(分支 `origin/hel-905-unified-review`;复审验证基线=03cec26,其后仅本表的登记提交,执行以该分支最新 head 为准。HEL-905 总工统一复审通过:11 文件 SHA256 一致、后台 380/380+12/12+ruff 独立复跑、需求检查 4/4;前端构建/单测/浏览器未独立复跑,如实见 HEL-905 结论) | **复审通过,待主卡请批新窗口** | +| 连续 ASR 计数落地(HEL-906) | `ecec9df`(分支 `hel-906-asr-usage-counting`,基于 `0b804a4`;执行以该分支最新 head 为准,候选 PR 不合并) | 已落地并通过 17 项确定性离线测试+语音区回归 98 项+ruff;待总管复核后与统一 head 合并为窗口执行依据 | ## 1. 部署形态与回滚 @@ -121,13 +122,15 @@ | 试听合成 | ≤10 | `preview_tts` 行(含 TTS 出站无成功响应者) | 工程监看(同上) | | 通话 TTS 段 | ≤40 | worker 侧流水/日志计数 | 工程监看(见下,需窗口前验证命令) | | 音色登记(8090 upload) | ≤3 | 上传出站次数(含断连后已生效者) | 工程监看(面板上传账) | -| **连续通话 ASR 音频时长** | ≤45 分钟(3 通 × ≤15 分钟实操上限) | 见下:**待补阻塞** | 工程监看(无程序闸) | -| **连续通话 ASR 连接重试** | ≤6 次/通 | 见下:**待补阻塞** | 工程监看(无程序闸) | +| **连续通话 ASR 音频时长** | ≤45 分钟(3 通 × ≤15 分钟实操上限) | 实际送入帧计时(含重发),见下:**HEL-906 已落地** | **程序硬闸**(worker 侧发送前拒绝;未布防=拒绝) | +| **连续通话 ASR 连接重试** | ≤6 次/通 | 失败后重试计数(正常一句一连不计 retry),见下 | **程序硬闸**(建连前拒绝;未布防=拒绝) | | 新增付费支出 | 0 | 全程零付费 API | 工程守则 | -**硬闸与监看的界线(如实)**:只有 LLM 请求/tokens 与嵌入是代码级硬闸 -(统一账本 acquire,超限直接拒绝);其余上限是**工程监看或程序计数**, -靠实时看数+负责人停机,**不拿事后流水冒充硬闸**。 +**硬闸与监看的界线(如实,HEL-906 后更新)**:LLM 请求/tokens、嵌入 +(统一账本 acquire)与**连续通话 ASR 音频/连接重试(worker 侧 +AsrUsageGuard,布防后发送前/建连前拒绝)**都是代码级硬闸;其余上限是 +**工程监看或程序计数**,靠实时看数+负责人停机,**不拿事后流水冒充 +硬闸**。ASR 闸的跨进程有界收敛与崩溃少计边界见下段「程序能保证」。 **登记转写 ASR 口径的如实边界(HEL-905 复审核实)**:`register_asr` 流水 只在**登记成功(含本地元数据落盘失败)且参考文字来自转写**时记录;面板侧 @@ -139,7 +142,8 @@ **连续通话 ASR(worker 内 FunASR 连续识别,区别于登记转写 ASR)的计数 手段与停机**: -- 墙钟代理(可程序数,命令可执行;**如实声明其边界**):实例旁会话账本 +- 墙钟代理(可程序数,命令可执行;**如实声明其边界**。HEL-906 后降为 + **下界交叉核对**:执行手段以上方实际帧计数硬闸为准):实例旁会话账本 `-voice-sessions.json` 只保留**当前** `.sessions`(在途)与 `.debts` (删除未落定的欠账)——**删除成功的通话会从账本里移除**,因此 `jq '[.debts[] | (.first_debt_at - .session.created_at)] | add // 0' @@ -151,12 +155,37 @@ ≥麦克风推流时长的上界,再加 §2 每通 ≤15 分钟操作掐表即 ≤45 分钟总上限 的执行手段;窗口负责人:总管。到线即停:停开新会话并挂断在途会话 (`DELETE /api/voice/session/{id}`)。 -- **待补阻塞(如实声明,不假称齐备)**:逐通精确音频时长与 ASR 连接 - 重试次数没有本仓库可执行的程序计数——worker 属共享 .12 栈、不改其代 - 码。候选手段是窗口前由总管在 .12 上验证可执行性:LiveKit 服务端房间 - 指标/日志(如 `lk room list`/服务日志中该房间的 track 与重连事件)或 - worker 日志采样。**窗口开始前若验证不通过,该项保持阻塞,窗口不得 - 启动含连续通话的步骤**;不得以墙钟代理冒充分钟级音频上限。 +- **已落地(HEL-906,修掉本节前置缺口)**:逐通精确音频时长与 ASR 连接 + 重试次数现在有本仓库可执行的程序计数与到线停机——`src/cybergril/voice/ + asr_usage.py`(仅标准库)+专属 worker 真实送数接缝(`stt_funasr.py` + 建连前检查、发送前拒绝、发送成功计数;`worker.py` 按 job 注入并以房间 + 名标识每通,触线回调 `ctx.shutdown` 结束本通)。计数口径: + - **音频**=实际发送帧的 `样本数/采样率` 之和(重采样后的输出帧按其 + 自身 16k 计),同一帧重发按重复计;墙钟与事后成功流水不参与。 + - **连接**=每次 websocket 建连尝试(含失败)逐条落账;FunASR 一句一 + 连的正常重建**不是** retry,只有上次尝试失败/接收侧死亡/流异常结束 + 之后的建连才计 retry(≤6 次/通在建连前拒绝)。 + - **账本**=追加写 JSONL(默认 `/opt/voice-agent-cybergril/asr-usage.jsonl`, + `CYBERGRIL_ASR_USAGE_LEDGER` 可改),逐通 call_start/audio/ + connect_attempt/connection_died/call_end/block 永不改写:删房成功会 + 从会话账本移除该通,但这里的逐通历史保留,窗口总量由重放账本恢复, + 同窗口重启进程不能重置预算。 + - **布防**=窗口启动时由负责人显式设 `CYBERGRIL_ASR_WINDOW_ID`+上限 + (`..._MAX_AUDIO_SECONDS=2700`、`..._MAX_CONNECT_RETRIES_PER_CALL=6`); + 未设即 fail-closed 拒绝一切 ASR 连接/音频(真实 cap=0,含未获批的 + 现在)。旧 HEL-879 封账永不重开,新窗口用新 window id 独立预算。 + - **程序能保证**:布防进程内逐帧发送前硬停(越限帧一个字节不出站)、 + 每通重试上限建连前拒绝、逐通/全窗计数不因删房/重启丢失。**剩余只能 + 监看**:两 worker 进程并行通话时对端最近 ≤ max(resync, flush)=5s 的 + 音频可能未计入本轮判定(有界过冲,每次建连检查会重放账本收敛); + 进程崩溃前 ≤5s 的已发音频可能少计;真实 FunASR/LiveKit 行为仍须 + 窗口前在 .12 用 `scripts/gen_hel877_sdk_check.py` 同法加载本模块联验。 + - **可复现验证命令**(离线,零真实调用): + `python -m pytest tests/test_voice_asr_usage.py -q`(17 项:不同采样率、 + 静音/取消/失败/重连/反复结束、触线前拒绝、落盘恢复、删房不丢历史、 + 跨窗口不误停、worker 接线与默认 fail-closed); + `python -m cybergril.voice.asr_usage [--window W]` + (窗口中实时核对逐通/全窗合计的只读汇总)。 **停机方法**:任一上限达到即停(LLM/嵌入自动拒;其余实时盯 `voice-usage.jsonl`、统一账本与会话账本);窗口结束停 8360/8361/8082/