CHORE: 补充 Android 跟读录音诊断日志

Author: echo-loop

TASKS.md

@@ -4,6 +4,8 @@
 
 ## 本次完成
 
+- [x] 删除低价值 WAV 指标公式单测（2026-10-09）：移除只用固定 250ms 样本验证 PCM 字节数和时长换算的断言；保留验证录音诊断能进入持久化应用日志的行为测试。未改生产代码。**完成时间**: 2026-10-09
+- [x] 补充 Android 跟读录音取证日志（2026-10-09）：记录 AudioRecord 初始化/启动状态、正帧数、0/负返回次数及最后非正返回值、停止时录音协程等待是否超时，并记录写入字节/时长、采集耗时和 WAV 裁剪前后文件大小/时长；通过现有持久化应用日志与日志支持包收集。只增加观测，不改变录音、裁剪、停止或识别行为，也不记录音频/识别文本；复核时增加诊断类型容错并在每轮会话清空旧统计。RecordingService 日志测试 3 项通过，4 个 Dart 文件定向分析无问题，Android `WavRecorderTrimTest` 通过，`git diff --check` 通过。未运行 `scripts/check.sh`：本次限于 Android 录音诊断日志与指标计算，定向验证覆盖改动范围。未在 vivo X100s Pro 上复现，根因仍待用户日志确认。**完成时间**: 2026-10-09 11:21
 - [x] 修复 iOS Apple AI 合成音频无法播放（2026-10-08）：平台 TTS 默认输出统一为 WAV，iOS 继续调用 `flutter_tts.synthesizeToFile`，macOS 保持现有原生合成路径；缓存命名空间升级至 v3，避免命中旧 CAF 缓存。新增默认 WAV 和旧缓存 key 失效回归测试。TTS 定向测试 28 项通过，4 个相关 Dart 文件定向分析通过，`git diff --check` 通过。未运行 `scripts/check.sh`：仅改动 TTS 格式和缓存兼容性，定向测试覆盖范围足够；未在 iPhone 上安装运行，真实设备播放需手动验证。**完成时间**: 2026-10-08 23:57
 - [x] 删除低价值的复述状态单测（2026-10-08）：移除仅检查 `RetellPlayerState.stepFinished` 默认值和 `copyWith` 行为的用例；保留段落切段及最后一段重复遍数的行为回归测试。此次仅删除测试，未运行测试。**完成时间**: 2026-10-08 23:55
 - [x] 修复段落复述播放中无法切换段落（2026-10-08）：切段和重复播放在旧播放取消后异步启动新播放并立即返回，页面仅在 Provider 标记 `stepFinished` 后处理最后一段完成。新增受控播放时序与最后一段重复遍数回归测试。Provider 25 项测试、页面 Widget 22 项通过；3 个 Dart 文件定向分析和 `git diff --check` 通过。未运行 `scripts/check.sh`：局部播放器异步边界修复由定向测试覆盖。未运行 Maestro：当前仅连接两台无线 iPhone、无模拟器；仓库 smoke flow 会清除应用数据且不覆盖复述切段，页面 Widget 测试已通过。**完成时间**: 2026-10-08 23:46

android/app/src/main/kotlin/app/echoloop/AndroidSpeechPracticeHandler.kt

@@ -222,6 +222,7 @@ class AndroidSpeechPracticeHandler(
     }
 
     private fun doStartSession(promptId: String, result: MethodChannel.Result) {
+        wavRecorder.resetCaptureDiagnostics()
         cleanupSentenceState()
         resetSentenceState(promptId)
 
@@ -249,10 +250,18 @@ class AndroidSpeechPracticeHandler(
             currentFilePath
         }
 
+        val wavBeforeTrim = filePath?.let(wavRecorder::wavFileMetrics)
+
         // 裁剪首尾静音（对齐 iOS/macOS）。
         if (!filePath.isNullOrEmpty()) {
             wavRecorder.trimSilence(filePath)
         }
+        val wavAfterTrim = filePath?.let(wavRecorder::wavFileMetrics)
+        val diagnostics = buildString {
+            append(wavRecorder.captureDiagnostics())
+            append(" wavBeforeTrim=$wavBeforeTrim")
+            append(" wavAfterTrim=$wavAfterTrim")
+        }
 
         // 确保 Dart 侧总能收到 finalTranscriptReady，避免等超时。
         if (!finalTranscriptEmitted) {
@@ -264,7 +273,12 @@ class AndroidSpeechPracticeHandler(
             ))
         }
 
