用途
Debug Voice 用于在事后把一次 Grok 实时语音会话变成可阅读的记录，并基于证据进行修复。它面向这样的场景：用户运行 /debug-voice、表示语音模式有缺陷、要求查看或捕获 Grok 实时语音会话中发生了什么，或语音集成出现问题。其基本立场是：智能体无法听到应用的声音，日志就是它的耳朵，用户是它的裁判；不涉及音频、不涉及令牌，也绝不在生产环境使用。
主要能力
该技能提供一套完整的语音调试流水线，包括：
- 只读地梳理应用结构，定位语音客户端（实时事件收发、麦克风采集、音频播放、令牌获取）、服务端（框架、路由声明方式、共享代码位置、环境变量读取方式、生产环境定义）、约定（语言、模块系统、格式化工具、脚本位置、.gitignore）以及客户端类型（浏览器、移动端、桌面端、CLI）。
- 在用户确认变更清单后，按应用现有语言、框架和约定安装日志组件，不引入第二套语言或工具链。
- 定义统一的日志契约：会话 id 为 UUID 生成的 8 位小写十六进制字符；每条日志为一行 JSON 对象，包含 t、ts、kind、src 及钩子字段。
- 客户端日志器负责缓冲条目，每 1 秒或达到 200 条时批量 POST 到接收端，停止时使用 keepalive 刷新，并吞掉所有传输错误，确保日志不会抛入语音路径。
- 服务端接收端 POST /api/voice/log，非开发环境或未设置 VOICE_LOG=1 时返回 404，sessionId 不合法或 entries 非数组时返回 400，每次最多追加 500 条、丢弃超过 16000 字符的行，写入 .voice-logs/<sessionId>.ndjson 并返回 204。
- 提供一组钩子点，覆盖会话开始、令牌获取、麦克风授权、音频图就绪、套接字连接、事件收发、阶段变化、麦克风分块聚合、预开缓冲刷新、首个音频增量、response.done、打断停止、用户停止以及服务端令牌路由等。
- 提供日志读取方式，可用 jq 查询里程碑与错误、服务端事件计数、每轮延迟与间隙、麦克风窗口等，无需应用工具链。
- 提供症状 → 日志特征 → 修复的对照表，覆盖静音但有转写、助手自我打断、卡顿、爆音或音调速度异常、无法连接或立即关闭、麦克风无反应、无用户转写、首词延迟、用户文本出现在回复之后、首词被截断等常见问题。
使用方式
工作流程分为五步：
- 梳理应用（只读）。
- 写出变更清单并展示，然后停止；在用户确认前不编辑任何文件。
- 按应用的语言、框架和约定安装约定好的组件。
- 验证接收端，把应用交给用户。
- 基于日志进入修复循环。
修复循环为：若应用尚无 .voice-logs 流水线则先插桩；用户在实际应用中测试并描述运行情况；读取失败时间点附近的日志；按症状 → 特征 → 修复表匹配；每次只改一处，重新测试，确认新日志中特征消失；记录确认结果。
适用场景
适用于任何技术栈的 Grok 实时语音集成调试，包括浏览器、移动端、桌面端和 CLI 客户端。非浏览器客户端同样 POST 相同的 JSON；单进程应用可跳过 HTTP 直接追加到文件。
限制
- 绝不记录令牌、密钥或原始音频；音频只记录字节数。
- 仅限开发环境；接收端在生产环境返回 404，除非设置 VOICE_LOG=1；.voice-logs/ 需加入 gitignore。
- 日志记录绝不能抛入语音路径。
- 音频必须聚合记录，绝不逐块记录。
- 每次重新测试只改一处，以便日志能说明是哪项修复起了作用。
- 不得臆造 xAI 事件名，添加特征前需在官方文档中确认。
- 关于具体收费、价格、平台支持范围等信息，资料中暂未提供。