---
name: cn86-sms-keyword-verification
description: 86手机号关键词验证码流程，基于 LubanSMS 通用短信接收 API 完成取号、轮询短信、提取验证码、释放号码，并可用“千问”等关键词做短信登录/注册 demo。
type: workflow
domain: utilities
version: 1.0.0
tags: [sms, verification, phone, keyword, china, qwen, lubansms]
triggers:
  keywords:
    primary: [86 手机号, 86手机号, 手机号获取, 短信验证码, 关键词验证码, 获取验证码, 接码]
    secondary: [千问验证码, qwen sms, lubansms, getKeywordNumber, getKeywordSms, keywordSmsHistory]
  context_boost: [注册, 登录, 验证码, 短信, 手机号, 关键词]
  priority: high
---

# CN86 SMS Keyword Verification

86 手机号 + 关键词获取验证码的标准流程技能。

本技能使用 `https://lubansms.com/v2/api` 的“通用短信接收”接口做 demo。你给的内部参考文档 `docs/sms-register-qwen.md` 里，附录实际也是按这组 LubanSMS 接口在写；文档里提到的千问（Qwen）示例关键词是 `千问`。

如需稳定执行，优先使用打包好的 `scripts/lubansms_keyword_cli.py`，不要手写临时 curl 再去人肉判断状态。

## 什么时候用

- 需要先拿一个 86 号码，再根据短信关键词轮询验证码
- 目标站点会把验证码发到中国手机号，但平台只给“按关键词取短信”的能力
- 要做可重复的注册/登录自动化 demo，例如千问短信登录
- 需要历史记录、余额检查、释放号码这些配套动作

## 需要的输入

- `keyword`：短信中能稳定命中的关键词，例如 `千问`
- `LUBAN_SMS_APIKEY`：运行时环境变量，不要写死进仓库
- 可选 `phone`：想复用已有号码时传入；留空则随机取号
- 可选 `timeout` / `interval`：轮询等待时长和间隔

## API Key 处理

优先使用环境变量：

```bash
export LUBAN_SMS_APIKEY='<your_api_key>'
export LUBAN_SMS_API_BASE='https://lubansms.com/v2/api'
```

只在一次性调试时才用 `--api-key` 直传。

## 标准流程

1. 先查余额，避免轮询到一半才发现 key 无效或余额不足。
2. 调 `getKeywordNumber` 申请号码。
3. 规范化手机号：
   - API 内部继续使用原始数字串，例如 `16741251148`
   - 对外展示可拼成 `+8616741251148`
   - 如果目标站点像千问一样把国家码拆开填，就传 `phoneCode=86` + 原始手机号
4. 在目标站点触发发送短信。
5. 调 `getKeywordSms` 按关键词轮询短信。
6. 从返回短信正文中提取验证码。
7. 成功或失败后都调用 `delKeywordNumber` 释放号码。
8. 排查问题时再查 `keywordSmsHistory`。

## 平台状态判断

- `code=0`：成功
- `code=400` 且 `msg=尚未收到短信,请稍后重试`：可继续轮询
- `code=400` 且 `msg=不正确的apikey`：立即停止，检查 key
- 其他 `code!=0`：视为 API 失败，不要盲目重试到超时

## 千问（Qwen）Demo

千问短信内容在参考文档里使用的关键词是 `千问`。

### 1. 先检查余额

```bash
export LUBAN_SMS_APIKEY='<your_api_key>'
python3 scripts/lubansms_keyword_cli.py balance
```

### 2. 一次性 demo：取号 → 等短信 → 提取验证码 → 释放号码

```bash
python3 scripts/lubansms_keyword_cli.py demo \
  --keyword 千问 \
  --timeout 300 \
  --interval 5
```

这个命令会：
- 申请一个随机 86 号码
- 输出原始号码和 `+86` 格式
- 等你在目标站点触发短信发送
- 轮询关键词短信并提取验证码
- 默认在结束时释放号码

### 3. 拆开执行

```bash
python3 scripts/lubansms_keyword_cli.py request-number
python3 scripts/lubansms_keyword_cli.py wait-code --phone 16741251148 --keyword 千问
python3 scripts/lubansms_keyword_cli.py release --phone 16741251148
```

## 常见坑

- 不要把 `LUBAN_SMS_APIKEY` 写进提交文件。
- 不要把 `+86` 或 `86` 前缀后的完整国际格式直接塞回 `phone=` 参数；平台接口通常要原始号码数字串。
- 不要忘记释放号码；无论成功、失败、超时都应该释放。
- 不要把“尚未收到短信”当成致命错误；这是正常轮询态。
- 不要只看关键词命中，不提取验证码；很多自动化链路最后需要明确的 OTP 数值。

## 推荐脚本

使用 `scripts/lubansms_keyword_cli.py`：

- `balance`：查余额
- `request-number`：申请号码
- `get-sms`：查一次关键词短信
- `wait-code`：轮询直到拿到验证码或超时
- `release`：释放号码
- `history`：查历史记录
- `demo`：完整演示流程

## 参考资料

- `references/lubansms-and-qwen-notes.md`