-        result.success(mapOf("filePath" to (filePath ?: "")))
+        result.success(
+            mapOf(
+                "filePath" to (filePath ?: ""),
+                "diagnostics" to diagnostics,
+            ),
+        )
     }
 
     private fun cancelSession(result: MethodChannel.Result) {

android/app/src/main/kotlin/app/echoloop/WavRecorder.kt

@@ -3,6 +3,7 @@ package app.echoloop
 import android.media.AudioFormat
 import android.media.AudioRecord
 import android.media.MediaRecorder
+import android.os.SystemClock
 import android.util.Log
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
@@ -14,6 +15,7 @@ import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.withTimeoutOrNull
 import java.io.File
 import java.io.RandomAccessFile
+import java.util.concurrent.atomic.AtomicLong
 import kotlin.math.max
 import kotlin.math.min
 import kotlin.math.sqrt
@@ -26,14 +28,25 @@ import kotlin.math.sqrt
  */
 class WavRecorder {
 
+    data class WavFileMetrics(val fileBytes: Long, val audioDurationMs: Long)
+
     /** 每个 buffer 的回调（RMS, 帧数），在 IO 线程上调用。 */
     var onBuffer: ((Float, Int) -> Unit)? = null
 
     private var audioRecord: AudioRecord? = null
     private var recordingJob: Job? = null
     private var wavFile: RandomAccessFile? = null
     private var currentFilePath: String? = null
-    private var totalDataBytes: Int = 0
+    @Volatile private var totalDataBytes: Int = 0
+    private val positiveReadFrames = AtomicLong(0)
+    private val zeroReadCount = AtomicLong(0)
+    private val errorReadCount = AtomicLong(0)
+    @Volatile private var lastNonPositiveReadResult: Int? = null
+    @Volatile private var recordingStartElapsedMs: Long? = null
+    @Volatile private var recordingStartState: Int? = null
+    @Volatile private var recordingStartAttempted = false
+    @Volatile private var recordingStarted = false
+    @Volatile private var stopJoinTimedOut = false
 
     /** 是否已初始化 AudioRecord。 */
     val isInitialized: Boolean get() = audioRecord != null
@@ -97,6 +110,7 @@ class WavRecorder {
      * @param filePath WAV 输出路径。
      */
     fun startRecording(filePath: String) {
+        recordingStartAttempted = true
         val recorder = audioRecord ?: return
         currentFilePath = filePath
         totalDataBytes = 0
@@ -106,12 +120,25 @@ class WavRecorder {
         wavFile = raf
 
         recorder.startRecording()
+        recordingStarted = true
+        recordingStartState = recorder.recordingState
+        recordingStartElapsedMs = SystemClock.elapsedRealtime()
 
         recordingJob = CoroutineScope(Dispatchers.IO).launch {
             val buffer = ShortArray(BUFFER_SIZE_FRAMES)
             while (isActive) {
                 val read = recorder.read(buffer, 0, buffer.size)
-                if (read <= 0) continue
+                if (read == 0) {
+                    zeroReadCount.incrementAndGet()
+                    lastNonPositiveReadResult = read
+                    continue
+                }
+                if (read < 0) {
+                    errorReadCount.incrementAndGet()
+                    lastNonPositiveReadResult = read
+                    continue
+                }
+                positiveReadFrames.addAndGet(read.toLong())
 
                 val rms = computeRms(buffer, read)
                 onBuffer?.invoke(rms, read)
@@ -129,9 +156,18 @@ class WavRecorder {
         // 先等录音协程真正退出，再操作 AudioRecord 和文件，避免 read() 与 stop() 并发。
         // 录音中 read() 最多阻塞一个 buffer 周期（~64ms）必然返回，join 不会卡死；
         // withTimeoutOrNull 兜底：极端情况（麦克风 hang）超时后退回原 stop() 行为，不劣于现状。
-        runBlocking {
-            withTimeoutOrNull(500) { recordingJob?.cancelAndJoin() }
+        val job = recordingJob
+        val recordingJobJoined = runBlocking {
+            if (job == null) {
+                true
+            } else {
+                withTimeoutOrNull(500) {
+                    job.cancelAndJoin()
+                    true
+                } ?: false
+            }
         }
+        stopJoinTimedOut = !recordingJobJoined
         recordingJob = null
 
         try {
@@ -147,6 +183,56 @@ class WavRecorder {
         return currentFilePath
     }
 
+    /** 返回本轮采集统计，不包含录音内容。 */
+    fun captureDiagnostics(): String {
+        val readFrames = positiveReadFrames.get()
+        val writtenBytes = totalDataBytes.toLong()
+        val elapsedMs = recordingStartElapsedMs?.let {
+            (SystemClock.elapsedRealtime() - it).coerceAtLeast(0L)
+        }
+        val writtenDurationMs =
+            (writtenBytes / BYTES_PER_SAMPLE * 1000L) / SAMPLE_RATE
+
+        return "audioRecordInitialized=${isInitialized} " +
+            "startAttempted=$recordingStartAttempted " +
+            "startSucceeded=$recordingStarted " +
+            "recordingStateAtStart=${recordingStartState ?: "unknown"} " +
+            "stopJoinTimedOut=$stopJoinTimedOut " +
+            "positiveReadFrames=$readFrames " +
+            "zeroReadCount=${zeroReadCount.get()} " +
+            "errorReadCount=${errorReadCount.get()} " +
+            "lastNonPositiveRead=$lastNonPositiveReadResult " +
+            "writtenDataBytes=$writtenBytes " +
+            "writtenDurationMs=$writtenDurationMs " +
+            "captureElapsedMs=${elapsedMs ?: -1}"
+    }
+
+    /** 读取 WAV 文件大小与 PCM 时长，供录音结束诊断使用。 */
+    fun wavFileMetrics(filePath: String): WavFileMetrics? {
+        val file = File(filePath)
+        if (!file.exists()) return null
+
+        val fileBytes = file.length()
+        val dataBytes = (fileBytes - WAV_HEADER_SIZE).coerceAtLeast(0L)
+        val frames = dataBytes / BYTES_PER_SAMPLE
+        val durationMs = frames * 1000L / SAMPLE_RATE
+        return WavFileMetrics(fileBytes = fileBytes, audioDurationMs = durationMs)
+    }
+
+    /** 新会话开始时清空上轮统计，即使本轮 AudioRecord 初始化失败也不会复用旧数据。 */
+    fun resetCaptureDiagnostics() {
+        totalDataBytes = 0
+        positiveReadFrames.set(0)
+        zeroReadCount.set(0)
+        errorReadCount.set(0)
+        lastNonPositiveReadResult = null
+        recordingStartElapsedMs = null
+        recordingStartState = null
+        recordingStartAttempted = false
+        recordingStarted = false
+        stopJoinTimedOut = false
+    }
+
     /** 释放 AudioRecord 和所有资源。 */
     fun release() {
         // 同 stopRecording：先 join 录音协程，消除与 stop()/release() 的并发。

lib/models/speech_practice_models.dart

@@ -151,7 +151,10 @@ class SpeechPracticeStopResult {
   /// 临时录音文件路径。
   final String? filePath;
 
-  const SpeechPracticeStopResult({this.filePath});
+  /// 原生录音诊断摘要；不包含录音内容。
+  final String? diagnostics;
+
+  const SpeechPracticeStopResult({this.filePath, this.diagnostics});
 }
 
 /// 文本比对结果。

lib/services/recording_service.dart

@@ -308,6 +308,10 @@ class RecordingService {
       );
     }
     final filePath = stopResult.filePath ?? _currentFilePath;
+    final diagnostics = stopResult.diagnostics;
+    if (diagnostics != null) {
+      AppLogger.log('RecordingDiag', 'promptId=$promptId $diagnostics');
+    }
     _recordingPromptId = null;
     _recordingStartedAt = null;
     AppLogger.log(

lib/services/speech_practice_platform.dart

@@ -225,8 +225,10 @@ class SpeechPracticePlatform implements SpeechPracticeBackend {
     _ensureSupported();
     AppLogger.log('SpeechPlatform', '┌ stopSession');
     final result = await _invokeMap('stopSession');
+    final diagnosticsValue = result['diagnostics'];
     final stopResult = SpeechPracticeStopResult(
       filePath: result['filePath'] as String?,
+      diagnostics: diagnosticsValue is String ? diagnosticsValue : null,
     );
     AppLogger.log(
       'SpeechPlatform',

test/services/recording_service_test.dart

@@ -2,6 +2,7 @@ import 'dart:async';
 
 import 'package:flutter_test/flutter_test.dart';
 import 'package:echo_loop/models/speech_practice_models.dart';
+import 'package:echo_loop/services/app_logger.dart';
 import 'package:echo_loop/services/recording_service.dart';
 import 'package:echo_loop/services/speech_practice_platform.dart';
 
@@ -12,6 +13,7 @@ class _Backend implements SpeechPracticeBackend {
   int startCalls = 0;
   int cancelCalls = 0;
   int shutdownCalls = 0;
+  String? stopDiagnostics;
 
   @override
   bool get isSupported => true;
@@ -56,6 +58,7 @@ class _Backend implements SpeechPracticeBackend {
   Future<SpeechPracticeStopResult> stopSession() async =>
       SpeechPracticeStopResult(
         filePath: '/tmp/${activePromptId ?? 'none'}.caf',
+        diagnostics: stopDiagnostics,
       );
 
   @override
@@ -116,4 +119,26 @@ void main() {
     await service.dispose();
     await backend.dispose();
   });
+
+  test('停止录音时将原生诊断记录到应用日志', () async {
+    const promptId = 'diagnostics:round';
+    final backend = _Backend()..stopDiagnostics = 'errorReadCount=2';
+    final service = RecordingService(backend);
+
+    await service.startRecording(promptId: promptId);
+    await service.stopSession(promptId: promptId);
+
+    expect(
+      AppLogger.instance.entries.any(
+        (entry) =>
+            entry.tag == 'RecordingDiag' &&
+            entry.message.contains('promptId=$promptId') &&
+            entry.message.contains('errorReadCount=2'),
+      ),
+      isTrue,
+    );
+
+    await service.dispose();
+    await backend.dispose();
+  });
 }