[diyuyi-agora]

No description provided.

[diyuyi-agora]

ASR design review（re-review @ 06a6db7）

针对上一轮 P1：recovery flush 在无锁下改写 self.metadata、以及 timed-out 边界 _prepare_finalize_context 重新写入 _finalize_contexts 且无清理。

静态核对（06a6db7d）

原问题	结论
§11.1 recovery flush 与 in-flight TTFW/TTLW 竞态	已修复：send_audio() / _handle_audio_frame 帧 metadata 更新、on_result 临时 metrics 上下文均经 _result_context_lock；recovery _flush_buffered_frames → _consume_buffered_frame → send_audio() 走同一路径。test_recovery_flush_preserves_in_flight_ttfw_session 覆盖。
timed-out 后队列边界仍注册 _finalize_contexts	已修复：_prepare_finalize_context(..., register_context=False) 跳过 re-register；_handle_finalize 在 _completed_finalizes + is_finalize_timed_out 分支 finally 执行 _finalize_contexts.pop；正常 _finish_finalize(timed_out=True) 亦 pop。test_finalize_timeout_seals_queued_turn_before_next_finalize 断言 "final-a" not in ext._finalize_contexts。

ASR checklist

项	结果
Package/addon/manifest/graph 命名；manifest 导入 asr-interface	pass
Config 校验与 config: 脱敏日志	pass
无效 config 单次 FATAL、阻止连接	pass
start_connection() 握手后才 connected	pass
连接失败/关闭关闭 base 连接状态	pass
expected / unexpected / stop / config swap 区分	pass
单一 reconnect owner、有界 backoff、stop/fatal 取消	pass
旧 client stale callback 忽略	pass
send/finalize/stop/config swap 不与同一 client 竞态	pass
缓冲策略有界、session-safe、recovery 后 flush	pass
AudioFrame 解锁；send_audio 返回值准确	pass
AudioTimeline 用户音频与注入 silence	pass
ASR result 形状 / final·locked / timestamps	pass
session_id 在 metadata；vendor 在 asr_info	pass
Finalize 必 echo finalize_id/session_id（含 timeout/断开）	pass
同 session 至少两轮 audio→finalize	pass（测试覆盖）
框架 severity 与 vendor_info 分离	pass
connect delay / TTFW / TTLW metadata	pass
vendor_metadata 与日志脱敏	pass
Dump 原始 PCM 无 finalize silence 污染	pass
stop/deinit 取消并 await 后台任务	pass
Standalone tests	pass（本地 72 pytest）
ASR guarder	pass（本地 12）
task format / task check / task lint	N/A（本次未复跑）

Findings（P1/P2 merge blockers）

无。

REVIEW PASS

[github-actions]

1. [P1] Handle pending VAD commit failures as transport failures — recognition.py:778–782

   With server_vad=true, finalize after speech_stopped but before transcription completion reaches these direct sends. They bypass _pump_or_reconnect()'s exception handling, so a socket failure escapes through _handle_finalize() into _audio_frame_consumer(), which latches _fatal and discards all subsequent audio. Even ConnectionClosedOK becomes a fatal ASR error. Apply the common transport classification/recovery handling to these sends, and test normal and abnormal closes through the input consumer. Merge blocker: ASR guide §§9.2/10.

2. [P2] Convert dropped PCM bytes to milliseconds — extension.py:917–919

   Disconnected-buffer overflow passes a byte count to AudioTimeline.add_dropped_audio(), whose argument is a duration in milliseconds. At the required 16 kHz mono PCM16 format, dropping 3,200 bytes records 3,200 ms instead of 100 ms. Recovered result and word timestamps consequently run 3.1 seconds late per such frame. Convert using the actual audio format and add an overflow/recovery regression asserting emitted timestamps; the standalone tests currently have no timestamp/timeline assertions. Merge blocker: §§6.3–6.4.

3. [P2] Saturate retry delay before evaluating the power — reconnect_manager.py:34

   Retries are unlimited by default, but failure 1,025 evaluates 0.5 * 2**1024 before applying min(), raising OverflowError. This escapes _reconnect_loop() and ends recovery, so transcription cannot resume when the service returns. Cap the exponent or saturate before multiplication, including the equivalent expression in handle_reconnect(). Add a delay regression beyond 1,024 failures; the current budget test stops at 50 and never calls next_delay(). Merge blocker: §9.2.

