UpKuaJing 短信工具

通过 UpKuaJing 开放平台 API 发送短信并跟踪短信任务状态。

概览

本技能通过以下方式接入 UpKuaJing 的短信服务：

• 短信发送（sms_send.py）：向手机号发送短信
• 短信任务列表（sms_task_list.py）：按时间范围筛选查看短信任务列表
• 短信任务记录列表（sms_task_record_list.py）：查看指定任务的详细发送记录

脚本运行方式

环境准备

1. 检查 Python 版本：python --version
2. 安装依赖：pip install -r requirements.txt

脚本目录：scripts/*.py
运行示例：python scripts/*.py

重要提示：始终使用直接脚本调用方式，例如 python scripts/sms_send.py。禁止使用 Shell 复合命令，如 cd scripts && python sms_send.py。

三大核心 API

短信发送（sms_send.py）

向手机号发送短信。

参数说明：参见 SMS Send API 文档

使用示例：

# 发送一条简单短信
python scripts/sms_send.py 
  --content "This is SMS content" 
  --phones '["13800138000"]'

# 启用双向模式发送（支持接收用户回复）
python scripts/sms_send.py 
  --content "This is SMS content" 
  --phones '["13800138000"]' 
  --channel_type 1

# 向多个手机号发送短信
python scripts/sms_send.py 
  --content "This is SMS content" 
  --phones '["13800138000","13800138001"]'

短信任务列表（sms_task_list.py）

查看短信任务列表，支持按时间范围筛选。

参数说明：参见 SMS Task List API 文档

使用示例：

# 获取任务列表（第一页，每页 10 条）
python scripts/sms_task_list.py --page_no 1 --page_size 10

# 按时间范围筛选
python scripts/sms_task_list.py 
  --start_time 1775812273 
  --end_time 1775900000 
  --page_no 1 
  --page_size 10

# 按状态筛选（0-待发送，1-发送中，2-发送完成）
python scripts/sms_task_list.py --status 2 --page_no 1 --page_size 10

短信任务记录列表（sms_task_record_list.py）

查看某条短信任务的详细发送记录。

参数说明：参见 SMS Task Record List API 文档

使用示例：

# 查询任务 ID 为 1496 的发送记录
python scripts/sms_task_record_list.py --task_id 1496 --page_no 1 --page_size 10

# 按时间范围与状态进一步筛选
python scripts/sms_task_record_list.py 
  --task_id 1496 
  --start_time 1775812273 
  --end_time 1775900000 
  --status 2 
  --page_no 1 
  --page_size 10

API Key 与 UpKuaJing 账户

• API Key：存储于 ~/.upkuajing/.env 文件中，变量名为 UPKUAJING_API_KEY
• 首次校验：若未配置，将提示用户手动提供或前往 UpKuaJing 开放平台申请

API Key 未配置

首次运行时检查 ~/.upkuajing/.env 文件中是否存在 UPKUAJING_API_KEY；
若该变量未设置，则提示用户选择以下任一操作：

1. 用户已有 API Key：由用户手动提供（需自行添加至 ~/.upkuajing/.env 文件）
2. 用户尚未申请：可通过 API 自动申请（执行 auth.py --new_key），新生成的 Key 将自动保存至 ~/.upkuajing/.env；
   等待用户做出选择；

账户充值

当 API 返回余额不足提示时，应明确告知用户并引导其完成充值：

1. 创建充值订单（执行 auth.py --new_rec_order）
2. 根据订单响应结果，向用户提供支付页面 URL，并指导用户打开链接完成支付；用户支付成功后需主动确认；

获取账户信息

使用以下命令查询当前 UPKUAJING_API_KEY 对应的账户信息：auth.py --account_info

费用说明

短信发送类 API 调用将产生费用，不同接口计费方式各异。
最新资费标准：用户可查阅《详细价格说明》文档；
或执行：python scripts/auth.py --price_info（返回全部接口的完整资费信息）

短信发送计费规则

短信发送按次计费——每次调用均按所含手机号数量收取对应费用。

任务列表与记录列表计费规则

免费使用——查询任务列表及任务记录列表不收取任何费用。

费用确认原则

任何会产生费用的操作，必须先向用户明确告知并等待其显式确认；不得在通知消息中同步执行该操作。

工作流程

决策指引

短信发送流程

1. 准备短信内容：包括短信正文、手机号列表
2. 执行发送：使用 sms_send.py 并传入相应参数
3. 获取响应：API 同步返回任务执行结果

任务核查流程

1. 查看任务列表：使用 sms_task_list.py，可选配时间筛选参数
2. 获取任务 ID：从任务列表响应中提取
3. 查看任务记录：使用 sms_task_record_list.py 并传入 task_id

错误处理

• API Key 无效或缺失：检查 ~/.upkuajing/.env 文件中 UPKUAJING_API_KEY 是否正确配置
• 账户余额不足：引导用户完成充值
• 参数非法：必须首先查阅 references/ 目录下的对应 API 文档，从中获取准确的参数名与格式，严禁凭经验猜测

API 文档参考

• 短信发送：查阅 references/sms-send-api.md
• 短信任务列表：查阅 references/sms-task-list-api.md
• 短信任务记录列表：查阅 references/sms-task-record-list-api.md

注意事项

• 所有文件路径在各平台下均统一使用正斜杠（/）
• 禁止猜测参数名称：务必从文档中获取准确的参数名与格式
• 禁止在响应中输出技术参数格式：不得在自然语言回复中展示代码风格的参数（如 --content），须转换为符合中文表达习惯的描述
• 禁止估算或猜测费用——必须执行 python scripts/auth.py --price_info 获取准确的资费信息
• 短信发送为同步提交：API 在提交后立即返回响应，但实际发送由短信服务器异步处理；响应中的 status 字段表示当前状态（1-发送中，2-发送完成，3-发送失败，4-部分成功）

相关技能

您可能还会用到的其他 UpKuaJing 技能：

• linkedin-person-search — 从 LinkedIn 数据源搜索人员
• global-company-person-search — 从全球企业数据库搜索人员
• linkedin-company-search — 从 LinkedIn 数据源搜索企业
• global-company-search — 从全球企业数据库搜索企业
• global-company-shareholder — 从全球企业数据库查询股东列表
• global-company-employee — 从全球企业数据库查询员工列表
• global-company-person-colleague — 从全球企业数据库查询同事列表
• global-company-person-alumni — 从全球企业数据库查询校友列表
• global-company-person-experience — 从全球企业数据库查询工作经历列表
• global-company-person-education — 从全球企业数据库查询教育经历列表
• global-company-person-school-detail — 从全球企业数据库查询学校详情
• upkuajing-global-company-people-search — 全球企业与人员联合搜索
• upkuajing-customs-trade-company-search — 海关贸易企业搜索
• upkuajing-email-tool — 发送邮件及管理邮件任务
• upkuajing-map-merchants-search — 基于地图的商户搜索
• upkuajing-contact-info-validity-check — 联系信息有效性校验
• phone-validity-check — 手机号码有效性校验
• email-validity-check — 邮箱地址有效性校验
• domain-validity-check — 域名有效性与安全性校验