验证与排障

验证分为代码检查、系统单元检查和真实通话。模拟测试不能证明蓝牙路由或远端音频内容。

代码检查

在仓库根目录运行：

npm ci --no-audit --no-fund
npm run build
npm run typecheck
npm run check --workspace convbased-raspberry-pi
./integrations/raspberry-pi/bluetooth-mic/check.sh
git diff --check

参考提交应通过 SDK 构建、TypeScript 检查、脚本语法检查和 18 项树莓派测试。缺少可选的 shellcheck 时，检查脚本会明确提示，但仍执行 Bash、Python 和 JavaScript 检查。

systemd 单元检查

systemd-analyze --user verify \
  integrations/raspberry-pi/bluetooth-mic/systemd/convbased-app.service \
  integrations/raspberry-pi/bluetooth-mic/systemd/convbased-link.service \
  integrations/raspberry-pi/bluetooth-mic/systemd/convbased-btagent.service

sudo systemd-analyze verify \
  integrations/raspberry-pi/bluetooth-mic/systemd/convbased-btclass.service \
  integrations/raspberry-pi/bluetooth-mic/systemd/convbased-bt-recover.service \
  integrations/raspberry-pi/bluetooth-mic/systemd/convbased-scoroute@.service

成功时命令不输出错误。

运行状态

通话前检查服务与音频设备：

systemctl --user is-active convbased-app convbased-link convbased-btagent
sudo systemctl is-active convbased-btclass convbased-bt-recover
arecord -l
wpctl status

通话期间检查临时 HFP 链路和 SCO 计数：

pw-link -l | grep -A3 -B1 -E 'bluez_(input|output)|convbased_out'
hciconfig -a

参考组合中的 HFP 节点在通话音频激活时出现，编号可能变化。不要把固定节点编号写入配置。

通过标准

一次端到端验收应同时满足：

• 手机完成配对、信任和重连，五分钟后不再接受新配对。
• 手机通话下行从 USB 耳机左右声道播放。
• USB 麦克风以 48 kHz 单声道进入实时客户端。
• 远端只听到转换后的声音，没有并行原声。
• SCO RX、TX 计数持续增长，错误计数不增长。
• 更换模型后设备自动重连；修改参数后约 20 秒内生效。
• 关闭“实时服务”后设备约 20 秒内断开，五项常驻服务仍为 active。

链路和计数只能证明路由；远端试听是判断音频内容的必要证据。

耳机音量

确认默认输出是 USB 耳机，再从 80% 开始：

wpctl set-mute @DEFAULT_AUDIO_SINK@ 0
wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.80
wpctl get-volume @DEFAULT_AUDIO_SINK@

检查失真和听力安全前，不要把软件增益调到 100% 以上。

常见故障

现象	优先检查	处理
PIN 或配对密钥错误	两端是否保留了不一致的旧绑定	两端删除旧记录，重新开放五分钟配对窗口。
应用退出且状态为 78	配置缺失、凭据拒绝或采集设备无效	修正私有配置和 MIC_DEVICE，再手动重启应用。
已配对但没有 HFP 节点	通话音频会话、HFP 配置与当前音频 profile	发起蜂窝或兼容 VoIP 通话并选择 Convbased Mic；仍未出现时检查 PipeWire 与 WirePlumber 配置。
远端静音	上行链路、SCO 路由或 USB 麦克风缺失	检查 pw-link、SCO TX 计数和 arecord -l。
远端听到原声	HFP 上行是否还连接其他音源，手机是否仍使用自身麦克风	重启 convbased-link，确认只有转换输出连接上行，并核对手机通话设备。
模型未更新	配置轮询失败或模型不可用	等待 20 秒；仍失败时检查日志、模型权限，再重启应用。
关闭后仍连接	开关未保存或设备未拉到新配置	刷新控制台确认状态，等待 20 秒；仍异常时停止应用并排查。
蓝牙负载下掉线	供电、信号、控制器错误，以及是否同时使用 2.4 GHz Wi-Fi	优先改用已验证的有线网络，并检查蓝牙错误计数与系统日志。

只查看必要日志，并限制行数：

journalctl --user -u convbased-app.service -n 100 --no-pager
journalctl --user -u convbased-link.service -n 100 --no-pager
journalctl --user -u convbased-btagent.service -n 100 --no-pager

复现记录

报告至少包含提交哈希、Pi 型号、系统、内核、BlueZ、PipeWire、WirePlumber、Node.js、网络类型、测试时长和结果。发布前删除 API Key、访问令牌、转发凭据、设备地址、参与者信息、原始日志和录音。

当前验证未覆盖 USB 蓝牙适配器、30 分钟通话浸泡、USB 耳机热插拔、USB UAC1 gadget 模式、宽带 HFP 编解码器、有线局域网之外的网络条件，以及参考手机之外的兼容性。不要把未验证组合写成已支持。