oathra

Oathra 是一个开源（Apache-2.0、TypeScript）的运行时，用于让 AI 代理拨打电话、进行谈判并取回预约或订单。它把“任务是否完成”的判定从模型手中拿走，交给代码：只有从对方发言中提取出的证据齐全时，日期、人数、金额、是否确定等字段才会被填充。AI 自己说“已确定”只会被记录，不构成证据。

用途与定位

• 让 AI 打电话完成预约、下单、确认等任务，同时避免“幻觉式完成”。
• 同一运行时既可在模拟器中运行，也可接入真实电话线路：先浏览器里让 AI 互相对话，满意后再连接电话公司。
• 既可作为独立应用（Gateway），也可通过 SDK、MCP 服务器等方式集成到其他系统。

主要能力

• 完成判定：基于“证据引擎”和确定性完成判定逻辑；拒绝、改口、含糊应答分别有规则处理（如“19时满了”不会生成 19:00 证据；“13日，不对，14日”保留 14日并附上覆盖历史；“大概可以”不算同意与确定；对方之后改价会使确定失效）。
• 调用契约：CallContract 定义通话目的与必填项，intake 可在获得明确同意后追加提问，支持 startAfter、dependsOn、choices 控制场景分支与回答选项；拒绝、保留、含糊、忙碌或超出选项时立即停止。
• 模拟与练习：模拟器、应用内的练习模式（观看 AI 通话，或自己扮演对方接 AI 的电话）、Battle 卡、Replay、回退到某一时间点。
• 电话层：setup phone、phone doctor、三级测试、带降级的线路路由。Twilio 直连（实通话验证过）、Plivo 与自定义 SIP（经 LiveKit，按文档实现，PSTN 未验证）。
• 语音引擎：GPT-Live（推荐，实通话验证过）、Gemini Live（gemini-3.8-live，真实线路未验证）、Deepgram + LLM + TTS；另有 Telnyx、Wavix、Sinch、ElevenLabs TTS。
• 金额与号码双重 ASR，管线目标延迟 650 ms。
• MCP 服务器：oathra mcp 提供 simulate_call、verify_transcript、inspect_call、list_calls、list_scenarios，全部本地运行，不拨打真实电话。
• 全渠道 Gateway：可从 LINE、Slack、Telegram、Web、iOS 发起请求与审批，通话后接入 Gmail / Calendar / SMS / HubSpot；已有实现与离线测试，真实账号与实线路未验证，默认是模拟器。
• 证据等级 ActionProof：V0（自我申告）到 V1（对话）、V2（已验证的邮件/短信/Webhook）、V3（已验证的业务系统）、V4（结果报告），对同一期望值进行比对；外部认证与连接由使用方的 VerificationProvider / VerificationAdapter 负责，不包含 OpenTable、TableCheck、Google Reserve 的实际连接适配器或凭据。
• 判断“会面型”完成（confirmation: "callee_acceptance"），在 1 万条销售对话对抗测试中误完成为零。

使用方式

• 快速试用（需 Node.js 22 以上，无需 API 密钥和电话号码）：npx oathra demo 打开应用；也可在浏览器“证据实验室”或对本地转录文本进行判定的“检查器”中试用，输入不会被上传。注意 npx oathra demo 拉取的 npm 版本停留在 0.1.0，从源码运行的具体步骤与发布版差异见 docs/FIRST_PROOF.md。
• 从源码运行：pnpm install && pnpm test。场景位于 scenarios/，店员角色位于 providers/simulator/src/characters/，电话公司可用 oathra provider create phone <id> 生成模板。
• 练习模式数据保留在 .oathra/demo/，通话记录保留在 .oathra/calls/，可在练习界面“记录”中回看。
• 启动参数：--allow-remote（同一网络的其他设备访问，需登录链接）、--tunnel（cloudflared / ngrok 生成外部 https 地址）、--allow-models（练习中可选择 OpenAI、Gemini、Ollama 作为通话 AI，对话会发送给对应公司并产生 API 费用）、--live --tunnel（使用本机密钥实际拨打电话）。
• play --json 只返回 result、intake 与保存路径 savedPath 的 JSON，不含对话日志或标题，便于把决定事项交给其他业务系统。
• 验证与集成：oathra verify 检查本地转录文本；从 oathra/evidence 读取带类型的 SDK，不需要 API 密钥；接入步骤与 LiveKit 连接示例见文档。
• MCP：oathra mcp 是 stdio 的 MCP 服务器，一次工具调用即可运行模拟通话并返回与对方发言绑定的证据结果，全本地运行、无 API 密钥与费用；工具中不包含真实拨号工具或可选付费 LLM 的参数。inspect_call 会把 .oathra/calls/ 的内容交给 MCP 客户端，在存在真实通话记录的目录使用时需注意。
• 外部 AI 请求真实电话：可通过 Multibot / 外部代理集成（实验性），使用连接命令签发专用凭据与试用额度（10 次、单次通话最长 5 分钟、24 小时），目标号码需为已验证的本人号码或显式指定。
• 商务 MCP（公开准备中）：Claude Code、ChatGPT 中查看商品与联系人、起草销售电话，经 OAuth 连接，拨号由本人在 Oathra 界面确认；固定 HTTPS 部署与官方客户端实际连接确认尚未完成。

应用界面（apps/gateway） 包含首页、请求、日程、练习、联系人、设置。“请求通话”中输入对方、号码、目的（含“闲聊”模板或历史记录），确认目标与费用说明后再拨号（真实拨号需 --live --tunnel 或作为服务器运行的 Gateway）。“闲聊”中要求新闻或公开信息时，会用 OpenAI 的网页检索核实并附日期与出处。

限制与现状

• 当前以技术介绍和验证范围咨询（L1）为主，不代表有偿 PoC（L2）或生产导入（L3）已完成。真实电话 100 件的成功率与 p95 响应时间尚未测量。
• 服务版（managed 模式）已实现带邮箱验证的公开注册、密码找回、邮箱密码登录、Stripe Checkout 购买页面/API、支付核对后一次性发放额度等，但真实环境的邮件、支付、定价、常设公开、从注册到购买再到实际通话计费的端到端验证尚未完成，配置齐全前公开注册与购买处于无效状态；不支持 SSO、MFA、自动退款。
• 不猜测通话对方属性，也不暗中收集目的外信息。
• 费用参考（资料给出）：Twilio 拨打日本手机 ¥28.78/分钟，GPT-Live 会话 $0.05/分钟。
• 各数字均由项目方自行测量，并可用文中命令复现。