Yuboto Omni API Assistant

核心用法

Yuboto Omni API 技能是一套面向企业消息服务的开发工具集，专注于 Yuboto（原 Octapush）全渠道通信平台的 API 集成。核心能力覆盖四大领域：

1. 消息发送：SMS 与 Viber 单条/批量发送，支持 CSV 导入、模板变量与发送方 ID 管理
2. 状态追踪：DLR（投递回执）查询、待处理消息轮询、历史记录检索
3. 账户管理：实时余额查询、发送成本预估、黑名单与联系人列表操作
4. 开发辅助：基于 Swagger 的端点发现、多源文档冲突仲裁、生产级代码生成

技术实现遵循明确的真相来源优先级：实时 Swagger JSON > 快速参考文档 > 旧版 PDF 提取 > 原始 PDF。当文档冲突时，以 Swagger 端点定义为准。

显著优点

• 多源文档整合：自动处理 PDF 与 Swagger 的差异，降低因文档过时导致的集成错误
• 安全优先设计：强制环境变量注入 API 密钥，禁止硬编码；提供 shell 历史泄露防护建议
• 完整 CLI 工具链：内置 8+ 条常用命令（balance/cost/send-sms/dlr/send-csv/poll-pending/history/status），支持零代码快速验证
• 批量场景优化：CSV 批量发送、待处理消息自动轮询，适合营销推送与事务通知场景
• 错误处理规范：代码生成模板包含结构化错误映射、重试机制与超时配置

潜在缺点与局限性

• 认证门槛：需人工联系 Yuboto 支持开通 API 权限，非自助注册即用
• 区域限制：以希腊（GR/+30）为默认示例，其他区域成本计算与发送方 ID 规则需额外验证
• Viber 高级功能依赖 Swagger：部分 Viber 特性文档不完整，需直接查阅 Swagger JSON
• .env 风险提示：poll_pending.sh 会 source 整个 .env 文件，存在意外加载无关密钥的风险
• 语言中立限制：生成示例默认无本地化，需用户主动要求希腊语/英语副本

适合人群

• 需集成 SMS/Viber 能力的后端工程师与 DevOps
• 构建营销自动化、OTP、通知系统的开发团队
• 现有 Yuboto/Octapush 用户优化 API 调用流程

常规风险

• 密钥泄露：CLI 参数传递 API 密钥会记录在 shell history，必须使用环境变量
• 敏感数据残留：本地日志可能包含手机号、消息预览、DLR 载荷，需定期清理
• 发送方 ID 合规：未获批准的发送方名称可能导致消息拦截或账户处罚
• 轮询成本：高频 poll-pending 可能触发 API 调用配额消耗，建议结合指数退避策略

核心用法

Yuboto Omni API 技能为企业级消息通信提供完整的代码集成与运维支持。核心功能覆盖三大场景：消息发送（SMS/Viber 单发/批量 CSV 发送）、状态追踪（DLR 送达回执查询、pending 消息轮询）、账户管理（余额查询、发送成本预估、历史记录检索）。

使用流程遵循"快速工作流"设计：首先通过 api_quick_reference.md 或 find_endpoints.py 脚本定位目标端点，然后在 swagger_v1.json 中验证请求参数、请求体和响应结构，最后生成包含认证头、重试机制、错误处理的完整代码。CLI 工具提供 8 条常用命令，支持从命令行快速验证 API 连通性和业务逻辑。

技能特别注重多源文档的一致性处理——当 PDF 文档与实时 Swagger 冲突时，优先以 Swagger 为真相来源，避免开发者因文档过时而产生集成错误。

显著优点

安全架构规范：API Key 强制通过 OCTAPUSH_API_KEY 环境变量注入，禁止硬编码；CLI 虽支持 --api-key 参数，但明确推荐环境变量方式以规避 shell 历史泄露风险。所有通信强制 HTTPS，依赖仅使用 Python 标准库与 requests，攻击面极小。

开发者体验优化：提供从端点发现、Schema 验证到代码生成的完整工作流；poll_pending.sh 等脚本实现本地状态持久化，支持消息生命周期的全程追踪；多语言示例保持中立，便于国际化团队协作。

运维友好设计：内置超时与基础重试机制；state/ 和 logs/ 目录结构化存储运行数据；批量 CSV 发送功能直接对接企业常见数据源格式。

潜在缺点与局限性

准入门槛：需要主动注册 Yuboto/Octapush 账户并向人工申请 API 权限，无法即开即用；审批周期可能影响项目进度。

功能边界：专注消息通道集成，不提供消息内容模板管理、用户分群、A/B 测试等高级营销自动化功能；Viber 富媒体功能需开发者自行查阅 Swagger 实现，技能内示例以 SMS 为主。

数据本地持久化风险：state/ 目录存储的消息记录包含明文电话号码和部分消息内容预览，在多用户共享环境或持久化卷场景中需额外注意文件权限与定期清理策略。

外部依赖单一：核心功能完全依赖 Yuboto 官方服务可用性，无降级通道设计；批量发送场景下若遇 API 速率限制，需开发者自行实现请求间隔控制。

适合的目标群体

• 企业后端开发者：需要快速集成短信验证码、订单通知、营销推送等能力的开发团队
• DevOps/运维工程师：负责消息通道监控、成本优化、送达率分析的运维人员
• 系统集成商：为客户项目对接 Yuboto 服务的第三方技术服务商
• 中小型企业技术负责人：寻求替代国际 SMS 服务商（如 Twilio、MessageBird）的本土化、高性价比方案

使用风险与注意事项

API Key 泄露风险：尽管技能本身安全处理密钥，但 .env 文件的不当使用（如误提交至版本控制）仍是常见隐患。建议生产环境仅使用环境变量注入，并配合密钥管理服务（如 AWS Secrets Manager、Azure Key Vault）。

敏感数据残留：本地 state/ 和 logs/ 文件长期积累可能包含大量用户隐私数据，需建立定期清理或加密归档机制；在 CI/CD 流水线中运行时，应避免将工作目录缓存至不可控存储。

网络与速率限制：批量发送场景可能触发服务商速率限制，建议实施指数退避重试和请求频率监控；跨国网络环境需关注 api.yuboto.com 的连通性与延迟表现。

合规性责任：消息内容（尤其是营销短信）需遵循当地通信法规（如中国《通信短信息服务管理规定》、欧盟 GDPR 的同意机制），技能本身不提供合规性检查，开发者需自行确保业务逻辑合法。

功能版本漂移：Yuboto API 持续演进，建议定期核对本地 Swagger 副本与官方在线文档的差异，关注 Viber 等富媒体通道的 API 变更公告。