/byted-vms-voice-notify

name: byted-vms-voice-notify
version: 2.0.0
description: 火山云通信语音通知 Skill. 在用户提到「语音通知 / 语音播报 / 自动外呼通知 / 语音提醒」并给出被叫号码与播报内容时调用. 支持单次发送 (SingleBatchAppend) 与批量任务 (CreateTask). 同时是所有 TTS 模板操作 (创建 / 更新 / 删除 / 查询) 以及录音文件 / 通用资源管理 (创建 / 查询 / 删除 / 直传 / 列表 / 可用资源 / 改名 / 删除) 的唯一入口.
license: Apache-2.0
metadata:
  author: leixin.alex@bytedance.com
  homepage: https://www.volcengine.com/docs/6358/172952?lang=zh
  knowledge_base: references/vms-fundamentals.md
  openclaw:
    emoji: "📞"
    requires:
      env:
        - VOLC_ACCESS_KEY
        - VOLC_SECRET_KEY
    os:
      - darwin
      - linux
    triggers:
      - 发送语音通知
      - 语音通知
      - 语音播报
      - 自动外呼通知
      - 语音提醒
      - 给.*打语音
      - 创建TTS模板
      - 创建tts模板
      - 更新TTS模板
      - 删除TTS模板
      - 查询TTS模板
      - 上传录音文件
      - 创建录音
      - 删除录音
      - 查询录音
      - 录音直传
      - 录音资源列表
      - 可用资源

byted-vms-voice-notify · 火山云通信语音通知

封装火山云通信 TOP 语音通知接口, 支持「单次发送」「批量任务」「号码池查询」「TTS 模板全套生命周期管理 (创建 / 更新 / 删除 / 查询)」「录音文件管理 (创建 / 查询 / 删除 / 直传)」「通用资源管理 (列表 / 可用 / 改名 / 删除)」.

何时使用

用户出现以下表达时:

• 「给 138xxxxxxxx 发语音通知」「打语音电话提醒」「语音播报」
• 「批量给一批号码外呼提醒」「创建语音通知任务」
• 「查一下我的语音文件 / TTS 模板」「我的号码池有哪些」
• 「创建 / 更新 / 删除 / 查询 TTS 模板」
• 「上传录音 (公网 URL)」「列出我的录音」「删掉这个录音」「录音直传」
• 「列出录音 / IVR 资源」「查可用资源」「改录音名字」「删除某个资源」

默认走 `SingleBatchAppend` 单次发送. 仅当用户明确要求「创建批量任务 / 任务化外呼 / 定时外呼」时切到 `CreateTask`.

> **TTS / 录音 / 通用资源的唯一入口**: 所有 TTS 模板操作 (`open_create_tts` / `delete_tts` / `list_resource --type 1`) 与所有录音 / 通用资源操作 (`create_voice` / `query_voice` / `delete_voice` / `get_upload_url` / `submit_upload` / `list_usable` / `update_resource` / `delete_resource`) 都在本 skill 内. `byted-vms-configure` 不再提供任何 TTS / 录音 / 资源入口, 它只保留跨业务的 `query_risk_deny` / `query_can_call` / `query_auth`.

环境变量

按以下优先级解析鉴权:

1. `ARK_SKILL_API_KEY` + `ARK_SKILL_API_BASE` → 火山引擎 arkclaw 企业版. 请先在火山后台页面配置好 AK/SK, 由 arkclaw 注入这两个环境变量 (`ARK_SKILL_API_KEY` 为 API 密钥, `ARK_SKILL_API_BASE` 为 API 基础地址), 脚本以 `Bearer` 鉴权直连该网关, 无需本地签名; 2. `VOLC_ACCESS_KEY` + `VOLC_SECRET_KEY` (兼容 `VOLCENGINE_ACCESS_KEY`/`VOLCENGINE_SECRET_KEY`) → 个人版 arkclaw / openclaw / coco / aime / claudecode 等普通 agent, 用户直接把 AK/SK 告诉 agent, 脚本本地做 HMAC-SHA256 (Volc V4) 签名; 3. 否则报错并提示用户填入 AK/SK.

核心命令

# 1. 查可用语音资源 (录音 type=0 / TTS 模板 type=1 / IVR type=2)
#    支持 --resource-key 精确过滤, 可替代独立的 query_tts.
python3 scripts/send_voice_notify.py list_resource \
    [--type 0|1|2] [--keyword 欠费] [--resource-key <ResourceKey>]

# 2. 查号码池
python3 scripts/send_voice_notify.py list_number_pool [--keyword 北京]

# 3. 单次发送语音通知 (SingleBatchAppend)
python3 scripts/send_voice_notify.py single_append \
    --phone <Phone> \
    --resource <ResourceKey> \
    --number-pool-no <NumberPoolNo> \
    [--type 0|1|2] \
    [--phone-param '{"name":"<UserName>"}'] \
    [--ring-again-times 1] [--ring-again-interval 5] \
    [--ext "biz=<BizTag>"]

