Troubleshooting.zh CN

故障排查

English · 首页

先生成标准的隐私安全支持报告，再从最小故障层开始隔离：service → control/state → ASR → refinement → output → HUD。

voice-input diagnostics
voice-input diagnostics --format json

Diagnostics schema 4 是首选支持材料。它包含 allowlist 内的配置选择、stage/failure category 和聚合计数/计时，但不包含 transcript、endpoint、model、key、术语、provider message、window metadata 或 Agent source。分享前仍应检查一次。

不要把 voice-input status 输出粘贴到报告中，无论是否使用 --extended。Status 用于本地 UI 集成，可能包含当前或最近的 transcript 和 tooltip 文本。

Service 与 control socket

systemctl --user status voice-input.service voice-input-hud.service
systemctl --user cat voice-input.service voice-input-hud.service
journalctl --user -u voice-input.service -u voice-input-hud.service -b

Daemon 应创建：

$XDG_RUNTIME_DIR/voice-input/control.sock
$XDG_RUNTIME_DIR/voice-input/state.json
$XDG_RUNTIME_DIR/voice-input/waveform.sock

检查 metadata，同时避免打印 state 内容：

stat "$XDG_RUNTIME_DIR/voice-input/control.sock" \
     "$XDG_RUNTIME_DIR/voice-input/state.json" \
     "$XDG_RUNTIME_DIR/voice-input/waveform.sock"

常见原因：

• failed to connect to daemon：daemon 已停止、在读取 config/credential 时失败，或者 CLI 与 service 使用不同的 XDG_RUNTIME_DIR。
• Config parse error：运行 voice-input config >/dev/null，并根据 配置参考 检查 enum 拼写。
• 更新后二进制文件与 asset 不匹配：重新执行 make enable-service，然后检查生成的 unit path。
• Service 无法访问 Hyprland：确保 systemd 用户管理器环境包含图形会话变量，再重启 daemon。

手动启动的 daemon 与 systemd daemon 不能竞争同一个 socket。启动其中一个之前应停止另一个。

Settings 无法打开、保存或恢复

Settings 需要 Quickshell 0.3 或更高版本。先执行不涉及 secret 的可执行文件与 asset 检查：

/usr/bin/qs --version
test -x "$(command -v voice-input)"
test -d ~/.local/share/voice-input/quickshell-settings
pgrep -af 'qs.*voice-input/quickshell-settings'

再次运行 voice-input settings 时，程序应通过 Quickshell IPC 激活已有窗口。如果要查看 QML 启动诊断，请先关闭 Settings，再以前台方式运行其配置：

VOICE_INPUT_BIN="$(readlink -f "$(command -v voice-input)")" \
  /usr/bin/qs --no-duplicate --path \
  "$HOME/.local/share/voice-input/quickshell-settings"

Settings QML 通过带版本号的 NDJSON 与专用隐藏 Rust backend 通信。每个 request 的 timeout 为 30 秒；每个 response line 上限为 2 MiB。QML 只接受精确 protocol schema、匹配的正 safe request ID 和符合 method 的 payload shape。错误 version、未知 envelope field、过期或未知 ID、malformed JSON、oversized line 和无效 method payload 都会被拒绝，不会部分应用。

仅在故障排查时验证不涉及 secret 的 envelope：

printf '%s\n' \
  '{"version":1,"id":1,"method":"settings.get","params":{}}' \
  | voice-input settings-backend --stdio \
  | jq '{version, id, ok, error: (.error.code // null)}'

预期输出包含 version: 1、相同的 id 和 ok: true。不要在 shell 中发送 credential replacement request。

如果隐藏 backend 退出或违反 protocol，Settings 会在 250 ms、500 ms、1 s、2 s、4 s 和 8 s 后自动重启，最多自动重试六次。只有有效 response 会重置 failure count。重试耗尽后，使用 Reload 立即手动重试；它不会悄悄创建无限 restart loop。

保存失败时，可以在不打印配置的情况下验证配置，并检查权限：

voice-input config >/dev/null
stat -c '%a %n' "$HOME/.config/voice-input" \
  "$HOME/.config/voice-input/config.toml"
systemctl --user status voice-input.service

