电话通信

无需更改核心工具即可赋予 Hermes 电话功能。配置并持久化 Twilio 号码，发送和接收 SMS/MMS，进行直接呼叫，以及通过 Bland.ai 或 Vapi 发起 AI 驱动的外呼。

技能元数据

来源	可选 — 使用 hermes skills install official/productivity/telephony 安装
路径	optional-skills/productivity/telephony
版本	1.0.0
作者	Nous Research
许可证	MIT
标签	telephony, phone, sms, mms, voice, twilio, bland.ai, vapi, calling, texting
相关技能	maps, google-workspace, agentmail

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理所看到的指令。

电话通信 — 无需更改核心工具即可实现号码、呼叫和短信

此可选技能在保持电话通信功能独立于核心工具列表之外的同时，为 Hermes 提供实用的电话功能。

它附带一个辅助脚本 scripts/telephony.py，可以执行以下操作：

• 将提供商凭据保存到 ~/.hermes/.env
• 搜索并购买 Twilio 电话号码
• 记住该自有号码以供后续会话使用
• 从自有号码发送 SMS / MMS
• 无需 webhook 服务器即可轮询该号码的入站 SMS
• 使用 TwiML <Say> 或 <Play> 进行直接 Twilio 呼叫
• 将自有 Twilio 号码导入 Vapi
• 通过 Bland.ai 或 Vapi 发起 outbound AI 呼叫

解决的问题

此技能旨在涵盖用户实际需要的实用电话任务：

• 外呼
• 发短信
• 拥有可复用的代理号码
• 稍后检查发送到该号码的消息
• 在会话之间保留该号码及相关 ID
• 为入站 SMS 轮询和其他自动化提供面向未来的电话身份

它不会将 Hermes 转变为实时入站电话网关。入站 SMS 通过轮询 Twilio REST API 处理。这对于许多工作流（包括通知和一些一次性代码检索）已经足够，无需添加核心 webhook 基础设施。

安全规则 — 强制要求

1. 在拨打电话或发送短信前务必确认。
2. 切勿拨打紧急号码。
3. 切勿将电话通信用于骚扰、垃圾邮件、冒充或任何非法行为。
4. 将第三方电话号码视为敏感操作数据：
   • 不要将其保存到 Hermes 记忆中
   • 除非用户明确要求，否则不要将其包含在技能文档、摘要或后续笔记中
5. 可以持久化代理拥有的 Twilio 号码，因为这是用户配置的一部分。
6. VoIP 号码不保证适用于所有第三方双因素认证 (2FA) 流程。请谨慎使用并明确设定用户预期。

决策树 — 使用哪项服务？

使用此逻辑而非硬编码的提供商路由：

1) “我希望 Hermes 拥有一个真实的电话号码”

使用 Twilio。

原因：

• 购买和保留号码的最简单途径
• 最佳的 SMS / MMS 支持
• 最简单的入站 SMS 轮询方案
• 通往入站 webhook 或呼叫处理的最清晰未来路径

用例：

• 稍后接收短信
• 发送部署警报 / cron 通知
• 为代理维护可复用的电话身份
• 日后尝试基于电话的身份验证流程

2) “我现在只需要最简单的外呼 AI 电话”

使用 Bland.ai。

原因：

• 设置最快
• 只需一个 API 密钥
• 无需先自行购买/导入号码

权衡：

• 灵活性较低
• 语音质量尚可，但并非最佳

3) “我想要最佳的对话式 AI 语音质量”

使用 Twilio + Vapi。

原因：

• Twilio 提供自有号码
• Vapi 提供更佳的对话式 AI 呼叫质量和更多的语音/模型灵活性

推荐流程：

1. 购买/保存 Twilio 号码
2. 将其导入 Vapi
3. 保存返回的 VAPI_PHONE_NUMBER_ID
4. 使用 ai-call --provider vapi

4) “我想使用自定义预录制语音消息进行呼叫”

使用带有公共音频 URL 的 Twilio 直接呼叫。

原因：

• 播放自定义 MP3 的最简单方式
• 与 Hermes text_to_speech 加上公共文件主机或隧道配合良好

文件和持久状态

该技能在两个位置持久化电话通信状态：

~/.hermes/.env

用于长期存在的提供商凭据和自有号码 ID，例如：

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER
• TWILIO_PHONE_NUMBER_SID
• BLAND_API_KEY
• VAPI_API_KEY
• VAPI_PHONE_NUMBER_ID
• PHONE_PROVIDER（AI 呼叫提供商：bland 或 vapi）

