Debug Voice 是一项用于调试 Grok 实时语音会话的技能。其核心思路是:智能体无法直接听到应用的声音,日志就是它的耳朵,用户则是判断者。该技能通过为语音会话建立可读的日志管道,让开发者能够在事后根据证据定位问题并修复。
用途
当用户运行 /debug-voice、反馈语音模式存在缺陷、希望查看或捕获 Grok 实时语音会话中发生的情况,或语音集成出现异常时,可使用该技能。它适用于任意技术栈,日志管道以一份小型契约形式定义,开发者可用应用已有的语言和框架实现。
主要能力
该技能提供一套工作流程:首先只读地梳理应用,识别语音客户端、服务端、项目约定、客户端类型以及音频增量处理位置;然后制定变更计划并等待用户确认;接着按照应用的语言、框架和约定安装日志组件;验证日志接收端点后交给用户测试;最后根据日志进行修复循环。
日志契约定义了会话 ID 格式、每行一个 JSON 对象的条目结构、客户端与服务端字段差异、脱敏规则、客户端日志器的缓冲与刷新行为、服务端接收端点的请求处理逻辑,以及一系列钩子点(如会话开始、令牌获取、麦克风授权、音频图就绪、WebSocket 事件、音频输入输出统计、打断停止等)。日志记录事件名称和非音频字段、耗时、字节数、麦克风 RMS,但绝不记录令牌、API 密钥、原始音频或超过 400 字符的字符串。音频增量只计数字节,不逐块记录。
使用方式
该技能要求先制定计划,在用户确认变更列表之前不编辑任何文件。安装时匹配应用现有语言和工具链,不引入第二种语言或工具链。日志接收端点仅在开发环境或设置 VOICE_LOG=1 时可用,生产环境返回 404。.voice-logs/ 目录应加入 .gitignore。日志记录不得向语音路径抛出异常。验证步骤包括用 curl 测试接收端点的正常与异常请求,并检查生成的 NDJSON 文件。读取日志可使用 jq 命令或直接阅读文件,服务端条目仅有 ts 字段,需通过 start 条目的 ts 对齐到客户端时钟。修复循环要求每次只改一处并重新测试,确认日志签名消失后再记录。
适用场景
适用于使用 Grok 实时语音功能的应用调试,包括浏览器、移动端、桌面端或 CLI 客户端。典型症状包括:有转录但无声音、助手自我打断、音频卡顿、爆音或音调异常、无法连接或立即关闭、麦克风无输入、无用户转录、首词延迟、用户文本出现在回复之后、首词被截断等。技能提供了症状到日志签名再到修复的起始对照表,并建议在确认修复后追加到“Confirmed from sessions”记录中。
限制
该技能仅用于开发环境调试,生产环境默认关闭日志接收端点。日志不记录令牌、密钥或原始音频。不得编造 xAI 事件名称,添加签名前需在官方文档中确认。该技能不提供音频录制或回放功能,仅通过字节计数和事件元数据辅助诊断。具体收费、价格、平台支持范围等事实暂未提供。