目录和文件的预期权限分别为 700 和 600。Revision conflict 表示 Settings 加载后，原始配置的精确内容又发生了变化；请 reload 并重新应用修改。如果持久化成功但重启失败，新文件仍然已经保存——请单独排查 service。

HUD 不显示、停止更新或出现在错误显示器

标准部署使用独立的 Quickshell service。只重启 daemon 不会重启 HUD：

systemctl --user restart voice-input-hud.service
journalctl --user -u voice-input-hud.service -f

检查 /usr/bin/qs、已安装 asset 和 runtime metadata，同时避免打印 transcript state：

test -x /usr/bin/qs
test -d ~/.local/share/voice-input/quickshell
stat "$XDG_RUNTIME_DIR/voice-input/state.json" \
     "$XDG_RUNTIME_DIR/voice-input/waveform.sock"

HUD 消费两个独立输入：

1. state.json 驱动 phase、文本、计时、geometry 和 focused-monitor placement。
2. waveform.sock 发送 NDJSON reset/waveform frame，并在断开后重连。

State file malformed、oversized 或按 updated_at_ms/revision 判断为 stale 时，QML reader 会保留上一份有效 state snapshot。Waveform frame malformed、oversized、来自其他/过期 session 或 sequence 过旧时，它同样保留上一份有效 waveform frame。有效 waveform payload 要求 safe session/sequence integer、非零 waveform session ID、恰好 30 个 bar、恰好 12 个 spectrum 值，并且每个归一化 scalar/array value 都在 [0,1]。Socket 断开会重置 waveform 显示；无效 frame 不会替换上一份有效 frame。

如果 phase 会更新但 bar 保持不动，请检查麦克风 PCM 和 ASR speech activity。Qwen Realtime 的 Server VAD 未标记 voice active 时，程序会有意隐藏 waveform。如果 HUD 出现在错误显示器，请在观察 HUD journal 的同时复现 focus change 和 monitor hotplug。不要把 extended status 用作 HUD 诊断。

只应在 daemon 停止时删除 stale socket；正常启动会自行删除并重新绑定：

systemctl --user stop voice-input.service
rm -f "$XDG_RUNTIME_DIR/voice-input/control.sock" \
      "$XDG_RUNTIME_DIR/voice-input/waveform.sock"
systemctl --user start voice-input.service

空白或无语音 dictation

停止时，如果 Qwen Realtime session 没有 server speech event，程序会等待 350 ms 宽限期。宽限期结束不会立即取消 session；程序会把 empty-audio 判断延后到常规 finalization，由 realtime/final ASR 和已配置 recovery 决定是否存在 transcript。确认 no-words 后，程序会返回 idle，不执行 refinement 或输出。

测试本地 capture：

pw-record --raw --rate 16000 --channels 1 --format s16 /tmp/voice-input-test.raw
# 短暂说话，以 Ctrl+C 停止；确认文件非空，然后删除。
rm -f /tmp/voice-input-test.raw

同时检查 audio.device、provider 连接、turn/VAD control 和所选 recovery mode。主动运行 voice-input record cancel 或捕获到空 audio buffer 时，会按设计返回 idle 且不输出文本。

录音自行停止，或 Qwen Realtime 开始延迟

Capture 会在达到 audio.max_duration_secs 后自动停止；该字段默认为 300 秒。这属于正常停止：程序仍会按配置执行 final ASR、本地 fallback、refinement 和输出。

以下情况可让 Qwen Realtime 重建一次 streaming session，并从头重放保留的全部 PCM：

• finish 前发生可恢复 transport failure；
• 服务端确认 active speech 后，transcript 连续停滞八秒；或
• 已经出现文本后，持续检测到与 pitch 相关的本地语音，但八秒没有 server event。

Pitch-correlated 路径不是简单的 RMS/noise trigger。Replacement 追赶期间，录音、elapsed time 和保留音频会继续。重放后，replacement transcript 成为权威结果。第二次 failure、finish 后 failure、delivery overload 或 worker interruption 会让程序拒绝不完整 remote text，并使用已启用的全音频 final pass 或本地 fallback。Diagnostics 会报告聚合的 reconnect 和 recovery outcome，但不包含 transcript。

如果没有 recovery，请按需启用 final_pass_enabled 或 fallback_to_local。增大时长上限也会增加保留 PCM 和潜在的全音频 upload 大小。

