| name | byted-sms-sender |
| version | 1.3.1 |
| metadata | {"author":"volcengine-sms-team"} |
| description | 火山引擎国内短信（SMS）与短信营销全流程服务，面向外部客户提供短信开通后的运营、发送和分析能力。用户只要提到“短信”“短信服务”“短信营销”“营销短信”“短信群发”“群发短信”“批量短信”“验证码短信”“通知短信”“短信签名”“短信模板”“短信发送”“群发任务”“发送记录”“短信回执”“送达率”“成功率”“失败原因”或“短信数据分析”，或者希望通过火山引擎发送、管理、查询、排查和分析国内短信时，应优先使用。支持已审核资质和消息组查询、签名与模板申请、单条短信发送与回执查询、群发任务创建与明确授权后的启动、任务取消，以及客户可见的数据分析。不要用于资质申请、国际短信、WhatsApp 或非客户可见的技术诊断。 |
火山引擎短信
先定位本 Skill 目录，再将
python3 <skill目录>/scripts/sms_cli.py 作为唯一命令入口。
脚本可从任意当前目录运行。脚本优先通过 ve volcsms 执行 Action，并继续负责
预检、授权摘要、脱敏与对账；不要绕过脚本直接执行写 Action。不要手写 HTTP 请求
或臆造 Action 名，构造不熟悉的参数前先查看对应命令的 --help。
鉴权边界
- 对短信 API 的请求只使用火山引擎 V4 AK/SK 鉴权；临时凭证同时签入
SessionToken。
- 第一优先级：使用
ve >= 1.1.0 的 ve volcsms <Action> 命令。由官方 CLI
复用 ve login、当前 Profile 或 VOLCENGINE_PROFILE 指定的 Profile，并
负责凭证刷新、签名与请求发送。Skill 不读取 CLI 配置文件。
- 第二优先级：只有 CLI 不存在、不支持
volcsms，或在请求发出前明确无法使用
时，才使用兼容直连路径。该路径先通过官方 CLIConfigCredentialProvider
复用 ve Profile；无法解析时按顺序读取进程环境变量和
~/.openclaw/.env 中完整的 VOLCENGINE_ACCESS_KEY 与
VOLCENGINE_SECRET_KEY。临时凭证同时使用 VOLCENGINE_SESSION_TOKEN。
- 兼容直连路径内，任一凭证来源或变量组不完整时直接报错，不跨来源或跨变量组
拼接。没有可用凭证时，只提示配置
VOLCENGINE_ACCESS_KEY、
VOLCENGINE_SECRET_KEY，以及临时凭证所需的 VOLCENGINE_SESSION_TOKEN。
- 如果
ve 不存在或低于 1.1.0，先通过官方 npm 包
@volcengine/cli 安装或升级。requirements.txt 中的 Python SDK 只用于
兼容直连路径；不要自行读取 CLI 配置文件。
- 不要直接读取或解析 Volcengine CLI 配置、SSO 缓存或控制台登录缓存；
凭证加载与刷新必须交给官方 CLI 或 Provider。
- 不要通过命令行参数传递 AK/SK 或 SessionToken。
- 官方 Provider 返回的 Session Token 属于客户直连 V4 凭证，必须作为已签名的
X-Security-Token 发送。
- 调用身份由最终选中的鉴权路径确定，不接受账号 ID 覆盖。
选择工作流
命令导航
- 资源查询：
list-message-groups、message-group-detail、
list-qualifications、list-signatures、list-templates。
- 申请：先执行
signature-preview，再执行 signature-submit；
先执行 template-preview，再执行 template-submit。
- 单条发送：使用完整客户短信内容、签名、消息组和短信类型调用
match-template，查找内容完全一致且已审核通过的模板。随后用明确选定的模板
ID 执行 send-preview，取得当前会话中的明确授权后执行 send-submit；
使用 send-status 查询回执。
- 群发：
batch-template-demo、batch-precheck、batch-create、
batch-detail、batch-list、batch-launch-preview、
batch-launch-submit、batch-cancel。
- 客户数据分析：使用
analytics。聚合统计是提交级数据；只有显式传入
--include-logs 才查询消息级证据。分析账号全量发送日志时，先枚举客户可见的
消息组，再逐个查询。--channel-type 只限定聚合统计；
--mobile 只作为发送日志请求过滤条件，必须与 --include-logs 同时使用，
不得返回，也不会限定同一报告中的聚合趋势。
强制安全门禁
- 不支持资质申请，只查询已审核资质。如果客户没有可用资质，停止签名申请流程，
明确引导客户登录火山引擎控制台，在“国内短信 > 资质管理”完成资质申请；待资质
审核通过后再继续。不要代替客户提交资质申请。
- 签名和模板申请必须先生成预览；只有执行摘要仍与预览一致时才能提交。
- 签名申请必须遵循客户明确指定的消息组子集。客户不确定或未指定时，绑定当前
可见的全部消息组。默认全选时，提交前立即重新查询；可见集合变化后必须重新
生成预览。
- 签名来源
source 必须为整数：1 = 公司、2 = App、
3 = 商标。消息组行业不是签名申请门禁；只有客户主动询问时才使用
message-group-detail。
- 单条发送必须针对当前脱敏发送摘要取得明确授权。只有取得授权后，才能把预览
摘要作为授权摘要传入；泛化的“继续”或“是”不构成授权。
- 单条发送前，根据完整短信内容判断短信类型，再匹配模板。只检查本次发送需要的
消息组、签名、模板及变量关系；不要查询资质或消息组行业。签名缺少
usable、资质 ID 或短信类型字段不视为失败，但明确
usable=false 必须拒绝。
- 按客户明确的发送方式选择单条发送或群发；客户明确要求群发时，即使本次只有一个
测试号码也使用群发工作流。
- 创建群发任务不等于授权发送。展示最新任务摘要并在当前会话收到
确认启动任务 <taskId> 后，才能启动。
- 保留群发创建交接信息：
taskId、subAccount、文件 SHA-256 和号码统计。
任务详情缺少这些值时，在启动预览中补入交接信息。
- 发送或启动前立即重新查询可变资源；任何摘要变化都会使原授权失效。
- 群发任务禁止使用验证码模板。
- 群发任务状态
3、4、5 只表示已接受启动、正在准备或正在发送；不能据此
宣称任务完成、短信已送达或发送成功。状态 6 只表示任务处理完成，也不能替代
消息级回执。只有公开发送日志提供送达证据时，才能报告具体号码成功或失败；暂时
查不到数据时说明“已启动，回执待更新”，不要把零统计或查询失败解释成成功。
- 保留公开短信错误码，只能通过
actions.md 中的官方文档链接解释；
不要硬编码、推断或输出非公开实现原因。
- 除非
actions.md 明确声明服务端幂等字段与对账方式，否则不要自动重试写
Action。
- CLI 写调用只有在能够确认子进程未发出请求时才允许进入兼容路径。CLI 超时、
响应丢失或无法判断是否已发送时，必须返回
outcome_unknown，不得换后端重放。
- 如果写请求可能已到达服务端但响应丢失，返回
outcome_unknown，并使用查询
Action 对账；不要盲目重复提交。
输出边界
返回 CLI JSON 信封，但不要暴露完整手机号、可能含敏感信息的短信内容、凭证、
Authorization 请求头、签名 URL 查询参数，以及任何非客户可见字段。
保留公开 Request ID 与公开错误码，供客户支持排查。
