按手机号提取 m0 sms_send_record 最近一条验证码(buss_type=验证码+soft_delete=0+id DESC 首条),正则提取 4-8 位数字码,send_state 不过滤并配文案,返回 ageSeconds 供判断 90s redis 有效期。零行级权限,安全模型靠专用 scope 门禁:prod 只绑研发专用 scope 6、dev 只绑 测试专用 scope,显式排除业务 scope(全平台唯一)。王恒拍板 4 决策点全部按建议值执行。 测试:SmsToolsTest 10 例全绿;测试环境冒烟 4/4(有记录提取/无记录 notice/非法入参/ operation scope 拒绝)。
5.7 KiB
短信验证码提取工具 MCP 设计(REQ-20261113-0009,已批准 2026-11-13)
拍板结论(2026-11-13 王恒):§7 四个待拍板点全部按建议值执行—— ① buss_type 固定过滤"验证码";② send_state 不过滤、失败记录也返回并标注; ③ 不加时间窗、返回 ageSeconds;④ 工具名
sms.vercode.latest.query、category=admin。 (实现注:kind 按平台惯例为read/write,本工具 kind=read,设计稿中"query"为笔误。)
1. 背景
研发/测试场景需要"按手机号提取最近一条短信验证码"(自动化登录、联调、测试账号验证)。 老系统没有现成查询接口,目前只能人工查库。本设计新增 1 个只读 MCP 工具。
敏感性说明:验证码 = 登录绕过原语。本工具按运维工具口径设计——零行级权限, 访问控制完全靠专用 scope 门禁(同 warehouse.order.handler.update 模式), 只绑研发专用/测试专用作用域,永不绑业务 scope(prod 1/2/3/5)。
2. 数据源调研结论
表:m0 sms_send_record(参考库 beans/b0/SmsSendRecord.java,m0 mapper)。
| 列 | 说明 |
|---|---|
| user_mobile | 手机号 |
| sms_content | 发送内容,验证码记录为 验证码=123456 或 【小趣智品】验证码=123456 |
| buss_type | 业务类型,验证码记录固定为 验证码(SendSmsController.java:84/97、LoginController.java:195/208、AccountController、ChargeController 均同) |
| send_state | 0 成功 / 1 失败(失败记录 content 里也有码,但 redis 未写入,实际不可用) |
| report_state | 验证码记录固定写 99(不过滤) |
| soft_delete | 0 正常 / 99 停用 |
| create_time | 发送时间 |
验证码本体:RandomUtil.randomNumbers(6),6 位数字;redis 有效期 90 秒
(SendSmsController.java:93)。非生产/白名单环境直接返回 123456 且不落库,
所以测试环境查不到记录属正常现象。
3. 工具定义
| 项 | 值 |
|---|---|
| 工具名 | sms.vercode.latest.query |
| category | admin |
| kind | read(只读) |
| 工具类 | 新建 SmsTools(同域后续可加短信记录列表工具) |
| 数据源 | 纯 MySQL m0,无 ES、无 Redis |
| 行级权限 | 无(scope 门禁,见 §6) |
4. 参数契约
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mobile | string | 是 | 11 位手机号,精确匹配 user_mobile |
查询口径(固定,全部保老系统写入口径):
user_mobile = mobilebuss_type = '验证码'soft_delete = 0- 按
id DESC取第一条(自增 id 等价于 create_time 最新,避免时间精度并列)
提取规则:对 sms_content 跑正则 验证码\s*[=::]\s*(\d{4,8}),命中取第一组;
不命中(历史脏数据/格式漂移)返回 vercode=null + 原始 smsContent,不报错。
5. 返回契约
统一 ToolResult 结构,record 对象:
{
"record": {
"id": 123456789,
"mobile": "13800000000",
"vercode": "483920",
"smsContent": "验证码=483920",
"sendState": 0,
"sendStateText": "发送成功",
"bussType": "验证码",
"createTime": "2026-11-13 17:20:30",
"ageSeconds": 45
},
"notice": null
}
- 无记录:
record=null+notice="该手机号暂无验证码短信记录" ageSeconds= 当前时间 - createTime,供调用方判断 90 秒有效期(工具不做硬过期判断, 失败记录 sendState=1 也照样返回并配文案,由调用方决定可用性——待拍板点 2)- 错误码:
INVALID_ARGUMENT(手机号为空/非 11 位),ToolCallException透出文案
6. scope 绑定(安全核心)
| 环境 | 绑定 | 说明 |
|---|---|---|
| prod | 只绑 scope 6(研发专用,code=code) | INSERT IGNORE scope_tool(6, tool_id);严禁绑 1/2/3/5 |
| dev | seed-dev 只加「测试专用」scope 绑定 | 不加 operation 等业务 scope |
按 2026-11-07 王恒口径"所有工具默认绑研发专用 scope 6",本工具是唯一显式排除 其他所有 scope 的工具(其他查询工具是"默认绑 6",本工具是"只绑 6")。 服务 Token 只有 sync 作用域,天然调不到。
审计:每次调用落 svc audit_log(含调用方 token 身份、入参 mobile、request_id), 与现有工具审计链路一致。
7. 待拍板点(建议值)
- buss_type 固定过滤"验证码"(建议)vs 不过滤取任意短信最新一条。
- send_state 不过滤,最新一条即使是发送失败也返回、文案标注(建议——失败记录 同样能反映"系统生成了什么码",联调更有用)vs 只看 send_state=0。
- 不做时间窗硬限制,返回 ageSeconds(建议)vs 加 withinMinutes 参数只查近 N 分钟。
- 工具名
sms.vercode.latest.query(建议),category=admin。
8. 变更文件清单
- 新增
entity/m0/SmsSendRecord.java(本地拷贝,全列对齐参考库——PR #31 教训) - 新增
mapper/m0/SmsSendRecordMapper.java - 新增
mcp/tool/SmsTools.java(1 个工具方法) - 新增
SmsToolsTest(参数校验/提取正则含【小趣智品】前缀格式/空记录/sendState 文案/soft_delete 过滤) sql/seed-dev.sql:测试专用 scope 绑定README.md+doc/agent-mcp-tools-reference.md:登记- 装配层零改动(ToolObject 扫描自动注册)
9. 测试与上线流程
按 AGENTS.md 标准流程:单测全绿 → ./deploy/test-up.sh 测试环境冒烟
(scopeCode=test 签 Token;注意 dev 库可能无验证码记录,空记录路径也要验)→
push main → remote-deploy → 确认 ToolSyncService 新增 tool → 绑 prod scope 6 →
生产只读核验(tools/list 可见 + 真实手机号查询)。ai-proj 走自审批闭环。