@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/productivity/telephony/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: telephony
+description: Give Hermes phone capabilities without core tool changes. Provision and persist a Twilio number, send and receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi.
+version: 1.0.0
+author: Nous Research
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [telephony, phone, sms, mms, voice, twilio, bland.ai, vapi, calling, texting]
+    related_skills: [maps, google-workspace, agentmail]
+    category: productivity
+---
+
+# Telephony — Numbers, Calls, and Texts without Core Tool Changes
+
+这个可选的 skill 赋予 Hermes 实用的电话功能，同时避免将 telephony 引入核心工具列表中。
+
+它附带了一个辅助脚本，`scripts/telephony.py`，它可以：
+- 将服务商凭据保存到 `${HERMES_HOME:-~/.hermes}/.env`
+- 搜索并购买一个 Twilio 电话号码
+- 记住已拥有的号码以备后续会话使用
+- 使用拥有的号码发送 SMS / MMS
+- 为该号码轮询接收 SMS，无需 webhook 服务器
+- 使用 TwiML `<Say>` 或 `<Play>` 拨打 Twilio 直拨电话
+- 将已拥有的 Twilio 号码导入 Vapi
+- 通过 Bland.ai 或 Vapi 拨打 AI 外呼电话
+
+## 这个工具解决什么问题
+
+这个 skill 旨在涵盖用户实际需要的实用电话任务：
+- 外呼
+- 发短信
+- 拥有一个可重复使用的 agent 号码
+- 稍后检查发送到该号码的短信
+- 在不同会话之间保留该号码及相关 ID
+- 为接收 SMS 轮询和其他自动化提供面向未来的 telephony 身份
+
+它**不会**将 Hermes 变成一个实时的电话呼入网关。接收 SMS 是通过轮询 Twilio REST API 来处理的。这对于许多工作流来说已经足够了，包括通知接收和一些一次性验证码获取，而无需添加核心的 webhook 基础设施。
+
+## 安全规则 — 强制执行
+
+1. 在拨打电话或发送短信之前务必进行确认。
+2. 绝对不要拨打紧急号码。
+3. 绝对不要将 telephony 用于骚扰、发送垃圾信息、冒充或任何非法活动。
+4. 将第三方电话号码视为敏感的操作数据：
+   - 不要将它们保存到 Hermes 内存中
+   - 除非用户明确要求，否则不要将它们包含在 skill 文档、摘要或后续笔记中
+5. 持久化保存 **agent 拥有的 Twilio 号码** 是允许的，因为那是用户配置的一部分。
+6. VoIP 号码**不保证**适用于所有第三方的 2FA 流程。使用时请谨慎，并明确设定用户的预期。
+
+## 决策树 — 该使用哪个服务？
+
+请使用以下逻辑，而不是硬编码的服务商路由：
+
+### 1) “我希望 Hermes 拥有一个真实的电话号码”
+使用 **Twilio**。
+
+原因：
+- 购买和保留号码的最简单途径
+- 最佳的 SMS / MMS 支持
+- 最简单的接收 SMS 轮询方案
+- 未来过渡到接收 webhook 或呼叫处理的最干净路径
+
+使用场景:
+- 稍后接收短信
+- 发送部署警报 / cron 定时任务通知
+- 为 agent 维持一个可重复使用的电话身份
+- 以后进行基于电话的身份验证流程实验
+
+### 2) “我现在只需要最简单的 AI 外呼电话”
+使用 **Bland.ai**。
+
+原因：
+- 设置最快
+- 只需一个 API key
+- 无需自己先购买/导入号码
+
+权衡：
+- 灵活性较差
+- 语音质量不错，但不是最好的
+
+### 3) “我希望获得最好的对话式 AI 语音质量”
+使用 **Twilio + Vapi**。
+
+原因：
+- Twilio 提供你拥有的号码
+- Vapi 提供更好的对话式 AI 通话质量和更多的语音/模型灵活性
+
+推荐的流程:
+1. 购买/保存一个 Twilio 号码
+2. 将其导入 Vapi
+3. 保存返回的 `VAPI_PHONE_NUMBER_ID`
+4. 使用 `ai-call --provider vapi`
+
+### 4) “我想用自定义的预录语音消息进行呼叫”
+使用 **Twilio direct call** 结合公开的音频 URL。
+
+原因：
+- 播放自定义 MP3 的最简单方法
+- 与 Hermes 的 `text_to_speech` 以及公共文件托管或隧道完美搭配
+
+## 文件和持久化状态
+
+该 skill 在两个位置持久化保存 telephony 状态：
+
+### `${HERMES_HOME:-~/.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`
+用于保存应该跨会话保留的、专属于该 skill 的状态，例如：
+- 记住的默认 Twilio 号码 / SID
+- 记住的 Vapi 电话号码 ID
+- 用于收件箱轮询检查点的最后接收消息 SID/日期
+
+这意味着：
+- 下次加载该 skill 时，`diagnose` 可以告诉你已经配置了哪个号码
+- `twilio-inbox --since-last --mark-seen` 可以从上一个检查点继续
+
+## 定位辅助脚本
+
+安装此 skill 后，按如下方式定位脚本：
+
+```bash
+SCRIPT="$(find ~/.hermes/skills -path '*/telephony/scripts/telephony.py' -print -quit)"
+```
+
+如果 `SCRIPT` 为空，说明该 skill 尚未安装。
+
+## 安装
+
+这是一个官方的可选 skill，请从 Skills Hub 安装它：
+
+```bash
+hermes skills search telephony
+hermes skills install official/productivity/telephony
+```
+
+## 服务商设置
+
+### Twilio — 拥有的号码、SMS/MMS、直拨电话、接收 SMS 轮询
+
+注册地址：
+- https://www.twilio.com/try-twilio
+
+然后将凭据保存到 Hermes：
+
+```bash
+python3 "$SCRIPT" save-twilio ACXXXXXXXXXXXXXXXXXXXXXXXXXXXX your_auth_token_here
+```
+
+搜索可用号码：
+
+```bash
+python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 5
+```
+
+购买并记住一个号码：
+
+```bash
+python3 "$SCRIPT" twilio-buy "+17025551234" --save-env
+```
+
+列出已拥有的号码：
+
+```bash
+python3 "$SCRIPT" twilio-owned
+```
+
+稍后将其中的一个设置为默认值：
+
+```bash
+python3 "$SCRIPT" twilio-set-default "+17025551234" --save-env
+# or
+python3 "$SCRIPT" twilio-set-default PNXXXXXXXXXXXXXXXXXXXXXXXXXXXX --save-env
+```
+
+### Bland.ai — 最简单的 AI 外呼
+
+注册地址：
+- https://app.bland.ai
+
+保存配置：
+
+```bash
+python3 "$SCRIPT" save-bland your_bland_api_key --voice mason
+```
+
+### Vapi — 更好的对话语音质量
+
+注册地址：
+- https://dashboard.vapi.ai
+
+首先保存 API key：
+
+```bash
+python3 "$SCRIPT" save-vapi your_vapi_api_key
+```
+
+将你拥有的 Twilio 号码导入 Vapi，并持久化保存返回的电话号码 ID：
+
+```bash
+python3 "$SCRIPT" vapi-import-twilio --save-env
+```
+
+如果你已经知道 Vapi 的电话号码 ID，请直接保存它：
+
+```bash
+python3 "$SCRIPT" save-vapi your_vapi_api_key --phone-number-id vapi_phone_number_id_here
+```
+
+## 诊断当前状态
+
+随时检查该 skill 已经知道的信息：
+
+```bash
+python3 "$SCRIPT" diagnose
+```
+
+在稍后的会话中恢复工作时，请首先使用此命令。
+
+## 常见工作流
+
+### A. 购买一个 agent 号码并在以后继续使用它
+
+1. 保存 Twilio 凭据：
+```bash
+python3 "$SCRIPT" save-twilio AC... auth_token_here
+```
+
+2. 搜索号码：
+```bash
+python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 10
+```
+
+3. 购买并将其保存到 `${HERMES_HOME:-~/.hermes}/.env` + 状态文件中：
+```bash
+python3 "$SCRIPT" twilio-buy "+17025551234" --save-env
+```
+
+4. 下次会话时，运行：
+```bash
+python3 "$SCRIPT" diagnose
+```
+这将显示已记住的默认号码和收件箱检查点状态。
+
+### B. 从 agent 号码发送短信
+
+```bash
+python3 "$SCRIPT" twilio-send-sms "+15551230000" "Your deployment completed successfully."
+```
+
+附带媒体：
+
+```bash
+python3 "$SCRIPT" twilio-send-sms "+15551230000" "Here is the chart." --media-url "https://example.com/chart.png"
+```
+
+### C. 稍后在没有 webhook 服务器的情况下检查接收到的短信
+
+轮询默认 Twilio 号码的收件箱：
+
+```bash
+python3 "$SCRIPT" twilio-inbox --limit 20
+```
+
+仅显示在上一个检查点之后到达的消息，并在阅读完毕后推进检查点：
+
+```bash
+python3 "$SCRIPT" twilio-inbox --since-last --mark-seen
+```
+
+这是针对“下次加载该 skill 时，我该如何访问该号码收到的消息？”的主要解答。
+
+### D. 使用内置 TTS 拨打 Twilio 直拨电话
+
+```bash
+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>`
+- 你希望进行单向语音传递（简报、警报、笑话、提醒、状态更新）
+- 你**不需要**实时的对话式电话呼叫
+
+单独生成或托管音频，然后：
+
+```bash
+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 电话。
+
+示例 agent 流程:
+- 要求 Hermes 使用 `text_to_speech` 创建消息音频
+- 如果需要，使用临时静态主机 / 隧道 / 对象存储 URL 暴露该文件
+- 使用 `twilio-call --audio-url ...` 通过电话传递它
+
+托管 MP3 的不错选项：
+- 临时的公开对象/存储 URL
+- 连接到本地静态文件服务器的临时隧道
+- 电话服务商可以直接获取的任何现有 HTTPS URL
+
+重要提示：
+- Hermes TTS 非常适合用于预录制的出境消息
+- Bland/Vapi 更适合**实时的对话式 AI 通话**，因为它们自己处理实时 telephony 音频堆栈
+- 此处并没有将 Hermes STT/TTS 单独用作全双工电话对话引擎；那将需要比该 skill 试图引入的更重量级的流式/webhook 集成
+
+### F. 使用 Twilio 直拨电话导航电话树 / IVR
+
+如果在通话接通后你需要按下按键，请使用 `--send-digits`。
+Twilio 会将 `w` 解释为短暂等待。
+
+```bash
+python3 "$SCRIPT" twilio-call "+18005551234" --message "Connecting to billing now." --send-digits "ww1w2w3"
+```
+
+这对于在转接给人工或传递简短的状态消息之前到达特定的菜单分支很有用。
+
+### G. 使用 Bland.ai 拨打 AI 外呼电话
+
+```bash
+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
+```
+
+检查状态：
+
+```bash
+python3 "$SCRIPT" ai-status <call_id> --provider bland
+```
+
+在完成后向 Bland 提出分析问题：
+
+```bash
+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：
+```bash
+python3 "$SCRIPT" vapi-import-twilio --save-env
+```
+
+2. 拨打电话：
+```bash
+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. 检查结果：
+```bash
+python3 "$SCRIPT" ai-status <call_id> --provider vapi
+```
+
+## 建议的 agent 流程
+
+当用户要求呼叫或发短信时：
+
+1. 通过决策树确定哪条路径符合请求。
+2. 如果配置状态不明确，运行 `diagnose`。
+3. 收集完整的任务细节。
+4. 在拨号或发短信之前与用户确认。
+5. 使用正确的命令。
+6. 如果需要，轮询结果。
+7. 总结结果，不要将第三方号码持久化保存到 Hermes 内存中。
+
+## 这个 skill 目前仍做不到的事
+
+- 实时的呼入电话接听
+- 基于 webhook 的实时 SMS 推送到 agent 循环中
+- 保证支持任意的第三方 2FA 服务商
+
+这些功能将需要比一个纯可选 skill 更多的基础设施。
+
+## 注意事项
+
+- Twilio 试用账户和地区规则可能会限制你可以呼叫/发送短信的对象。
+- 某些服务会拒绝 VoIP 号码用于 2FA。
+- `twilio-inbox` 会轮询 REST API；它不是即时推送传递。
+- Vapi 外呼仍然依赖于拥有有效的已导入号码。
+- Bland 最简单，但音质并不总是最好的。
+- 不要将任意的第三方电话号码存储在 Hermes 内存中。
+
+## 验证 checklist
+
+设置完成后，你应该能够仅使用此 skill 完成以下所有操作：
+
+1. `diagnose` 显示服务商就绪状态和已记住的状态
+2. 搜索并购买一个 Twilio 号码
+3. 将该号码持久化保存到 `${HERMES_HOME:-~/.hermes}/.env`
+4. 从拥有的号码发送 SMS
+5. 稍后轮询拥有的号码接收到的短信
+6. 拨打 Twilio 直拨电话
+7. 通过 Bland 或 Vapi 拨打 AI 电话
+
+## 参考资料
+
+- Twilio phone numbers: https://www.twilio.com/docs/phone-numbers/api
+- Twilio messaging: https://www.twilio.com/docs/messaging/api/message-resource
+- Twilio voice: https://www.twilio.com/docs/voice/api/call-resource
+- Vapi docs: https://docs.vapi.ai/
+- Bland.ai: https://app.bland.ai/