3.8 KiB
3.8 KiB
Why
你想做的不是完整短信客户端，而是一个只服务自己手机的验证码接收工具：在小米 12S、澎湃 OS 3、Android 15 上尽可能可靠地读取新收到短信里的验证码，并把关键结果快速展示出来。
这类需求的关键不在 UI，而在 Android 15 与厂商系统对短信权限、广播分发、后台限制和验证码短信格式的真实行为。因此必须先把可用 API、兜底路径和真机验证方案写清楚，再进入编码。
What Changes
- 新建一个 Android App 规格方案，目标能力限定为“接收短信验证码、解析验证码、展示最近结果、输出诊断状态”。
- 明确三条可用 SMS 获取路径，并按优先级落地：
Telephony.Sms.Intents.SMS_RECEIVED_ACTION+RECEIVE_SMS：主路径，适合个人自用、非 Play 上架场景，直接读取收到短信内容。SMS User Consent API：备选路径，不要求短信带 app hash，但需要用户对单条短信授权，适合验证系统广播被限制时的可行性。SMS Retriever API：受控格式路径，不需要短信权限，但要求验证码短信包含当前 app 的 hash，更适合服务端可控验证码，不适合作为读取任意平台验证码的主路径。
- 明确不把 Android Studio、Gradle、JDK 环境初始化纳入本次工作，后续实现时参考已有
Weather项目的构建环境。 - 设计验证码解析策略，支持常见 4-8 位数字码、中文验证码文案、带空格/短横线的验证码，以及短信多段 PDU 合并后的正文。
- 设计真机验证路径，重点验证 Android 15 + HyperOS 3 上：
- 运行时申请
RECEIVE_SMS是否成功。 - 应用在前台/后台时
SMS_RECEIVED_ACTION是否触发。 - 短信正文是否能被解析为完整 message body。
- 常见短信验证码是否能稳定提取。
- 运行时申请
- 建立诊断能力，暴露权限状态、API 路径状态、最近一次广播时间、最近一次解析结果和失败原因。
Capabilities
New Capabilities
sms-code-capture: 定义应用通过系统短信广播、Google SMS 验证 API 备选路径接收短信正文并抽取验证码的行为要求。sms-permission-diagnostics: 定义应用对短信权限、接收状态、API 可用性和解析失败原因的诊断展示要求。sms-code-validation-workflow: 定义在小米 12S、澎湃 OS 3、Android 15 真机上的验证流程和测试通过标准。
Modified Capabilities
- 无。当前
SmsReceive目录没有既有 OpenSpec 能力规格。
Impact
- 预期后续会创建一个最小 Android 工程或复用 Weather 工程环境生成同类 Android 工程配置。
- 预期会影响 Android Manifest、运行时权限申请、BroadcastReceiver、短信 PDU 解析、验证码正则解析、前台诊断 UI 和测试用例。
- 需要引入或使用的主要 Android/Google API：
android.provider.Telephony.Sms.Intents.SMS_RECEIVED_ACTIONandroid.permission.RECEIVE_SMSTelephony.Sms.Intents.getMessagesFromIntent(Intent)com.google.android.gms.auth.api.phone.SmsRetrieverSMS User Consent API
- 不以 Play Store 上架合规为目标，因此可以使用短信权限；但实现仍必须本地化处理短信内容，不上传、不持久化完整短信正文，减少隐私风险。
Validation
- OpenSpec 文档结构完整，至少包含
proposal.md、design.md、tasks.md和三个 capability spec。 - API 方案必须明确主路径、备选路径、适用条件和限制，不写成泛泛而谈的短信读取方案。
- 设计必须说明 Android 15、HyperOS 3、个人自用 sideload/debug 场景下的权限与后台行为风险。
- 后续实现前必须能从任务列表直接进入编码，不再需要重新讨论核心架构。
- 后续实现完成后，必须在目标真机上完成至少一轮短信接收、解析和诊断验证。