byted-vms-voice-notify

Files (5)

• LICENSE
• SKILL.md
• vms-fundamentals.md · references/
• _topclient.py · scripts/
• send_voice_notify.py · scripts/

SKILL.md (first lines)

# 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.

## 核心命令

```bash
# 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]

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples