故障排查¶
以下命令中的系统安装路径是 /usr/libexec/typeless-ibus-engine。用户级安装时，请替换为
~/.local/libexec/typeless-ibus-engine。
基础诊断¶
/usr/libexec/typeless-ibus-engine --config-path
/usr/libexec/typeless-ibus-engine --print-config
/usr/libexec/typeless-ibus-engine --list-devices
/usr/libexec/typeless-ibus-engine --check
查看本地日志¶
/usr/libexec/typeless-ibus-engine --log-path
tail -f ~/.local/state/typeless-ibus/logs/typeless-ibus.latest.jsonl
日志使用一行一个 JSON 对象的格式。识别会话可用 session_id 关联，最终文本位于
voice_session.finished 事件的 transcript 字段。完整格式见本地日志。
Fn 没有反应¶
部分设备的 Fn 由键盘固件处理，Linux 收不到独立按键事件。请从 IBus 输入法菜单改用
右 Ctrl、F8 或其他受支持的触发键。
找不到麦克风¶
默认使用系统输入设备。先运行 --list-devices 查看 cpal 能发现的输入设备，再通过
config set input-device DEVICE 选择设备；default 或配置文件中的 null 表示系统默认。
IBus 中找不到输入法¶
安装后注销并重新登录，或重新启动 IBus。用户级安装还可以重新执行：
然后在桌面环境的输入源设置中添加 typeless-ibus；GNOME 用户可打开
“设置 → 键盘 → 输入源”。
ASR 配置与握手诊断¶
该命令不读取麦克风，也不依赖 IBus，并按配置文件选择 provider。默认豆包模式会在没有
本地凭据时自动获取凭据，然后检查 settings Token 接口以及 WebSocket 的 StartTask、
StartSession 握手，并隐藏所有凭据。首次握手失败时会使用同一设备身份重试；仍然失败
才注册一个仅用于诊断的临时身份，且不会覆盖本地凭据。
除豆包外，各云端接口没有统一的无音频探测协议，因此该命令只校验当前 provider 的配置， 并打印脱敏后的 endpoint、model 和鉴权状态；请用下面的真实音频诊断确认接口可用性。
真实音频诊断¶
该命令发送指定的 16 kHz、单声道、16-bit little-endian PCM 文件，并要求服务返回非空
文字。豆包失败日志中的 x_tt_logid，以及其他云端接口返回的 request_id、
x-request-id 或 x-trace-id 等请求标识，会在不记录密钥和音频的前提下写入诊断日志，
可用于排查对应的上游请求。
正式输入遇到 service discovery failure 时会先等待 2 秒，再获取新凭据并重放当前音频；
第二次失败不会无限重试。40200011/concurrency quota exceeded 也会等待 2 秒后用当前
凭据重试一次，但不会刷新本地凭据；这两类错误都不会无限重试。