~/.hermes/telephony_state.json

用于仅属于技能且应在会话间保留的状态，例如：

• 记住的默认 Twilio 号码 / SID
• 记住的 Vapi 电话号码 ID
• 用于收件箱轮询检查点的最后入站消息 SID/日期

这意味着：

• 下次加载该技能时，diagnose 可以告诉你已配置的号码
• twilio-inbox --since-last --mark-seen 可以从上一个检查点继续

定位辅助脚本

安装此技能后，按如下方式定位脚本：

SCRIPT="$(find ~/.hermes/skills -path '*/telephony/scripts/telephony.py' -print -quit)"

如果 SCRIPT 为空，则表示尚未安装该技能。

安装

这是一个官方可选技能，请从 Skills Hub 安装：

hermes skills search telephony
hermes skills install official/productivity/telephony

提供商设置

Twilio — 自有号码、SMS/MMS、直接呼叫、入站 SMS 轮询

注册地址：

• https://www.twilio.com/try-twilio

然后将凭据保存到 Hermes：

python3 "$SCRIPT" save-twilio ACXXXXXXXXXXXXXXXXXXXXXXXXXXXX your_auth_token_here

搜索可用号码：

python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 5

购买并记住一个号码：

python3 "$SCRIPT" twilio-buy "+17025551234" --save-env

列出自有号码：

python3 "$SCRIPT" twilio-owned

稍后将其中一个设置为默认号码：

python3 "$SCRIPT" twilio-set-default "+17025551234" --save-env
# or
python3 "$SCRIPT" twilio-set-default PNXXXXXXXXXXXXXXXXXXXXXXXXXXXX --save-env

Bland.ai — 最简单的出站 AI 呼叫

注册地址：

• https://app.bland.ai

保存配置：

python3 "$SCRIPT" save-bland your_bland_api_key --voice mason

Vapi — 更好的对话语音质量

注册地址：

• https://dashboard.vapi.ai

首先保存 API 密钥：

python3 "$SCRIPT" save-vapi your_vapi_api_key

将你拥有的 Twilio 号码导入 Vapi 并持久化返回的电话号码 ID：

python3 "$SCRIPT" vapi-import-twilio --save-env

如果你已经知道 Vapi 电话号码 ID，可以直接保存：

python3 "$SCRIPT" save-vapi your_vapi_api_key --phone-number-id vapi_phone_number_id_here

诊断当前状态

随时检查技能已知的信息：

python3 "$SCRIPT" diagnose

在后续会话中恢复工作时，请首先使用此命令。

常见工作流

A. 购买代理号码并在以后继续使用

1. 保存 Twilio 凭据：

python3 "$SCRIPT" save-twilio AC... auth_token_here

2. 搜索号码：

python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 10

3. 购买并将其保存到 ~/.hermes/.env + 状态中：

python3 "$SCRIPT" twilio-buy "+17025551234" --save-env

4. 下次会话时，运行：

python3 "$SCRIPT" diagnose

这将显示记住的默认号码和收件箱检查点状态。

B. 从代理号码发送短信

python3 "$SCRIPT" twilio-send-sms "+15551230000" "Your deployment completed successfully."

附带媒体文件：

python3 "$SCRIPT" twilio-send-sms "+15551230000" "Here is the chart." --media-url "https://example.com/chart.png"

C. 在没有 webhook 服务器的情况下稍后检查入站短信

轮询默认 Twilio 号码的收件箱：

python3 "$SCRIPT" twilio-inbox --limit 20

仅显示在上次检查点之后到达的消息，并在阅读完成后推进检查点：

python3 "$SCRIPT" twilio-inbox --since-last --mark-seen

这是“下次加载技能时如何访问该号码接收到的消息？”的主要答案。

D. 使用内置 TTS 进行直接 Twilio 呼叫

python3 "$SCRIPT" twilio-call "+15551230000" --message "Hello! This is Hermes calling with your status update." --voice Polly.Joanna

E. 使用预录制/自定义语音消息进行呼叫

这是复用 Hermes 现有 text_to_speech 支持的主要路径。

在以下情况下使用：

• 你希望呼叫使用 Hermes 配置的 TTS 语音，而不是 Twilio <Say>
• 你希望进行单向语音交付（简报、警报、笑话、提醒、状态更新）
• 你不需要实时对话电话呼叫

单独生成或托管音频，然后：

python3 "$SCRIPT" twilio-call "+155****0000" --audio-url "https://example.com/briefing.mp3"

