hotato

hotato

找出 Agent 调用中出错的环节。将其固定下来，在修复之前，CI 会持续报错。

pip install hotato
hotato check --demo             # a bundled failing call: what broke, and when
hotato check ./call.wav         # then your own recording
hotato vapi health              # or your last 100 Vapi calls

零配置。支持 Vapi、Retell、Bland、Synthflow、Millis 或本地音频。 适用于任何录音：单声道、双声道或文字稿。依据时间计算，而非评判。离线运行。免费。MIT 许可证。

hotato.dev

可发现的问题

• 言行不一致：来电者打断通话要求取消（插话打断），Agent 却说“已取消”，预约工具仍然触发。hotato 从音频中提取轮次时序，从 OTel 跟踪记录中提取工具调用。
• 延迟飙升：回复前的停顿从 800 ms 增至 2 s 以上。
• 长时间静默：停顿达到 5 s，或线路陷入静默。
• 抢话：Agent 在来电者说话时开始新的发言。

快速入门

Vapi

pip install hotato
export VAPI_API_KEY=...
hotato vapi health --last 7d --output report.html

打开 report.html：查看每起关键事件的时间戳，以及语音稳定性评分。

Retell

export RETELL_API_KEY=...
hotato retell health --call-id CALL_ID

必须指定 --call-id，且可重复指定：你可以指定要拉取的 Retell 通话。 hotato bland health、hotato synthflow health 和 hotato millis health 使用与 Vapi 相同的格式。这些平台会将双方语音混合到同一声道，因此 它们会测量静默时长、长时间静默和延迟间隔，并为每项发现提供 测得的置信度；插话打断和抢话则需要双声道。

本地音频

hotato autopsy ./call.wav

会将独立的 HTML 报告写入 hotato-output/，并生成 pin 读取的 JSON 文件。在浏览器中打开 HTML 文件。

从发现问题到在 CI 中设为门禁

autopsy 会将一段录音转换为带时间戳的事件。scan 会读取一个文件夹并跟踪趋势。准备就绪后，可将发现的问题纳入 CI： hotato pin 会将单个事件转换为可移植的失败检查，而 hotato prove 会重新运行所有已存储的检查；如果无法重新读取证据，它会让构建失败，而不是判定通过。每个判定都包含其自身在五个维度上的证据：结果、策略、对话、语音、可靠性。

固定的检查会重新测量其存储的录音，因此该问题会让构建持续报错，还能发现被编辑的捆绑包、放宽的策略，或对相同字节评分不同的引擎升级。要清除问题，需针对当前 Agent 重新录制同一时刻：hotato drive <bundle> 会通过 Vapi 或 Twilio 发起通话；其他平台的操作指南请参阅 docs/RECAPTURE.md。

固定问题 →

如需持续使用：定期运行 hotato vapi health，并打开 hotato console --production-db evidence.db 实时查看通话。

将其接入 CI

退出代码就是判定结果：0 通过，1 失败，2 拒绝（无法判断）。

# .github/workflows/voice-qa.yml
on: [pull_request]
jobs:
  hotato:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: attenlabs/[email protected]
        with:
          contracts: contracts/
          hotato-version: 1.20.0

contracts/ 保存 pin 写入的内容。完整工作流：docs/CI.md。

让你的 Agent 使用它

让 Claude Code、Cursor 或任何编码 Agent 使用此代码库：它会读取 AGENTS.md，并在离线状态下端到端运行整个循环，无需密钥。通过本地 stdio，MCP 服务会提供评分器以及读取／验证／提议工具： uvx --from "hotato[mcp]" hotato-mcp（docs/MCP.md）。部署由你负责。

数据不会离开你的设备

hotato 在调用它的设备上离线运行。核心部分仅使用 Python 标准库：无需账户、无需密钥，也不会自行发起网络调用。你的轨迹、提示词 和音频都会留在磁盘上。使用你自行托管的大模型评分，是单独选择启用的附加功能，不属于核心部分。

深入了解

完整循环，逐条命令说明：docs/LIFECYCLE.md。 从首次接触到 CI 门禁：docs/GETTING-STARTED.md。 使用你已有的数据：docs/CONNECT.md · docs/TRACE.md · docs/SIMULATE.md。 每项判定的依据：docs/EVIDENCE-CONTRACT.md。 与托管式替代方案对比：docs/COMPARE.md。

完整工具集——采集、模拟、负载、基准测试、修复梯级、 集群控制平面——位于 hotato lab 下（hotato lab --help）。 公开命令稳定可靠。hotato lab 迭代更快，而且所有在 1.17 之前可用的 命令名称仍可照常使用。

规格

PYTHONPATH=src python3 -m hotato.benchmark \
  --scenarios corpus/real/scenarios --audio corpus/real/audio

参与贡献

欢迎提交问题和 PR：CONTRIBUTING.md · SECURITY.md · CHANGELOG · docs/

许可证

MIT（LICENSE）

mcp-name: io.github.attenlabs/hotato