byted-sms-sender

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 覆盖。

选择工作流

• 查询 Action 名、参数、版本、响应字段和重试分类时，读取 references/actions.md。
• 申请签名或模板、发送短信、管理群发任务前，读取 references/workflows.md。
• 执行任何写操作或处理客户数据前，读取 references/rules.md。

命令导航

• 资源查询：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 与公开错误码，供客户支持排查。