Qwen Realtime 或 final pass 失败

先运行：

voice-input diagnostics --format json
journalctl --user -u voice-input.service -f

检查：

• provider = "alibaba-qwen-realtime"，并且存在适用于该 region 的有效 Alibaba credential；
• 在本地检查 endpoint region、model compatibility、DNS、TLS 和网络访问——不要把 endpoint/model 值粘贴到报告中；
• connect/finalize timeout；
• 启用 fallback_to_local = true 时是否存在 /usr/bin/voxtype；
• 启用 final_pass_enabled = true 时的 final base URL/timeout。

只有已识别的 DashScope realtime host 才能推导空的 final-pass base URL。自定义 host 需要明确填写。分享 journal 前，请在本地检查 provider close reason；diagnostics 才是适合支持报告的安全摘要。

Qwen Audio3 Streaming 或 Native 失败

Audio3 是实验功能，需要同时选择 Qwen-Audio-3 (experimental)，并确认/启用其明确的 gate。稳定版 setup wizard 有意不提供该选项。

按顺序检查以下层：

1. Credential 与 region： Audio3 共用加密 Alibaba key。Key 具有 region scope；在 Beijing/Singapore 之间切换可能需要替换 key。Voice Input 不会探测其他 region，也不会迁移 key。
2. Endpoint mode： Regional 使用所选 region 对应的已审查固定 Streaming/Native 地址对。Custom 会原样使用配置的两个 URL，包括 path、port、query 和任何 proxy 行为。
3. Preset 与 control： Standard 是默认值。Low-latency 和 Long-form 会解析为不同的 silence/semantic control。在 Custom 中，semantic punctuation 与 multi-threshold mode 不能同时启用；可选 threshold 必须通过本地验证。
4. Dynamic vocabulary： entry 会发送到 Streaming 和 Native。检查 duplicate/count/term limit 和 weight（1–5 或 50）。Diagnostics 只报告 entry 数量，绝不包含术语。
5. Native mode： Streaming only 不会上传完整录音。Adaptive 会在 streaming degraded/empty/interrupted/overloaded、没有显式完成时运行 Native，并且通常会对达到至少 30 秒的录音运行 Native。如果健康的 stream 已明确完成且确实发送了 Session Context，则只因时长触发的规则不适用。Always 对每个未取消且非空的录音运行 Native。Native 输入上限为 10 MiB。
6. Reconnect： 在 finish-task 前，Streaming 允许一个 replacement task；它会丢弃旧 transcript，在新 run-task 中发送完全相同的开始时术语，并重放保留 PCM。程序绝不发送 continue-task。第二次或 finish 后 interruption 会转入 Native/本地 recovery。

先使用 diagnostics：

voice-input diagnostics --format json

要使用不敏感的预录 16 kHz mono PCM16 WAV 分别隔离两种远程 API：

voice-input asr stream-test --file sample.wav  # Audio3 WebSocket Streaming
voice-input asr test --file sample.wav         # Audio3 Native full-audio

两个命令都要求已选择并明确启用 Audio3。它们会把文件发送到解析后的 Regional route 或精确 Custom endpoint，并可能产生远程 API 费用。它们不会启动 daemon，也不会把输出粘贴到其他应用。

/usr/bin/voxtype fallback 失败

test -x /usr/bin/voxtype
/usr/bin/voxtype --help

Voice Input 只通过以下形式代理 backend setup：

voice-input setup gpu [backend arguments...]
voice-input setup onnx [backend arguments...]

识别时，程序会把 engine/model/language flag 和 transcribe <temporary-wav> 传给配置的可执行文件。请在 Voxtype 自身确认选定的 engine/model。不要设置 backend_command = "voice-input"，否则会递归调用。

External backend execution 具有 timeout、并行 stdout/stderr 排空和输出上限。Timeout 会终止 process group；输出超限或运行失败时，程序会报告已清理的 error，而不是 provider output。请使用 diagnostics，并只在本地检查 backend log。

OpenCC 报错或中文繁简转换不符合预期

本地和远程中文最终文本都会调用：

opencc -c t2s   # simplified-chinese
opencc -c s2t   # traditional-chinese

检查命令：

command -v opencc
printf '測試\n' | opencc -c t2s

