核心用法
Yuboto Omni API 技能是面向开发者的通信 API 集成工具，主要服务于 Yuboto/Octapush 平台的短信和即时通讯功能开发。
主要功能覆盖：
- 消息发送：SMS 单发/批量发送、Viber 富媒体消息，支持 CSV 文件导入和自动分片（默认 200 条/批）
- 状态追踪：实时查询投递回执（DLR）、轮询待处理消息、历史记录检索
- 账户管理：余额查询、发送成本预估、联系人/黑名单/订阅列表管理
- 开发辅助：基于 Swagger 的端点发现、多源文档冲突解决（优先 Swagger > PDF）
典型工作流：
1. 通过 api_quick_reference.md 或 find_endpoints.py 定位端点
2. 在 swagger_v1.json 中验证请求/响应 Schema
3. 使用 yuboto_cli.py 生成带重试、超时、结构化错误处理的代码
显著优点
- 多层级文档溯源：明确四级信源优先级（Swagger > 速查手册 > PDF 摘录 > 原 PDF），解决文档版本冲突
- 生产级安全默认：自动分片发送（防 API 限流）、250ms 批次延迟、本地敏感数据轮换（5000 条上限）
- 零外部依赖：纯 Python 标准库实现，无需安装
requests等第三方包 - OpenClaw 原生集成：支持集中式凭证管理，避免密钥硬编码
潜在缺点
- 区域限制：Yuboto 主要面向希腊及欧洲市场，国际短信路由覆盖需额外确认
- 发件人审核：SMS 发件人 ID 必须经过平台预审核，否则返回错误码 108
- 凭证获取门槛：需人工联系支持团队开通 API 权限，非自助开通
- 无 .env 支持：强制要求环境变量或 OpenClaw 配置，对本地开发流程有一定侵入性
适合人群
- 需要集成 SMS/Viber 商务通知的欧洲市场开发者
- 运维团队需批量发送并追踪投递状态的场景
- 现有 Yuboto/Octapush 用户需要 API 迁移或故障排查
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 密钥泄露 | API Key 为 Base64 编码但明文存储 | 强制使用环境变量，禁止 CLI 传参 |
| 数据残留 | 本地日志含手机号、消息预览 | 配置 `YUBOTO_MAX_SENT_LOG_LINES` 限制，定期清理 |
| 限流触发 | 批量发送未分片可能导致账户限流 | 默认启用 200 条/批 + 250ms 延迟 |
| 文档漂移 | PDF 与 Swagger 端点定义可能不一致 | 工具链优先读取 Swagger，人工复核关键字段 |