Add CN86 SMS keyword verification skill and README

cn86-sms-keyword-verification/SKILL.md

@@ -0,0 +1,127 @@
+---
+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`