# 4. 批量任务 (CreateTask)
python3 scripts/send_voice_notify.py create_task \
    --name "<TaskName>" \
    --type 1 \
    --resource <ResourceKey> \
    --number-pool-no <NumberPoolNo> \
    --start-time "2026-05-28 10:00:00" \
    --end-time   "2026-05-28 18:00:00" \
    --concurrency 5 \
    [--select-number-rule 1]   # 服务端必填: 1=随机 (默认) / 2=轮询 / 3=尾号匹配
    --phone-list-json '[{"Phone":"<Phone>","PhoneParam":{"name":"<UserName>"}}]'

# 5. TTS 模板生命周期 (本 skill 是 TTS 唯一入口)
#    5.1 创建 (审核后才能用)
python3 scripts/send_voice_notify.py open_create_tts \
    --content "您好, <模板文案>" --name "<模板名称>" [--lang zh] [--remark "..."]
#    注意: 仅当用户明确给出全部模板参数 (文案 + 语速/音调/音量等) 时才允许直接调用;
#    若用户仅提模糊的「定制化模板」诉求, 必须先引导跳转控制台手工配置, 见下文「定制化模板诉求」章节.

#    5.2 删除 (内部走 OpenDeleteResource; TOP 没有独立 OpenDeleteTts)
python3 scripts/send_voice_notify.py delete_tts --resource-key <ResourceKey>

#    注: TTS 模板平台不支持 OpenAPI 改文案 / 改名 / 改语速音调等;
#         如需调整请前往控制台手工修改并重审: https://console.volcengine.com/cloud_vms/voice-file

#    5.3 查询 (统一走 list_resource --type 1)
python3 scripts/send_voice_notify.py list_resource --type 1 \
    [--resource-key <ResourceKey>] [--keyword <Name关键字>]

# 6. 单次发送结果查询 (按 SingleOpenId)
python3 scripts/send_voice_notify.py query_single --single-open-id <SingleOpenId>

# 7. 单次发送取消 (尚未拨打前可取消)
python3 scripts/send_voice_notify.py cancel_single --single-open-id <SingleOpenId>

# 8. 批量任务追加号码 (BatchAppend, 单次 ≤ 1 万)
python3 scripts/send_voice_notify.py batch_append \
    --task-open-id <TaskOpenId> \
    --phones <PhoneA>,<PhoneB>
# 或用 JSON, 支持每个号码携带 PhoneParam:
python3 scripts/send_voice_notify.py batch_append \
    --task-open-id <TaskOpenId> \
    --phone-list-json '[{"Phone":"<Phone>","PhoneParam":{"name":"<UserName>"}}]'

# 9. 任务生命周期控制
python3 scripts/send_voice_notify.py pause_task  --task-open-id <TaskOpenId>
python3 scripts/send_voice_notify.py resume_task --task-open-id <TaskOpenId>
python3 scripts/send_voice_notify.py stop_task   --task-open-id <TaskOpenId>

# 10. 更新任务参数 (执行窗口 / 并发 / 重呼策略 / 禁呼时段)
python3 scripts/send_voice_notify.py update_task \
    --task-open-id <TaskOpenId> \
    [--start-time "2026-05-28 10:00:00"] [--end-time "2026-05-28 18:00:00"] \
    [--concurrency 5] \
    [--ring-again-times 1] [--ring-again-interval 5] \
    [--forbid-time-list-json '[{"BeginTime":"12:00","EndTime":"13:30"}]'] \
    [--recall true]

# 11. 录音文件管理
#     11.1 上传录音 (TOP 没有 OpenCreateVoice, 必须走直传两步法)
#          step1: 申请直传 URL
python3 scripts/send_voice_notify.py get_upload_url \
    --file-name hello.wav --content-type audio/wav --sub-service-type 102
#          step2: 用返回的 UploadUrl 直接 PUT 文件 (curl/客户端自行完成)
#          step3: 提交注册
python3 scripts/send_voice_notify.py submit_upload \
    --upload-id <UploadId> --name "欢迎语" --sub-service-type 102
#          (旧的 create_voice 子命令已弃用, 调用会返回 ApiNotSupported 引导文案)
#     11.2 查录音 (按 ResourceKey 精确 / Name 模糊本地过滤)
python3 scripts/send_voice_notify.py query_voice \
    [--sub-service-type 102] [--resource-key <Key>] [--name 关键词] [--limit 20]
#     11.3 删除录音
python3 scripts/send_voice_notify.py delete_voice --resource-key <ResourceKey>

# 12. 通用资源管理
#     12.1 查可用 (审核通过) 资源
python3 s