如果无法启动 OpenCC，识别会返回错误。如果退出码非零或输出为空，Voice Input 会保留未转换的 transcript。English、Japanese 和 Korean 不调用 OpenCC。

LLM refinement 未改变文本或发生 timeout

voice-input llm test
voice-input diagnostics --format json

确认 enabled = true、model 非空、在本地检查 API base 正确，并且存在 openrouter-api-key。不要在共享报告中包含 endpoint 或 model。带上下文的请求和符合条件的纯 transcript 重试共用一个 deadline。timeout_ms 限制在 1–30 秒；预算至少为 10 秒时，会为 recovery 保留最后五秒。

Refinement 在所有 failure 下都会保留 ASR 文本。如果仍有预算，transport error、可识别 payload/context failure、无效 response structure、truncation 或上下文预算耗尽可以触发无上下文重试。Authentication/rate-limit response 和 provider-declared error 会立即保留原始文本。Prompt 只执行编辑；它绝不会回答或执行 transcript command，session 术语也是不可信数据。

粘贴文本未出现，或 clipboard 发生变化

所有文本都会通过 clipboard 粘贴。检查本地工具：

command -v hyprctl wl-copy wl-paste
command -v xclip xdotool          # 仅 XWayland
voice-input diagnostics --format text

请检查：

• 目标可能不接受 shift+Insert；可把 paste_keys 或 xwayland_paste_keys 改为支持的组合，例如 ctrl+v。
• 确认 Hyprland 支持 dispatch sendshortcut，并且活动窗口接受配置的按键。
• Clipboard manager 或应用可能在 220 ms 恢复等待期间改变 owner。
• Backup 只保存一个选定 MIME payload，并跳过 sensitive metadata MIME；不支持的格式可能无法完整恢复。
• Wayland 临时和恢复 payload 只会在兼容 clipboard manager 中按 sensitive 处理。X11 没有同等保证。
• Crash 可能留下私有 clipboard-backup 临时文件；如果恢复中断，请仅在本地检查临时目录。
• 如果 modifier 尚未释放，可以增加 pre_type_delay_ms；toggle+modifier 快捷键已经强制至少等待 500 ms。
• Legacy output mode 字段不会改变当前统一使用 clipboard 的输出路径。

输出 helper process 具有 deadline 和输出上限，报告的 error 会经过清理。

Credential 文件存在但未加载

只列出 metadata，不要在共享 terminal 或 report 中解密 key：

ls -l ~/.config/credstore.encrypted/
systemctl --user cat voice-input.service

Blob 名必须恰好为 alibaba-api-key 和 openrouter-api-key。Settings 只提供保留或替换。修改 credential 后执行：

systemctl --user restart voice-input.service
voice-input diagnostics --format text

加密 credential 会提供给 systemd 启动的 service。手动 daemon 没有 $CREDENTIALS_DIRECTORY，除非它运行在适当的 credential context 中。请避免 plaintext TOML、环境变量、shell history 和 issue log。

Pi/Codex 术语未生效

Agent 上下文在录音开始时捕获，而不是停止时。安装后应重启 Pi 或 reload extension：

ls -l ~/.pi/agent/extensions/voice-input-session-registry.ts
ls -l "$XDG_RUNTIME_DIR/voice-input/agent-sessions/"

对于 Pi，请确认 Kitty 中当前聚焦的前台 process 是 Pi，并且已验证的 registry/session 为当前值。Codex 不使用该 extension；它需要在 CODEX_HOME/sessions 下恰好有一个符合条件且打开的 CLI session JSONL。开始后的 focus change 不会替换已冻结的术语 source；停止时焦点只选择 destination style/Agent Markdown。

Diagnostics 只报告是否实际发送了非空 Audio3 Session Context，绝不包含术语、path 或 source text。验证和 failure 行为见 Agent 上下文。

收集支持报告

使用 diagnostics 作为主要且通常足够的材料：

voice-input diagnostics --format json > voice-input-diagnostics.json

附加前请检查该文件。如果 maintainer 要求 log，只收集最小相关 service/time range，逐行检查，并删除用户名、path、endpoint、model、provider message 和意外内容。绝不分享 voice-input status 输出、state.json、Pi/Codex JSONL、原始音频、credential、clipboard backup 或未经检查的完整 journal。

另请参阅：安全与隐私 · 开发指南