推荐的 Hermes TTS -> Twilio Play 工作流：

1. 使用 Hermes text_to_speech 生成音频。
2. 使生成的 MP3 可公开访问。
3. 使用 --audio-url 发起 Twilio 呼叫。

代理流程示例：

• 要求 Hermes 使用 text_to_speech 创建消息音频
• 如果需要，通过临时静态主机/隧道/对象存储 URL 暴露文件
• 使用 twilio-call --audio-url ... 通过电话交付

MP3 的良好托管选项：

• 临时公共对象/存储 URL
• 指向本地静态文件服务器的短期隧道
• 电话提供商可以直接获取的任何现有 HTTPS URL

重要说明：

• Hermes TTS 非常适合预录制的出站消息
• Bland/Vapi 更适合实时对话 AI 呼叫，因为它们自己处理实时电话音频栈
• 此处并未将 Hermes STT/TTS 用作全双工电话对话引擎；那需要比本技能试图引入的更重的流式/webhook 集成

F. 使用 Twilio 直接呼叫导航电话树/IVR

如果需要在呼叫连接后按下数字键，请使用 --send-digits。 Twilio 将 w 解释为短暂等待。

python3 "$SCRIPT" twilio-call "+18005551234" --message "Connecting to billing now." --send-digits "ww1w2w3"

这在转接给人工或交付简短状态消息之前到达特定菜单分支时很有用。

G. 使用 Bland.ai 进行出站 AI 电话呼叫

python3 "$SCRIPT" ai-call "+15551230000" "Call the dental office, ask for a cleaning appointment on Tuesday afternoon, and if they do not have Tuesday availability, ask for Wednesday or Thursday instead." --provider bland --voice mason --max-duration 3

检查状态：

python3 "$SCRIPT" ai-status <call_id> --provider bland

完成后询问 Bland 分析问题：

python3 "$SCRIPT" ai-status <call_id> --provider bland --analyze "Was the appointment confirmed?,What date and time?,Any special instructions?"

H. 在你拥有的号码上使用 Vapi 进行出站 AI 电话呼叫

1. 将你的 Twilio 号码导入 Vapi：

python3 "$SCRIPT" vapi-import-twilio --save-env

2. 发起呼叫：

python3 "$SCRIPT" ai-call "+15551230000" "You are calling to make a dinner reservation for two at 7:30 PM. If that is unavailable, ask for the nearest time between 6:30 and 8:30 PM." --provider vapi --max-duration 4

3. 检查结果：

python3 "$SCRIPT" ai-status <call_id> --provider vapi

建议的代理程序

当用户请求呼叫或短信时：

1. 通过决策树确定哪种路径适合该请求。
2. 如果配置状态不明确，运行 diagnose。
3. 收集完整的任务详情。
4. 在拨号或发送短信之前与用户确认。
5. 使用正确的命令。
6. 如果需要，轮询结果。
7. 总结结果，不要将第三方号码持久化到 Hermes 记忆中。

此技能尚不支持的功能

• 实时接听呼入电话
• 基于 Webhook 的实时短信推送到代理循环中
• 保证支持任意第三方双因素认证（2FA）提供商

这些功能需要比纯可选技能更多的基础设施支持。

注意事项

• Twilio 试用账户和区域规则可能会限制您可以呼叫或发送短信的对象。
• 某些服务会拒绝将 VoIP 号码用于双因素认证（2FA）。
• twilio-inbox 通过轮询 REST API 获取数据，并非即时推送交付。
• Vapi 外呼仍然依赖于已导入的有效号码。
• Bland 使用最简单，但音质并非总是最佳。
• 不要在 Hermes 内存中存储任意的第三方电话号码。

验证清单

完成设置后，仅使用此技能应能够执行以下所有操作：

1. diagnose 命令显示提供商就绪状态和已记忆的状态
2. 搜索并购买 Twilio 号码
3. 将该号码持久化保存到 ~/.hermes/.env
4. 从拥有的号码发送短信
5. 稍后轮询该拥有号码的接收短信
6. 发起直接的 Twilio 呼叫
7. 通过 Bland 或 Vapi 发起 AI 呼叫

参考资料

• Twilio 电话号码：https://www.twilio.com/docs/phone-numbers/api
• Twilio 消息：https://www.twilio.com/docs/messaging/api/message-resource
• Twilio 语音：https://www.twilio.com/docs/voice/api/call-resource
• Vapi 文档：https://docs.vapi.ai/
• Bland.ai：https://app.bland.ai/