ASR checklist

Area	Result
Lifecycle	PASS on static inspection
Connection state	PASS on static inspection of handshake/status paths
Buffering	FAIL — dropped duration uses bytes (#2)
Finalize	FAIL — pending VAD commit failure latches fatal (#1)
Reconnect	FAIL — transport classification and backoff overflow (#1, #3)
Result shape	FAIL — timestamps include inflated dropped duration (#2)
Metrics	PASS on static inspection of connect delay and TTFW/TTLW metadata
Tests	FAIL — regressions above are missing; runtime execution N/A

These issues remain present at a61238c. Reviewed against the checked-out ASR guide and published ten_ai_base 0.7.62 (6189b87), since the base package is absent locally. Python/JSON parsing and patch application checks passed; the overflow and byte-to-duration arithmetic were independently checked. PR code, scripts, and tests were not executed, and dependencies were not installed. Existing passing guarder evidence references an earlier head.

[github-actions]

1. [P1] Handle pending VAD commit failures through transport recovery — recognition.py:783–787

   With server_vad=true, a finalize received after speech_stopped but before the final transcript reaches these direct sends. A socket failure bypasses _pump_or_reconnect() and escapes into _audio_frame_consumer(), which sets _fatal and discards all subsequent audio. Even ConnectionClosedOK becomes a fatal ASR error. Route these sends through the common close classification/recovery path and add normal/abnormal close regressions through the input consumer. Merge blocker: ASR guide §§9.2 and 10 require normal closes without ASR errors and recovery for transient failures.

2. [P2] Convert dropped PCM bytes to milliseconds — extension.py:917–919

   Disconnected-buffer overflow passes a byte count to AudioTimeline.add_dropped_audio(), which takes milliseconds. At 16 kHz mono PCM16, dropping 3,200 bytes records 3,200 ms instead of 100 ms. Recovered result and word timestamps consequently advance 3.1 seconds too far for each such frame. Convert using the configured audio format and test overflow followed by recovery against the emitted timestamps. Merge blocker: §§6.3–6.4 require correct buffering and timeline accounting.

3. [P2] Saturate the backoff before calculating the exponential — reconnect_manager.py:34

   Retries are unlimited by default, but failure 1,025 evaluates 0.5 * 2**1024 before min() can cap it, raising OverflowError. The exception exits _reconnect_loop(), leaving recovery stopped when the service returns. Cap the exponent or saturate before multiplication, including the equivalent expression in handle_reconnect(). Add a regression that evaluates delays beyond 1,024 failures; the existing unlimited-budget test only increments the counter 50 times. Merge blocker: §9.2 requires the reconnect policy to continue until success, stop, fatal failure, or its configured ceiling.

ASR checklist

Area	Result
Lifecycle	PASS on static inspection of cleanup paths
Connection state	PASS on static inspection of handshake/status paths
Buffering	FAIL — dropped duration uses bytes (#2)
Finalize	FAIL — pending VAD send failure permanently disables transcription (#1)
Reconnect	FAIL — transient/normal close handling and backoff overflow (#1, #3)
Result shape	FAIL — recovered timestamps include inflated dropped duration (#2)
Metrics	PASS on static inspection of connect delay and TTFW/TTLW paths
Tests	FAIL — the three regression cases above are missing; runtime execution N/A

Reviewed at 3cac629. These three previously reported issues remain present. Base contracts were checked against published ten_ai_base 0.7.62 (6189b87), since that package is absent from the checkout. All 11 added Python files and six added JSON files parse; patch application and runner shell syntax checks pass. The overflow and PCM-duration arithmetic were independently verified. PR code, scripts, and tests were not executed, and dependencies were not installed.

[github-actions]

Review: StepFun ASR (stepfun_asr_python)

Reviewed against docs/ai/L1/L2/asr_plugin_design_review.md. The base ten_ai_base/asr.py was not in the review checkout, so findings that depend on base internals come from reading the diff and the guide only.

Merge blockers (MUST)

1. Fatal vendor error reports disconnected while the socket is still open. extension.py on_error() calls on_disconnected(FATAL) for fatal types but never shuts down recognition. is_connected() keeps returning True, so the reported state is wrong (§5.1; §10: an error event does not prove the connection is closed). When the server closes the socket later, the finally in _receive_loop calls on_close(), and that calls on_disconnected() a second time. Close the transport when latching fatal and report disconnected once.

2. A normal close during the handshake reports disconnected twice and schedules reconnect twice. In recognition.start(), the ConnectionClosedOK and _normal_close branches call callback.on_close(), which runs on_disconnected() and _schedule_reconnect(). start() then returns into start_connection(), which takes the normal_close branch into _handle_connect_failure(report_error=False). That calls on_disconnected() again, record_failed_attempt(), and _schedule_reconnect() again. One root cause now has two reconnect triggers (§5.3, §9.1). Keep a single owner: start() should raise or return a status instead of calling on_close() itself.

3. Any exception in the input consumer is permanently fatal. The overridden _audio_frame_consumer catches every Exception, sets _fatal = True and sends FATAL input_processing. Recoverable cases end up here:

   • an odd-length frame (recognition.send_audio raises ValueError)
   • malformed frame metadata JSON
   • a dumper I/O error
   • a bug in any finalize helper

   After that, every frame is dropped and the session never reconnects. §9.2 reserves FATAL for auth, config and the retry ceiling. Drop and log bad frames instead.

4. Any exception while handling a received message is fatal. _receive_loop passes any non-websocket Exception to on_error(..., "invalid_response"), and invalid_response is in the fatal set. One malformed JSON frame, or any exception raised in on_result -> send_asr_result (for example a missing words[0]["start"]), disables ASR for the rest of the session. risk_blocked, which is per-content moderation, is also permanently fatal. Please justify this from the vendor docs, or downgrade to NON_FATAL and skip or reconnect.

5. No guarder or standalone run evidence. The PR body is empty. §13.2 requires task test-extension and task asr-guarder-test results for the en, zh, invalid and dump configs. The results that matter most here are two finalize cycles in one session, dump byte equality, and reconnect.

Should fix

6. Unrelated changes. soniox_asr_python/tests/configs/property_{en,zh}.json switch Soniox to the jp region and add language_hints_strict. That changes another vendor guarder baseline and belongs in a separate PR. In integration_tests/asr_guarder/tests/test_connection_status.py, about 50 lines of reformatting surround the one real change (adding stepfun_asr_python). Please keep only that line so the file still matches task format.

7. Heavy reliance on base-class private internals. The extension overrides _audio_frame_consumer and calls _handle_audio_frame, iterates audio_frames_queue._queue, and writes buffered_frames, buffered_frames_size and sent_buffer_length directly. It also reads recognition._current from the extension. This breaks quietly when the base changes, and it accounts for most of the complexity in the 1.2k-line extension. The documented pattern is simpler: flush explicitly from on_open (§6.3.4) and save the finalize context before super().on_data() (§8.2).

8. _flush_buffered_frames can lose frames. It pops a frame and then calls send_audio. If that returns False (a send failure, or a disconnect between the is_connected() check and the send), the frame is neither re-queued nor counted. Also, send_audio writes to the dumper even when delivered is False. If the base re-buffers rejected frames, the dump records those bytes twice and fails byte equality (§12.1).

9. Duplicate errors for one root cause. A non-fatal vendor error during the handshake sends NON_FATAL from on_error. start() then raises ConnectionError(session_error), and _handle_connect_failure sends a second NON_FATAL error with the same message (§10).

10. Reconnect is unbounded by default. reconnect_max_attempts defaults to 0, which means unlimited, so the default config never hits the escalate-to-fatal ceiling from §9.2. Please use a finite default.

11. Auth is classified by substring. _classify_connect_error treats any message containing 401 or 403 as fatal auth, which also matches IDs, ports or sizes. Use _extract_http_status or the structured error type instead.

12. Undeclared or dead code. Please declare or remove these:

    • on_open sends an asr_ready data message that is not declared in manifest.json or asr-interface.json.
    • _check_complete (asr_check_complete_end) is never called.
    • ReconnectManager.handle_reconnect is marked legacy and used only by tests.

13. Minor.

    • _normalize_language only maps en, zh, ja and ko. Other languages are emitted un-normalized (§7.1).
    • The README "As of / Codebase commit ... (with local changes)" lines will go stale.
    • _sanitize_config_error calls errors() and discards the result.
    • manifest.json has no trailing newline.

ASR checklist

Item	Status
Lifecycle	Pass. super() hooks are called, and an init failure latches fatal with one error.
Connection state	Fail (items 1, 2)
Buffering	Partial. Keep mode is bounded at 10 MiB and the buffer is flushed on open. A failed send can lose a frame or dump it twice (item 8).
Finalize	Pass from reading the code. Timeout fallback, the empty-commit ack, and the finalize_id/session_id echo are unit-tested. Guarder evidence still needed.
Reconnect	Fail (items 2, 3, 4, 10)
Result shape	Pass. session_id is under metadata and vendor fields are under asr_info. Language normalization is incomplete (item 13).
Metrics	Pass. connect_delay is sent after session.updated, and TTLW is cleared for VAD and timed-out finals.
Tests	Unit tests are extensive. Guarder evidence missing (item 5).

[github-actions]

1. [P1] Handle pending VAD commit failures through transport recovery — recognition.py:628–630

   With server_vad=true, finalize after speech_stopped but before transcription completes reaches _queue_commit() outside _pump_or_reconnect()'s exception handler. A socket failure therefore escapes into _audio_frame_consumer(), which sets _fatal and discards subsequent audio. Even ConnectionClosedOK becomes a fatal ASR error. Put this send inside the common transport classification/recovery path and add consumer-level regressions for normal and abnormal closes during this commit. Merge blocker: ASR guide §§9.2/10 require recovery for transient failures and no ASR error for normal closes.

2. [P1] Preserve finalize boundaries while preceding audio is buffered — extension.py:748–750

   If speech arrives while disconnected, the base handler puts it in buffered_frames. This flush then returns without sending it, but _handle_finalize() still calls recognition.commit(), whose boundary only includes already-sent bytes. For an otherwise empty stream, it immediately acknowledges an empty turn. After recovery, the buffered speech is appended without its finalize marker; with the default server_vad=false, it has no commit until another finalize/session boundary arrives. An omitted finalize metadata object also echoes an empty/stale session because neither metadata resolver reads buffered_frames. Preserve the boundary and originating metadata through recovery, with the existing timeout fallback. Add disconnected audio → finalize → reconnect coverage with no further input, asserting the final result and session echo. Merge blocker: §§6.3/8.1–8.2 require session-safe buffering and correct finalize/session association.

3. [P2] Retain an unsent frame when the recovery flush fails — extension.py:939–944

   The flush removes a frame and decrements the buffered byte count before checking delivery. If the recovered socket fails on its first append, send_audio() returns False, but that entirely unsent frame is never restored. The next connection therefore skips speech that the keep-buffer policy had retained, without recording a dropped duration. Keep an entirely unsent frame pending in FIFO order until successful delivery, and test failure on the first recovery append followed by another successful reconnect. Merge blocker: §§6.3–6.4 require correct buffering and audio-timeline accounting.

4. [P2] Saturate backoff before evaluating the exponential — reconnect_manager.py:34

   Retries are unlimited by default, but failure 1,025 evaluates 0.5 * 2**1024 before min() can cap the delay, raising OverflowError. This escapes _reconnect_loop() and terminates recovery, so transcription cannot resume when the service returns. Cap the exponent or saturate before multiplication, including the equivalent expression in handle_reconnect(). Add a regression that evaluates delays beyond 1,024 failures; the current budget test stops at 50 and never calls next_delay(). Merge blocker: §9.2 requires the reconnect policy to continue until success, stop, fatal failure, or its configured ceiling.

ASR checklist

Area	Result
Lifecycle	PASS — static inspection of cleanup paths
Connection state	PASS — static inspection of handshake/status paths
Buffering	FAIL — finalize boundary loss and failed-flush audio loss (#2, #3)
Finalize	FAIL — transport classification and disconnected turn/session handling (#1, #2)
Reconnect	FAIL — pending commit failure, failed flush, backoff overflow (#1, #3, #4)
Result shape	PASS — static inspection of required fields, word conversion, metadata placement
Metrics	PASS — static inspection of normal connect-delay and TTFW/TTLW paths
Tests	FAIL — the failure scenarios above are missing; runtime execution N/A

Reviewed head 869e716. The base package is absent locally, so lifecycle, buffering, timeline, and schema contracts were checked against published ten_ai_base 0.7.62 (6189b87). Static parsing passed for all 12 added Python files, six JSON files, and the TOML file; runner shell syntax and git apply --check also passed. The backoff overflow was independently reproduced with the arithmetic expression. PR code, tests, and scripts were not executed, and dependencies were not installed.